更新广告组

开发环境

POST

/v1.3/adgroups/update

完整的参数信息请参考：https://developers.e.qq.com/docs/api/adsmanagement/adgroups/adgroups_update?version=1.3&_preview=1

使用说明

对于朋友圈广告（campaign_type= CAMPAIGN_TYPE_WECHAT_ MOMENTS），一旦广告审核通过且当前时间大于广告投放起始时间，则只允许修改 adgroup 模块的 adgroup_name（广告组名称）、targeting（定向）、bid_amount（出价）、daily_budget（日预算）、configured_status（启用/暂停状态）、end_date（结束投放日期）、time_series（投放时间段）以及 ad 模块的所有属性，广告组其他属性及相关创意模块的所有属性均不允许修改。

targeting 和 targeting_id 不能同时填写，朋友圈广告只允许使用 targeting。

针对朋友圈广告（campaign_type = CAMPAIGN_TYPE_WECHAT_MOMENTS），仅支持以下定向：地域（geo_location）、年龄（age）、性别（gender）、学历（education）、婚恋育儿状态（marital_status）、应用安装（app_install_status）、自定义人群（custom_audience）、排除自定义人群（excluded_custom_audience）、操作系统（user_os）、联网方式（network_type）、移动运营商（network_operator）、设备价格（device_price）、再营销（原微信广告行为定向 wechat_ad_behavior）、行为兴趣意向定向（behavior_or_interest）、设备品牌型号定向（device_brand_model）、游戏付费能力（game_consumption_level）。

地理位置定向的省市区县以及商圈 id、行为兴趣意向定向、微信公众号类型定向、移动媒体类型定向的可选值列表可通过 targeting_tags/get 接口进行获取。

DPA 广告功能灰度开放，如有接入需求，请联系对接渠道运营同事线下进行申请。

非微信朋友圈广告的日预算（daily_budget）设置仅灰度开放，如有接入需求，请联系对接渠道运营同事线下进行申请。

非微信朋友圈广告的系统优选（auto_audience）设置仅灰度开放，如有接入需求，请联系对接渠道运营同事线下进行申请。

请求示例

Shell

JavaScript

Java

Swift

curl --location --request POST '/v1.3/adgroups/update' \
--header 'access_token;' \
--header 'timestamp;' \
--header 'nonce;' \
--data-urlencode 'account_id=<ACCOUNT_ID>' \
--data-urlencode 'adgroup_id=<ADGROUP_ID>' \
--data-urlencode 'adgroup_name=推广广告' \
--data-urlencode 'begin_date=2017-04-25' \
--data-urlencode 'end_date=2017-05-01' \
--data-urlencode 'bid_amount=200' \
--data-urlencode 'optimization_goal=OPTIMIZATIONGOAL_CLICK' \
--data-urlencode 'time_series=010100100110100010101010010101010101010100101010101010010101010101001010101010100101010101010111110010101001010110110100110001011001010100101010101010110011001010101010100101100101101110101010101010100110100110010100110101110111101110110110110110110110101101101101110110011101011101101011101101101101001010110111010111011010110110111011' \
--data-urlencode 'daily_budget=10000' \
--data-urlencode 'targeting_id=111111111' \
--data-urlencode 'scene_spec={"mobile_union":["MOBILE_UNION_IN_WECHAT"]}' \
--data-urlencode 'configured_status=AD_STATUS_NORMAL' \
--data-urlencode 'customized_category=本地生活,餐饮' \
--data-urlencode 'additional_user_action_sets=[]' \
--data-urlencode 'cold_start_audience=[1024]' \
--data-urlencode 'expand_enabled=false' \
--data-urlencode 'expand_targeting=[]' \
--data-urlencode 'deep_conversion_spec={"deep_conversion_type":"DEEP_CONVERSION_BEHAVIOR","deep_conversion_behavior_spec":{"bid_amount":200}}' \
--data-urlencode 'poi_list=[]' \
--data-urlencode 'bid_adjustment={
    "site_set_package": [
        {
            "site_set": [
                "SITE_SET_QZONE"
            ]
        }
    ],
    "region_group_package": [
        {
            "region_list": []
        }
    ]
}' \
--data-urlencode 'user_action_sets=[]' \
--data-urlencode 'custom_adgroup_tag=[]' \
--data-urlencode 'smart_targeting={
    "start_audience": [],
    "unbreakable_targeting": {
        "age": [],
        "gender": [],
        "geo_location": {
            "location_types": [],
            "regions": [],
            "business_districts": [],
            "custom_locations": []
        },
        "user_os": [],
        "app_install_status": [],
        "excluded_converted_audience": {
            "conversion_behavior_list": []
        }
    }
}' \
--data-urlencode 'dynamic_creative_id_set=[]'

