商品推广（版本 3）迁移指南

商品推广 API 版本 3 引入了用于创建并管理商品推广活动的简化界面。

亮点：

• 亚马逊广告 API 与广告平台之间的功能对等
• 错误响应功能增强，更有利于问题排查
• 整合了扩展接口和列表接口
• 能够在 POST 和 PUT 请求中针对创建或更新响应来请求获取完整对象
• 使用广泛匹配或精准匹配来根据名称筛选列出操作

接口对等参数

| 版本 2 接口 | 版本 3 接口 | |----------------------------------------------------------------- |--- | | POST v2/sp/campaigns | POST /sp/campaigns | | PUT /v2/sp/campaigns | PUT /sp/campaigns | | GET /v2/sp/campaigns
GET /v2/sp/campaigns/{campaignId}
GET /v2/sp/campaigns/extended
GET /v2/sp/campaigns/{campaignId}/extended
| POST /sp/campaigns/list | | DELETE /v2/sp/campaigns/{campaignId} | POST /sp/campaigns/delete | | POST v2/sp/adGroups | POST /sp/adGroups | | PUT /v2/sp/adGroups | PUT /sp/adGroups | | GET /v2/sp/adGroups
GET /v2/sp/adGroups/{adGroupId}
GET /v2/sp/adGroups/extended
GET /v2/sp/adGroups/{adGroupId}/extended | POST /sp/adGroups/list | | DELETE /v2/sp/adGroups/{adGroupId} | POST /sp/adGroups/delete | | POST v2/sp/productAds | POST /sp/productAds | | PUT /v2/sp/productAds | PUT /sp/productAds | | GET /v2/sp/productAds
GET /v2/sp/productAds/{adId}
GET /v2/sp/productAds/extended
GET /v2/sp/productAds/{adId}/extended | POST /sp/productAds/list | | DELETE /v2/sp/productAds/{adId} | POST /sp/productAds/delete | | POST v2/sp/keywords | POST /sp/keywords | | PUT /v2/sp/keywords | PUT /sp/keywords | | GET /v2/sp/keywords
GET /v2/sp/keywords/{keywordId}
GET /v2/sp/keywords/extended
GET /v2/sp/keywords/{keywordId}/extended | POST /sp/keywords/list | | DELETE /v2/sp/keywords/{keywordId} | POST /sp/keywords/delete | | POST v2/sp/negativeKeywords | POST /sp/negativeKeywords | | PUT /v2/sp/negativeKeywords | PUT /sp/negativeKeywords | | GET /v2/sp/negativeKeywords
GET /v2/sp/negativeKeywords/{keywordId}
GET /v2/sp/negativeKeywords/extended
GET /v2/sp/negativeKeywords/{keywordId}/extended | POST /sp/negativeKeywords/list | | DELETE /v2/sp/negativeKeywords/{keywordId} | POST /sp/negativeKeywords/delete | | POST v2/sp/campaignNegativeKeywords | POST /sp/campaignNegativeKeywords | | PUT /v2/sp/campaignNegativeKeywords | PUT /sp/campaignNegativeKeywords | | GET /v2/sp/campaignNegativeKeywords
GET /v2/sp/campaignNegativeKeywords/{keywordId}
GET /v2/sp/campaignNegativeKeywords/extended
GET /v2/sp/campaignNegativeKeywords/{keywordId}/extended | POST /sp/campaignNegativeKeywords/list | | DELETE /v2/sp/campaignNegativeKeywords/{keywordId} | POST /sp/campaignNegativeKeywords/delete | | POST v2/sp/targets | POST /sp/targets | | PUT /v2/sp/targets | PUT /sp/targets | | GET /v2/sp/targets
GET /v2/sp/targets/{targetId}
GET /v2/sp/targets/extended
GET /v2/sp/targets/{targetId}/extended | POST /sp/targets/list | | DELETE /v2/sp/targets/{targetsId} | POST /sp/targets/delete | | POST v2/sp/negativeTargets | POST /sp/negativeTargets | | PUT /v2/sp/negativeTargets | PUT /sp/negativeTargets | | GET /v2/sp/negativeTargets
GET /v2/sp/negativeTargets/{targetId}
GET /v2/sp/negativeTargets/extended
GET /v2/sp/negativeTargets/{targetId}/extended | POST /sp/negativeTargets/list | | DELETE /v2/sp/negativeTargets/{targetsId} | POST /sp/negativeTargets/delete |

编号

所有实体编号（广告活动、广告组、广告等）现在都可被识别为字符串而不是整数。

日期格式

日期（例如，广告活动startDate）应采用 YYYY-MM-DD 格式。这与版本 2 有所不同，其标准日期格式为 YYYYMMDD。

GET 与LIST 操作

商品推广（版本 2）主要使用 GET 请求来读取资源。在版本 2 中，大多数资源都有四个独立的 GET 接口：批量获取、单独实体获取、批量扩展和单独扩展。在版本 3 中，所有读取操作都以 POST 操作的形式实现。这使您能够在请求消息体中使用筛选器来按实体编号、状态、关键词等条件进行筛选。

调用示例

以下示例向您展示了如何列出所有已启用的商品推广活动。

curl --location --request POST 'https://advertising-api.amazon.com/sp/campaigns/list' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxx' \
--header 'Accept: application/vnd.spCampaign.v3+json' \
--header 'Content-Type: application/vnd.spCampaign.v3+json' \
--data-raw '{
  "stateFilter": {
    "include": [
      "ENABLED"
    ]
  },
  "maxResults": 10
}'

批量存档

现在，您可以在一次调用中对多个实体（广告活动、广告组、广告等）进行存档。

示例

