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-推广计划暂停推广,系统指定,客户端不可改变 |
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": [ ] } }