搜索推广API

    CreativeService

    数据类型

    CreativeType

    属性名类型说明限制
    creativeId Long创意id -
    adgroupId Long推广单元id -
    titleString创意标题长度限制:
    最大50个字节,最小9字节,1个中文按2个字节计算;
    通配符和断句符不计入
    description1 String创意描述第一行长度限制:
    最大80个字节,最小9字节,1个中文按2个字节计算;
    通配符和断句符不计入
    description2 String创意描述第二行长度限制:
    最大80个字节,1个中文按2个字节计算;
    通配符不计入;不可含有断句符;
    pcDestinationUrl String访问url 长度限制:
    不得超过1024个字符;
    域名需与账户网站域名相同
    pcDisplayUrl String显示url 长度限制:
    不得超过36个字符;
    域名需与账户网站域名相同
    mobileDestinationUrl String访问url 长度限制:
    不得超过1017个字符;
    域名需与账户网站域名相同
    mobileDisplayUrl String显示url 长度限制:
    不得超过36个字符;
    域名需与账户网站域名相同
    pause boolean 暂停/启用创意取值范围:
    true - 暂停;
    false - 启用
    status Integer创意状态取值范围:
    51-有效;
    52-暂停推广;
    53-不宜推广;
    54-待激活;
    55-审核中;
    56-部分无效;
    57-有效-移动url审核中。
    该属性由系统指定,客户端不可改变。
    说明:
    部分无效:投放设备为全部设备时,m物料审核未过,pc物料审核通过。
    涅槃将对外展示的一级状态。
    这种情况下api当前对外显示的是“部分无效”
    devicePreferenceInteger设备偏好0:整合型
    1:移动设备优先
    tabsInteger物料标签取值范围:0~5(0表示没标签)
    目前仅支持一个物料标签,即取数组第一个元素作为物料标签

    接口描述

    getCreative

    根据指定的单元id、创意id获取创意信息。

    Json示例

    {
    "ids":[***,***,…],"idType":7,"getTemp":0,"creativeFields":["creativeId","title","adgroupId","description1",…]
    }

    输入信息(getCreativeRequest)

    属性名类型说明限制
    creativeFieldsString[] 指定需要返回的创意属性请参考表CreativeFields
    idsLong[] 查询id集合;
    idType=5;类型为单元id,不超过1000个;
    idType=7,类型为创意id,不超过3000个
    必填;建议分批多次请求
    idTypeInteger5:单元id;7:创意id必填
    getTemp Integer是否查询创意影子选填,默认为0;
    0:只查询创意本身;
    1:只查询创意影子;
    想要获得创意的全集,
    需要调用该方法两次,
    分别为getTemp=0和getTemp=1
    offlinereasonsOfflineReason[]物料推广下线原因当有多个推广下线原因时,数组会有多个元素,每个代表一种原因

    说明: 影子是指:用户先向系统提交了创意A,然后又对A进行修改(例如修改url),修改后的创意为A’,在A'通过审核生效之前,线上的生效创意仍然为A。此时getTemp为0查询到的是A, getTemp为1查询到的是A’。

    offlinereasons
    该数据对象定义了推广下线原因

    属性 类型 说明
    mainReason String 推广下线主要原因id,值为”3”时,代表不宜推广
    detailReason String 推广下线具体原因,当mainReason为“3”时,本字段代表审核拒绝的具体原因 结构说明:detailReason为json字符串,解析后为嵌套数组,内层数组第一个元素为具体拒绝理由 处理说明:字符串先解析成外层json数组,取外层数组第一个元素json数组作为内层数组,取内层数组的第一个元素字符串 示例:"[["\"您提交的物料涉及不合规内容,可能涉及以下问题(物料文字不合规:前面有名词但不是主语),请修改提交内容\"",""]]";

    创意字段(CreativeFields)

    基本字段是每次必返的字段(不论用户传不传);复合字段是由多个简单属性组合的属性,用户请求会将这些简单字段打包返回;其余字段为简单字段,用户请求则返回。

    字段名说明字段类型
    creativeId创意id基本字段
    adgroupId推广单元id基本字段
    title创意标题-
    pause暂停/启用创意-
    status创意状态-
    description1创意描述第一行-
    description2创意描述第二行-
    pcDestinationUrlpc访问url-
    pcDisplayUrlpc显示url-
    mobileDestinationUrlmobile访问url-
    mobileDisplayUrlmobile显示url复合字段,包含如下CreativeType属性:mobileDisplayUrl ,pcDisplayUrl
    devicePreference设备偏好基本字段
    tabs物料标签-

    返回信息(getCreativeResponse)

    属性名类型说明
    creativeTypesCreativeType[]不请求的的属性(基础属性除外)无返回值

    代码示例

    • 请求 请求示例,按照创意id获取创意的所有字段信息: 若只需获取部分字段,只需填入需要获取的字段值;若需按单元id获取,请设置idType=5。

      { "header":{ "opUsername":"searchlab", //mcc操作员账户名称 "opPassword":"*" //mcc操作员账户密码 "tgUsername":"searchlab", "tgPassword":"*", "tgSubname":"searchlab", //mcc被操作的账户 "bceUser":"014df051fa131234a2a*" //mcc类型的bceuser }, "body":{ "ids": [ creative_id ], "idType": 7, "creativeFields": [ "adgroupId", "creativeId", "title", "description1", "description2", "pcDestinationUrl", "mobileDestinationUrl", "pcDisplayUrl", "mobileDisplayUrl", "pause", "status", "devicePreference" ] } }

    • 返回

      { "header": { "desc": "success", "failures": [], "oprs": 1, "succ": 1, "oprtime": 0, "quota": used_quota_of_this_operation, "rquota": your_remain_quota, "status": 0 }, "body": { "data": [ { "creativeId": creative_id, "adgroupId": adgroup_id, "title": "title", "description1": "description1", "description2": "description2", "destinationUrl": null, "displayUrl": null, "pause": false, "status": 55, "mobileDestinationUrl": "http://www.your_website.com/", "mobileDisplayUrl": "www.your_website.com/", "pcDestinationUrl": "http://www.your_website.com/", "pcDisplayUrl": "www.your_website.com/", "devicePreference": 0 } ] } }

    addCreative

    新增创意(可批量)。

    Json示例

    {
    "creativeTypes":[{"adgroupId":***,"title":***,…},{"adgroupId":***,"title":"***","description1":***,"description2":***,"pause":***,…},…]
    }

    输入信息(addCreativeRequest)

    属性名类型说明限制
    creativeTypes CreativeType[] 新增创意对象数组参见下表;单次请求不超过3000个;建议分批多次请求

    新增CreativeType[]的限制如下:

    属性名类型说明限制
    creativeId Long创意id 无效
    adgroupId Long推广单元id 必填
    title String创意标题必填
    description1 String创意描述第一行必填
    description2 String创意描述第二行选填
    pcDestinationUrlString访问url 1、若所属计划device=0 (即设备属性设置为“全部设备”),
    该属性为必填;
    2、若所属计划device=1(即设备属性设置为“仅移动设备”),
    该属性为无效属性
    pcDisplayUrlString显示url 1、若所属计划device=0(即设备属性设置为“全部设备”),
    该属性为选填,默认值为PcDestinationUrl的域名;
    2、若所属计划device=1(即设备属性设置为“仅移动设备”),
    该属性为无效属性
    mobileDestinationUrl String访问url
    1、若所属计划device=0(即设备属性设置为“全部设备”),
    该属性为选填;
    2、若所属计划device=1(即设备属性设置为“仅移动设备”),
    该属性为必填
    mobileDisplayUrl String显示url 1、若所属计划device=0(即设备属性设置为“全部设备”),
    该属性为选填,默认值为mobileDestinationUrl的域名;
    2、若所属计划device=1(即设备属性设置为“仅移动设备”),
    该属性为选填,默认值为mobileDestinationUrl的域名
    pause boolean 暂停/启用创意选填;默认为false
    status Integer创意状态无效属性
    devicePreferenceInteger设备偏好选填;
    0:整合型
    1:移动设备优先
    若device=1,则只能填1,默认为1
    若device=0,只能填0或者1,默认为0
    bidprefer=1时,两者均可,默认为0;
    bidprefer=2时,仅能为1
    tabsInteger物料标签(选填)
    取值范围:0~5(0表示没有添加物料标签)
    如果填入[],则表示没有添加标签,等同于标签为0
    目前仅支持一个物料标签,即取数组第一个元素作为物料标签

    返回信息(addCreativeResponse)

    属性名类型说明限制
    creativeTypes CreativeType[] 新增创意对象数组按请求顺序返回添加成功的创意,添加失败的创意返回错误信息及位置

    代码示例

    • 请求 在单元下添加一个创意:

      { "header":{ "opUsername":"searchlab", //mcc操作员账户名称 "opPassword":"*" //mcc操作员账户密码 "tgUsername":"searchlab", "tgPassword":"*", "tgSubname":"searchlab", //mcc被操作的账户 "bceUser":"014df051fa131234a2a*" //mcc类型的bceuser }, "body":{ "creativeTypes": [ { "adgroupId": your_adgroup_id, "title": "title", "description1": "description1", "description2": "description2", "pause": false, "pcDestinationUrl": "www.your_website.com/", "pcDisplayUrl": "www.your_website.com/", "mobileDestinationUrl": "www.your_website.com/", "mobileDisplayUrl": "www.your_website.com/", "status": 0, "devicePreference": 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": [ { "creativeId": new_creative_id, "adgroupId": your_adgroup_id, "title": "title", "description1": "description1", "description2": "description2", "pause": false, "status": 55, "mobileDestinationUrl": "http://www.your_website.com/", "mobileDisplayUrl": "www.your_website.com/", "pcDestinationUrl": "http://www.your_website.com/", "pcDisplayUrl": "www.your_website.com/", "devicePreference": 0 } ] } }

    updateCreative

    更新创意(可批量)。

    Json示例

    {
    "creativeTypes":[{"creativeId":***,"title":***,…},{"creativeId":***,"title":"***","pause":***,"description2":***,"mobileDisplayUrl":***,"pcDestinationUrl":"***",,…},…]
    }

    输入信息(updateCreativeRequest)

    属性名类型说明限制
    creativeTypes CreativeType[] 更新创意对象数组,不超过3000个参见下表;建议分批多次请求

    更新CreativeType[]的限制如下:

    属性名类型说明限制
    creativeId Long创意id 必填
    adgroupId Long 推广单元id 无效
    title String创意标题必填
    description1 String创意描述第一行必填
    description2 String创意描述第二行选填
    pcDestinationUrlString访问url1、若所属计划device=0(即设备属性设置为“全部设备”),
    该属性为必填;
    2、若所属计划device=1(即设备属性设置为“仅移动设备”),
    该属性为无效属性
    pcDisplayUrlString显示url1、若所属计划device=0(即设备属性设置为“全部设备”),该属性为选填,
    默认值为NULL:不更新该属性;
    2、若所属计划device=1(即设备属性设置为“仅移动设备”),
    该属性为无效属性
    mobileDestinationUrlString访问url1、若所属计划device=0(即设备属性设置为“全部设备”),
    该属性为选填;
    2、若所属计划device=1(即设备属性设置为“仅移动设备”),
    该属性为必填
    mobileDisplayUrlString显示url1、若所属计划device=0(即设备属性设置为“全部设备”),该属性为选填
    ,默认值为NULL:不更新该属性;
    2、若所属计划device=1(即设备属性设置为“仅移动设备”),该属性为选填,
    默认值为NULL:不更新该属性
    pause Boolean暂停/启用创意选填;默认值为NULL:不更新该属性
    status Integer创意状态无效属性
    devicePreferenceInteger设备偏好选填;
    若device=0,可以填0或者1;
    若device=1,只能填1。默认值为NULL:不更新该属性
    tabsInteger物料标签(选填)
    更新取值范围:0~5 (0表示清空标签)
    空数组[]表示清空标签,等同于标签id=0
    说明:如果客户打了多个标签,选第一个标签

    返回信息(updateCreativeResponse)

    属性名类型说明限制
    creativeTypes CreativeType[] 更新创意对象数组按输入顺序返回正确更新的
    CreativeType[]数组,更新失败的创意对象不返回。

    说明: 针对更新创意的九个有效字段:

    • creativeId 必填
    • 第一组:

      • title;组内必填
      • description1;组内必填
      • description2;组内必填
      • pcDestinationUrl;组内必填
      • pcDisplayUrl;组内选填
      • mobileDestinationUrl;组内必填
      • mobileDisplayUrl;组内选填
    • 第二组

      • pause;组内选填

    两组可以单独选一组来操作,也可以共同操作,但需要遵守“组内必填选填”规范

    代码示例

    • 请求 更新某个创意:

      { "header":{ "opUsername":"searchlab", //mcc操作员账户名称 "opPassword":"*" //mcc操作员账户密码 "tgUsername":"searchlab", "tgPassword":"*", "tgSubname":"searchlab", //mcc被操作的账户 "bceUser":"014df051fa131234a2a*" //mcc类型的bceuser }, "body":{ "creativeTypes": [ { "creativeId": your_creative_id, "title": "title", "description1": "description11", "description2": "description22", "pause": true, "pcDestinationUrl": "http://www.your_website.com/", "pcDisplayUrl": "www.your_website.com/", "mobileDestinationUrl": "http:/www.your_website.com/", "mobileDisplayUrl": "www.your_website.com/", "status": 0, "devicePreference": 1 } ] } }

    • 返回 只返回用户更新的字段信息:

      { "header": { "desc": "success", "failures": [], "oprs": 1, "succ": 1, "oprtime": 0, "quota": used_quota_of_this_operation, "rquota": your_remain_quota, "status": 0 }, "body": { "data": [ { "creativeId": your_creative_id, "adgroupId": your_adgroup_id, "title": "title", "description1": "description11", "description2": "description22", "pause": true, "status": 52, "mobileDestinationUrl": "http://www.your_website.com/", "mobileDisplayUrl": "www.your_website.com/", "pcDestinationUrl": "http://www.your_website.com/", "pcDisplayUrl": "www.your_website.com/", "devicePreference": 1 } ] } }

    deleteCreative

    删除指定的创意(可批量) 。

    Json示例

    {
              "creativeIds":[***,***,***,…]
    }

    输入信息(deleteCreativeRequest)

    属性名类型说明限制
    creativeIds Long[] - 单次请求不超过10000;建议分批多次请求

    返回信息(deleteCreativeResponse )

    属性名类型说明限制
    -删除失败的id查看错误提示Total返回删除成功的数量。

    代码示例

    • 请求 删除两个创意:

      { "header":{ "opUsername":"searchlab", //mcc操作员账户名称 "opPassword":"*" //mcc操作员账户密码 "tgUsername":"searchlab", "tgPassword":"*", "tgSubname":"searchlab", //mcc被操作的账户 "bceUser":"014df051fa131234a2a*" //mcc类型的bceuser }, "body":{ "creativeIds": [ creative_id_1, creative_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": [ ] } }

    上一篇
    AdgroupService
    下一篇
    KRService