搜索推广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