搜狗首页  |   服务首页  |   客服热线:010-56898080

API参考  |  计划服务

计划服务 (CpcPlanService)

通过 CpcPlanService ,您可以管理您账户下的所有的推广计划。包括添加、删除、更新计划。例如,您可以修改某个计划的消费限额、设定 IP排除 、设定投放地区、更改计划名称、暂停 / 取消暂停计划等操作。每个推广下可以有一个或者多个推广组,对推广组的操作由 CpcPlanService 完成。

数据类型

属性名 类型 说明 限制
cpcPlanId Long 推广计划 id -
cpcPlanName String 推广计划名称 长度限制:最大 36 个字节, 1 个中文按 2 个字节计算
budget Double 推广计划每日预算 取值范围: >=50 && <=min(10000000, 账户预算 ) ;
NULL :无设置预算
regions Integer 投放地区列表 数组元素个数最大值:无
NULL : 无设置地区
excludeIps String ip 排除列表 无效属性
negativeWords String 否定关键词列表 否定词长度:最大 40 字节, 1 个中文按 2 个字节计算
NULL :无否定词限制
exactNegativeWords String 精确否定关键词列表 否定词长度:最大 40 字节, 1 个中文按 2 个字节计算
NULL :无精确否定词限制
schedule ScheduleType[] 推广暂停时段 数组元素无个数限制
NULL : 无限制
budgetOfflineTime OffLineType[] 到达预算下线时段 数组元素个数限制:最近有过下线时段的自然日的下线和上线时段
(若某日期距当前已超过 30天,则不返回)
注:时间为 date 类型,格式示例”2018-08-11T20:00:00.691+08:00”
showProb Integer 创意展现方式 无效属性
pause Boolean 暂停 / 取消暂停推广计划 取值范围:
true - 暂停
false - 取消暂停
默认值为 false
joinUnion Boolean 是否内容关联 取值范围:
true – 是
false – 否
默认值为 true
unionPrice Double 内容关联出价 无效属性
mobilePriceRate Double 移动设备价格比例 范围0.10到10.00,默认为1.00。
status Integer 推广计划状态 取值范围:
11---- 正常
12---- 暂停
13---- 计划预算撞线(且状态正常)
14---- 账户预算撞线
15---- 不在投放时段
opt Opt 可选字段 目前无效,用于扩展接口

ScheduleType 该数据对象定义了推广计划设置的暂停时段

属性名 类型 说明 限制
weekDay Integer 推广暂停时段日 以星期几为单位, 7 个值可供输入:
1 - 星期一
2 - 星期二
3 - 星期三
4 - 星期四
5 - 星期五
6 - 星期六
7 - 星期日
在 updateCpcPlan 接口中,该字段设置为 0 表示清空原有暂停时段设置
startHour Long 推广时段暂停开始时间 以小时为单位,取值范围 : [0,23]
endHour Long 推广时段暂停结束时间 以小时为单位,取值范围 : [1,24]

OfflineTimeType 对象定义了推广计划的到达预算下线时间段

属性名 类型 说明 限制
flag Integer 标识改时间点是发生了上线还是下线 1 - 上线
0 - 下线
time dateTime 下线 / 上线时间点

接口描述

getAllCpcPlanId

该方法获取 SOAPHeader 中 username 下所有的计划 ID 。
输入信息: getAllCpcPlanIdRequest ,无具体参数
返回信息: getAllCpcPlanIdResponse

属性名 类型 说明 限制
cpcPlanIdType CpcPlanIdType - -

cpcPlanIdType 对象定义如下:

属性名 类型 说明 限制
cpcPlanIds Long[] 计划 id 数组

getAllCpcPlan

获取 SOAPHeader 中 username 下所有的计划
输入信息: getAllCpcPlan

返回信息: getAllCpcPlanResponse

属性名 类型 说明 限制
cpcPlanTypes CpcPlanType [] - -

getCpcPlanByCpcPlanId

方法说明:根据指定的计划 id 获取推广计划 (id 可批量 )
输入信息: getCpcPlanByCpcPlanIdRequest

属性名 类型 说明 限制
cpcPlanIds Long[] 指定的计划 ID 数组 必填

返回信息: getCpcPlanByCpcPlanIdResponse

