入门与指南专题介绍帐号管理营销资产广告管理数据洞察人群管理数据接入接口清单
授权认证 帐号管理 营销资产 广告管理 数据洞察 辅助工具 用户行为数据 用户人群数据 用户标签数据 用户属性数据
附录

发起请求

本节将为您介绍如何发起一次API请求。


请求URL

Marketing API 请求URL约定了使用的协议、域名、模块、版本、资源及动作,详细定义如下:

    • 正式环境为 https://api.e.qq.com/<API_VERSION>/<RESOURCE_NAME>/<RESOURCE_ACTION>
    • 沙箱环境为 https://sandbox-api.e.qq.com/<API_VERSION>/<RESOURCE_NAME>/<RESOURCE_ACTION>

其中:

    • 协议:正式环境和沙箱环境均使用 HTTPS;
    • API_VERSION:版本号,当前最新版本号为 v1.1;
    • RESOURCE_NAME:表示要操作的资源,如campaigns、adcreatives;
    • RESOURCE_ACTION:表示对资源的动作,如 get、add。

各接口对应的 <RESOURCE_NAME>/<RESOURCE_ACTION> 在文档中描述为接口请求路径,例如:正式环境新建一个推广计划,接口文档中描述的请求路径为 campaigns/add,完整地址为 https://api.e.qq.com/v1.0/campaigns/add。

HTTP Method

调用方应根据具体接口的要求设置 HTTP Method为 GET或POST。

HTTP Header

调用方应遵循HTTP协议设置相应的 Header,目前支持的Header有:Content-Type,用于指定数据格式。例如:

Content-Type: application/json

编码方式

Marketing API支持的编码方式为 UTF-8。

请求通用参数

1、每个请求接口中的均需传入以下通用参数,详细定义如下表所示:

名称 类型 必填 限制 描述
access_token string 以Query Parameter方式在请求路径中传递。 授权令牌,完成 OAuth 2.0 授权后获得,参考【授权认证】章节。
timestamp timestamp 以Query Parameter方式在请求路径中传递。 当前的时间戳,单位为秒,允许客户端请求最大时间误差为300秒。

  • MarketingAPI 所使用的时间戳,若无特殊说明,均为秒级时间戳
  • MarketingAPI 所使用的时区为GMT+8,例如当时间戳为1494840119时,表示 2018-05-15 17:21:59
nonce string 以Query Parameter方式在请求路径中传递。 随机字串标识,不超过32个字符,由调用方自行生成,需保证全局唯一性。

2、在V1.1版本的get接口中,请求参数增加fields字段,用于指定返回的字段列表。

名称 类型 必填 限制 描述
fields string[] 指定返回的字段列表,为选填字段,如不填写,则根据默认值进行返回

增加fields的接口以及默认值如下表:

