接口文档SDK业务专题开发者工具

创建异步报表任务
全部接口
V1.1
loading

所属权限 Ads Insight
请求地址 async_reports/add
请求方法 post

全局参数

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

参数名称 参数类型
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
task_name*
string 任务名称
字段长度最小 1 字节,长度最大 120 字节
report_fields*
string[] 指定异步报表返回的字段,[字段列表]
数组最小长度 1,最大长度 512
字段长度最小 1 字节,长度最大 64 字节
level*
enum 异步报表类型级别,腾讯广告平台广告主,仅可使用:REPORT_LEVEL_AD, REPORT_LEVEL_ADVERTISER, REPORT_LEVEL_CAMPAIGN, REPORT_LEVEL_ADGROUP, REPORT_LEVEL_MATERIAL_VIDEO, REPORT_LEVEL_MATERIAL_IMAGE, REPORT_LEVEL_PROMOTED_OBJECT, REPORT_LEVEL_CREATIVE_TEMPLATE, REPORT_LEVEL_PRODUCT_CATELOG,REPORT_LEVEL_AGE, REPORT_LEVEL_GENDER, REPORT_LEVEL_REGION_RECENTLY_IN, REPORT_LEVEL_REGION_VISITED_IN, REPORT_LEVEL_REGION_LIVE_IN, REPORT_LEVEL_REGION_TRAVEL_IN, REPORT_LEVEL_CITY_RECENTLY_IN, REPORT_LEVEL_CITY_VISITED_IN, REPORT_LEVEL_CITY_LIVE_IN, REPORT_LEVEL_CITY_TRAVEL_IN,REPORT_LEVEL_BIDWORD,REPORT_LEVEL_QUERYWORD,[枚举详情]
枚举列表:{ REPORT_LEVEL_ADGROUP_WECHAT, REPORT_LEVEL_AD_WECHAT, REPORT_LEVEL_POI_WECHAT, REPORT_LEVEL_AD, REPORT_LEVEL_ADVERTISER, REPORT_LEVEL_CAMPAIGN, REPORT_LEVEL_ADGROUP, REPORT_LEVEL_MATERIAL_VIDEO, REPORT_LEVEL_MATERIAL_IMAGE, REPORT_LEVEL_PROMOTED_OBJECT, REPORT_LEVEL_CREATIVE_TEMPLATE, REPORT_LEVEL_PRODUCT_CATELOG, REPORT_LEVEL_AGE, REPORT_LEVEL_GENDER, REPORT_LEVEL_REGION_RECENTLY_IN, REPORT_LEVEL_REGION_VISITED_IN, REPORT_LEVEL_REGION_LIVE_IN, REPORT_LEVEL_REGION_TRAVEL_IN, REPORT_LEVEL_CITY_RECENTLY_IN, REPORT_LEVEL_CITY_VISITED_IN, REPORT_LEVEL_CITY_LIVE_IN, REPORT_LEVEL_CITY_TRAVEL_IN, REPORT_LEVEL_BIDWORD, REPORT_LEVEL_QUERYWORD }
filtering
struct[] 过滤条件,若此字段不传,或传空则视为无限制条件,若获取联盟广告位信息此字段必填,详见 [过滤条件]
数组最小长度 1,最大长度 5
field*
string 过滤字段,腾讯广告平台广告主:当 level 为 REPORT_LEVEL_PRODUCT_CATELOG 时,field 必须选择 product_catalog_id
可选值:{ product_catalog_id }
operator*
enum 操作符
当 field 取值 product_catalog_id 时,枚举列表:{ EQUALS }
values*
string[] 字段取值,values 数组元素的个数限制与 operator 的取值相关,详见 [过滤条件]
time_line
enum 时间口径,[枚举详情]
枚举列表:{ REQUEST_TIME, REPORTING_TIME, ACTIVE_TIME }
group_by
string[] 聚合参数,所有 level 均可使用:{site_set};当 level 取值{REPORT_LEVEL_PRODUCT_CATELOG}时,详细规则请看使用说明
数组最小长度 1,最大长度 4
字段长度最大 255 字节
granularity*
enum 异步报表粒度,[枚举详情]
枚举列表:{ DAILY, HOURLY }
date*
string 日期,格式 YYYY-MM-DD,当 granularity 为 HOURLY 时,只支持最近 30 天内的数据,当 granularity 为 DAILY 时,只支持最近 365 天内的数据
字段长度为 10 字节
weixin_official_accounts_upgrade_enabled
boolean 针对微信公众号账户是否使用升级的新调用方式,true:使用升级的新方式,false:不使用,不传则默认值 false ;详细情况请查看公告[Marketing API 微信公众平台账户服务升级]
可选值:{ true, false }
adq_accounts_upgrade_enabled
boolean 针对腾讯广告平台广告账户是否使用升级的新调用方式,true:使用升级的新方式,可以调用新指标体系; false:不使用,仅能调用旧指标体系,不传则默认值 false ;
可选值:{ true, false }

使用说明

  1. 每账号(account_id)限制最多 5 分钟创建 1 个异步报表任务,多种级别异步报表任务算多个。
  2. level 取值 REPORT_LEVEL_PRODUCT_CATELOG 时,group_by 的使用规则如下: 1)按商品信息层级聚合:单选,支持按如下层级聚合,商品 id(product_outer_id),商品系列(product_set_id),品牌 id(brand_id),店铺 id(shop_id),一级类目 id(first_category_id),二级类目 id(second_category_id ),三级类目 id(third_category_id),例如:希望获取商品系列的整账户表现,可指定 group by product_set_id ; 2)按数据层级聚合:单选,支持按如下数据层级聚合,账户(不指定时默认为账户),计划(campaign_id),广告组(adgroup_id),广告(ad_id),例如:希望获取计划层级的商品库报表,可指定 group by campaign id ; 3)按商品信息层级(单选)x 数据层级(单选)聚合进行,例如:希望获取商品*计划粒度的报表数据,可指定 groupby product_outer_id campaign id。
  3. 商品报表仅支持查看指定商品库下,单日花费最高的 10000 条商品的效果数据。
  4. level=REPORT_LEVEL_PRODUCT_CATELOG 时,暂不支持通过代理商 id 拉取数据。

请求示例


curl 'https://api.e.qq.com/v1.1/async_reports/add?access_token=<ACCESS_TOKEN>&timestamp=<TIMESTAMP>&nonce=<NONCE>' \
-d 'account_id=<ACCOUNT_ID>' \
-d 'task_name=test_task_name' \
-d 'report_fields=["adgroup_id","cost"]' \
-d 'level=REPORT_LEVEL_ADGROUP_WECHAT' \
-d 'filtering=[{"field":"task_id","operator":"EQUALS","values":["1024"]}]' \
-d 'group_by=[]' \
-d 'granularity=HOURLY' \
-d 'date=2020-03-20' 
					

应答字段

名称 类型 描述
task_id
integer 任务 id

应答示例

{
    "code": 0,
    "message": "",
    "message_cn": "",
    "data": {
        "task_id": 1024
    }
}

可视化调试工具

相关阅读