搜索推广API

    AdgroupService

    数据类型

    AdgroupType

    属性名类型说明限制
    adgroupId Long推广单元id -
    campaignId Long 推广计划id -
    adgroupName String 推广单元名称长度限制:最大30个字节,
    1个中文按2个字节计算
    maxPrice Double 推广单元最高出价取值范围:(0,999.99] &&<= 所属计划预算
    negativeWords String[] 单元否定关键词否定词长度:最大40字节,1个中文按2个字节计算;
    数组元素个数最大值:200;
    NULL :无否定词限制
    exactNegativeWords String[] 单元精确否定关键词精确否定词长度:最大40字节,1个中文按2个字节计算;
    数组元素个数最大值:200;
    NULL :无精确否定词限制
    pause Boolean 暂停/启用推广单元取值范围:
    true - 暂停,
    false - 启用
    status Integer推广单元状态取值范围:
    31-有效,
    32-暂停推广,
    33-推广计划暂停推广,系统指定,客户端不可改变
    priceRatioDouble单元移动出价比例bidprefer=1有效值范围:[0.1~10] ,默认为1
    bidprefer=2时仅能为默认值null;
    pcPriceRatioDouble单元计算机出价比例bidprefer=2取值范围:0<=数值<=10,默认值为1
    bidprefer=1时仅能为默认值null
    accuPriceFactorDouble精确出价比例0.1<=数值<=10,
    默认值为1.0
    wordPriceFactorDouble短语出价比例0.1<=数值<=10,
    默认值为1.0
    widePriceFactorDouble广泛出价比例0.1<=数值<=10,
    默认值为1.0
    matchPriceStatusInteger分匹配状态0:开启,要求精确系数>= 短语系数>= 广泛系数,
    且三个比例系数均不能为空,
    1:关闭

    接口描述

    getAdgroup

    根据指定的单元id获取推广单元。

    Json示意:

    {
         "ids":[***,***,…],"idType":3,"adgroupFields":["adgroupId","adgroupName","campaignId",…]
    }

    输入信息(getAdgroupRequest)

    属性名类型说明限制
    adgroupFieldsString[] 指定需要返回的单元属性不请求的属性没有返回值,
    取值请参考表adgroupFields
    idsLong[]查询id集合idType=5;类型为单元id,不超过5000个;
    idType=3,类型为计划id,不超过100个;
    必填;建议分批多次请求
    idTypeInteger3:计划id;
    5:单元id
    必填

    单元字段(adgroupFields)

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

    字段名说明字段类型
    adgroupId推广单元id基本字段
    campaignId推广计划id 基本字段
    adgroupName推广单元名称-
    pause暂停/启用推广单元-
    maxPrice推广单元最高出价-
    negativeWords单元否定关键词-
    exactNegativeWords单元精确否定关键词-
    status推广单元状态-
    accuPriceFactor精确出价比例-
    wordPriceFactor短语出价比例-
    widePriceFactor广泛出价比例-
    matchPriceStatus分匹配状态-
    priceRatio单元无线出价比例默认使用计划的
    pcPriceRatio单元计算机出价比例默认使用计划的

    返回信息(getAdgroupResponse)

    属性名类型说明
    adgroupTypes AdgroupType[] -不请求的属性无返回值

    代码示例

    • 请求

    获取一个单元的全部字段信息:

    {
    "header":{
    	"opUsername":"searchlab",   			//mcc操作员账户名称
        "opPassword":"*********"        		//mcc操作员账户密码
        "tgUsername":"searchlab", 
        "tgPassword":"*********", 
        "tgSubname":"searchlab",				//mcc被操作的账户
        "bceUser":"014df051fa131234a2a*****" 	//mcc类型的bceuser
    },
    "body":{
         "ids": [
                adgroup_id_1,
                adgroup_id_2
            ],
            "idType": idType,
            "adgroupFields": [
                "adgroupId",
                "campaignId",
                "adgroupName",
                "maxPrice",
                "pause",
                "negativeWords",
                "exactNegativeWords",
                "status",
                "accuPriceFactor",
                "wordPriceFactor",
                "widePriceFactor",
                "matchPriceStatus",
                "priceRatio"    ]
      }
    }
    • 返回

      { "header": { "desc": "success", "failures": [], "oprs": 2, "succ": 2, "oprtime": 0, "quota": used_quota_of_this_operation, "rquota": your_remain_quota, "status": 0 }, "body": { "data": [ { "campaignId": campaign_id_1, "adgroupId": adgroup_id_1, "adgroupName": "adgroup_name_1", "maxPrice": mp1, "pause": pause1, "negativeWords": [ "nw11", "nw12" ], "exactNegativeWords": [ "ew11", "ew12" ], "status": st1, "accuPriceFactor": af1, "wordPriceFactor": wf1, "widePriceFactor": wpf1, "matchPriceStatus": wps1, "priceRatio": pr1 }, { "campaignId": campaign_id_2, "adgroupId": adgroup_id_2, "adgroupName": "adgroup_name_2", "maxPrice": mp2, "pause": pause2, "negativeWords": [ "nw21", "nw22" ], "exactNegativeWords": [ "ew21", "ew22" ], "status": st2, "accuPriceFactor": af2, "wordPriceFactor": wf2, "widePriceFactor": wpf2, "matchPriceStatus": wps2, "priceRatio": pr2 } ] } }

    addAdgroup

    新增推广单元(可批量)。

    Json示意

    {
    "adgroupTypes":[{"campaignId":***,"maxPrice":***,…},{"campaignId":***,"adgroupName":"***","maxPrice":"***","pause":***,"negativeWords":["*","*",…],"exactNegativeWords":["*","*",…],"priceRatio":***,…},…]
    }

    输入信息(9addAdgroupRequest)

    属性名类型说明限制
    adgroupTypes AdgroupType[] 新增推广单元对象数组参见下表,没有输入值的属性,无返回值;
    单次请求不超过5000个;建议分批多次请求

    新增AdgroupType[]时,限制如下:

    属性名限制
    adgroupId 无效属性
    campaignId 必填
    adgroupName 必填
    maxPrice 必填
    negativeWords 选填;NULL :无否定词限制
    exactNegativeWords 选填;NULL :无精确否定词限制
    pause 选填;默认为 false
    status 无效属性
    priceRatio选填
    PC优先的取值范围参考上面
    移动优先的仅能为1或null
    pcPriceRatio选填
    移动优先的取值范围参考上面
    PC优先的仅能为1或null
    accuPriceFactor选填0.1<=数值<=10
    wordPriceFactor选填0.1<=数值<=10
    widePriceFactor选填0.1<=数值<=10
    matchPriceStatus选填0:开启,要求精确系数>= 短语系数>= 广泛系数,
    且三个比例系数均不能为空;
    1:关闭

    返回信息(addAdgroupResponse)

    属性名类型说明限制
    adgroupTypes AdgroupType[] 新增推广单元对象数组按请求顺序返回添加成功的单元,添加失败的单元返回错误信息及位置

    代码示例

    • 请求 在某个计划下,添加一个单元。

      { "header":{ "opUsername":"searchlab", //mcc操作员账户名称 "opPassword":"*" //mcc操作员账户密码 "tgUsername":"searchlab", "tgPassword":"*", "tgSubname":"searchlab", //mcc被操作的账户 "bceUser":"014df051fa131234a2a*" //mcc类型的bceuser }, "body":{ "adgroupTypes": [ { "campaignId": your_campaign_id, "adgroupName": "campaign_name", "maxPrice": "20", "pause": false, "priceRatio": 1, "accuPriceFactor": 3, "wordPriceFactor": 2, "widePriceFactor": 1, "matchPriceStatus": 0, "status": 0 } ] } }

    • 返回 已添加的单元信息:

      { "header": { "desc": "success", "failures": [], "oprs": 1, "succ": 1, "oprtime": 0, "quota": used_quota_of_this_operation, "rquota": your_remain_quota, "status": 0 }, "body": { "data": [ { "adgroupId": 809749664, "campaignId": 21197684, "adgroupName": "hellokitty000", "maxPrice": 20, "pause": false, "status": 31, "accuPriceFactor": 3, "wordPriceFactor": 2, "widePriceFactor": 1, "matchPriceStatus": 0, "priceRatio": 1 } ] } }

    updateAdgroup

    更新推广单元(可批量)。

    Json示意

    {
    "adgroupTypes":[{"adgroupId":"***","campaignId":***,"maxPrice":***},{"adgroupId":***,"campaignId":***,"adgroupName":"***","maxPrice":"***","pause":***,"negativeWords":["***","***"],"exactNegativeWords":["***","***",…],"priceRatio":***,…},…]
    }

    输入信息(updateAdgroupRequest)

    属性名类型说明限制
    adgroupTypes AdgroupType[] 更新推广单元对象数组参见下表;单次请求不超过5000个;建议分批多次请求

    更新AdgroupType[]时,限制如下:

    属性名限制
    adgroupId 必填
    campaignId 无效
    adgroupName 选填;默认为NULL :不更新该属性
    maxPrice 选填;默认为NULL :不更新该属性
    negativeWords 选填;默认为NULL :不更新该属性;
    值为空数组:取消否定词
    exactNegativeWords 选填;默认为NULL:不更新该属性;
    值为空数组:取消精确否定词
    pause 选填;默认为NULL :不更新该属性
    status 无效属性
    priceRatio选填
    PC优先的取值范围参考上面,可以输入-1,代表使用计划出价比例
    移动优先的仅能为1或null
    pcPriceRatio选填
    移动优先的取值范围参考上面,可以输入-1,代表使用计划出价比例
    PC优先的仅能为1或null
    accuPriceFactor选填0.1<=数值<=10
    wordPriceFactor选填0.1<=数值<=10
    widePriceFactor选填0.1<=数值<=10
    matchPriceStatus选填0:开启,要求精确系数>= 短语系数>= 广泛系数,
    且三个比例系数均不能为空;
    1:关闭

    返回信息(updateAdgroupResponse)

    属性名类型说明限制
    adgroupTypes AdgroupType[] 更新推广单元对象数组按照输入参数顺序返回AdgroupType[]数组,更新失败的单元不返回.

    代码示例

    • 请求

    更新某个计划下的单元:

    {
    "header":{
    	"opUsername":"searchlab",   			//mcc操作员账户名称
        "opPassword":"*********"        		//mcc操作员账户密码
        "tgUsername":"searchlab", 
        "tgPassword":"*********", 
        "tgSubname":"searchlab",				//mcc被操作的账户
        "bceUser":"014df051fa131234a2a*****" 	//mcc类型的bceuser
    },
    "body":{
        "adgroupTypes": [
            {
                "adgroupId": your_adgroup_id,
                "adgroupName": "adgroup_name",
                "maxPrice": "30",
                "pause": true,
                "priceRatio": NULL,
                "accuPriceFactor": 4,
                "wordPriceFactor": 3,
                "widePriceFactor": 2,
                "matchPriceStatus": 1,
                "status": 0
            }
        ]
      }
    }
    • 返回

    只返回用户更新的字段:

    {
        "header": {
            "desc": "success",
            "failures": [],
            "oprs": 1,
            "succ": 1,
            "oprtime": 0,
            "quota": used_quota_of_this_operation,
            "rquota": your_remain_quota,
            "status": 0
        },
        "body": {
            "data": [
                {
                    "adgroupId": your_adgroup_id,
                    "campaignId": your_campaign_id,
                    "adgroupName": "adgroup_name",
                    "maxPrice": 30,
                    "pause": true,
                    "status": 32,
                    "matchPriceStatus": 1,
                    "priceRatio": NULL
                }
            ]
        }
    }

    deleteAdgroup

    删除指定的单元(可批量)

    Json示意

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

    输入信息(deleteAdgroupRequest)

    属性名类型说明限制
    adgroupIds long[] - 单次请求不超过10000个,建议分批多次请求

    返回信息(deleteAdgroupResponse)

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

    代码示例

    • 请求

    删除两个单元:

    {
    "header":{
    	"opUsername":"searchlab",   			//mcc操作员账户名称
        "opPassword":"*********"        		//mcc操作员账户密码
        "tgUsername":"searchlab", 
        "tgPassword":"*********", 
        "tgSubname":"searchlab",				//mcc被操作的账户
        "bceUser":"014df051fa131234a2a*****" 	//mcc类型的bceuser
    },
    "body":{
        "adgroupIds": [
          adgroup_id_1,
          adgroup_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": [ ] } }

    上一篇
    NewCreativeService
    下一篇
    CreativeService