advertiser/get account_id
funds/get fund_type,balance,fund_status,realtime_cost
fund_statements_daily/get fund_type,trade_type,time,amount,description
fund_statements_detailed/get time,external_bill_no,trade_type,amount,description
realtime_cost/get campaign_id,adgroup_id,cost
qualifications/get industry_qualifications,ad_qualifications,additional_industry_qualifications,industry_qualifications_wechat,ad_qualifications_wechat
campaigns/get campaign_id
adgroups/get adgroup_id
adcreatives/get adcreative_id
ads/get ad_id
promoted_objects/get promoted_object_id
targetings/get targeting_id
adcreative_templates/get adcreative_template_id
capabilities/get wechat_ecommerce_product_spec,wechat_link_ad_spec
images/get image_id
dynamic_ad_images/get dynamic_ad_template_id
dynamic_creatives/get account_id
system_status/get adgroup_id
videos/get video_id
targeting_tags/get id,name,parent_id,parent_name,city_level
estimation/get approximate_count,impression,min_bid_amount,max_bid_amount
daily_reports/get date
hourly_reports/get hour
targeting_tag_reports/get date
pages/get page_id
tracking_reports/get date,hour
async_tasks/get task_id
custom_audiences/get audience_id
custom_audience_files/get custom_audience_file_id
custom_audience_insights/get dimension_type,match_rate,distribution
custom_audience_estimations/get user_count
custom_audience_reports/get user_count
user_action_sets/get user_action_set_id
user_action_set_reports/get date
user_property_sets/get user_property_set_id
analyse_results/get external_user_id
predictive_lead_scoring/get external_user_id
custom_tags/get tag_id
product_catalogs/get product_catalog_id
dynamic_ad_templates/get dynamic_ad_template_id
ecommerce_order/get ecommerce_order_id
shop_property_sets/get shop_property_set_id
adcreative_previews/get user_id
custom_tag_files/get tag_id,custom_tag_file_id
wechat_pages/get page_id
wechat_articale_pages/get page_id
product_brands/get external_brand_id
product_categories/get external_category_id
product_combines/get external_combine_product_id
product_commission_rules/get external_commission_rule_id
product_coupons/get external_coupon_id
product_promotions/get external_promotion_id
product_salesinfos/get external_store_id
product_skus/get external_sku_id
product_spus/get external_spu_id
stores/get external_store_id
data_warehouses/get data_warehouse_id
union_position_packages/get union_package_id
union_position_daily_reports/get union_position_id
analyse_tasks/get analyse_task_id
audience_launches/get audience_id
custom_feature_class_project_grants/get project_id
custom_feature_classes/get feature_class_id
custom_features/get feature_id
dataset_files/get dataset_file_id
datasets/get dataset_id
split_tests/get split_test_id
credit_bills/get repaid_amount
wechat_leads/get agency_id,agency_name,campaign_id,campaign_name,adgroup_id,adgroup_name,click_id,leads_info
leads/get campaign_id,campaign_name,adgroup_id,adgroup_name,wechat_agency_id,wechat_agency_name,wechat_campaign_id,wechat_campaign_name,wechat_adgroup_id,wechat_adgroup_name,click_id,lead_spec_list
wechat_funds/get fund_type,balance,credit_roll_spec,miniprogram_spec
wechat_fund_statements_detailed/get time,bill_number,amount,fund_type,description
wechat_credit_bills/get repaid_amount,need_repay_amount,bill_date,start_time,end_time,due_time
wechat_advertiser/get account_id
product_items/get product_outer_id
diagnosis/get adgroup_id
business_manager_relations/get account_id,corporation_name
xijing_template/get page_template_id,page_type,page_name,page_title,component_spec_list,mobile_app_id
adcreative_template_detail/get adcreative_template_id
custom_data_salt/get salt_id
product_items_detail/get feed_id,system_status,reject_message,product_item_spec
products_system_status/get feed_id,product_id,system_status,reject_message
product_catalogs_reports/get product_catalog_id
android_channel_packages/get android_app_id,channel_package_id,package_name
advertiser_reports/get account_id
campaign_reports/get account_id
adgroup_reports/get account_id
dynamic_ad_templates/add dynamic_ad_template_id
wechat_ad_labels/get label_category,label

完整请求示例 

API请求中需要提供必要的通用参数、每个接口要求的参数,并声明正确的编码方式。以curl发起请求获取和创建一个推广计划为例。

获取一个推广计划:

curl 'https://api.e.qq.com/v1.1/campaigns/get?access_token=<ACCESS_TOKEN>&timestamp=<TIMESTAMP>&nonce=<NONCE>' \
    -H 'Content-Type: application/json' \
    -d 'account_id=51959'
    -d 'fields=["campaign_id","campaign_name","campaign_type", "daily_budget"]'


< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
<
{ 
    "code":0,
    "message":"",
    "data":
    {
        "list":[  
            {  
                "campaign_id":12345,
                "campaign_name":"推广计划1",
                "campaign_type":"CAMPAIGN_TYPE_NORMAL",
                "daily_budget":1000000
            },
            {  
                "campaign_id":12346,
                "campaign_name":"推广计划2",
                "campaign_type":"CAMPAIGN_TYPE_NORMAL",
                "daily_budget":10000
            },
       "page_info":{  
            "page":1,
            "page_size":2,
            "total_number":2,
            "total_page":1
        }
    } 
}

创建一个推广计划:

curl 'https://api.e.qq.com/v1.1/campaigns/add?access_token=<ACCESS_TOKEN>&timestamp=<TIMESTAMP>&nonce=<NONCE>' \
    -H 'Content-Type: application/json' \
    -d '{
        "account_id": 51959,
        "campaign_name": "test",
        "campaign_type": "CAMPAIGN_TYPE_NORMAL",
        "daily_budget": 10000,
        "promoted_object_type","PROMOTED_OBJECT_TYPE_APP_IOS"
    }'

* Connected to api.e.qq.com (10.10.10.10) port 443 (#0)

> POST / HTTP/1.1
> User-Agent: curl/7.41.0
> Host: api.e.qq.com
> Content-Type: application/json
> Content-Length: 64
* upload completely sent off: 64 out of 64 bytes

< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
<
{ 
    "code":0,
    "message":"",
    "data":
    {
        "campaign_id":23456
    } 
}