响应示例

{
    "code": 0,
    "message": "",
    "message_cn": "",
    "data": {
        "adgroup_id": "<ADGROUP_ID>"
    }
}

请求参数

Header 参数

access_token

string

必需

以Query Parameter方式在请求路径中传递。授权令牌，完成 OAuth 2.0 授权后获得，参考授权认证章节。

默认值:

<ACCESS_TOKEN>

timestamp

string

必需

以Query Parameter方式在请求路径中传递。当前的时间戳，单位为秒，允许客户端请求最大时间误差为300秒。
MarketingAPI 所使用的时间戳，若无特殊说明，均为秒级时间戳
MarketingAPI 所使用的时区为GMT+8，例如当时间戳为1494840119时，表示 2018-05-15 17:21:59

默认值:

nonce

string

必需

以Query Parameter方式在请求路径中传递。随机字串标识，不超过32个字符，由调用方自行生成，需保证全局唯一性。

默认值:

<NONCE>

Body 参数application/x-www-form-urlencoded

account_id

integer

必需

广告主帐号 id，有操作权限的帐号 id，不支持代理商 id

示例值:

<ACCOUNT_ID>

adgroup_id

integer

广告组 id

必需

示例值:

<ADGROUP_ID>

adgroup_name

string

可选

广告组名称，同一帐号下的广告组名称不允许重复。字段长度最小 1 个等宽字符，长度最大 60 等宽字符（即字段最大长度为 60 个中文字或全角标点，120 个英文字或半角标点。一个等宽字符等价于一个中文，等价于两个英文。）
字段长度最小 1 字节，长度最大 180 字节

示例值:

推广广告

begin_date

string

可选

开始投放日期，日期格式：YYYY-MM-DD，且日期小于等于 end_date
字段长度为 10 字节

示例值:

2017-04-25

end_date

string

可选

结束投放日期，日期格式：YYYY-MM-DD，大于等于今天，且大于等于 begin_date ；如果希望长期投放，传空字符串；针对微信流量的更新 end_time 的场景，会有额外的规则（更新后的 end_time 至少是当前时间的 6h 之后且当前更新时间到 end_time 与投放时段有交集）
字段长度最小 0 字节，长度最大 10 字节

示例值:

2017-05-01

bid_amount

integer

可选

广告出价，单位为分，出价限制：
CPC 出价限制：介于 10 分-10,000 分之间（0.1 元-100 元，单位为人民币）
CPM 出价限制：介于 150 分-99,900 分之间（1.5 元-999 元，单位为人民币，当 SITE_SET 仅为 SITE_SET_PCQQ 时，介于 50 分-99,900 分之间）
CPA 出价限制：介于 100 分-50,000 分之间（1 元-500 元，单位为人民币）
oCPC/oCPM 出价限制：介于 1 分-500,000 分之间（0.01 元-5000 元，单位为人民币）

示例值:

200

optimization_goal

string

可选

