CampaignService
数据类型
CampaignType
请求参数:
参数名称 | 类型 | 说明 | 限制 |
---|---|---|---|
campaignId | Long | 推广计划id | - |
campaignName | String | 推广计划名称 | 长度限制:最大30个字节,1个中文按2个字节计算 |
budget | Double | 推广计划每日预算 | 默认为null:不限定预算,取值范围:[50, 10000000];当设置为周预算时,取值范围:[388, 70000000];当不设置预算时,输入任意值均默认为0; |
regionTarget | Integer[] | 推广地域列表 | 默认为null:不限定推广地域,默认使用账户推广地域可选地域对应代码见“地域代码” |
negativeWords | String[] | 否定关键词列表 | 默认为null:无否定词限制否定词长度:最大40字节,1个中文按2个字节计算数组元素个数最大值:200 |
exactNegativeWords | String[] | 精确否定关键词列表 | 默认为null:无精确否定关键词;精确否定词长度:最大40字节,1个中文按2个字节计算;数组元素个数最大值:200 |
schedule | ScheduleType[] | 推广暂停时段 | 默认为null: 无推广暂停时段限制。数组元素个数限制:每天可设置最多12个推广暂停时间,每周可设置最多84个推广暂停时间 |
budgetOfflineTime | OfflineTimeType[] | 到达预算下线时段 | 数组元素个数限制:最近有过下线时段的7个自然日的下线和上线时段(这7个自然日中若某日期距当前已超过30天,则不返回)null : 无到达预算下线时段。注:时间为date类型,格式示例”Jul 10, 2015 11:00:00 AM” |
showProb | Integer | 创意展现方式 | 默认值为1;取值范围:1 优选2 轮显 |
device | Integer | 计划的投放设备 | 选填,默认值为全部(包括计算机+移动设备);取值范围:0:全部(包括计算机+移动设备) |
priceRatio | Double | 计算机优先计划的无线出价比例 | bidprefer=1时取值范围:0.1<=数值<=10,默认值为1.0bidprefer=2时,无效字段,get请求返回默认值1 |
pcPriceRatio | Double | 移动优先计划的计算机出价比例 | 普通计划且bidprefer=2时生效取值范围:0<=数值<=10,默认值为1.0bidprefer=1时,无效字段,get请求返回默认值1 |
pause | Boolean | 暂停/启用推广计划 | 默认值为false;取值范围:true - 暂停;false - 启用 |
rmktStatus | Boolean | 启用/暂停混合再营销计划 | 默认值为true(仅支持混合再营销计划);取值范围:true – 启用false – 暂停 |
status | Integer | 推广计划状态 | 系统指定,客户端不可改变;取值范围:21-有效22-处于暂停时段23-暂停推广24-推广计划预算不足25-账户预算不足 |
campaignType | Integer | 计划类型 | 0:普通计划1:再营销计划2:混合再营销计划 |
bidPrefer | Integer | 出价优先 | 默认值:11:计算机优先2:移动优先所有计划都支持bidprefer,默认设置为1,仅m账户均设置为1, 非仅m账户的仅m计划是1 |
isDynamicCreative | Boolean | 子链开关 | True:开启False:关闭(默认开启) |
isDynamicTagSublink | Boolean | 标签子链开关 | True:开启False:关闭(默认开启) |
isDynamicTitle | Boolean | 动态标题开关 | True:开启False:关闭(默认开启) |
isDynamicHotRedirect | Boolean | 热点直达开关 | True:开启False:关闭(默认开启) |
rmktPriceRatio | Double | 混合再营销出价比例 | 仅campaignType=2时有效取值范围:[1.10,9.99] |
ScheduleType
该数据对象定义了推广计划设置的暂停时段。
参数名称 | 类型 | 说明 | 限制 |
---|---|---|---|
weekDay | int | 推广暂停时段日 | 以星期几为单位,7个值可供输入:1 - 星期一2 - 星期二3 - 星期三4 - 星期四5 - 星期五6 - 星期六7 - 星期日在updateCampaign接口中,该字段设置为空数组,即"schedule":[]表示清空原有暂停时段设置 |
startHour | long | 推广时段暂停开始时间 | 以小时为单位,取值范围:[0,23] |
endHour | long | 推广时段暂停结束时间 | 以小时为单位,取值范围:[1,24] |
OfflineTimeType
该数据对象定义了推广计划的到达预算下线时间段。
参数名称 | 类型 | 说明 | 限制 |
---|---|---|---|
flag | Int | 标识改时间点是发生了上线还是下线 | 1 - 上线0 - 下线 |
time | dateTime | 下线/上线时间点 | - |
接口描述
getCampaign
根据指定的计划id获取推广计划(id可批量) 。
Json示意
{
"campaignId":[***,***,…],"campaignFields":["campaignId","regionTarget","budgetOfflineTime",…]
}
输入信息(getCampaignRequest)
参数名称 | 类型 | 说明 | 限制 |
---|---|---|---|
campaignIds | Long[] | 指定的计划ID数组 | 必填。输入null返回整个账户的计划id |
campaignFields | String[] | 需要查询的计划属性 | 不请求的属性没有返回值,id信息必返。取值请参考表CampaignFields |
mobileExtend | int | 是否获取移动优先计划类型 | 0不获取;1 获取 默认为0不获取 |
计划字段(CampaignFields)
基本字段是每次必返的字段(不论用户传不传);复合字段是由多个简单属性组合的属性,用户请求会将这些简单字段打包返回;其余字段为简单字段,用户请求则返回。
字段名 | 说明 | 字段类型 |
---|---|---|
campaignId | 推广计划id | 基本字段 |
campaignName | 计划名 | - |
budget | 计划预算 | - |
campaignType | 计划类型 | - |
budgetOfflineTime | 最近7天预算撞线时间 | - |
device | 推广设备 | - |
exactNegativeWords | 精确否定关键词 | - |
isDynamicCreative | 子链开关 | - |
isDynamicTagSublink | 标签子链开关 | - |
isDynamicTitle | 动态标题开关 | - |
isDynamicHotRedirect | 热点直达开关 | - |
regionTarget | 计划推广地域 | - |
negativeWords | 计划否定关键词 | - |
pause | 计划启停 | - |
rmktStatus | 混合再营销计划启用/暂停 | - |
priceRatio | 无线出价比例 | - |
pcPriceRatio | 计算机出价比例 | - |
schedule | 循环暂停 | - |
showProb | 创意展现策略 | - |
status | 计划状态 | - |
rmktPriceRatio | 混合再营销出价比例 | - |
bidPrefer | 出价优先 | - |
返回信息(getCampaignResponse)
参数名称 | 类型 | 说明 | 限制 |
---|---|---|---|
campaignTypes | CampaignType[] | - | - |
代码示例
- 请求
获取计划的全部字段信息。
{
"header":{
"opUsername":"searchlab", //mcc操作员账户名称
"opPassword":"*********" //mcc操作员账户密码
"tgUsername":"searchlab",
"tgPassword":"*********",
"tgSubname":"searchlab", //mcc被操作的账户
"bceUser":"014df051fa131234a2a*****" //mcc类型的bceuser
},
"body":{
"campaignIds": [
campaign_id_1,
campaign_id_2
],
"campaignFields": [
"campaignName",
"budget",
"regionTarget",
"negativeWords",
"exactNegativeWords",
"schedule",
"budgetOfflineTime",
"showProb",
"pause",
"status",
"isDynamicCreative",
"campaignType",
"device",
"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, "campaignName": "campaign_name_1", "budget": 120, "regionTarget": [ 1000 ], "negativeWords": [ "nw2", "nw1" ], "exactNegativeWords": [ "enw1", "enw2" ], "schedule": [ { "startHour": 12, "endHour": 13, "weekDay": 1 } ], "budgetOfflineTime": [], "showProb": 1, "pause": false, "status": 21, "isDynamicCreative": true, "campaignType": 0, "device": 1, "priceRatio": 1 }, { "campaignId": campaign_id_2, "campaignName": "campaign_name_2", "budget": 240, "regionTarget": [ 1000 ], "negativeWords": [ "nw11", "nw22" ], "exactNegativeWords": [ "enw11", "enw22" ], "schedule": [ { "startHour": 9, "endHour": 17, "weekDay": 1 } ], "budgetOfflineTime": [], "showProb": 1, "pause": false, "status": 21, "isDynamicCreative": false, "campaignType": 0, "device": 1, "priceRatio": 1 } ] } }
addCampaign
新增推广计划,新增时可设置计划的属性设置(包含无线推广的属性设置)。 支持一次新增多个计划,每个账户下最多支持100个计划。 无效属性不返回,没有输入值的属性不返回。
Json示意
{
"campaignTypes":[{"campaignName":"***","budget":***,..},{..},..]
}
输入信息(addCampaignRequest)
参数名称 | 类型 | 说明 | 限制 |
---|---|---|---|
campaignTypes | CampaignType[] | 新增批量推广计划对象 | 参见下表 |
对addCampaignRequest对象的输入限制如下:
参数名称 | 类型 |
---|---|
campaignId | 无效 |
campaignName | 必填 |
budget | 选填;默认为NULL:不限制预算 |
regionTarget | 选填;默认为NULL:不设置地域;使用账户级别的地域设置 |
negativeWords | 选填;默认为NULL : 不设定否定词 |
exactNegativeWords | 选填;默认为NULL : 不设定精确否定词 |
schedule | 选填;默认为NULL:不设定投放暂停周期 |
budgetOfflineTime | 无效 |
showProb | 选填;默认为1 |
showProb | 选填;默认为1 |
device | 选填,默认为00:全部(计算机+移动设备) |
priceRatio | 选填, 当bidPrefer=1(无线出价比例) 时,参考取值范围; bidPrefer=2填1以外值均不合法 注意下仅m账户特殊逻辑 |
pcPriceRatio | 选填,当bidPrefer=2 (计算机出价比例)时,参考取值范围;bidPrefer=1时填1以为均不合法 |
pause | 选填,默认值为false |
status | 无效 |
campaignType | 无效 |
isDynamicCreative | 子链开关,默认为true |
isDynamicTagSublink | 标签子链开关,默认为true |
isDynamicTitle | 动态标题开关,默认为true |
isDynamicHotRedirect | 热点直达开关,默认为true |
bidPrefer | 选填,默认为1,仅能从1,2中选 |
返回信息(addCampaignResponse)
参数名称 | 类型 | 说明 | 限制 |
---|---|---|---|
campaignTypes | CampaignType[] | 按请求顺序返回添加成功的计划,添加失败的计划返回错误信息及位置 | - |
代码示例
-
请求 获取帐户的全部属性:
{ "header":{ "opUsername":"searchlab", //mcc操作员账户名称 "opPassword":"*" //mcc操作员账户密码 "tgUsername":"searchlab", "tgPassword":"*", "tgSubname":"searchlab", //mcc被操作的账户 "bceUser":"014df051fa131234a2a*" //mcc类型的bceuser }, "body":{ "campaignTypes": [ { "campaignName": "SEYCHELLES", "budget": 120, "regionTarget": [ 1000 ], "schedule": [ { "startHour": "12", "endHour": "13", "weekDay": "1" } ], "showProb": "1", "status": "0", "isDynamicCreative": true, "priceRatio": "1.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": [
{
"campaignId": new_campaign_id,
"campaignName": "SEYCHELLES",
"budget": 120,
"regionTarget": [
1000
],
"schedule": [
{
"startHour": 12,
"endHour": 13,
"weekDay": 1
}
],
"showProb": 1,
"status": 21,
"isDynamicCreative": true,
"priceRatio": 1
}
]
}
}
updateCampaign
根据指定的计划ID更新推广计划的属性 支持批量更新推广计划的属性,每账户最多100个计划。 不更新的属性,无返回值
Json示意
{
"campaignTypes":[{"campaignId":"***","campaignName":"***","budget":"***","regionTarget":***,"negativeWords":***,"exactNegativeWords":***,"schedule":***,"budgetOfflineTime":null,"showProb":null,"pause":null,"status":null,"isDynamicCreative":null,"campaignType":null,"device":"2","priceRatio":"1.0",…},{"campaignId":"***","campaignName":"***","budget":"***",…},…]
}
输入信息(updateCampaignRequest)
参数名称 | 类型 | 说明 | 限制 |
---|---|---|---|
campaignTypes | CampaignType[] | 新增批量推广计划对象 | 参见下表 |
对campaignTypes对象的输入限制如下:
参数名称 | 类型 |
---|---|
campaignId | 必填 |
campaignName | 选填;默认为NULL:不修改该属性 |
budget | 选填;默认为 NULL:不限制预算0:取消计划预算限制 |
regionTarget | 选填;默认为NULL:不设置地域;值为空数组:取消投放地域限制 |
negativeWords | 选填;默认为NULL : 不设定否定词;值为空数组:取消否定词 |
exactNegativeWords | 选填;默认为NULL : 不设定精确否定词;值为空数组:取消精确否定词 |
schedule | 选填;默认为NULL:不修改该属性;该字段设置为空数组,即"schedule":[]表示清空原有暂停时段设置 |
budgetOfflineTime | 无效,返回为null |
showProb | 选填;默认为NULL :不修改该属性 |
device | 无效字段 |
priceRatio | 选填, 当bidPrefer=1(无线出价比例) 时,参考取值范围; bidPrefer=2填1以外值均不合法 注意下仅m账户特殊逻辑 |
pcPriceRatio | 选填,当bidPrefer=2 (计算机出价比例)时,参考取值范围; bidPrefer=1时填1以为均不合法 |
pause | 选填,默认为NULL :不修改该属性 |
status | 无效 |
campaignType | 无效 |
isDynamicCreative | 选填,子链开关,默认为true |
isDynamicTagSublink | 选填,标签子链开关,默认为true |
isDynamicTitle | 选填,动态标题开关,默认为true |
isDynamicHotRedirect | 选填,热点直达开关,默认为true |
rmktStatus | 选填;仅campaignType=2时有效默认为NULL :不修改该属性 |
rmktPriceRatio | 选填;仅campaignType=2时有效取值范围:1.10<=数值<=9.99 |
返回信息(updateCampaignResponse)
参数名称 | 类型 | 说明 | 限制 |
---|---|---|---|
campaignTypes | CampaignType[] | 按请求顺序返回更新成功的计划,更新失败的计划不返回。 | - |
代码示例
- 请求
更新一个计划。
{
"header":{
"username":"your_username",
"password":"your_password",
"token":"your_token",
"target":"target_username"
},"body":{
"campaignTypes": [
{
"campaignId": your_campaign_id,
"campaignName": "Sipadan",
"regionTarget": [
2000
],
"schedule": [
{
"startHour": "1",
"endHour": "4",
"weekDay": "2"
}
],
"showProb": 2,
"status": 0,
"isDynamicCreative": false,
"priceRatio": 2.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": [ { "campaignId": 21199148, "campaignName": "Sipadan", "budget": 123, "regionTarget": [ 2000 ], "schedule": [ { "startHour": 1, "endHour": 4, "weekDay": 2 } ], "showProb": 2, "status": 23, "isDynamicCreative": false, "priceRatio": 2.0 } ] } }
deleteCampaign
删除指定的计划(可批量)
Json示意
{
"campaignIds":[***,***,***,…]
}
输入信息(deleteCampaignRequest)
参数名称 | 类型 | 说明 | 限制 |
---|---|---|---|
campaignIds | long[] | 需要删除的计划id | 必填 |
返回信息(deleteCampaignResponse)
参数名称 | 类型 | 说明 | 限制 |
---|---|---|---|
- | - | 删除失败的id查看错误提示 | Total返回删除成功的数量。 |
代码示例
- 请求
删除两个计划。
{
"header":{
"opUsername":"searchlab", //mcc操作员账户名称
"opPassword":"*********" //mcc操作员账户密码
"tgUsername":"searchlab",
"tgPassword":"*********",
"tgSubname":"searchlab", //mcc被操作的账户
"bceUser":"014df051fa131234a2a*****" //mcc类型的bceuser
},
"body":{
"campaignIds": [
campaign_id_1,
campaign_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": [ ] } }