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-推广计划暂停推广，系统指定，客户端不可改变
priceRatio	Double	单元移动出价比例	bidprefer=1有效值范围：[0.1~10] ，默认为1 bidprefer=2时仅能为默认值null；
pcPriceRatio	Double	单元计算机出价比例	bidprefer=2取值范围：0<=数值<=10，默认值为1 bidprefer=1时仅能为默认值null
accuPriceFactor	Double	精确出价比例	0.1<=数值<=10，默认值为1.0
wordPriceFactor	Double	短语出价比例	0.1<=数值<=10，默认值为1.0
widePriceFactor	Double	广泛出价比例	0.1<=数值<=10，默认值为1.0
matchPriceStatus	Integer	分匹配状态	0：开启，要求精确系数>= 短语系数>= 广泛系数，且三个比例系数均不能为空， 1：关闭

接口描述

getAdgroup

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

Json示意：

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

输入信息(getAdgroupRequest)

属性名	类型	说明	限制
adgroupFields	String[]	指定需要返回的单元属性	不请求的属性没有返回值，取值请参考表adgroupFields
ids	Long[]	查询id集合	idType=5；类型为单元id，不超过5000个； idType=3，类型为计划id，不超过100个；必填；建议分批多次请求
idType	Integer	3：计划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

搜索推广API

搜索推广API

AdgroupService

数据类型

AdgroupType

接口描述

getAdgroup

addAdgroup

updateAdgroup

deleteAdgroup