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

发起请求

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

请求URL

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

其中:

  • 协议:正式环境和沙箱环境均使用 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.1/campaigns/add

HTTP Method

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

HTTP Header

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

Content-Type: application/json

编码方式

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

接口调用限制

类别 限制描述
接口功能 不同应用程序在接口功能上可能存在差异,由开发者创建应用的时候根据应用的使用场景进行选择
调用天频次 1、目前custom_audience_files/add及custom_tag_files/add两个接口对每个应用程序都有调用天频次限制, 其余接口均没有天频次限制
2、达到限制后,您当日将无法继续调用超限的接口,第二天可自动恢复正常
3、如需要调整限制可以联系您的运营接口人
调用分钟频次 1、系统对每个应用程序调用每个接口都有调用分钟频次限制,不同应用等级下的调用次数不同,具体可通过应用程序管理页面了解
2、达到限制后,您需要暂停对该接口的调用,5分钟后可自动恢复正常
3、如需要调整限制可以联系您的运营接口人

特殊字符限制

如无特殊声明,API接口所有输入参数的值均不能包含以下这些特殊字符:< > & ‘ ” / \ 以及TAB、换行、回车键。

请求通用参数

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、所有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
    } 
}