属性名 类型 说明 限制
cpcPlanTypes CpcPlanType[] - -

addCpcPlan

方法说明:新增推广计划 ( 可批量 )

通过 addCpcPlan() 方法,您可以在您的账户下添加新的推广计划。在调用该方法前,您首先需要构造 CpcPlanType 对象,并设置该对象的必要的属性。 ( 详情请见下面的 API 参考 ) 添加成功后,您可以获得新增推广计划的 id ,此 id 全局唯一。您可以根据此 id 对推广计划进行更新 / 删除操作。

输入信息: addCpcPlanRequest

属性名 类型 说明 限制
cpcPlanTypes CpcPlanType[] 新增推广计划对象数组 参见下表

新增 CpcPlanType [] 时,限制如下:

属性名 限制
cpcPlanId 无效
cpcPlanName 必填
budget 选填
默认为 NULL: 不设置预算
regions 选填
默认为 NULL: 不设置投放地区;使用账户级别的地区设置
excludeIps 无效属性
negativeWords 选填
默认为 NULL : 不设定否定词
exactNegativeWords 选填
默认为 NULL : 不设定精确否定词
schedule 选填
默认为 NULL: 不设定投放暂停周期
budgetOfflineTime 无效属性
showProb 无效属性
pause 选填
默认为 false
joinUnion 是否内容关联,默认为 true
unionPrice 无效属性
mobilePriceRate 范围0.10到10.00,默认为1.00。
status 无效属性
opt 扩展属性,暂时为无效属性

返回信息: addCpcPlanResponse

属性名 类型 说明
cpcPlanTypes CpcPlanType[] 按请求顺序返回全部计划,添加失败的计划的 id 置 0 。

updateCpcPlan

方法说明 :更新推广计划 ( 可批量 )

通过 updateCpcPlan() 方法,您可以更新除 cpcPlanId 和 status 属性的外的任何一个属性。在调用该方法前,您需要首先构造一个 CpcPlanType 对象。设置该对象的属性为您所需要的值,然后把该对象传递给 updateCpcPlan() 方法即可。如果您在一次请求中,不想更新推广组的某些属性 ( 如 cpcPlanName 、投放地区等 ) ,可把这些属性置为 NULL 即可。服务器端会忽略属性值为 NULL 的更新。

输入信息: updateCpcPlanRequest

属性名 类型 说明 限制
cpcPlanTypes CpcPlanType[] 更新推广计划对象数组 参见下表

更新 CpcPlanType [] 时,限制如下:

属性名 限制
cpcPlanId 必填
cpcPlanName 选填
默认为 NULL: 不修改该属性
budget 选填
默认为 NULL: 不修改该属性
0 :取消计划预算限制
regions 选填
默认为 NULL: 不修改该属性
值为 0( 数组仅 1 个元素 , 且为 0) :取消投放地域限制
excludeIps 无效属性
negativeWords 选填
默认为 NULL : 不修改该属性
值为 $( 数组仅 1 个元素 , 且为 $) :取消否定词
exactNegativeWords 选填
默认为 NULL : 不修改该属性
值为 $( 数组仅 1 个元素 , 且为 $) :取消精确否定词
schedule 选填
默认为 NULL : 不修改该属性
数组仅 1 个元素 , 且该元素的 weekDay 为 0 :取消暂停时段
budgetOfflineTime 无效属性 , 返回为 null
showProb 选填
默认为 NULL : 不修改该属性
pause 选填
默认为 NULL : 不修改该属性
joinUnion 是否内容关联
unionPrice 无效属性
mobilePriceRate 选填,默认为NULL,表示不更新。
status 无效属性
opt 扩展字段,暂时为无效属性

返回信息: updateCpcPlanResponse

属性名 类型 说明
cpcPlanTypes CpcPlanType[] 按请求顺序返回更新成功的计划,更新失败的计划不返回。

deleteCpcPlan

方法说明:删除指定的计划 ( 可批量 )

通过 deleteCpcPlan() 方法,您可以删除您账户下的一个或者多个推广计划。推广计划被删除后,其名下的推广组、关键词、创意数据均会被同时删除。

输入信息: deleteCpcPlanRequest

属性名 类型 说明 限制
cpcPlanIds Long[] - 必填

返回信息: deleteCpcPlanResponse