搜索推广API

    AdgroupService

    更新时间：2019-08-08

    数据类型

    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