CampaignService

更新时间：2019-06-14

数据类型

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.0 bidprefer=2时，无效字段，get请求返回默认值1
pcPriceRatio	Double	移动优先计划的计算机出价比例	普通计划且bidprefer=2时生效取值范围：0<=数值<=10，默认值为1.0 bidprefer=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	出价优先	默认值：1 1：计算机优先 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	选填，默认为0 0：全部（计算机+移动设备）
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": [ ] } }

服务访问地址

AccountService

搜索推广API

搜索推广API

CampaignService

数据类型

CampaignType

ScheduleType

OfflineTimeType

接口描述

getCampaign

addCampaign

updateCampaign

deleteCampaign