获取广告组
全部接口
V1.1
loading

所属权限	Ads Management,Ads Insights
请求地址	adgroups/get
请求方法	get

全局参数

全局参数是指每一个接口都需要使用到的参数。详情参考，代码案例参考。

参数名称	参数类型
access_token	授权令牌，完成 OAuth 2.0 授权后获得，参考授权认证章节
timestamp	当前的时间戳，单位为秒，允许客户端请求最大时间误差为 300 秒。 MarketingAPI 所使用的时间戳，若无特殊说明，均为秒级时间戳 MarketingAPI 所使用的时区为 GMT+8，例如当时间戳为 1494840119 时，表示 2017-05-15 17:21:59
nonce	随机字串标识，不超过 32 个字符，由调用方自行生成，需保证全局唯一性
fields	get 接口增加 fields 字段，用于指定返回参数的字段列表，为选填字段。fields 取值范围为 get 接口返回的 list 中的字段。如不填写，则根据默认值进行返回

请求参数

标有*的参数为必填项

名称	类型	描述
account_id*	integer	广告主帐号 id，有操作权限的帐号 id，不支持代理商 id
filtering	struct[]	过滤条件，若此字段不传，或传空则视为无限制条件，详见 [过滤条件] 数组最小长度 1，最大长度 6
field*	string	过滤字段可选值：{ adgroup_id, configured_status, adgroup_name, campaign_id, promoted_object_type, ad_count, created_time, last_modified_time, product_mode, product_source, union_package_id, exclude_union_package_id, ad_num, dynamic_ad_type, status, auto_derived_creative_status }
operator*	enum	操作符当 field 取值 adgroup_id 时，枚举列表：{ EQUALS, IN } 当 field 取值 configured_status 时，枚举列表：{ EQUALS } 当 field 取值 adgroup_name 时，枚举列表：{ EQUALS, CONTAINS } 当 field 取值 campaign_id 时，枚举列表：{ EQUALS } 当 field 取值 promoted_object_type 时，枚举列表：{ EQUALS } 当 field 取值 ad_count 时，枚举列表：{ EQUALS, LESS_EQUALS, LESS, GREATER_EQUALS, GREATER } 当 field 取值 created_time 时，枚举列表：{ EQUALS, LESS_EQUALS, LESS, GREATER_EQUALS, GREATER } 当 field 取值 last_modified_time 时，枚举列表：{ EQUALS, LESS_EQUALS, LESS, GREATER_EQUALS, GREATER } 当 field 取值 product_mode 时，枚举列表：{ EQUALS } 当 field 取值 product_source 时，枚举列表：{ EQUALS } 当 field 取值 union_package_id 时，枚举列表：{ EQUALS, IN } 当 field 取值 exclude_union_package_id 时，枚举列表：{ EQUALS, IN } 当 field 取值 ad_num 时，枚举列表：{ EQUALS } 当 field 取值 dynamic_ad_type 时，枚举列表：{ EQUALS } 当 field 取值 status 时，枚举列表：{ EQUALS } 当 field 取值 auto_derived_creative_status 时，枚举列表：{ EQUALS }
values*	string[]	字段取值，values 数组的个数限制与 operator 的取值相关，详见 [过滤条件] 当 field 取值 configured_status 时，枚举列表：{ AD_STATUS_NORMAL, AD_STATUS_SUSPEND } 当 field 取值 adgroup_name 时，字段长度最小 1 字节，长度最大 180 字节当 field 取值 promoted_object_type 时，枚举列表：{ PROMOTED_OBJECT_TYPE_APP_ANDROID, PROMOTED_OBJECT_TYPE_APP_IOS, PROMOTED_OBJECT_TYPE_ECOMMERCE, PROMOTED_OBJECT_TYPE_LINK_WECHAT, PROMOTED_OBJECT_TYPE_APP_ANDROID_MYAPP, PROMOTED_OBJECT_TYPE_APP_ANDROID_UNION, PROMOTED_OBJECT_TYPE_LOCAL_ADS_WECHAT, PROMOTED_OBJECT_TYPE_QQ_BROWSER_MINI_PROGRAM, PROMOTED_OBJECT_TYPE_LINK, PROMOTED_OBJECT_TYPE_QQ_MESSAGE, PROMOTED_OBJECT_TYPE_QZONE_VIDEO_PAGE, PROMOTED_OBJECT_TYPE_LOCAL_ADS, PROMOTED_OBJECT_TYPE_ARTICLE, PROMOTED_OBJECT_TYPE_LEAD_AD, PROMOTED_OBJECT_TYPE_TENCENT_KE, PROMOTED_OBJECT_TYPE_QZONE_PAGE_ARTICLE, PROMOTED_OBJECT_TYPE_QZONE_PAGE_IFRAMED, PROMOTED_OBJECT_TYPE_QZONE_PAGE, PROMOTED_OBJECT_TYPE_APP_PC, PROMOTED_OBJECT_TYPE_MINI_GAME_WECHAT, PROMOTED_OBJECT_TYPE_MINI_GAME_QQ, PROMOTED_OBJECT_TYPE_WECHAT_CHANNELS, PROMOTED_OBJECT_TYPE_WECHAT_OFFICIAL_ACCOUNT, PROMOTED_OBJECT_TYPE_MINI_PROGRAM_WECHAT, PROMOTED_OBJECT_TYPE_APP_QUICK_APP } 当 field 取值 created_time 时，字段长度为 10 字节当 field 取值 last_modified_time 时，字段长度为 10 字节当 field 取值 product_mode 时，枚举列表：{ SINGLE, MULTIPLE } 当 field 取值 product_source 时，字段长度最小 1 字节，长度最大 180 字节当 field 取值 ad_num 时，枚举列表：{ SINGLE, MULTIPLE } 当 field 取值 dynamic_ad_type 时，枚举列表：{ DYNAMIC_AD_TYPE_COMMON, DYNAMIC_AD_TYPE_DYNAMIC_PRODUCT, DYNAMIC_AD_TYPE_DYNAMIC_ARTICLE, DYNAMIC_AD_TYPE_DYNAMIC_ELEMENT, DYNAMIC_AD_TYPE_DYNAMIC_CREATIVE, DYNAMIC_AD_TYPE_MULTI_CREATIVE } 当 field 取值 status 时，枚举列表：{ STATUS_PENDING, STATUS_DENIED, STATUS_SUSPEND, STATUS_READY, STATUS_ACTIVE, STATUS_STOP, STATUS_ACTIVE_CAMPAIGN_SUSPEND, STATUS_PART_READY, STATUS_PART_ACTIVE } 当 field 取值 auto_derived_creative_status 时，枚举列表：{ AUTO_DERIVED_CREATIVE_STATUS_DEFAULT, AUTO_DERIVED_CREATIVE_STATUS_SUCCESS, AUTO_DERIVED_CREATIVE_STATUS_FAIL }
page	integer	搜索页码，默认值：1 最小值 1，最大值 99999
page_size	integer	一页显示的数据条数，默认值：10。最小值 1，最大值 100
is_deleted	boolean	是否已删除，true：是，false：否可选值：{ true, false }

