開発者ガイドの概要

Amazon Ads APIの概要

Amazon Marketing Stream登録の管理

Amazon Marketing Streamの初期設定が完了したら、次の操作を使用して登録の表示、追加、更新、非表示を管理できます。

ヒント

Postmanコレクションを使用して、Amazon Marketing Stream APIをテストできます。コレクションと環境を設定したら、Amazon Marketing Streamフォルダーを確認してAPIを呼び出してください。

ヒント

CLIを試してみましょう。このドキュメントのすべての操作を処理するCLIが、Amazon Marketing Streamのリファレンス実装（GitHubで提供）の一部として提供されています。

すべての登録を表示する

広告プロフィールに紐づけられているすべてのデータセット登録を表示するには、GET /streams/subscriptionsエンドポイントを使用します。

リクエスト

このリソースでは、Amazon-Advertising-API-Scopeで渡したプロフィールIDで作成された登録が返されます。maxResultsクエリパラメーターを使用して、1ページあたりに返される結果の件数を制御できます。

サンプル

curl --location --request GET 'https://advertising-api.amazon.com/streams/subscriptions?maxResults=10' \
--header 'Amazon-Advertising-API-ClientId: xxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxx' \
--header 'Authorization: Bearer xxxxxxxxx'

レスポンス

サンプル

{
   "nextToken": "string",
   "subscriptions": [
     {
       "createdDate": "2022-02-16T20:11:05.323Z",
       "destinationArn": "string",
       "dataSetId": "sp-traffic",
       "subscriptionId": "54321",
       "updatedDate": "2022-02-18T20:11:05.323Z",
       "status": "ACTIVE"
     },
     {
       "createdDate": "2022-02-15T20:11:05.323Z",
       "destinationArn": "string",
       "dataSetId": "sp-conversion",
       "subscriptionId": "12345",
       "updatedDate": "2022-03-19T20:11:05.323Z",
       "status": "ARCHIVED"
     },
   ]
 }

結果ページがさらにある場合は、次の呼び出しのstartingTokenクエリパラメーターにnextToken値を渡すことができます。

登録を追加する

新しいデータセットまたは広告主を登録する必要がある場合は、POST /streams/subscriptionsエンドポイントを使用します。

登録を追加する前に、データセットに関連するIAMポリシーをSQSキューに追加したことを確認してください。登録を実行してデータの受信を開始するには、SQSで登録を確認する必要があります。

現在サポートされているデータセットは、データガイドで確認できます。

リクエスト

destinationArnについては、リクエストするdataSetIdに対応するIAMポリシーが適用されたSQS ARNを必ず指定してください。

サンプル

curl --location --request POST 'https://advertising-api.amazon.com/streams/subscriptions' \
--header 'Amazon-Advertising-API-ClientId: xxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxx' \
--header 'Content-Type: application/vnd.MarketingStreamSubscriptions.StreamSubscriptionResource.v1.0+json' \
--header 'Authorization: Bearer xxxxxxxxx' \
--data-raw '{
"clientRequestToken": "123456xyz789101112",
"dataSetId": "sp-traffic",
"notes": "Advertiser 1 sp-traffic subscription",
"destinationArn": "QUEUE_ARN"
}‘

レスポンス

呼び出しが成功すると、subscriptionIDを示すレスポンスが返されます。これを使用して登録ステータスを確認できます。

サンプル

{
   "subscriptionId": "xxxxxxxxxxxxx",
   "clientRequestToken": "123456xyz789101112",
 }

登録ステータスを確認する

登録を作成のうえ確認した後、GET /streams/subscriptions/{subscriptionId}エンドポイントを使用することで、登録のステータス情報を表示できます。

ヒント

すべての登録が有効かどうか、登録のステータスを定期的に確認してください。登録でトークンが使用されたユーザーが広告エンティティに対するアクセス権を失った場合、その登録は一時停止されることがあります。

可能性のあるステータス

| ステータス | 説明 | |--- |--- | | PROVISIONING | 登録が作成され、Amazon側でプロビジョニングされています。プロビジョニングが完了すると、登録はPENDING_CONFIRMATIONステータスに移行します。 | | PENDING_CONFIRMATION | 登録の作成とプロビジョニングが完了し、SQSキューでの確認を待機中です。 | | FAILED_CONFIRMATION | SQSでの登録の確認が3日以内に行われませんでした。この場合は、新しい登録を作成し、3日間の有効期限内に登録を確認してください。 | | ACTIVE | 登録は有効で、データを配信しています。 | | ARCHIVED | 登録は非表示にされました。 | | SUSPENDED | 登録は一時停止されています。これは、登録を作成したアカウントが、広告コンソールで広告主に対するアクセス権を失った場合に発生します。 |

警告

SUSPENDEDの登録をACTIVEに設定することはできません。登録が一時停止された場合は、データに対するアクセス権限を持つアカウントを使用して登録処理をもう一度行う必要があります。

リクエスト

サンプル

curl --location -g --request GET 'https://advertising-api.amazon.com/streams/subscriptions/xxxxxxxxxx' \
--header 'Amazon-Advertising-API-ClientId: xxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxx' \
--header 'Authorization: Bearer Atza| xxxxxxxx'

レスポンス

サンプル

{
    "subscription": {
        "createdDate": "2021-10-14T18:25:52.861Z",
        "notes": "Advertiser 1 sp-traffic subscription",
        "subscriptionId": "xxxxxxxxxx",
        "destinationArn": "QUEUE_ARN",
        "dataSetId": "sp-traffic",
        "updatedDate": "2021-10-15T18:25:52.861Z",
        "status": "PROVISIONING"
    }
 }

登録を非表示にする

現在、Amazon Marketing Streamの登録を削除する方法はありません。代わりに、PUT /streams/subscriptions/{subscriptionId}エンドポイントを使用し、statusをARCHIVEDに設定することで登録を非表示にできます。ステータスを「ARCHIVED」に設定すると、登録に関連する広告主アカウントとデータセットのすべてのデータ配信が停止します。

リクエスト

サンプル

curl --location -g --request PUT 'https://advertising-api.amazon.com/streams/subscriptions/xxxxxxxxx' \
--header 'Amazon-Advertising-API-ClientId: xxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxx' \
--data-raw '{
 "status": "ARCHIVED"
}'

レスポンス

成功すると、200のレスポンスが返されます。

Amazon Advertising logo