发起请求

本节将为您介绍如何发起一次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.3；
• RESOURCE_NAME：表示要操作的资源，如campaigns、adcreatives；
• RESOURCE_ACTION：表示对资源的动作，如 get、add。

各接口对应的 <RESOURCE_NAME>/<RESOURCE_ACTION> 在文档中描述为接口请求路径，例如：正式环境新建一个推广计划，接口文档中描述的请求路径为 campaigns/add，完整地址为 https://api.e.qq.com/v1.3/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>' \
    -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
    } 
}