curl --location --request POST 'https://advertising-api.amazon.com/sp/campaigns/delete' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxx' \
--header 'Accept: application/vnd.spCampaign.v3+json' \
--header 'Content-Type: application/vnd.spCampaign.v3+json' \
--data-raw '{
  "campaignIdFilter": {
    "include": [
      "campaignId1",
      "campaignId2"
    ]
  }
}'

用于检查预算规则应用情况的最新工作流程

在版本 2 中，GET v2/sp/campaigns 和 GET v2/sp/campaigns/{campaignId} 响应包含一个 ruleBasedBudget 对象，该对象用于指定是否有预算规则正在进行广告活动处理，以及是否已应用新的预算。版本 3 POST sp/campaigns/list 不包含单独的预算规则对象。相反，如果广告活动的预算受到预算规则的影响，则由 POST /sp/campaigns/list 返回的广告活动预算对象中将包含 effectiveBudget 字段。

您可以使用 effectiveBudget 作为已应用预算规则的指标，然后使用 GET /sp/campaigns/{campaignId}/budgetRules 检索该广告活动的完整预算规则历史记录。

GET /sp/campaigns/{campaignId}/budgetRules 的响应类似于：

{
    "associatedRules": [
        {
            "createdDate": 1666126775339,
            "lastUpdatedDate": 1666126775339,
            "ruleDetails": {
                "budgetIncreaseBy": {
                    "type": "PERCENT",
                    "value": 99.0
                },
                "duration": {
                    "dateRangeTypeRuleDuration": {
                        "endDate": null,
                        "startDate": "20221018"
                    },
                    "eventTypeRuleDuration": null
                },
                "name": "Test 3",
                "performanceMeasureCondition": null,
                "recurrence": {
                    "daysOfWeek": null,
                    "type": "DAILY"
                },
                "ruleType": "SCHEDULE"
            },
            "ruleId": "5582d17b-cea1-468f-9694-faf2fa2705da",
            "ruleState": "ACTIVE",
            "ruleStatus": "ACTIVE",
            "ruleStatusDetails": {
                "reasonCode": null,
                "status": "ACTIVE"
            }
        }
    ]
}

您可以使用 ruleStatus 字段来了解哪条规则对广告活动产生了影响。ruleStatus 显示为 ACTIVE 表示该规则当前正在应用于广告活动预算。您可以在预算规则评估中进一步了解可能的状态及其含义。

您也可以使用 GET /sp/campaigns/{campaignId}/budgetRules/budgetHistory 查看特定广告活动的完整规则应用情况的历史记录。

产品广告

KDP 作者现在可以使用 customText 字段来通过自定义广告文案创建产品广告。进一步了解。

扩展的商品投放

版本 3 商品投放中提供了新的谓词类型 (ASIN_EXPANDED_FROM)。您可以借助单独的定向子句，使用扩展的商品投放来投放单独的 ASIN 以及类似的 ASIN。

要进一步了解，请参阅商品投放概述。

广告活动否定投放

供应商现在可以为自动广告活动和手动广告活动创建广告活动级别的否定投放内容。卖家只能为自动广告活动创建广告活动否定投放内容。

要进一步了解，请参阅否定商品投放。

枚举大小写规则

版本 3 中的所有枚举（包括状态和投放表达式类型）都改用大写（UPPER_CASE）惯例。

投放内容谓词更改示例：

| 版本 2 | 版本 3 | |--- |--- | | queryBroadRelMatches | QUERY_BROAD_REL_MATCHES | | queryHighRelMatches | QUERY_HIGH_REL_MATCHES | | asinAccessoryRelated | ASIN_ACCESSORY_RELATED | | asinSubstituteRelated | ASIN_SUBSTITUTE_RELATED | | sinCategorySameAs | ASIN_CATEGORY_SAME_AS | | asinBrandSameAs | ASIN_BRAND_SAME_AS | | asinPriceLessThan | ASIN_PRICE_LESS_THAN | | asinPriceBetween | ASIN_PRICE_BETWEEN | | asinPriceGreaterThan | ASIN_PRICE_GREATER_THAN | | asinReviewRatingLessThan | ASIN_REVIEW_RATING_LESS_THAN | | asinReviewRatingBetween | ASIN_REVIEW_RATING_BETWEEN | | asinReviewRatingGreaterThan | ASIN_REVIEW_RATING_GREATER_THAN | | asinSameAs | ASIN_SAME_AS | | asinIsPrimeShippingEligible | ASIN_IS_PRIME_SHIPPING_ELIGIBLE | | asinAgeRangeSameAs | ASIN_AGE_RANGE_SAME_AS | | asinGenreSameAs | ASIN_GENRE_SAME_AS | | | |

接受用于版本控制的标头

版本 3 接口的版本控制由Accept 和 Content-Type 标头控制，而不受路径控制。对于每个接口，请查看 Media-type 下拉列表，以了解 Accept 和 Content-Type 标头应使用的值。

Prefer 标头

您可以使用 Prefer 标头来指定是否要将完整的对象表示形式作为响应的一部分。如果您不指定 Prefer 标头，则只会在响应中看到已创建的实体的编号。

指的是给出对象在原始请求中的顺序的索引。

文档改进

• 适用于创建手动广告活动 和自动广告活动的操作指南。
• 资源指南现可用于广告活动、广告组、关键词、商品投放、自动投放以及更多产品。

Postman 集合

所有版本 3 的 CRUD 接口均可在亚马逊广告 API Postman 集合中使用。您可以通过 GitHub下载集合和环境文件。

版本 2 错误修复

• 产品广告现已完整推出，因此您可以了解创建成功或失败的内容。