开发人员指南概述

亚马逊广告 API 概览

开始使用策略性建议 API

接口

策略性建议 API 支持以下三个 API 接口：

  1. POST /recommendations/list - 为广告主列出所有可用的策略性广告活动建议。合作伙伴和广告主可以使用筛选条件（包括广告产品、建议类型等）来筛选结果。
  2. PUT /recommendations/{recommendationId} - 更新建议的值。
  3. POST /recommendations/apply - 应用一个或多个建议，一次最多 100 个。

前提条件

要调用所有三个接口，您需要以下标头进行授权。

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

商品信息建议

如果建议可用，广告主和合作伙伴可以使用 POST /recommendations/list 接口请求建议列表。此接口支持各种筛选条件，您可以使用这些筛选条件对返回的建议进行自定义。

支持的筛选条件值

您可以使用以下一个或多个筛选条件组合，以缩小特定建议的范围。

| 字段 | 可能的值 | |--- |--- | | RECOMMENDATION_ID | string | | AD_PRODUCT | [SP、SB、SD] 中的一个 | | RECOMMENDATION_TYPE | 查看所有建议类型的描述。[NEW_CAMPAIGN、NEW_VIDEO_CAMPAIGN、NEW_AD_GROUP、CAMPAIGN_BIDDING_STRATEGY、CAMPAIGN_BUDGET、CAMPAIGN_END_DATE、CAMPAIGN_TOP_PLACEMENT、CAMPAIGN_PRODUCT_PLACEMENT、CAMPAIGN_STATE、NEW_CAMPAIGN_BIDDING_RULE、CAMPAIGN_BIDDING_RULE、NEW_CAMPAIGN_BUDGET_RULE、CAMPAIGN_BUDGET_RULE、AD_GROUP_STATE、AD_GROUP_DEFAULT_BID、AD_GROUP_BID_OPTIMIZATION、NEW_KEYWORD、KEYWORD_BID、KEYWORD_STATE、NEW_NEGATIVE_KEYWORD、NEGATIVE_KEYWORD_STATE、NEW_PRODUCT_AD、PRODUCT_AD_STATE、NEW_PAT、PAT_STATE、PAT_BID、NEW_NEGATIVE_PAT、NEGATIVE_PAT_STATE、NEW_AUDIENCE_TARGETING、AUDIENCE_TARGETING_STATE、AUDIENCE_TARGETING_BID、NEW_NEGATIVE_AUDIENCE_TARGETING、NEGATIVE_AUDIENCE_TARGETING_STATE] 中的一个 | | STATUS | [PUBLISHED、APPLY_IN_PROGRESS、APPLY_SUCCESS、APPLY_FAILED、REJECTED] 中的一个 | | GROUPING_TYPE | [CAMPAIGN_INCREASE_CLICKS、UNDERPERFORMING_CAMPAIGN_INCREASE_CLICKS] 中的一个 |

示例

获取所有建议

要查看与您的配置文件相关的所有建议，您可以使用空请求体进行调用。

请求

curl --location 'https://advertising-api.amazon.com/recommendations/list' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxx' \
--data '{
}'

响应

以下示例返回向品牌推广活动添加两个新关键词的建议。

"recommendations": [
        {
            "adGroupId": "2223334444",
            "adId": null,
            "adProduct": "SB",
            "applyFailureReason": null,
            "asin": null,
            "asinGroupTemplateId": null,
            "budgetRecommendation": null,
            "budgetRule": null,
            "campaignId": "11122223333",
            "campaignTemplateId": null,
            "consolidatedRecommendation": null,
            "currentValue": null,
            "estimatedImpact": null,
            "groupingType": null,
            "keywordSortingDimension": null,
            "keywordSortingRank": null,
            "recommendationId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx1",
            "recommendationType": "NEW_KEYWORD",
            "recommendedValue": "1.44",
            "resolvedTargeting": "mens shoes",
            "ruleBasedBidding": null,
            "sku": null,
            "status": "PUBLISHED",
            "targetId": null,
            "targeting": "mens shoes",
            "targetingMatchType": "EXACT"
        },
        {
            "adGroupId": "2223334444",
            "adId": null,
            "adProduct": "SB",
            "applyFailureReason": null,
            "asin": null,
            "asinGroupTemplateId": null,
            "budgetRecommendation": null,
            "budgetRule": null,
            "campaignId": "11122223333",
            "campaignTemplateId": null,
            "consolidatedRecommendation": null,
            "currentValue": null,
            "estimatedImpact": null,
            "groupingType": null,
            "keywordSortingDimension": null,
            "keywordSortingRank": null,
            "recommendationId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx2",
            "recommendationType": "NEW_KEYWORD",
            "recommendedValue": "2.02",
            "resolvedTargeting": "men socks",
            "ruleBasedBidding": null,
            "sku": null,
            "status": "PUBLISHED",
            "targetId": null,
            "targeting": "men socks",
            "targetingMatchType": "EXACT"
        }
]

获取所有商品推广建议

以下示例展示如何请求仅与商品推广活动相关的建议。

请求

{
    "maxResults": 10,
    "filters": [
            {
                "include": true,
                "field": "AD_PRODUCT",
                "values": [
                        "SP"
          ],
                "operator": "EXACT"
            }
   ]
}

响应

以下响应展示了增加现有商品推广活动预算的建议示例。


