开发人员指南概述

亚马逊广告 API 概览

搜索广告快照入门

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

快照包含与您的广告活动相关的元数据。您可以在不同级别（例如广告活动、广告组、关键词）请求快照。快照包含请求时所需实体的信息。无法通过快照检索历史元数据。

由于快照是异步的，您需要进行三次调用来生成快照：

  1. 请求快照
  2. 等待生成快照
  3. 下载快照

提示：请在 Postman 中尝试

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

标头

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

参数 描述
Amazon-Advertising-API-ClientId 与您的“Login with Amazon”应用程序关联的客户端编号。用于身份验证。
Authorization 您的访问令牌。用于身份验证。
Amazon-Advertising-API-Scope 与特定站点中广告账户关联的配置文件标识符。
Content-Type 设置为 application/json。

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

请求快照

首先，确定您需要的快照类型。每个快照包含所选广告类型中指定广告活动实体的元数据。

  1. 选择快照的广告类型。每种类型的广告都有一个指定的接口，并具有不同的规范。从下表中选择正确的接口：

    广告类型 接口 文档
    商品推广 /v2/sp/{recordType}/snapshot 链接
    品牌推广 /v2/hsa/{recordType}/snapshot 链接
    展示型推广 /sd/{recordType}/snapshot 链接

  2. 选择快照类型。快照类型决定了返回的详情级别（例如广告组或广告活动级别）。每种类型的搜索广告支持不同的快照类型。

    有关每种搜索广告类型可用的快照类型的更多信息，请参阅快照类型。

    将所需的快照类型输入到路径中，用以替换 recordType。

  3. （可选）添加筛选条件。在请求体中，您可以添加筛选条件，通过将 stateFilter 设置为 enabled、paused 或 archived 来仅返回特定状态的实体。您可以请求获取多个状态，例如 "stateFilter": "enabled,paused"。如果未添加筛选条件，则无论状态如何，快照中将包含所有实体。

    注意

    对于展示型推广快照，您还可以根据 tactic 进行筛选，该筛选条件基于广告活动中使用的投放类型（商品投放或受众投放）对快照进行细分。如果未指定“tactic（方案）”，快照中将包含所有广告活动。

    有关详细信息，请参阅展示型推广快照参考。

  4. 要请求快照，请使用汇编的请求消息体调用所需的 POST 端点（参见第 1 步）。请注意，请求必须包含请求体，即使为空也要包含。

请求示例

以下代码片段要求在广告组级别提供商品推广快照。

如果您要复制请求示例，请确保使用与您的地理位置对应的正确 URL，并对您的账户使用有效的身份验证凭据。

curl --request POST 'https://advertising-api.amazon.com/v2/sp/adGroups/snapshot' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxxxxx' \
--header 'Amazon-Advertising-API-ClientId: xxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxx' \
--data-raw '{}'

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

    成功的响应体应类似于：

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

检查快照状态

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

您可以使用请求快照 流程的第 5 步返回的 snapshotId 调用相应的 GET 快照端点来检查快照生成状态。

广告类型 接口 文档
商品推广 /v2/sp/snapshots/(snapshotId) 链接
品牌推广 /v2/hsa/snapshots/{snapshotId} 链接
展示型推广 /sd/snapshots/(snapshotId) 链接
请求示例 
<p>如果您要复制请求示例，请确保使用适用于您所在地理位置的正确URL，以及您的账户的有效身份验证凭据和您的唯一快照标识符。</p>

```shell
curl --request GET 'https://advertising-api.amazon.com/v2/sp/snapshots/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 状态代码；对于展示型推广的 GET 状态接口的所有成功调用将返回 202 状态代码。

要检查快照生成过程是否已完成，请检查响应体中的 status 参数。如果快照仍在生成过程中，则 status 设置为 IN_PROGRESS。

{
    "snapshotId":"amzn1.clicksAPI.xxxxxx",
    "recordType":"ad Groups",
    "status":"IN_PROGRESS",
    "statusDetails":"In the process of generating Snapshot."
}

当您的快照准备好下载时，status 将返回为 SUCCESS：

{
    "snapshotId":"amzn1.clicksAPI.xxxxxx",
    "recordType":"ad Groups",
    "status":"SUCCESS",
    "statusDetails":"Snapshot has been successfully generated.",
    "location":"https://advertising-api.amazon.com/sd/snapshots/amzn1.amzn1.clicksAPI.xxxxxx/download","fileSize":371,
    "expiration":1643734785541
}

提示

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

下载快照

快照准备就绪后，请使用 snapshotId 调用相应的下载接口：

广告类型 接口 文档
商品推广 /v2/sp/snapshots/{snapshotId}/download 链接
品牌推广 /v2/hsa/snapshots/{snapshotId}/download 链接
展示型推广 /sd/snapshots/{snapshotId}/download 链接

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

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

```shell
curl --request GET 'https://advertising-api.amazon.com/v2/sp/snapshots/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 "mySnapshot.json"
```
</details>

使用快照元数据

在应用程序逻辑中使用快照来提高对亚马逊广告 API 的其他请求的效率。例如，为了最有效地生成报告，我们建议在报告请求中排除广告活动元数据，然后使用指定的 reportType 级别的实体的唯一标识符将报告结果与快照元数据进行关联。

有关每种类型的快照返回的字段的更多信息，请参阅各种广告类型和快照类型的对应字段。

Amazon Advertising logo