使用说明

is_deleted 参数不传时默认为 false，只返回未删除记录。
is_deleted 参数为 true 时，需要同时在 filtering 传参数 last_modified_time。
当根据广告组 id 进行查询且 is_deleted 参数不传或为 false 时，获取的广告组列表包含已删除的广告组。

请求示例


curl -G 'https://api.e.qq.com/v1.1/adgroups/get?access_token=<ACCESS_TOKEN>&timestamp=<TIMESTAMP>&nonce=<NONCE>' \
-d 'account_id=<ACCOUNT_ID>' \
-d 'filtering=[{"field":"adgroup_name","operator":"EQUALS","values":["test"]}]' \
-d 'page=1' \
-d 'page_size=10' \
-d 'is_deleted=false'

应答字段

名称	类型	描述
list	struct[]	返回信息列表
campaign_id	int64	推广计划 id
adgroup_id	int64	广告组 id
adgroup_name	string	广告组名称
site_set	enum[]	投放版位集合，当前单版位或者 SITE_SET_TENCENT_NEWS+SITE_SET_TENCENT_VIDEO+SITE_SET_MOBILE_UNION+SITE_SET_KANDIAN+SITE_SET_QQ_MUSIC_GAME 的组合，[枚举详情]
automatic_site_enabled	boolean	是否开启自动版位功能（暂不包含 SITE_SET_WECHAT 和 SITE_SET_MOMENTS），此字段与 site_set 字段至少需要写入一个。
optimization_goal	enum	广告优化目标类型，[枚举详情]
billing_event	enum	计费类型，[枚举详情]
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 元，单位为人民币）
total_budget	integer	总预算，单位为分，仅合约 CPM 广告有效，其他广告无效
daily_budget	integer	广告组日预算，单位为分，设置为 0 表示不设预算（即不限）
promoted_object_type	enum	推广目标类型，[枚举详情]
promoted_object_id	string	推广目标 id，详见 [查询推广目标 id]
app_android_channel_package_id	string	安卓应用渠道包 id，在投放推广目标类型为 Android 应用的情况下，可以填写腾讯开放平台安卓应用和腾讯广告渠道包的渠道包 id。渠道包 id 可以从推广目标模块的读取接口获取，渠道包 id 字段由"xx;yy" 两部分组成，在写入时 xx 会被置为 0，0 为正常。
mini_game_program_id	string	微信小游戏 id
targeting_id	int64	定向 id，仅非朋友圈广告有效
targeting	struct	定向详细设置，存放所有定向条件
age	struct[]	年龄定向（仅支持单年龄段，范围为 14~66，66 代表的是 66 岁及 66 岁以上，如 18~66 代表大于等于 18 岁）
min	integer	年龄最小值限制，（其中 15、16、17 不可以使用）
max	integer	年龄最大值限制
gender	enum[]	性别定向（仅单选），[枚举详情]
education	enum[]	用户学历，[枚举详情]，该功能即将下线，仅部分行业灰度开放，如有问题可联系您的客户运营
marital_status	enum[]	婚恋育儿状态，[枚举详情]，该功能即将下线，仅部分行业灰度开放，如有问题可联系您的客户运营
working_status	enum[]	工作状态，[枚举详情]
geo_location	struct	地理位置定向，针对朋友圈广告（campaign_type=CAMPAIGN_TYPE_WECHAT_MOMENTS）地域必填，非朋友圈广告选填如使用地域定向"regions"、"business_districts"、"custom_locations" 不能同时为空
location_types	enum[]	地点类型，[枚举详情]，选择限制：对于微信流量（site_set=SITE_SET_WECHAT、SITE_SET_MOMENTS、SITE_SET_MINI_GAME_WECHAT），仅能选择"LIVE_IN"（常住）；使用商圈（business_district）以及自定义地理位置（custom_locations）时，仅可选 "VISITED_IN"（去过），"LIVE_IN"（常住）；如：["LIVE_IN", "VISITED_IN"]
regions	integer[]	省市区县列表，当投放微信流量（site_set=SITE_SET_WECHAT、SITE_SET_MOMENTS、SITE_SET_MINI_GAME_WECHAT）时，仅支持中国大陆（不包含港澳台）地域 id，可通过 [targeting_tags/get] 接口获取
business_districts	integer[]	商圈 id 列表，可通过 [targeting_tags/get] 接口获取
custom_locations	struct[]	自定义地理位置列表，使用火星系坐标，当广告类型为朋友圈广告时（campaign_type=CAMPAIGN_TYPE_WECHAT_MOMENTS），custom_locations 的数组长度限制为最小长度 1。
longitude	float	经度，单位度
latitude	float	纬度，单位度
radius	integer	半径，单位米
user_os	enum[]	操作系统定向, 当 promoted_object_type=PROMOTED_OBJECT_TYPE_APP_ANDROID、PROMOTED_OBJECT_TYPE_APP_ANDROID_UNION、PROMOTED_OBJECT_TYPE_APP_ANDROID_MYAPP 时，广告只会在 Android 操作系统上展示；当 promoted_object_type=PROMOTED_OBJECT_TYPE_APP_IOS 时，广告只会在 iOS 操作系统上展示，[枚举详情]
new_device	enum[]	新设备，最近三个月第一次使用该设备的用户，[枚举详情]
device_price	enum[]	设备价格定向，该功能即将下线，仅部分行业灰度开放，如有问题可联系您的客户运营，[枚举详情]
device_brand_model	struct	设备品牌型号定向，该功能即将下线，仅部分行业灰度开放，如有问题可联系您的客户运营
included_list	integer[]	设备品牌型号定向，可通过 [targeting_tags/get] 接口获取
excluded_list	integer[]	排除设备品牌型号列表，不能与 included_list 同时使用，可通过 [targeting_tags/get] 接口获取
network_type	enum[]	联网方式定向，[枚举详情]
network_operator	enum[]	移动运营商定向，该功能即将下线，仅部分行业灰度开放，如有问题可联系您的客户运营，[枚举详情]
network_scene	enum[]	上网场景，[枚举详情]
dressing_index	enum[]	穿衣指数，[枚举详情]
uv_index	enum[]	紫外线指数，[枚举详情]
makeup_index	enum[]	化妆指数，[枚举详情]
climate	enum[]	气象，[枚举详情]
temperature	struct[]	温度（仅单温度段，以绝对零度值（-273）表示 0 度，依次增加，例如 223~323 表示-50 度到 50 度。数字与“~”之间不允许存在空格）
min	integer	温度最小值限制
max	integer	温度最大值限制
air_quality_index	enum[]	空气质量指数，[枚举详情]
app_install_status	enum[]	应用安装（应用用户），当且仅当 promoted_object_type 为 PROMOTED_OBJECT_TYPE_APP_ANDROID、PROMOTED_OBJECT_TYPE_APP_ANDROID_MYAPP、PROMOTED_OBJECT_TYPE_APP_ANDROID_UNION 时使用，[枚举详情]
consumption_status	enum[]	消费水平，[枚举详情]，该功能即将下线，仅部分行业灰度开放，如有问题可联系您的客户运营
game_consumption_level	enum[]	游戏消费能力，原 gamer_consumption_ability 定向升级版，gamer_consumption_ability 和 game_consumption_level 不能同时使用.，该功能即将下线，仅部分行业灰度开放，如有问题可联系您的客户运营，[枚举详情]
residential_community_price	struct[]	居住社区价格（仅支持单价格段，范围为：1~100000，单位是“元/m ²”）
min	integer	居住社区价格最小值限制，可填写的值为 1,1000,2000,3000,4000,5000,6000,7000,8000,9000,10000,20000,30000,40000,50000,60000,70000,80000,90000,100000
max	integer	居住社区价格最大值限制，可填写的值为 1000,2000,3000,4000,5000,6000,7000,8000,9000,10000,20000,30000,40000,50000,60000,70000,80000,90000,100000,999999999，最大值 999999999 代表 10 万以上
financial_situation	enum[]	财产状态，该功能即将下线，仅部分行业灰度开放，如有问题可联系您的客户运营，[枚举详情]
consumption_type	enum[]	消费类型定向，[枚举详情]
wechat_ad_behavior	struct	微信再营销，原微信广告行为定向升级为微信再营销，当且仅当投放微信流量（site_set=SITE_SET_WECHAT、SITE_SET_MOMENTS）时有效
actions	enum[]	包含的行为列表，多个行为之间为并集（or）的关系数组最小长度 0，最大长度 10 QQ 账号支持枚举列表：{WECHAT_OFFICIAL_ACCOUNT_AD_LIKE，WECHAT_MOMENTS_AD_LIKE，MINI_GAME_WECHAT_REGISTERED }，[枚举详情]
excluded_actions	enum[]	排除的行为列表，多个行为之间为并集（or）的关系数组最小长度 0，最大长度 10 QQ 账号支持枚举列表：{WECHAT_OFFICIAL_ACCOUNT_AD_LIKE，WECHAT_MOMENTS_AD_LIKE，MINI_GAME_WECHAT_REGISTERED }，[枚举详情]
custom_audience	integer[]	自定义定向用户群，通过 [人群管理模块] 创建的人群 id，custom_audience 和 excluded_custom_audience 个数之和不能超过 200 个，如果有组合人群，则组合人群包数不能超过 50。 2022 年 6 月 30 日起，竞价 oCPC、oCPM 场景内，仅能使用“一方人群”的人群包，人群详情可参考[人群管理模块]。
excluded_custom_audience	integer[]	自定义排除用户群，通过 [人群管理模块] 创建的人群 id，custom_audience 和 excluded_custom_audience 个数之和不能超过 200 个，如果有组合人群，则组合人群包数不能超过 50。 2022 年 6 月 30 日起，竞价 oCPC、oCPM 场景内，仅能使用“一方人群”的人群包，人群详情可参考[人群管理模块]。
behavior_or_interest	struct	行为兴趣意向定向，2022 年 6 月 30 日起，该定向将无法在竞价 oCPC、oCPM 场景使用。
interest	struct	行为兴趣意向定向的兴趣部分
targeting_tags	string[]	兴趣标签列表（待废弃，后续仅支持 category_id_list、keyword_list）
category_id_list	integer[]	兴趣标签 id 列表，和关键词列表 keyword_list 个数之和不能大于 250，通过[targeting_tags/get]可获取兴趣标签列表 id 和对应标签名称
keyword_list	string[]	兴趣关键词列表，和兴趣标签 id 列表 category_id_list 个数之和不能大于 250，通过[targeting_tags/get]可获取兴趣关键词列表
behavior	struct[]	行为兴趣意向定向的行为部分，targeting_tags、category_id_list、keyword_list 三个结构不能同时为空
targeting_tags	string[]	行为标签列表（待废弃，后续仅支持 category_id_list、keyword_list）
category_id_list	integer[]	行为标签 id 列表，和关键词列表 keyword_list 个数之和不能大于 250，通过[targeting_tags/get]可获取行为标签列表 id 和对应标签名称
keyword_list	string[]	行为关键词列表，和行为标签 id 列表 category_id_list 个数之和不能大于 250，通过[targeting_tags/get]可获取行为关键词列表
scene	enum[]	行为兴趣意向定向的行为部分的场景，[枚举详情]
time_window	enum	行为兴趣意向定向的行为部分的时间窗，[枚举详情]
intensity	enum[]	行为兴趣意向定向的行为部分的强度，[枚举详情]
intention	struct	行为兴趣意向定向的意向部分
targeting_tags	integer[]	意向标签列表
wechat_official_account_category	integer[]	微信流量类型定向，当且仅当投放微信版位（SITE_SET_WECHAT）且非朋友圈广告（campaign_type != CAMPAIGN_TYPE_WECHAT_MOMENTS）时可以使用，通过[targeting_tags/get]可获取微信流量类型
mobile_union_category	integer[]	移动媒体类型定向，当且仅当投放移动联盟流量时（site_set = SITE_SET_MOBILE_UNION）时可以使用。（字段待废弃，2021 年 10 月 29 日后不支持新建和更新）
business_interest	integer[]	商业兴趣定向，通过 [targeting_tags/get] 接口获取
keyword	struct	关键词定向
words	string[]	关键词
app_behavior	struct	app 行为定向
object_type	enum	行为对象的类型，仅支持 APP 类目，[枚举详情]
object_id_list	integer[]	行为对象的 id，当 object_type = APP_CLASS 时，表示类目 id，类目 id 需填写最细一级 id
time_window	integer	行为对象的有效期，单位天
act_id_list	enum[]	app 行为对象的行为，[枚举详情]
paid_user	enum[]	付费用户，[枚举详情]
deprecated_custom_audience	integer[]	自定义人群，通过 [人群管理模块] 创建的人群 id，不支持人群类型为 COMBINE 的人群 id
deprecated_excluded_custom_audience	integer[]	排他人群，通过 [人群管理模块] 创建的人群 id，不支持人群类型为 COMBINE 的人群 id
deprecated_region	integer[]	地域定向，可通过 [targeting_tags/get] 接口获取
mini_game_qq_status	enum[]	QQ 小游戏使用定向，[枚举详情]，当且仅当投放 QQ 小游戏推广目标（promoted_object_type= PROMOTED_OBJECT_TYPE_MINI_GAME_QQ）时可以使用
excluded_converted_audience	struct	排除已转化用户定向
excluded_dimension	enum	排除已转化用户定向范围同应用，仅当推广目标为应用下载时可以使用，没有选择自定义转化行为（excluded_dimension）时，使用该定向出价需要满足是 oCPC、oCPM 广告；同商品，仅当 SDPA 商品广告下使用，不支持自定义转化行为默认排除已下单、和已付费用户，不限制出价方式；非同应用、非同商品，没有选择自定义转化行为（excluded_dimension）时，使用该定向出价需要满足是 oCPC、oCPM 广告；，[枚举详情]
conversion_behavior_list	enum[]	自定义转化行为，没有选择自定义转化行为（excluded_dimension）时，使用该定向需要校验是 oCPC、oCPM 广告
targeting_translation	string	已选择定向条件的描述
is_include_unsupported_targeting	boolean	是否包含不支持定向，true：包含 API 暂不支持读写的定向信息，false：不包含 API 暂不支持读写的定向信息
scene_spec	struct	场景定向
mobile_union	enum[]	优量汇行业定投流量包，当且仅当投放优量汇流量时可以使用（已废弃，请使用优量汇行业精选流量包，但不能和 mobile_union_industry 同时使用时），[枚举详情]
exclude_mobile_union	enum[]	优量汇行业屏蔽流量包，当且仅当投放优量汇流量时可以使用（已废弃，请使用优量汇行业精选流量包，但不能和 mobile_union_industry 同时使用时），[枚举详情]
mobile_union_industry	enum[]	优量汇行业精选流量包，根据你所处的行业精选部分在当前行业下转化效果较好的优质流量，当选择的版位中包含优量汇版位（SITE_SET_MOBILE_UNION）时才可以使用。（字段待废弃，2021 年 10 月 29 日后不支持新建和更新），[枚举详情]
union_position_package	integer[]	优量汇自定义定投，设置后，广告将只投放到流量包指定的优量汇广告位，一个广告最多可绑定 5 个定投流量包，单个流量包可以关联的广告位数最大为 2000 个，其中之前超过 5 个，更新 adgroup 的时候在不修改流量包的情况下，可以更新。当选择的版位中包含优量汇版位（SITE_SET_MOBILE_UNION）时才可以使用
exclude_union_position_package	integer[]	优量汇自定义屏蔽，设置后，广告将不投放到流量包指定的优量汇广告位，一个广告最多可绑定 5 个屏蔽流量包，单个流量包可以关联的广告位数最大为 2000 个，其中之前超过 5 个，更新 adgroup 的时候在不修改流量包的情况下，可以更新。当选择的版位中包含优量汇版位（SITE_SET_MOBILE_UNION）时才可以使用
display_scene	enum[]	优量汇广告展示场景，设置后，广告将只播放到指定的广告场景，如原生、激励视频、开屏等，当选择的版位中包含优量汇版位（SITE_SET_MOBILE_UNION）时才可以使用。注：修改展示场景时，要同步修改使用的创意内容。选用展示场景中可以使用的创意形式（可以通过接口文档查看），否则广告无法正常曝光，[枚举详情]
mobile_union_category	integer[]	优量汇媒体类型场景定向，当且仅当投放优量汇流量时（site_set = SITE_SET_MOBILE_UNION）时可以使用; 可用场景值从投放辅助工具（scene_spec_tags/get）获取。（字段待废弃，2021 年 10 月 29 日后不支持新建和更新）
tencent_news	enum[]	腾讯新闻流量场景，当选择的版位中包含腾讯新闻版位（SITE_SET_TENCENT_NEWS）时可以使用，功能灰度开放，如需使用可联系您的客户运营，[枚举详情]
wechat_scene	struct	微信公众号与小程序场景，当且仅当投放公众号流量（site_set = SITE_SET_WECHAT）时可以使用，可用场景值从投放辅助工具（scene_spec_tags/get）获取
official_account_media_category	integer[]	公众号媒体类型
mini_program_and_mini_game	integer[]	小程序小游戏流量类型
pay_scene	integer[]	订单详情页消费场景
wechat_position	integer[]	微信公众号与小程序定投，当且仅当投放公众号流量（site_set = SITE_SET_WECHAT）时可以使用，可用场景值从投放辅助工具（scene_spec_tags/get）获取
flow_optimization_enabled	boolean	是否使用智能场景匹配，仅支持优量汇版位使用，且不能和优量汇行业精选流量包(mobile_union_industry)或优量汇媒体类型场景定向（mobile_union_category）同时使用，flow_optimization_enabled 设置为 true, 开启智能场景匹配
begin_date	string	开始投放日期，日期格式：YYYY-MM-DD，且日期小于等于 end_date
first_day_begin_time	string	首日开始投放时间，首日开始投放时间：HH:ii:ss
end_date	string	结束投放日期，日期格式：YYYY-MM-DD，大于等于今天，且大于等于 begin_date ；如果希望长期投放，传空字符串
time_series	string	投放时间段，格式为 48 * 7 位字符串，且都为 0 和 1，以半个小时为最小粒度，从周一零点开始至周日 24 点结束。0 为不投放，1 为投放，全传 1 视为全时段投放，不允许全部传 0。
configured_status	enum	客户设置的状态，[枚举详情] 默认值：该字段默认值 AD_STATUS_NORMAL
customized_category	string	自定义分类，关键词用半角逗号','分隔，如：本地生活,餐饮
created_time	integer	创建时间（时间戳）
last_modified_time	integer	最后修改时间（时间戳）
ad_count	integer	广告数量，创意数量查询，（非动态创意）查询当前广告未删除的创意数量，单创意指广告下只有 1 条创意，多创意指大于 1 条创意。
dynamic_ad_spec	struct	动态商品广告属性，当广告形态为动态商品广告时，该字段必填。为了不同投放端体验的一致性，在创建广告时如广告创意 dynamic_adcreative_spec 字段不为空且对应广告组缺失 dynamic_ad_spec 或 product_source 内容，系统会自动将广告创意中 dynamic_ad_spec 或 product_source 内容写入对应广告组。
product_catalog_id	integer	商品库 id
product_mode	enum	动态商品广告（DPA）类型，支持单商品动态商品广告（SDPA）和多商品动态商品广告（MDPA），[枚举详情]
product_source	string	动态商品广告所使用的商品信息,可以填入商品系列 id 或者商品 id
product_recommend_methods	integer[]	动态多商品广告的商品推荐方式，有使用权限的推荐方式 id，当广告形态为动态多商品广告时，该字段必填，如填写多个推荐方式，需确保推荐方式的父节点为同一个
user_action_sets	struct[]	用户行为数据源，详见 [转化归因功能]，当 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 数据源。
type	enum	数据源类型，[枚举详情]
id	integer	数据源 id，通过 user_action_sets 模块创建和获取，数据源 id 对应的类型要与 user_action_sets 中指定的 type 一致
additional_user_action_sets	struct[]	补充的 app 用户行为数据源，字段待废弃。当 promoted_object_type 为 PROMOTED_OBJECT_TYPE_ECOMMERCE、PROMOTED_OBJECT_TYPE_LINK、PROMOTED_OBJECT_TYPE_QQ_BROWSER_MINI_PROGRAM，且行业为网服、电商、金融的广告主，可填写补充的 app 用户行为数据源。数据源需为安卓/ios 数据源，且需确保为同一个 app 的数据源。
type	enum	数据源类型，[枚举详情]
id	integer	数据源 id，通过 user_action_sets 模块创建和获取，数据源 id 对应的类型要与 user_action_sets 中指定的 type 一致
is_deleted	boolean	是否已删除，true：是，false：否
dynamic_creative_id	integer	DC 动态创意 id
is_rewarded_video_ad	boolean	是否是激励视频广告（字段已经废弃，忽略）
cost_guarantee_message	string	成本保障状态信息说明，不超过 1024 个字符
cost_guarantee_status	enum	成本保障状态，成本保障状态定义，[枚举详情]
bid_strategy	enum	出价策略，仅 oCPC/oCPM 广告可设置，枚举列表：[枚举详情]
cold_start_audience	integer[]	扩量种子人群（原冷启动人群名称升级扩量种子人群） 1、系统会学习您选择的人群包数据，帮助提升广告投放效果； 2、当且仅当广告为 oCPC/oCPM 开启自动扩量的广告、且投放的流量不是应用宝时； 3、仅支持人群类型为 CUSTOMER_FILE（号码文件人群）的可用人群 id、且人群数量大于 100 时；
auto_audience	boolean	是否使用系统优选，限制：系统优选不支持朋友圈广告使用；当 auto_audience=true 时系统自动选择匹配行为兴趣定向；系统优选(auto_audience)和行为兴趣定向(behavior_or_interest)不能同时填写，即行为兴趣和系统优选功能二选一；系统优选(auto_audience)和自动扩量(expand_enabled)功能、定向包 id（targeting_id）、自定义人群(custom_audience)功能互斥；
expand_enabled	boolean	是否使用自动扩量，当广告为 oCPC/oCPM、CPC 出价时，可将 expand_enabled 设置为 true，微信广告当且仅当出价为 oCPC/oCPM 时，才可将 expand_enabled 设置为 true。2022 年 6 月 30 日起，自动扩量无法与行为兴趣意向、“二方人群”人群包同时使用，expand_enabled 设置为 true, 开启自动扩量
expand_targeting	string[]	扩量不可突破定向，如果使用 oCPC/oCPM，会在 oCPC/oCPM 扩量定向的范围内寻找相似人群，原 targeting 接口传入的定向将失效。当且仅当 expand_enabled 设置为 true 时，expand_targeting 才可填写，且为必填。目前仅支持年龄、性别、地域、学历（不可突破学历仅教育行业可使用）定向设置为不可突破（前置需要定向 targeting 层级使用了年龄、性别、地域、学历时不可突破才可以选择相对应的值）。
deep_conversion_spec	struct	oCPC/oCPM 深度优化内容，oCPC/oCPM 深度优化内容，创建时若此字段不传，或传空则视为无限制条件；深度优化不可取消，也不支持在编辑环节从未使用深度优化切换为使用深度优化。
deep_conversion_type	enum	oCPC/oCPM 深度优化价值配置，[枚举详情]
deep_conversion_behavior_spec	struct	oCPC/oCPM 优化转化行为配置
goal	enum	优化转化行为目标，不可更改，如修改目标价格，需在结构体中传入已设置的优化转化行为目标。，枚举列表：[枚举详情]
bid_amount	integer	深度优化行为的出价，深度优化行为出价，单位为分，最小值 10，最大值 1000000; 当深度转化行为目标为次留率时，单位为%，最小值 1，最大值 99。如输入 40，代表次留率目标 40%
deep_conversion_worth_spec	struct	oCPC/oCPM 优化 ROI 配置
goal	enum	优化 ROI 目标，不可更改，如修改深度优化效果值，需在结构体中传入已设置的优化 ROI 目标，枚举列表：[枚举详情]
expected_roi	float	深度优化价值效果值，在深度 ROI 自动出价的场景下不能使用此字段。
deep_conversion_worth_advanced_spec	struct	oCPC/oCPM 强化 ROI 配置
goal	enum	强化 ROI 目标，不可更改，如修改强化优化效果值，需在结构体中传入已设置的强化 ROI 目标，枚举列表：[枚举详情]
expected_roi	float	深度优化价值效果值
deep_optimization_action_type	enum	oCPC/oCPM 深度优化方式配置当深度优化类型=优化深度转化行为时，此前支持选择“优化方式”；目前深度优化能力升级，两阶段/双目标优化方式已进行合并，因此优化方式字段即将下线，可以不再输入。如调用该字段，系统会默认按两阶段优化方式进行创建，了解更多
poi_list	string[]	门店 id 列表, 1. 推广目标类型 PROMOTED_OBJECT_TYPE_LOCAL_ADS_WECHAT，非朋友圈版位，使用 promoted_object_id 来表示门店 id，不能清空； 2. 推广目标类型 PROMOTED_OBJECT_TYPE_LOCAL_ADS_WECHAT，朋友圈版位，使用 poi_list 来表示门店 id，不能清空； 3. 其他推广目标下，使用 poi_list 来表示门店信息，可以清空；，最多可输入 100 个门店
conversion_id	integer	转化 id，包含优化目标，深度优化目标，数据上报方式，归因方式等信息，仅 ocpc/ocpm 广告可设置，转化 id 设置后不可修改。可通过辅助工具[转化查询接口]查询可使用的转化 id。当传入转化 id 时，可无需再传入 user_action_sets，additional_user_action_sets，optimization_goal，deep_conversion_spec 字段信息。如若同时传入转化 id 和 user_action_sets/additional_user_action_sets，将以转化 id 的信息为第一优先级；如若同时传入转化 id 和 optimization_goal/deep_conversion_spec，仅当转化 id 中包含的优化目标/深度优化目标与传入的优化目标/深度优化目标信息一致时，才允许创建，否则将不允许创建。功能灰度开放中。
deep_conversion_behavior_bid	integer	深度优化行为的出价，使用转化 id 确认优化目标和深度优化目标的广告主，深度优化行为的目标出价无需传 deep_conversion_spec 结构体中字段，可直接使用 deep_conversion_behavior_bid 字段传输深度出价，当深度转化行为目标为次留率时，单位为%，最小值 1，最大值 99。如输入 40，代表次留率目标 40%，单位为分。
deep_conversion_worth_rate	float	深度优化价值的期望 ROI，使用转化 id 确认优化目标和深度优化目标的广告主，深度优化价值的目标出价无需传 deep_conversion_spec 结构体中字段，可直接使用 deep_conversion_worth_rate 字段传输深度出价。深度 roi 自动出价的场景下不能使用此字段，该功能灰度开放中。
deep_conversion_worth_advanced_rate	float	强化优化价值的期望 ROI，使用转化 id 确认优化目标和强化优化目标的广告主，强化优化价值的目标出价无需传 deep_conversion_spec 结构体中字段，可直接使用 deep_conversion_worth_advanced_rate 字段传输深度出价。该功能灰度开放中。
android_channel_package_audit_message	string	广告包渠道包审核消息
system_status	enum	广告组在系统中的状态，[枚举详情]
bid_mode	enum	出价方式， 1. bid_mode 为 billing_event 升级字段，不可同时输入，升级后直接写入 bid_mode 字段即可； 2. 当投放智能出价广告，可写入 BID_MODE_OCPC/BID_MODE_OCPM。此时，optimization_goal 优化目标字段必填； 3. 当投放非智能出价广告，可写入 BID_MODE_CPC/BID_MODE_CPM/BID_MODE_CPA。此时，optimization_goal 优化目标字段不可填； 4. 针对非微信流量，BID_MODE_CPC 可编辑修改为 BID_MODE_OCPC，BID_MODE_CPM 可编辑修改为 BID_MODE_OCPM，其他修改不可操作。针对微信流量，bid_mode 字段不可修改； 5. 可通过 adcreative_templates/get 接口查询不同情况下支持的出价方式;，[枚举详情]
status	enum	广告状态，[枚举详情]
bid_adjustment	struct	出价系数设置内容，仅当投放 oCPC、oCPM 广告时可使用，编辑广告时，分版位功能仅支持出价系数的变更，分城市出价支持城市包和出价系数的变更。
site_set_package	struct[]	分版位组合出价系数设置。将投放的版位分为 2 个及以上的组合，分别设置出价系数。同一个版位，只能设置于一个分组中；未设置分组的版位，将默认设置为一个分组，且出价系数默认为 1
site_set	enum[]	投放版位集合，当前单版位或者 SITE_SET_TENCENT_NEWS+SITE_SET_TENCENT_VIDEO+SITE_SET_MOBILE_UNION+SITE_SET_KANDIAN+SITE_SET_QQ_MUSIC_GAME 的组合，[枚举详情]
bid_coefficient	float	广告出价系数，将对版位分组使用 bid_amount × bid_coefficient 用于控制优化目标的出价
deep_bid_coefficient	float	深度优化行为出价系数，将对版位分组使用 deep_conversion_behavior_spec.bid_amount × deep_bid_coefficient 用于控制深度优化目标的出价
region_group_package	struct[]	分城市组合出价系数设置。将投放的城市分为不同组合，分别设置出价系数。同一个城市，只能设置于一个分组中；未设置分组的城市，将默认设置为一个分组，且出价系数默认为 1。分城市出价打开或关闭后，不支持编辑关闭或打开。
region_list	integer[]	参数 region_list 只能使用合法省市区域,仅支持中国大陆（不包含港澳台）地域 id,地域 id 获取与地域定向 regions 保持一致，可通过 [targeting_tags/get] 接口获取。
bid_coefficient	float	广告出价系数。 1.bid_coefficient 控制将对城市分组使用 bid_amount × bid_coefficient 用于控制优化目标的出价。 2.deep_bid_coefficient 深度优化行为出价系数，将对版位分组使用 deep_conversion_behavior_spec.bid_amount × deep_bid_coefficient 用于控制深度优化目标的出价。
deep_bid_coefficient	float	广告出价系数。 1.bid_coefficient 控制将对城市分组使用 bid_amount × bid_coefficient 用于控制优化目标的出价。 2.deep_bid_coefficient 深度优化行为出价系数，将对版位分组使用 deep_conversion_behavior_spec.bid_amount × deep_bid_coefficient 用于控制深度优化目标的出价。
auto_acquisition_enabled	boolean	是否开启一键起量, 1. 一键起量会在 6 小时内尽量消耗完预算，期间产生的消耗不赔付，但转化计入赔付门槛判断； 2. 一条广告可使用多次一键起量功能，多次开启功能仅针对 2022 年 3 月 10 日起新建的广告有效，探索中任何原因导致广告暂停播放，都会导致起量中止； 3. 一键起量支持微信/非微信通投； 4. 一键起量仅支持 oCPX 广告使用，但不支持与自动出价同时使用。
auto_acquisition_budget	integer	一键起量探索预算，单位为分，一键起量预算设置后不可修改
creative_display_type	enum	创意展示类型，不填该字段默认优选模式，[枚举详情]
auto_derived_creative_enabled	boolean	是否开启自动衍生视频创意。开启后，根据广告主的投放数据以及上传的素材, 通过策略选择效果最佳的视频模板、音乐, 并复制已有创意元素, 程序化生成视频创意。
smart_bid_type	enum	出价类型，当出价类型为 SMART_BID_TYPE_SYSTEMATIC 时，不可传入 bid_amount，暂不支持微信流量，功能灰度开放中。smart_bid_type 出价类型仅支持 oCPX 广告使用，[枚举详情] 默认值：SMART_BID_TYPE_CUSTOM
smart_cost_cap	integer	自动出价下，系统计算的预计成本的上限值，单位为分
marketing_scene	enum	营销目标
custom_adgroup_tag	string[]	广告标签：广告主可传输多个字符串用于对广告进行标注。标注内容对广告投放无影响，仅用于广告管理。
smart_targeting	struct	智能定向功能,功能灰度开放，如需使用可联系您的运营接口同学。智能定向功能与自动扩量/系统优选相关字段不可同时设置。2022 年 6 月 30 日起，智能定向无法与行为兴趣意向、“二方人群”人群包同时使用
smart_targeting_version	integer	智能定向版本号。当 smart_targeting_version 设置为 1 后，该广告默认走智能定向通路，不可回退老通路，设置自动扩量/系统优选相关字段均会报错。当 smart_targeting_switch 设置为 true 时,smart_targeting_version 可不传，系统默认设置为 1，智能定向版本号
smart_targeting_switch	boolean	是否使用智能定向
start_audience	integer[]	智能定向一方助攻人群包列表
unbreakable_targeting	struct	智能定向 —— 不可突破定向详细设置
age	struct[]	年龄定向（仅支持单年龄段，范围为 14~66，66 代表的是 66 岁及 66 岁以上，如 18~66 代表大于等于 18 岁）
min	integer	年龄最小值限制，（其中 15、16、17 不可以使用）
max	integer	年龄最大值限制
gender	enum[]	性别定向（仅单选），[枚举详情]
geo_location	struct	地理位置定向，针对朋友圈广告（campaign_type=CAMPAIGN_TYPE_WECHAT_MOMENTS）地域必填，非朋友圈广告选填如使用地域定向"regions"、"business_districts"、"custom_locations" 不能同时为空
location_types	enum[]	地点类型，[枚举详情]，选择限制：对于微信流量（site_set=SITE_SET_WECHAT、SITE_SET_MOMENTS、SITE_SET_MINI_GAME_WECHAT），仅能选择"LIVE_IN"（常住）；使用商圈（business_district）以及自定义地理位置（custom_locations）时，仅可选 "VISITED_IN"（去过），"LIVE_IN"（常住）；如：["LIVE_IN", "VISITED_IN"]
regions	integer[]	省市区县列表，当投放微信流量（site_set=SITE_SET_WECHAT、SITE_SET_MOMENTS、SITE_SET_MINI_GAME_WECHAT）时，仅支持中国大陆（不包含港澳台）地域 id，可通过 [targeting_tags/get] 接口获取
business_districts	integer[]	商圈 id 列表，可通过 [targeting_tags/get] 接口获取
custom_locations	struct[]	自定义地理位置列表，使用火星系坐标，当广告类型为朋友圈广告时（campaign_type=CAMPAIGN_TYPE_WECHAT_MOMENTS），custom_locations 的数组长度限制为最小长度 1。
longitude	float	经度，单位度
latitude	float	纬度，单位度
radius	integer	半径，单位米
user_os	string[]	操作系统定向, 该功能即将下线，仅部分行业灰度开放，如有问题可联系您的客户运营，当 promoted_object_type=PROMOTED_OBJECT_TYPE_APP_ANDROID、PROMOTED_OBJECT_TYPE_APP_ANDROID_UNION、PROMOTED_OBJECT_TYPE_APP_ANDROID_MYAPP 时，广告只会在 Android 操作系统上展示；当 promoted_object_type=PROMOTED_OBJECT_TYPE_APP_IOS 时，广告只会在 iOS 操作系统上展示，[枚举详情]
app_install_status	enum[]	应用安装（应用用户），当且仅当 promoted_object_type 为 PROMOTED_OBJECT_TYPE_APP_ANDROID、PROMOTED_OBJECT_TYPE_APP_ANDROID_MYAPP、PROMOTED_OBJECT_TYPE_APP_ANDROID_UNION 时使用，[枚举详情]
excluded_converted_audience	struct	排除已转化用户定向
excluded_dimension	enum	排除已转化用户定向范围同应用，仅当推广目标为应用下载时可以使用，没有选择自定义转化行为（excluded_dimension）时，使用该定向出价需要满足是 oCPC、oCPM 广告；同商品，仅当 SDPA 商品广告下使用，不支持自定义转化行为默认排除已下单、和已付费用户，不限制出价方式；非同应用、非同商品，没有选择自定义转化行为（excluded_dimension）时，使用该定向出价需要满足是 oCPC、oCPM 广告；，[枚举详情]
conversion_behavior_list	enum[]	自定义转化行为，没有选择自定义转化行为（excluded_dimension）时，使用该定向需要校验是 oCPC、oCPM 广告
dynamic_creative_id_set	integer[]	DC 动态创意 id 集合
system_status_explanation	string	广告系统状态详情内容
auto_derived_landing_page_switch	boolean	是否开启自动衍生落地页开关
page_info	struct	分页配置信息
page	integer	搜索页码
page_size	integer	一页显示的数据条数
total_number	integer	总条数
total_page	integer	总页数