"recommendations": [
{
    "nextToken": null,
    "recommendations": [{
        "adGroupId": null,
        "adId": null,
        "adProduct": "SP",
        "applyFailureReason": null,
        "asin": null,
        "asinGroupTemplateId": null,
        "budgetRecommendation": {
            "sevenDaysMissedOpportunities": {
                "endDate": "2023-05-13",
                "estimatedMissedClicksLower": 310,
                "estimatedMissedClicksUpper": 937,
                "estimatedMissedImpressionsLower": 21856,
                "estimatedMissedImpressionsUpper": 65585,
                "estimatedMissedSalesLower": 391.0,
                "estimatedMissedSalesUpper": 1180.0,
                "percentTimeInBudget": 0.7434,
                "startDate": "2023-05-07"
            }
        },
        "budgetRule": null,
        "campaignId": "111222333344",
        "campaignTemplateId": null,
        "consolidatedRecommendation": null,
        "currentValue": "33.0",
        "estimatedImpact": null,
        "groupingType": null,
        "keywordSortingDimension": null,
        "keywordSortingRank": null,
        "recommendationId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx2",
        "recommendationType": "CAMPAIGN_BUDGET",
        "recommendedValue": "100.0",
        "resolvedTargeting": null,
        "ruleBasedBidding": null,
        "sku": null,
        "status": "PUBLISHED",
        "targetId": null,
        "targeting": null,
        "targetingMatchType": null
    }],
    "totalResults": 1
}
]

您可以使用响应中的 recommendationId 来更新或应用建议。

更新建议

如果您要对 API 返回的建议进行更改，可以使用 PUT /recommendations/{recommendationId}。可编辑字段取决于建议的类型。

更新建议值组合

| 建议类型 | 数据类型 | |--- |--- | | CAMPAIGN_BUDGET、CAMPAIGN_TOP_PLACEMENT、CAMPAIGN_PRODUCT_PLACEMENT、AD_GROUP_DEFAULT_BID、NEW_KEYWORD、KEYWORD_BID、NEW_PRODUCT_TARGETING、PRODUCT_TARGETING_BID、NEW_AUDIENCE_TARGETING、AUDIENCE_TARGETING_BID | number | | CAMPAIGN_END_DATE | string(YYYY-MM-DD) | | AD_GROUP_BID_OPTIMIZATION | [CLICKS、CONVERSIONS、REACH] 中的一个 | | CAMPAIGN_BIDDING_STRATEGY | [LEGACY_FOR_SALES、AUTO_FOR_SALES、MANUAL] 中的一个 | | CAMPAIGN_STATE、AD_GROUP_STATE、KEYWORD_STATE、NEGATIVE_KEYWORD_STATE、PRODUCT_AD_STATE、PRODUCT_TARGETING_STATE、NEGATIVE_PRODUCT_TARGETING_STATE、AUDIENCE_TARGETING_STATE、NEGATIVE_AUDIENCE_TARGETING_STATE | [ENABLED、PAUSED、ARCHIVED] 中的一个 |

示例

在以下示例中，您要将预算更新为 998 而不是 1000。

请求

PUT recommendations/xxxxxxx-xxxx-xxxxx-xxxx-xxxxx
{
    "recommendedValue":"998"
}

响应

{
    "recommendation": {
        "adGroupId": null,
        "adId": null,
        "adProduct": "SP",
        "applyFailureReason": null,
        "asin": null,
        "asinGroupTemplateId": null,
        "budgetRecommendation": null,
        "budgetRule": null,
        "campaignId": "11122333444",
        "campaignTemplateId": null,
        "consolidatedRecommendation": null,
        "currentValue": "1000",
        "estimatedImpact": null,
        "groupingType": null,
        "keywordSortingDimension": null,
        "keywordSortingRank": null,
        "recommendationId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
        "recommendationType": "CAMPAIGN_BUDGET",
        "recommendedValue": "998",
        "resolvedTargeting": null,
        "ruleBasedBidding": null,
        "sku": null,
        "status": "PUBLISHED",
        "targetId": null,
        "targeting": null,
        "targetingMatchType": null
    }
}

应用建议

对建议感到满意后，可以使用 POST /recommendations/apply 接口自动应用建议。您可以使用此接口应用一个或多个建议。

示例

在以下示例中，您将应用单个建议 ID。

请求

POST recommendations/apply

{
    "recommendationIds": [
        "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"
    ]
}

响应

{
    "failures": [],
    "successes": [{
        "index": 0,
        "recommendation": {
            "adGroupId": null,
            "adId": null,
            "adProduct": "SP",
            "applyFailureReason": null,
            "asin": null,
            "asinGroupTemplateId": null,
            "budgetRecommendation": null,
            "budgetRule": null,
            "campaignId": "11122333444",
            "campaignTemplateId": null,
            "consolidatedRecommendation": null,
            "currentValue": "1000",
            "estimatedImpact": null,
            "groupingType": null,
            "keywordSortingDimension": null,
            "keywordSortingRank": null,
            "recommendationId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
            "recommendationType": "CAMPAIGN_BUDGET",
            "recommendedValue": "998",
            "resolvedTargeting": null,
            "ruleBasedBidding": null,
            "sku": null,
            "status": "APPLY_SUCCESS",
            "targetId": null,
            "targeting": null,
            "targetingMatchType": null
        },
        "recommendationId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
        "success": {
            "code": "OK",
            "message": "Success."
        }
    }]
}
Amazon Advertising logo