计划服务 (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
无