应答示例

{
    "code": 0,
    "message": "",
    "message_cn": "",
    "data": {
        "list": [
            {
                "campaign_id": "<CAMPAIGN_ID>",
                "adgroup_id": "<ADGROUP_ID>",
                "adgroup_name": "推广广告",
                "site_set": [
                    "SITE_SET_QZONE"
                ],
                "optimization_goal": "OPTIMIZATIONGOAL_CLICK",
                "billing_event": "BILLINGEVENT_CLICK",
                "bid_amount": 200,
                "daily_budget": 10000,
                "promoted_object_type": "PROMOTED_OBJECT_TYPE_LINK",
                "targeting_id": 111111111,
                "scene_spec": {
                    "mobile_union": [
                        "MOBILE_UNION_IN_WECHAT"
                    ]
                },
                "begin_date": "2017-04-25",
                "end_date": "2017-05-01",
                "time_series": "010100100110100010101010010101010101010100101010101010010101010101001010101010100101010101010111110010101001010110110100110001011001010100101010101010110011001010101010100101100101101110101010101010100110100110010100110101110111101110110110110110110110101101101101110110011101011101101011101101101101001010110111010111011010110110111011",
                "configured_status": "AD_STATUS_NORMAL",
                "customized_category": "本地生活,餐饮",
                "created_time": 1491019858,
                "last_modified_time": 1491098468,
                "user_action_sets": [],
                "additional_user_action_sets": [],
                "is_deleted": false,
                "cold_start_audience": [
                    1024
                ],
                "expand_enabled": false,
                "expand_targeting": [],
                "deep_conversion_spec": {
                    "deep_conversion_type": "DEEP_CONVERSION_BEHAVIOR",
                    "deep_conversion_behavior_spec": {
                        "bid_amount": 200
                    }
                },
                "poi_list": [],
                "system_status": "AD_STATUS_NORMAL",
                "bid_adjustment": {
                    "site_set_package": [
                        {
                            "site_set": [
                                "SITE_SET_QZONE"
                            ]
                        }
                    ],
                    "region_group_package": [
                        {
                            "region_list": []
                        }
                    ]
                },
                "custom_adgroup_tag": [],
                "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": []
                        }
                    }
                },
                "dynamic_creative_id_set": []
            }
        ],
        "page_info": {
            "page": 1,
            "page_size": 10,
            "total_number": 1,
            "total_page": 1
        }
    }
}

首页

开发文档

最新动态

腾讯广告

获取广告组
全部接口
V1.1
loading

全局参数

请求参数

请求示例

应答字段

应答示例

可视化调试工具

相关阅读

首页

开发文档

最新动态

腾讯广告

获取广告组 全部接口 V1.1 loading

全局参数

请求参数

请求示例

应答字段

应答示例

可视化调试工具

相关阅读

获取广告组
全部接口
V1.1
loading