スポンサープロダクト広告バージョン3移行ガイド

スポンサープロダクト広告APIのバージョン3では、スポンサープロダクト広告キャンペーンの作成と管理のためのシンプルなインターフェイスが導入されています。

ハイライト：

• Amazon Ads 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 |

ID

すべてのエンティティID（キャンペーン、広告グループ、広告など）が整数ではなく文字列として認識されるようになりました。

日付形式

日付（キャンペーンのstartDateなど）の形式はYYYY-MM-DDにする必要があります。これは、標準の日付形式がYYYYMMDDであったバージョン2からの変更点です。

GET操作とLIST操作の比較

スポンサープロダクト広告バージョン2では、主にGETリクエストを使用してリソースを読み取っていました。バージョン2では、ほとんどのリソースに4つの個別のGETエンドポイント（バッチ取得、単一エンティティ取得、バッチ拡張、単一拡張）がありました。バージョン3では、すべての読み取り操作がPOST操作として実装されています。これにより、リクエストボディでフィルターを使用して、エンティティID、状態、キーワードなどでフィルタリングできます。

呼び出し例

次の例は、有効になっているすべてのスポンサープロダクト広告キャンペーンを一覧表示する方法を示しています。

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
}'

一括で非表示にする

1回の呼び出しで複数のエンティティ（キャンペーン、広告グループ、広告など）を非表示にできるようになりました。

例

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によって返されるキャンペーンのbudgetオブジェクトに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）を使用できるようになりました。拡張された商品ターゲティングを使用すると、1つのターゲティング句を使用して、1つの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ヘッダーによって制御されます。各エンドポイントについて、メディアタイプドロップダウンを確認して、AcceptヘッダーとContent-Typeヘッダーに使用する値を理解してください。

優先ヘッダー

優先ヘッダーを使用して、レスポンスの一部として完全なオブジェクト表現が必要かどうかを指定できます。優先ヘッダーを指定しない場合、レスポンスには作成されたエンティティのIDのみが表示されます。

元のリクエストにおけるオブジェクトの順序を示すインデックス。

ドキュメントの改善

• マニュアルキャンペーンとオートキャンペーンの作成方法を示すガイドが利用できるようになりました。
• キャンペーン、広告グループ、キーワード、商品ターゲティング、オートターゲティングなどのリソースガイドが利用できるようになりました。

Postmanコレクション

バージョン3のCRUDエンドポイントはすべてAmazon Ads API Postmanコレクションで利用できます。コレクションと環境ファイルはGitHubからダウンロードできます。

バージョン2のバグ修正

• プロダクト広告がすべて表示されるようになったため、正常に作成されたものや作成に失敗したものがわかります。