开发人员指南概述

亚马逊广告 API 概览

开始使用搜索广告报告（版本 3 ）

本教程概述了如何异步请求和下载搜索广告活动的报告。

由于亚马逊广告 API 报告是异步的，因此您需要进行三步调用才能生成报告：

  1. 请求报告
  2. 等待报告生成
  3. 下载报告

提示：请在 Postman 中尝试

使用亚马逊广告 API Postman 集合的 Reporting 文件夹来按照本教程进行操作。有关设置说明，请参阅亚马逊的 Postman 教程。

标头

本教程中描述的每个请求都需要四个标头参数：

参数 描述
Amazon-Advertising-API-ClientId 与您的 Login with Amazon 应用程序关联的客户端编号。用于身份验证。
Authorization 您的访问令牌。用于身份验证。
Amazon-Advertising-API-Scope 与特定站点中广告账户关联的配置文件标识符。确保您对与配置文件关联的站点使用的是正确的基本 URL。
Content-Type 设置为 application/vnd.createasyncreportrequest.v3+json。

有关 API 身份验证的简介，请参阅授权概述。

请求报告

版本 3 报告支持多种报告类型、时间段和指标。有关支持配置的更多信息，请参阅报告类型。

所有报告请求都使用单个接口： POST /reporting/reports。有关参数的详细信息，请参阅 API 参考。

timeUnit 和支持的列 (columns)

timeUnit 可以设置为 DAILY 或 SUMMARY。如果您将 timeUnit 设置为 DAILY，则应在“columns”列表中包含 date。如果您将 timeUnit 设置为 SUMMARY，则应在“columns”列表中包含 startDate 和 endDate。

请求体示例： 摘要

{
    "name":"SP campaigns report 7/5-7/10",
    "startDate":"2022-07-05",
    "endDate":"2022-07-10",
    "configuration":{
        "adProduct":"SPONSORED_PRODUCTS",
        "groupBy":["campaign"],
        "columns":["impressions","clicks","cost","campaignId","startDate","endDate"],
        "reportTypeId":"spCampaigns",
        "timeUnit":"SUMMARY",
        "format":"GZIP_JSON"
    }
}

请求体示例： 每日 (DAILY)

{
    "name":"SP campaigns report 7/5-7/10",
    "startDate":"2022-07-05",
    "endDate":"2022-07-10",
     "configuration":{
        "adProduct":"SPONSORED_PRODUCTS",
        "groupBy":["campaign"],
        "columns":["impressions","clicks","cost","campaignId","date"],
        "reportTypeId":"spCampaigns",
        "timeUnit":"DAILY",
        "format":"GZIP_JSON"
    }
}

groupBy

所有报告请求都需要在报告配置中使用 groupBy 参数。GroupBy 决定了报告的粒度级别。请参阅报告类型以查看每种报告类型有哪些可用的 groupBy 值。如果报告类型支持，您可以在请求中使用多个 groupBy 值。

筛选条件

筛选条件是在请求的 groupBy 级别确定的。要了解有哪些筛选条件可用，请参阅报告类型。

注意

您只能使用报告配置中包含的所有 groupBy 值都支持的筛选条件。

使用筛选条件的请求体示例

{
    "name":"SP campaigns report 7/5-7/10",
    "startDate":"2022-07-05",
     "endDate":"2022-07-10",
    "configuration":{
        "adProduct":"SPONSORED_PRODUCTS",
        "groupBy":["campaign"],
        "columns":["impressions","clicks","cost","campaignId","startDate","endDate"],
        "reportTypeId":"spCampaigns",
        "timeUnit":"SUMMARY",
        "format":"GZIP_JSON",
         "filters": [
            {
                "field": "campaignStatus",
                "values": ["ENABLED","PAUSED"]
            }
        ]
    }
}

请求示例

此示例显示了在 7 月 5 日至 7 月 21 日期间某个商品推广活动摘要报告的请求。

注意

