开发人员指南概述

亚马逊广告 API 概览

品牌安全开发人员指南

展示型推广品牌安全 API 可用于在“亚马逊品牌注册”中注册的供应商和卖家，适用地区为美国、加拿大、英国、德国、西班牙、法国、意大利、荷兰、巴西、墨西哥和阿联酋。展示型推广可以在第三方网站和移动应用上投放站内和站外广告。品牌安全功能可让您更好地控制广告的投放位置，从而保护您的品牌并阻止广告在与您的品牌政策不一致的第三方网站上投放。您可以上传一个域/移动应用的列表，在这些域/应用中，您希望阻止广告在您的展示型推广活动中展示。这项功能将在广告主级别提供，从而使每个广告主都能控制其广告在亚马逊站外的展示位置。

注意

亚马逊广告制定了全球品牌安全政策，该政策采取了各种措施来防止您的广告出现在包含敏感内容、商品和服务的网页和应用中。

具体而言，我们不允许投放以下内容类别的广告：

独立的品牌安全提供商会持续更新亚马逊的列表，筛选出以上类别的内容。此外，根据亚马逊的“受限商品政策”和“社区准则”，某些商品会被禁止，或者需要遵守其他要求。即使是“受限商品政策”允许的某些商品，亚马逊也可能不会展示其广告，例如性健康用品或敏感的历史纪念品。

在建立品牌安全列表时，您无需列举所有可能的网站，因为亚马逊品牌安全将针对上面列出的类别提供保护。您的列表中应包含与您的品牌政策不一致（或任何其他业务原因）的网站。

每个广告主配置一个品牌安全列表。您可以向品牌安全列表上传条目，每个请求可增加 10,000 个条目，其中条目可以是网站或移动应用。

可用于创建和管理禁止列表的主要 API 是 /sd/brandSafety/deny。它包含以下操作：

  1. 检索条目： GET /sd/brandSafety/deny
  2. 将条目追加到列表中： POST /sd/brandSafety/deny
  3. 删除列表： DELETE /sd/brandSafety/deny

注意

POST 和 DELETE 操作是异步的，而 GET 操作是同步的。

亚马逊目前不支持更新列表。如果您需要修改或从列表中移除条目，则需要删除列表并重新上传列表。如果您没有列表的本地副本，可以使用 GET /sd/brandSafety/deny 接口下载列表。

当您执行上述操作时，您将获得一个 requestId，用于确认请求已得到处理。

{
 "requestId": "<string>"
}

然后，您可以使用 GET /sd/brandSafety/:requestId/status API 来检索传入 requestId 的 API 的状态。当此 API 返回 COMPLETED 时，此操作已完成，但此 API 不会告诉您操作的实际结果。

{
 "status": "COMPLETED",
 "statusDetails": "some details"
}

您需要使用 GET /sd/brandSafety/:requestId/results API 来检索操作的实际结果。删除列表时，此操作不可用。有关验证已删除列表的详细信息，将在本文档后面介绍。您可以检查各个域条目以了解特定域是否已成功更新。

{
 "results": [
  {
   "status": "SUCCESS",
   "details": "<string>",
   "domainId": "<long>",
   "name": "<string>"
  },
  {
   "status": "SUCCESS",
   "details": "<string>",
   "domainId": "<long>",
   "name": "<string>"
  }
 ]
}

建立品牌安全列表

您可以建立品牌安全列表，禁止以下内容：

注意

您不能阻止单个网页，例如 index.html。当网站不包含网页时，例如 www.example.com/someURI，通常假定实际链接为 www.example.com/someURI/index.html。

网站格式为 example.com 或 example.net，并且必须遵循此处规定的域命名标准。此外，仅支持 ASCII 字符。该列表不支持来自非 ASCII 字符集的字符表示。

品牌安全列表是使用 POST /sd/brandSafety/deny 操作创建的，方法是在请求中包含以下 payload。

{
    "domains": [
        {
            "name": "example.com",
            "type": "WEBSITE"
        },
        {
            "name": "com.example.myapp",
            "type": "APP"
        },
        {
            "name": "1234567890",
            "type": "APP"
        }
    ]
}

使用 API 时，您最多可以在列表中添加 10K 个条目。如果您需要发送超过 10K 的条目，则需要在另一个请求中发送条目。

说明

前提条件：

在本节中，您将运行 API 请求来管理品牌安全列表。已经提供了一个包含预配置请求的 Postman 集合。当您运行请求时，它将捕获响应信息作为变量，以便在后续请求中使用。在运行这些请求之前，您需要使用 OAuth 刷新令牌请求获取刷新令牌，或者在 Postman 脚本中手动添加一个刷新令牌。

有关设置环境的更多信息，请参阅此处。

使用案例 1： 将域/移动应用添加到品牌安全列表

