搜索广告报告入门

本教程介绍了如何异步请求并下载商品推广活动、品牌推广活动和展示型推广活动的报告。

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

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

提示：请在 Postman 中尝试

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

警告

自 2023 年 3 月 30 日起，版本 2 的报告功能不再支持商品推广报告。有关更多信息，请参阅搜索广告报告（版本 3）入门。

标头

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

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

请求报告

首先，定义报告的规范，包括广告和报告类型、日期和指标。

1. 选择报告的广告类型。每种类型的搜索广告都有指定的请求接口，因此请确保根据您需要的搜索广告类型使用正确的接口。

   要获取品牌推广活动和展示型推广活动的效果数据，请分别为每种类型进行单独的请求。

   注意

   每个接口的请求体参数存在差异，请查阅参考文档以获取更多信息。

   广告类型	接口	参考
   商品推广	POST /v2/sp/{recordType}/report	[DEPRECATED]
   品牌推广	POST /v2/hsa/{recordType}/report	链接
   展示型推广	POST /sd/{recordType}/report	链接

2. 选择报告类型。报告类型决定了报告中数据的细分方式（例如，按广告组或广告活动级别）。每种搜索广告类型支持不同的报告类型。将所需的报告类型输入到路径中，用以替换 recordType。

   进一步了解报告类型。

3. 构建请求体。所有广告类型都需要 reportDate 和 metrics。

   • 报告日期： 每个报告包含一天的数据。对于较长时间范围的数据，请进行多次报告请求。
   • 指标： 指标表示报告中的键值对。每种广告类型和报告类型的组合支持不同的指标。使用逗号分隔的列表形式输入指标，不含空格。进一步了解可用的指标。

   注意

   展示型推广报告请求还需要请求体参数 tactic，根据广告活动中使用的投放类型（商品投放或受众投放）对报告数据进行细分。如果同时投放使用商品投放和受众投放的广告活动，请确保请求两个版本的报告以接收完整的数据集。
   
   有关更多信息，请参阅展示型推广报告参考。

   根据您创建的报告类型，可能还有其他可选或必需的参数可用于进一步细分报告。请查阅接口参考以获取所有可用参数。

4. 要请求报告，请使用汇编的请求体调用所需的 POST 接口（参见第 1 步中的表格）。

curl --request POST 'https://advertising-api.amazon.com/v2/sd/campaigns/report' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxxxxx' \
--header 'Amazon-Advertising-API-ClientId: xxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxx' \
--data-raw '{
"reportDate": "20211102",
"metrics": "campaignId,impressions,clicks,cost"
}'

5. 成功调用将返回一个 202 响应，其中包含一个reportId 以及 status 值 IN_PROGRESS。记下 reportId，以便在下一步中使用。

   成功的响应体应类似于：

   {
       "reportId":"amzn1.clicksAPI.v1.t1.xxxxxxxxxxxxx",
       "recordType":"campaign",
       "status":"IN_PROGRESS",
       "statusDetails":"Report is being generated."
   }
   

检查报告状态

成功进行 POST 调用后，报告生成最多可能需要 15 分钟。

您可以通过使用第 4 步中返回的 reportId 调用 GET 报告接口来检查报告生成状态。

GET /v2/reports/{reportId}

请求示例

<p>如果您要复制请求示例，请确保使用适用于您所在地理位置的正确 URL，以及您的账户的有效身份验证凭据和您的唯一报告标识符。</p>

```shell
curl --request GET 'https://advertising-api.amazon.com/v2/reports/amzn1.clicksAPI.xxxxxx' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Atza|xxxxxxxxx' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxx' \
```
</details>

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

{
    "reportId":"amzn1.xxxxxxxxxx",
    "status":"IN_PROGRESS",
    "statusDetails":"Report generation is in progress."
}

当您的报告可供下载时, 其 status 返回 COMPLETE:

{
    "reportId":"amzn1.xxxxxxxxxx",
    "status":"SUCCESS",
    "statusDetails":"Report has been successfully generated.",
    "location":"https://ad-api.integ.amazon.com/v1/reports/amzn1.xxxxxxxxxx/download",
    "fileSize":150,
    "expiration":1651536000000
}

提示

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

下载报告

报告准备就绪后，请使用 reportId 调用下载接口：

GET /v2/report/{reportId}/download

成功调用将返回 307 重定向响应。重定向链接指向您可以下载报告文件的 S3 存储桶。以 JSON 格式下载的报告文件将以 Gzip 格式进行压缩。

请求示例

<p>如果您要复制请求示例，请确保使用适用于您所在地理位置的正确 URL，以及您的账户的有效身份验证凭据和您的唯一报告标识符。</p>

<p>如果使用 cURL 请求，则应使用 `--output` 标志来指定报告数据的文件。</p>

```shell
curl --request GET 'https://advertising-api.amazon.com/v2/reports/amzn1.clicksAPI.xxxxxx/download' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Atza|xxxxxxxxx' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxx' \
--output "myReport.json"
```
</details>

阅读您的报告

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

[
    {
        "campaignId":123456789,
        "impressions":55,
        "clicks":2,
        "cost":3.5
    },
    {
        "campaignId":123456780,
        "impressions":32,
        "clicks":3,
        "cost":5.3
    }
]

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

提示

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

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

• 指标
• API 与广告平台之间的报告差异
• 报告类型

• © 2023 Amazon.com, Inc. or its affiliates.
• Conditions of Use
• Privacy Notice
• License Agreement
• Data Policies