本教程中的调用示例采用北美 API 接口 (https://advertising-api.amazon.com)。请参阅 API 概述，了解根据您所在的站点应使用的区域接口。

curl --location --request POST 'https://advertising-api.amazon.com/reporting/reports' \
--header 'Content-Type: application/vnd.createasyncreportrequest.v3+json' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxx' \
--data-raw '{
    "name":"SP campaigns report 7/5-7/10",
    "startDate":"2022-07-05",
    "endDate":"2022-07-10",
    "configuration":{
        "adProduct":"SPONSORED_PRODUCTS",
        "groupBy":["campaign","adGroup"],
        "columns":["campaignId","adGroupId","impressions","clicks","cost","purchases1d","purchases7d","purchases14d","purchases30d","startDate","endDate"],
        "reportTypeId":"spCampaigns",
        "timeUnit":"SUMMARY",
        "format":"GZIP_JSON"
    }
}'

响应

成功的请求会生成 200 响应，其中包括请求的报告配置、reportId 和 status。请记下 reportId，以便在下一步中使用。

{
    "configuration": {
        "adProduct": "SPONSORED_PRODUCTS",
        "columns": [
            "campaignId",
            "adGroupId",
            "impressions",
            "clicks",
            "cost",
            "purchases1d",
            "purchases7d",
            "purchases14d",
            "purchases30d",
            "startDate",
            "endDate"
        ],
        "filters": null,
        "format": "GZIP_JSON",
        "groupBy": [
            "campaign",
            "adGroup"
        ],
        "reportTypeId": "spCampaigns",
        "timeUnit": "SUMMARY"
    },
    "createdAt": "2022-07-19T14:03:00.853Z",
    "endDate": "2022-07-05",
    "failureReason": null,
    "fileSize": null,
    "generatedAt": null,
    "name": "SP campaigns report 7/5-7/21",
    "reportId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
    "startDate": "2022-07-05",
    "status": "PENDING",
    "updatedAt": "2022-07-19T14:03:00.853Z",
    "url": null,
    "urlExpiresAt": null
}

检查报告状态

成功进行 POST 调用后，报告生成最多可能需要 3 小时。

您可以通过使用初始请求中返回的 reportId 来调用 GET 报告接口，以检查报告生成状态： GET /reporting/reports/{reportId}。

请求示例

curl --location --request GET 'https://advertising-api.amazon.com/reporting/reports/xxxxx-xxxxx-xxxxx' \
--header 'Content-Type: application/vnd.createasyncreportrequest.v3+json' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxxxx'  \

所有对 GET 状态接口的成功调用都会返回 200 状态码。要检查报告生成过程是否已完成，请检查响应体中的 status 参数。如果报告仍在生成过程中，则 status 设置为 PENDING 或 PROCESSING。

当您的报告准备就绪可供下载时，status 将返回 COMPLETED，并且 url 字段中将显示一个地址。

提示

报告的生成可能需要长达三个小时。反复调用查看报告状态可能会生成 429 响应，这表明您的请求已被限制。要以程序化方式检索报告，您的应用程序逻辑应在请求之间设置延迟。有关更多信息，请参阅带有指数退避功能的重试逻辑。

下载报告

报告准备就绪后，GET reporting/reports/{reportId} 的 url 字段包含指向 S3 存储桶的链接，您可以通过该链接下载报告。您可以使用 cURL 进行 GET 调用，或在浏览器中输入 URL。

阅读您的报告

解压缩报告文件后，即可看到报告的原始 JSON。本教程中使用的示例报告可能类似于：


[
    {
        "purchases7d":2,
        "cost":14.5,
        "purchases30d":3,
        "endDate":"2022-07-10",
        "campaignId":158410630682987,
        "clicks":13,
        "purchases1d":1,
        "impressions":2216,
        "adGroupId":72320882861500,
        "startDate":"2022-07-05",
        "purchases14d":3
    },
    {
        "purchases7d":2,
        "cost":9.45,
        "purchases30d":2,
        "endDate":"2022-07-10",
        "campaignId":158410630682987,
        "clicks":10,
        "purchases1d":2,
        "impressions":3721,
        "adGroupId":55720282058882,
        "startDate":"2022-07-05",
        "purchases14d":2
    }
]

此示例返回两个商品推广活动的展示量、点击量和成本数据。

提示

要获取广告活动元数据，可以请求快照，然后使用 campaignId 连接两个数据集。

现在您可以生成报告了，请进一步了解以下内容：

Amazon Advertising logo