广告优化目标类型。目前部分优化目标灰度开放中，详情可查看：https://developers.e.qq.com/docs/guide/ads/ocpa
可投放的优化目标组合可通过 optimization_goal_permissions/get 接口查询；
微信流量不允许更改优化目标，非微信流量仅允许在 CPC 切换 oCPC，CPM 切换 oCPM 时更改优化目标，[枚举详情]
枚举列表：{ OPTIMIZATIONGOAL_NONE, OPTIMIZATIONGOAL_BRAND_CONVERSION, OPTIMIZATIONGOAL_FOLLOW, OPTIMIZATIONGOAL_CLICK, OPTIMIZATIONGOAL_IMPRESSION, OPTIMIZATIONGOAL_APP_DOWNLOAD, OPTIMIZATIONGOAL_APP_ACTIVATE, OPTIMIZATIONGOAL_APP_REGISTER, OPTIMIZATIONGOAL_ONE_DAY_RETENTION, OPTIMIZATIONGOAL_APP_PURCHASE, OPTIMIZATIONGOAL_ECOMMERCE_ORDER, OPTIMIZATIONGOAL_ECOMMERCE_CHECKOUT, OPTIMIZATIONGOAL_LEADS, OPTIMIZATIONGOAL_ECOMMERCE_CART, OPTIMIZATIONGOAL_PROMOTION_CLICK_KEY_PAGE, OPTIMIZATIONGOAL_VIEW_COMMODITY_PAGE, OPTIMIZATIONGOAL_ONLINE_CONSULTATION, OPTIMIZATIONGOAL_TELEPHONE_CONSULTATION, OPTIMIZATIONGOAL_PAGE_RESERVATION, OPTIMIZATIONGOAL_DELIVERY, OPTIMIZATIONGOAL_MESSAGE_AFTER_FOLLOW, OPTIMIZATIONGOAL_CLICK_MENU_AFTER_FOLLOW, OPTIMIZATIONGOAL_PAGE_EFFECTIVE_ONLINE_CONSULT, OPTIMIZATIONGOAL_PAGE_EFFECTIVE_PHONE_CALL, OPTIMIZATIONGOAL_CONFIRM_EFFECTIVE_LEADS_CONSULT, OPTIMIZATIONGOAL_CONFIRM_EFFECTIVE_LEADS_PHONE, OPTIMIZATIONGOAL_LEADS_COLLECT, OPTIMIZATIONGOAL_FIRST_PURCHASE, OPTIMIZATIONGOAL_APPLY, OPTIMIZATIONGOAL_PRE_CREDIT, OPTIMIZATIONGOAL_CREDIT, OPTIMIZATIONGOAL_WITHDRAW_DEPOSITS, OPTIMIZATIONGOAL_PROMOTION_VIEW_KEY_PAGE, OPTIMIZATIONGOAL_MOBILE_APP_CREATE_ROLE, OPTIMIZATIONGOAL_CANVAS_CLICK, OPTIMIZATIONGOAL_PROMOTION_CLAIM_OFFER, OPTIMIZATIONGOAL_ECOMMERCE_ADD_TO_WISHLIST, OPTIMIZATIONGOAL_CONFIRM_EFFECTIVE_LEADS_RESERVATION, OPTIMIZATIONGOAL_PAGE_RECEIPT, OPTIMIZATIONGOAL_PAGE_SCAN_CODE, OPTIMIZATIONGOAL_SELECT_COURSE, OPTIMIZATIONGOAL_CONFIRM_POTENTIAL_CUSTOMER_PHONE, OPTIMIZATIONGOAL_MOBILE_APP_AD_INCOME, OPTIMIZATIONGOAL_MOBILE_APP_ACCREDIT, OPTIMIZATIONGOAL_PURCHASE_MEMBER_CARD, OPTIMIZATIONGOAL_PAGE_CONFIRM_EFFECTIVE_LEADS, OPTIMIZATIONGOAL_ADD_DESKTOP, OPTIMIZATIONGOAL_RESERVATION, OPTIMIZATIONGOAL_FIRST_ECOMMERCE_ORDER, OPTIMIZATIONGOAL_FIRST_TWENTY_FOUR_HOUR_ECOMMERCE_ORDER, OPTIMIZATIONGOAL_ECOMMERCE_SCANCODE_WX, OPTIMIZATIONGOAL_CLASS_PARTICIPATED, OPTIMIZATIONGOAL_INSURANCE_PURCHASE, OPTIMIZATIONGOAL_MOBILE_APP_SEVEN_DAYS_RETENTION, OPTIMIZATIONGOAL_LIKE, OPTIMIZATIONGOAL_EXTERNAL_LINK_CLICK, OPTIMIZATIONGOAL_BUY_COUPONS, OPTIMIZATIONGOAL_LEAVE_INFORMATION, OPTIMIZATIONGOAL_CORE_ACTION, OPTIMIZATIONGOAL_ONE_DAY_RETENTION_RATIO, OPTIMIZATIONGOAL_PROMOTION_READ_ARTICLE, OPTIMIZATIONGOAL_RESERVATION_CHECK, OPTIMIZATIONGOAL_OPEN_ACCOUNT, OPTIMIZATIONGOAL_SEVEN_DAY_ECOMMERCE_ORDER, OPTIMIZATIONGOAL_ADD_WECHAT, OPTIMIZATIONGOAL_WECOM_CONSULT, OPTIMIZATIONGOAL_ADD_GROUP, OPTIMIZATIONGOAL_QUICK_ORDER, OPTIMIZATIONGOAL_PRE_PAY, OPTIMIZATIONGOAL_PAGE_ONLINE_CONSULT_ACTIVE_ONE_MSG, OPTIMIZATIONGOAL_CALL_DURATION_THIRTY_SECONDS, OPTIMIZATIONGOAL_CLAIM_COURSE, OPTIMIZATIONGOAL_QUIT_GROUP, OPTIMIZATIONGOAL_VIEW_ACQUISITION_CONTENT, OPTIMIZATIONGOAL_BACK_FLOW, OPTIMIZATIONGOAL_PAGE_ONLINE_CONSULT_THREE_MSG, OPTIMIZATIONGOAL_RENEWAL, OPTIMIZATIONGOAL_LOW_PRICE_COURSE, OPTIMIZATIONGOAL_CONSULT_INTENTION, OPTIMIZATIONGOAL_EVERY_DAY_RETENTION, OPTIMIZATIONGOAL_PROMOTION_VIEW_KEY_PAGE_UV, OPTIMIZATIONGOAL_LIVE_STREAM_DURATION_1MIN, OPTIMIZATIONGOAL_LIVE_STREAM_INTERACTION, OPTIMIZATIONGOAL_ECOMMERCE_CANCEL_ORDER }

