CampaignService
所有文档

          搜索推广API

          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.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