使用 POST /sd/brandSafety/deny 操作将条目添加到品牌安全列表中。

注意

如果您需要将现有域列表从 CSV 文件转换为 JSON，可以使用多种免费工具在格式之间进行转换。

{
    "domains": [
        {
            "name": "foo.com",
            "type": "WEBSITE"
        },
        {
            "name": "api.example.com",
            "type": "WEBSITE"
        },
        {
            "name": "com.example.app",
            "type": "APP"
        },
        {
            "name": "1234567890",
            "type": "APP"
        }
    ]
}

响应返回以下内容：

{
    "requestId": "a2fd14cb81c72cb32ac071e13b105f14"
}

当您使用 GET /sd/brandSafety/:requestId/status 操作立即查看状态时，您可能会看到以下内容：

{
    "status": "IN_PROGRESS",
    "statusDetails": "Your request is still in progress.Please check again later."
}

几分钟后，当您再次尝试请求时（取决于列表的大小），您将看到以下内容：

{
    "status": "COMPLETED",
    "statusDetails": "Your request has been completed.For POST requests, you can check your request results at /sd/brandSafety/a2fd14cb81c72cb32ac071e13b105f14/results to check the status of each domain in the request.For DELETE requests you can call GET /sd/brandSafety/deny to verify that your Brand Safety Deny List is now empty."
}

您可以使用以下操作查看 requestId 的详细响应： GET /sd/brandSafety/:requestId/results

{
    "results": [
        {
            "status": "SUCCESS",
            "details": "Domain successfully added",
            "domainId": 5750546536593170213,
            "name": "foo.com"
        },
        {
            "status": "SUCCESS",
            "details": "Domain successfully added",
            "domainId": 6337651429473114930,
            "name": "api.example.com"
        },
        {
            "status": "SUCCESS",
            "details": "Domain successfully added",
            "domainId": 8394201756681458405,
            "name": "com.example.app"
        },
        {
            "status": "SUCCESS",
            "details": "Domain successfully added",
            "domainId": 8662947689235204460,
            "name": "1234567890"
        }
    ]
}

您可以使用以下操作验证完整的域列表： GET /sd/brandSafety/deny

{
    "domains": [
        {
            "domainId": 5750546536593170213,
            "name": "foo",
            "type": "WEBSITE",
            "state": "ENABLED",
            "createdAt": "2021-04-27T18:48:20.253Z",
            "lastModified": "2021-04-27T18:48:20.253Z"
        },
        {
            "domainId": 6337651429473114930,
            "name": "api.example.com",
            "type": "WEBSITE",
            "state": "ENABLED",
            "createdAt": "2021-04-27T18:48:20.253Z",
            "lastModified": "2021-04-27T18:48:20.253Z"
        },
        {
            "domainId": 8394201756681458405,
            "name": "com.example.app",
            "type": "APP",
            "state": "ENABLED",
            "createdAt": "2021-04-27T18:48:20.253Z",
            "lastModified": "2021-04-27T18:48:20.253Z"
        },
        {
            "domainId": 8662947689235204460,
            "name": "1234567890",
            "type": "APP",
            "state": "ENABLED",
            "createdAt": "2021-04-27T18:48:20.253Z",
            "lastModified": "2021-04-27T18:48:20.253Z"
        }
    ]
}

使用案例 2： 删除品牌安全列表

如果您要删除品牌安全列表，只需调用 DELETE /sd/brandSafety/deny 操作

响应将返回以下内容：

{
    "requestId": "011686d6c372870e46e598894b7ce832"
}

几分钟后，当您使用操作 GET /sd/brandSafety/:requestId/status 检查状态时（取决于列表的大小），您会看到以下内容：

{
    "status": "COMPLETED",
    "statusDetails": "Your request has been completed.For POST requests, you can check your request results at /sd/brandSafety/a2fd14cb81c72cb32ac071e13b105f14/results to check the status of each domain in the request.For DELETE requests you can call GET /sd/brandSafety/deny to verify that your Brand Safety Deny List is now empty."
}

操作 GET /sd/brandSafety/:requestId/results 不适用于 DELETE 操作，但您可以调用 GET /sd/brandSafety/deny 操作并验证域列表是否为空。

{
    "domains": []
}

使用案例 3： 更新品牌安全列表

如果您需要更新列表中的条目，则需要使用 DELETE /sd/brandSafety/deny 操作删除列表，然后使用 POST /sd/brandSafety/deny 操作创建条目。 您可以按照“使用案例 2”中的说明进行删除，然后按照“使用案例 1”中的步骤在品牌安全列表中创建条目。

附录：

当用户修改其品牌安全禁止列表时，将以异步方式处理请求，并向用户提供 requestId。此 requestId 可用于在提交请求后最多 90 天内检查请求的状态。

Amazon Advertising logo