示例值:

OPTIMIZATIONGOAL_CLICK

time_series

string

可选

投放时间段，格式为 48 * 7 位字符串，且都为 0 和 1，以半个小时为最小粒度，从周一零点开始至周日 24 点结束。0 为不投放，1 为投放，全传 1 视为全时段投放，不允许全部传 0。
字段长度为 336 字节

示例值:

010100100110100010101010010101010101010100101010101010010101010101001010101010100101010101010111110010101001010110110100110001011001010100101010101010110011001010101010100101100101101110101010101010100110100110010100110101110111101110110110110110110110101101101101110110011101011101101011101101101101001010110111010111011010110110111011

daily_budget

integer

可选

广告组日预算，单位为分，设置为 0 表示不设预算（即不限），
日预算要求介于 5,000 分– 4,000,000,000 分之间（50 元-40,000,000 元，单位为人民币）

对于微信朋友圈广告（campaign_type=CAMPAIGN_TYPE_WECHAT_MOMENTS 或 site_set=SITE_SET_MOMENTS）：

修改日预算不能低于该广告组今日已消耗金额的 1.5 倍
每次修改幅度不能低于当前日预算加上 5000 分（50 元，单位为人民币）

对于非微信朋友圈广告（campaign_type!=CAMPAIGN_TYPE_WECHAT_MOMENTS 且 site_set!=SITE_SET_MOMENTS）：

修改后的日预算不能低于该广告组今日已消耗金额加上 5,000 分（50 元，单位为人民币）
每次修改幅度不能低于当前日预算加上 5,000 分（50 元，单位为人民币）

示例值:

10000

targeting_id

string

可选

定向包 id，与 targeting 不能同时填写且不能同时为空，（当 campaign_type=CAMPAIGN_TYPE_NORMAL 时可以使用定向包能力）

示例值:

111111111

scene_spec

string

场景定向

可选

示例值:

{"mobile_union":["MOBILE_UNION_IN_WECHAT"]}

configured_status

string

可选

客户设置的状态，[枚举详情]
枚举列表：{ AD_STATUS_NORMAL, AD_STATUS_SUSPEND }
默认值：该字段默认值 AD_STATUS_NORMAL

示例值:

AD_STATUS_NORMAL

customized_category

string

可选

自定义分类，关键词用半角逗号','分隔，如：本地生活,餐饮
字段长度最小 0 字节，长度最大 200 字节

示例值:

本地生活,餐饮

additional_user_action_sets

string

可选

补充的 app 用户行为数据源，字段待废弃。
当 promoted_object_type 为 PROMOTED_OBJECT_TYPE_ECOMMERCE、PROMOTED_OBJECT_TYPE_LINK、PROMOTED_OBJECT_TYPE_QQ_BROWSER_MINI_PROGRAM，且行业为网服、电商、金融的广告主，可填写补充的 app 用户行为数据源。数据源需为安卓/ios 数据源，且需确保为同一个 app 的数据源。
数组最小长度 0，最大长度 100

示例值:

[]

cold_start_audience

integer

可选

扩量种子人群（原冷启动人群名称升级扩量种子人群）
1、系统会学习您选择的人群包数据，帮助提升广告投放效果；
2、当且仅当广告为 oCPC/oCPM 开启自动扩量的广告、且投放的流量不是应用宝时；
3、仅支持人群类型为 CUSTOMER_FILE（号码文件人群）的可用人群 id、且人群数量大于 100 时；
数组最大长度 10

示例值:

[1024]

expand_enabled

string

可选

