搜索推广API

    NewCreativeService

    数据类型

    SublinkType

    SublinkType描述了计算机推广子链的数据类型。

    属性名类型说明限制
    sublinkId Long返回推广
    子链的id
    -
    sublinkInfos SublinkInfo[]推广子链
    描述集合
    将按照输入的先后顺序展现子链的描述;
    (说明:pc蹊径目前最多支持子链描述数为3-5。)
    移动设备蹊径支持1-4条子链,总长度支持8-32个字符。最少1条,最多4条;
    每条限制8个汉字,16个字符,总共32个字符。仅一条数据时,
    最小字符数8个
    adgroupId Long推广单元id -
    pause Boolean 暂停/启用创意取值范围:
    true - 暂停;
    false - 启用
    status int 推广子链状态取值范围:
    61-有效;
    62-暂停推广;
    63-不宜推广;
    65-审核中。
    该属性由系统指定,
    客户端不可改变
    deviceInteger投放设备0:计算机;
    1:移动设备

    SublinkInfo

    SublinkInfo描述了单条计算机推广子链的数据类型。

    属性名类型说明限制
    description String 推广子链文字描述长度限制:
    PC:5个计算机推广子链一共最多支持56个字符,
    每个子链最多支持16个字符,
    56个字符可以在16个字符最大限度之下随意分配给各个子链;
    移动:移动推广蹊径支持1-4条子链,
    总长度支持8-32个字符。最少1条,最多4条;
    每条限制8个汉字,16个字符,总共32个字符。仅一条数据时,最小字符数8个
    destinationUrl String 访问url 长度限制:不得超过1024个字符;域名需与账户网站域名相同,
    URL必须以`http://`或`https://`开头

    PhoneType

    属性名类型说明限制
    phoneIdlong电话ID
    phoneNumString电话号码
    adgroupIdlong所属单元ID
    pauseboolean暂停/启用取值范围:
    true - 暂停;
    false - 启用
    statusint状态取值范围:
    71-有效;
    72-暂停推广;
    73-不宜推广。
    该属性由系统指定,客户端不可改变

    EcallType

    属性名类型说明限制
    ecallIdLong网页回呼id -
    ecallGroupidLong网页回呼分组id-
    ecallGroupNameString网页回呼分组名称-
    adgroupId Long推广单元id -
    pauseboolean暂停/启用取值范围:true - 暂停false - 启用
    statusint状态取值范围:101-有效,102-暂停推广,103-无效;该属性由系统指定,客户端不可改变

    EcallGroupType

    属性名类型说明限制
    ecallGroupidLong网页回呼分组id -
    ecallGroupNameString网页回呼分组名称-

    接口描述

    根据指定的id类型和id信息,获取推广子链。

    Json示例

    {
         "ids":[***,***,…],"device":***,"idType":***,"getTemp":***,"sublinkFields":["sublinkId","sublinkInfos","getTemp","pause","status"]
     }

    输入信息(getSublinkRequest)

    属性名类型说明限制
    ids Long[] 待查询id集合必填
    idTypeIntegerId类型5:单元id,ids限制2500个;
    12:蹊径id,ids限制不超过5000个;
    建议分批多次请求
    sublinkFieldsString[]需要查询的推广子链属性必填。Device必返,用于标识推广子链的投放设备
    getTemp Integer是否查询影子必填;
    0:只查询计算机推广子链接本身;
    1:只查询计算机推广子链影子。
    想要获得计算机推广子链的全集,需要调用该方法两次,
    分别为getTemp=0和getTemp=1
    deviceInteger投放设备必填;
    0:计算机;
    1:移动设备

    推广子链字段(sublinkFields)

    基本字段是每次必返的字段(不论用户传不传);复合字段是由多个简单属性组合的属性,用户请求会将这些简单字段打包返回;其余字段为简单字段,用户请求则返回。

    字段名说明字段类型
    sublinkId推广子链的id基本字段
    adgroupId推广单元id
    sublinkInfos推广子链描述集合复合字段
    pause暂停/启用创意
    status推广子链状态

    返回信息(getSublinkResponse)

    属性名类型说明限制
    sublinkTypes SublinkType[]计算机推广子链信息-

    代码示例

    • 请求

    按照蹊径id获取蹊径的全部字段信息。 如果只需获取部分字段,只需填入需要获取的字段值;若需按单元id获取,请设置idType=5。

    {
    "header":{
    	"opUsername":"searchlab",   			//mcc操作员账户名称
        "opPassword":"*********"        		//mcc操作员账户密码
        "tgUsername":"searchlab", 
        "tgPassword":"*********", 
        "tgSubname":"searchlab",				//mcc被操作的账户
        "bceUser":"014df051fa131234a2a*****" 	//mcc类型的bceuser
    },
    "body":{
        "ids": [
      		sublink_id
        ],
        "idType": 12,
        "sublinkFields": [
            "sublinkId",
            "adgroupId",
            "pause",
            "status",
            "sublinkInfos",
            "getTemp"
        ],
        "getTemp": 0
      }
    }
    • 返回

      { "header": { "desc": "success", "failures": [], "oprs": 2, "succ": 2, "oprtime": 0, "quota": used_quota_of_this_operation, "rquota": your_remain_quota, "status": 0 }, "body": { "data": [ { "sublinkId": sublinkId, "sublinkInfos": [ { "description": "Bi bro, Shifu go", "destinationUrl": "http://www.your_website.com//1" }, { "description": "Se bro, Shifu go", "destinationUrl": "http://www.your_website.com//2" }, { "description": "Bud, Shifu go", "destinationUrl": "http://www.your_website.com/***/3" } ], "adgroupId": 809942603, "pause": false, "status": 65, "device": 0 } ] } }

    新增计算机推广子链,可批量添加。

    说明: 一个单元下目前最多支持1条计算机推广子链,因此如果该单元下已有推广子链,则会报错9116。

    Json示意

    {
         "sublinkTypes":[{"adgroupId":***,"pause":***,"status":***,"device":**,"sublinkInfos":[{"description":"***","destinationUrl":"***"},{"description":"***","destinationUrl":"***"},{"description":"***","destinationUrl":"***"}]},{***},…]
     }

    输入信息(addSublinkRequest)

    属性名类型说明限制
    sublinkTypes SublinkType[]新增计算机推广子链对象数组不超过5000;参见下表;建议分批多次请求

    新增SublinkType的限制:

    属性名类型限制
    sublinkId Long 无效
    sublinkInfos SublinkInfo[]必填
    adgroupId Long 必填
    pause Boolean 选填;默认为false
    status Integer无效属性
    deviceInteger必填

    SublinkInfo的限制:

    属性名限制
    description 必填
    destinationUrl 必填

    返回信息(addSublinkResponse)

    属性名类型说明限制
    sublinkTypes SublinkType[]新增计算机推广子链对象数组按请求顺序返回添加成功的推广子链,添加失败的推广子链返回错误信息及位置

    代码示例

    • 请求 为某个单元添加一条蹊径:

      { "header":{ "opUsername":"searchlab", //mcc操作员账户名称 "opPassword":"*" //mcc操作员账户密码 "tgUsername":"searchlab", "tgPassword":"*", "tgSubname":"searchlab", //mcc被操作的账户 "bceUser":"014df051fa131234a2a*" //mcc类型的bceuser }, "body":{ "sublinkTypes": [ { "adgroupId": adgroup_id, "pause": false, "status": 0, "device": 0, "sublinkInfos": [ { "description": "Bi bro, Shifu go", "destinationUrl": "www.your_website.com//1" }, { "description": "Se bro, Shifu go", "destinationUrl": "www.your_website.com//2" }, { "description": "Bud, Shifu go", "destinationUrl": "www.your_website.com/***/3" } ] } ] } }

    • 返回

    返回用户添加的信息:

    {
        "header": {
            "desc": "success",
            "failures": [],
            "oprs": 1,
            "succ": 1,
            "oprtime": 0,
            "quota": used_quota_of_this_operation,
            "rquota": your_remain_quota,
            "status": 0
        },
        "body": {
            "data": [
                {
                    "sublinkId": new_sublink_id,
                    "sublinkInfos": [
                        {
                            "description": "Bi bro, Shifu go",
                            "destinationUrl": "http://www.your_website.com/***/1"
                        },
                        {
                            "description": "Se bro, Shifu go",
                            "destinationUrl": "http://www.your_website.com/***/2"
                        },
                        {
                            "description": "Bud, Shifu go",
                            "destinationUrl": "http://www.your_website.com/***/3"
                        }
                    ],
                    "adgroupId": adgroup_id,
                    "pause": false,
                    "status": 65,
                    "device": 0
                }
            ]
        }
    }

    更新计算机推广子链,可批量更新。

    注意: 更新时,新提交的计算机推广子链会覆盖之前存在的推广子链,不管新提交的子链描述数是否大于之前的推广子链。

    Json示例

    {
         "sublinkTypes":[{"sublinkId":***,"adgroupId":***,"pause":***,"status":***,"device":**,"sublinkInfos":[{"description":"***","destinationUrl":"***"},{"description":"***","destinationUrl":"***"},{"description":"***","destinationUrl":"***"}]},{***},…]
     }

    输入信息(updateSublinkRequest)

    属性名类型说明限制
    sublinkTypes SublinkType[]更新计算机推广子链对象数组;
    不超过5000
    参见下表;建议分批多次请求

    更新SublinkType的限制:

    属性名类型说明限制
    sublinkId Long 返回计算机推广子链的id 必填
    sublinkInfos SublinkInfo[]子链描述集合必填
    adgroupId Long 推广单元id 无效
    pause Boolean 暂停/启用创意选填;默认值为NULL:不更新该属性
    status Integer创意状态无效属性
    deviceInteger投放设备无效属性

    SublinkInfo的限制:

    属性名限制
    description 必填
    destinationUrl 必填

    返回信息(updateSublinkResponse)

    属性名类型说明限制
    sublinkTypes SublinkType[]更新计算机推广子链对象数组按输入顺序返回全部SublinkType[]数组,更新失败的推广子链对象不返回。

    说明: 接口返回结果会自动补齐。例如客户在计算机推广子链信息1和3的位置上传了描述,但是没有在2的位置上传描述,在结果中是把3的内容补齐到2的位置。

    代码示例

    • 请求

    更新一条蹊径。

    {
    "header":{
    	"opUsername":"searchlab",   			//mcc操作员账户名称
        "opPassword":"*********"        		//mcc操作员账户密码
        "tgUsername":"searchlab", 
        "tgPassword":"*********", 
        "tgSubname":"searchlab",				//mcc被操作的账户
        "bceUser":"014df051fa131234a2a*****" 	//mcc类型的bceuser
    },
    "body":{
        "sublinkTypes": [
            {
                "sublinkId": sublink_id,
                "pause": false,
                "status": 0,
                "device": 0,
                "sublinkInfos": [
                    {
                        "description": "Bi bro, Shifu go",
                        "destinationUrl": "www.your_website.com/***/1"
                    },
                    {
                        "description": "Se bro, Shifu go",
                        "destinationUrl": "www.your_website.com/***/2"
                    },
                    {
                        "description": "Bud, Shifu go",
                        "destinationUrl": "www.your_website.com/***/3"
                    }
                ]
            }
        ]
      }
    }
    • 返回 只返回用户更新的字段信息:

      { "header": { "desc": "success", "failures": [], "oprs": 1, "succ": 1, "oprtime": 0, "quota": used_quota_of_this_operation, "rquota": your_remain_quota, "status": 0 }, "body": { "data": [ { "sublinkId": sublink_id, "sublinkInfos": [ { "description": "Bi bro, Shifu go", "destinationUrl": "http://www.your_website.com//1" }, { "description": "Se bro, Shifu go", "destinationUrl": "http://www.your_website.com//2" }, { "description": "Bud, Shifu go", "destinationUrl": "http://www.your_website.com/***/3" } ], "adgroupId": adgroup_id, "pause": false, "status": 62, "device": 0 } ] } }

    Json示例 删除指定的附加创意。

    {
        "sublinkIds":[***,***,…]
    }

    输入信息(deleteSublinkRequest)

    属性名类型说明限制
    sublinkIds long[] 附加创意id 必填,单次请求不超过10000;建议分批多次请求

    返回信息(deleteSublinkResponse)

    属性名类型说明限制
    删除失败的id,请查看错误提示Total返回删除成功的数量

    代码示例

    • 请求 删除两条蹊径:

      { "header":{ "opUsername":"searchlab", //mcc操作员账户名称 "opPassword":"*" //mcc操作员账户密码 "tgUsername":"searchlab", "tgPassword":"*", "tgSubname":"searchlab", //mcc被操作的账户 "bceUser":"014df051fa131234a2a*" //mcc类型的bceuser }, "body":{ "sublinkIds": [ sublink_id_1, sublink_id_2 ] } }

    • 返回

      { "header": { "desc": "success", "failures": [], "oprs": 2, "succ": 2, "oprtime": 0, "quota": used_quota_of_this_operation, "rquota": your_remain_quota, "status": 0 }, "body": { "data": [ ] } }

    getPhone

    根据指定的单元ID或电话ID获取电话信息。

    Json示例

    {
        "ids":[***,***,…],"idType":9,"phoneFields":["phoneId","phoneNum","adgroupId",…]
     }

    输入信息(getPhoneRequest)

    属性名 类型 说明 限制
    phoneFieldsString[] 指定需要返回的电话属性请参考表PhoneFields
    ids Long[] 查询id集合;
    idType=5;类型为单元id,不超过2500个;
    idType=9,类型为电话id,不超过5000个
    必填 ;建议分批多次请求
    idTypeInteger5:单元id;9:电话id必填

    推广电话字段(PhoneFields)

    基本字段是每次必返的字段(不论用户传不传);其余字段为简单字段,用户请求则返回。

    字段名 说明 字段类型
    phoneId电话id基本字段
    adgroupId推广单元id基本字段
    phoneNum电话号码
    pause暂停/启用
    status状态

    返回信息(getPhoneResponse)

    属性名 类型 说明
    PhoneTypes PhoneType []不请求的的属性(基础属性除外)无返回值

    addPhone

    输入信息(addPhoneRequest)

    属性名类型说明限制
    phoneTypesPhoneType[]新增电话对象数组;不超过5000参见下表;建议分批多次请求

    新增PhoneType的限制:

    属性名类型限制
    phoneIdlong无效属性
    phoneNumString必填
    adgroupIdlong必填
    pauseboolean选填
    statusint无效属性

    返回信息(addPhoneResponse)

    属性名类型说明限制
    phoneTypesPhoneType[]新增电话对象数组按请求顺序返回添加成功的电话,添加失败的电话返回错误信息及位置。
    说明:操作部分错误时会抛出90127的错误代码

    updatePhone

    输入信息(updatePhoneRequest)

    属性名类型说明限制
    phoneTypesPhoneType[]更新电话对象数组,不超过5000参见下表;建议分批多次请求

    更新PhoneType的限制:

    属性名类型限制
    phoneIdlong必填
    phoneNumstring必填
    adgroupIdlong无效
    pauseboolean选填;默认值为null:不更新该属性
    statusint无效属性

    返回信息(updatePhoneResponse)

    属性名类型说明限制
    phoneTypesPhoneType[]更新电话对象数组按输入顺序返回全部PhoneType[]数组,更新失败的电话对象不返回。
    说明:操作部分错误时会抛出90127的错误代码

    getEcall

    根据指定的单元ID或网页回呼ID获取网页回呼信息。

    Json示例

    {
    "ids":[***,***,…],"idType":23,"ecallFields":[" ecallGroupid "," pause"," status",…]
     }

    输入信息(getEcallRequest)

    属性名 类型 说明 限制
    ecallFieldsString[] 指定需要返回的网页回呼属性请参考表EcallFields;网页回呼Id号和单元id号必返,不填的属性将被返回为null
    ids Long[] 查询id集合:
    dType=5;类型为单元id,不超过2500个 ;
    idType=23,类型为网页回呼id,不超过5000个
    必填 ;建议分批多次请求
    idTypeInteger5:单元id;
    23:网页回呼id
    必填

    网页回呼字段(ecallFields)

    其中,基本字段是每次必返的字段(不论用户传不传);其余字段为简单字段,用户请求则返回。

    字段名 说明 字段类型
    ecallId电话id基本字段
    ecallGroupId网页回呼分组id基本字段
    adgroupId推广单元id基本字段
    ecallGroupName网页回呼分组名称
    pause暂停/启用
    status状态

    返回信息(getEcallResponse)

    属性名 类型 说明
    ecallTypes EcallType []不请求的的属性(基础属性除外)无返回值

    addEcall

    输入信息(addEcallRequest)

    属性名类型说明限制
    ecallTypesEcallType []新增网页回呼对象数组;不超过5000参见下表

    新增EcallType的限制:

    属性名类型限制
    ecallIdLong无效属性
    ecallGroupidLong必填
    ecallGroupNameString无效属性
    adgroupIdLong必填
    pauseboolean选填
    statusint无效属性

    返回信息(addEcallResponse)

    属性名类型说明限制
    ecallTypesEcallType []新增网页回呼对象数组按请求顺序返回添加成功的网页回呼,添加失败的网页回呼返回错误信息及位置

    updateEcall

    输入信息(updateEcallRequest)

    属性名类型说明限制
    ecallTypesEcallType[]更新网页回呼对象数组,不超过5000参见下表;建议分批多次请求

    更新EcallType的限制:

    属性名类型限制
    ecallIdlong必填
    ecallGroupidlong选填
    adgroupIdlong无效
    pauseboolean选填;默认值为null:不更新该属性
    statusint无效属性

    返回信息(updateEcallResponse)

    属性名类型说明限制
    ecallTypesEcallType[]更新网页回呼对象数组返回全部EcallType[]数组,更新失败的网页回呼对象不返回。

    getEcallGroup

    输出信息(getEcallGroupResponse)

    属性名类型说明限制
    ecallGroupTypesEcallGroupType[]网页回呼分组数组返回用户所有的网页回呼分组信息。若用户没有开通离线宝权限,则报错。
    上一篇
    ReportService
    下一篇
    AdgroupService