是否使用自动扩量，当广告为 oCPC/oCPM、CPC 出价时，可将 expand_enabled 设置为 true，微信广告当且仅当出价为 oCPC/oCPM 时，才可将 expand_enabled 设置为 true。2022 年 6 月 30 日起，自动扩量无法与行为兴趣意向、“二方人群”人群包同时使用，expand_enabled 设置为 true, 开启自动扩量
可选值：{ true, false }

示例值:

false

expand_targeting

string

可选

扩量不可突破定向，如果使用 oCPC/oCPM，会在 oCPC/oCPM 扩量定向的范围内寻找相似人群，原 targeting 接口传入的定向将失效。当且仅当 expand_enabled 设置为 true 时，expand_targeting 才可填写，且为必填。
目前仅支持年龄、性别、地域、学历（不可突破学历仅教育行业可使用）定向设置为不可突破（前置需要定向 targeting 层级使用了年龄、性别、地域、学历时不可突破才可以选择相对应的值）。
数组最小长度 0，最大长度 4
可选值：{ age, gender, geo_location, education }

示例值:

[]

deep_conversion_spec

string

可选

oCPC/oCPM 深度优化内容，oCPC/oCPM 深度优化内容，创建时若此字段不传，或传空则视为无限制条件；
深度优化不可取消，也不支持在编辑环节从未使用深度优化切换为使用深度优化。

示例值:

{"deep_conversion_type":"DEEP_CONVERSION_BEHAVIOR","deep_conversion_behavior_spec":{"bid_amount":200}}

poi_list

string

可选

门店 id 列表,

推广目标类型 PROMOTED_OBJECT_TYPE_LOCAL_ADS_WECHAT，非朋友圈版位，使用 promoted_object_id 来表示门店 id，不能清空；

推广目标类型 PROMOTED_OBJECT_TYPE_LOCAL_ADS_WECHAT，朋友圈版位，使用 poi_list 来表示门店 id，不能清空；

其他推广目标下，使用 poi_list 来表示门店信息，可以清空；，最多可输入 100 个门店
数组最小长度 0，最大长度 500
字段长度最小 0 字节，长度最大 64 字节

示例值:

[]

bid_adjustment

string

可选

出价系数设置内容，仅当投放 oCPC、oCPM 广告时可使用，编辑广告时，分版位功能仅支持出价系数的变更，分城市出价支持城市包和出价系数的变更，转化价值分层出价能力仅支持出价系数的变更。

示例值:

{ "site_set_package": [ { "site_set": [ "SITE_SET_QZONE" ] } ], "region_group_package": [ { "region_list": [] } ] }

user_action_sets

string

可选

用户行为数据源，详见 [转化归因功能]，当 promoted_object_type 为 PROMOTED_OBJECT_TYPE_LEAD_AD、PROMOTED_OBJECT_TYPE_ECOMMERCE、PROMOTED_OBJECT_TYPE_LINK 时，允许传入 WEB + iOS + Android 数据源；当 promoted_object_type 为 PROMOTED_OBJECT_TYPE_APP_ANDROID 时，至少选择一个安卓数据源，可同时使用 web 数据源；当 promoted_object_type 为 PROMOTED_OBJECT_TYPE_APP_IOS 时，至少选择一个 ios 数据源，可同时使用 web 数据源。
数组最小长度 1，最大长度 100

示例值:

[]

custom_adgroup_tag

string

可选

广告标签：广告主可传输多个字符串用于对广告进行标注。标注内容对广告投放无影响，仅用于广告管理。
数组最小长度 0，最大长度 10
字段长度最小 0 字节，长度最大 1024 字节

示例值:

[]

smart_targeting

string

可选

智能定向功能,功能灰度开放，如需使用可联系您的运营接口同学。
智能定向功能与自动扩量/系统优选相关字段不可同时设置。2022 年 6 月 30 日起，智能定向无法与行为兴趣意向、“二方人群”人群包同时使用

示例值:

{ "start_audience": [], "unbreakable_targeting": { "age": [], "gender": [], "geo_location": { "location_types": [], "regions": [], "business_districts": [], "custom_locations": [] }, "user_os": [], "app_install_status": [], "excluded_converted_audience": { "conversion_behavior_list": [] } } }

dynamic_creative_id_set

integer

可选

DC 动态创意 id 集合
数组最小长度 1，最大长度 20

示例值:

[]

返回响应

🟢200成功

application/json

Body

code

integer

必需

message

string

必需

message_cn

string

必需

data

object

必需

adgroup_id

string

广告组 id

必需

修改于 2023-11-06 02:26:27

创建广告组

获取广告组