開発者ガイドの概要

Amazon Ads APIの概要

スポンサー広告のスナップショットの使用を開始する

このチュートリアルでは、スポンサープロダクト広告キャンペーン、スポンサーブランド広告キャンペーン、スポンサーディスプレイ広告キャンペーンのスナップショットを非同期でリクエストしてダウンロードする方法の概要を説明します。

スナップショットには、キャンペーンに関連するメタデータが含まれています。さまざまなレベル（キャンペーン、広告グループ、キーワードなど）でスナップショットをリクエストできます。スナップショットには、リクエスト時に要求したエンティティに関する情報が含まれています。スナップショットから過去のメタデータを取得することはできません。

スナップショットは非同期であるため、スナップショットを生成するには次の3つの呼び出しが必要です。

  1. スナップショットをリクエストする
  2. スナップショットが生成されるのを待つ
  3. スナップショットをダウンロードする

ヒント：Postmanで試してみましょう

このチュートリアルに従って、Amazon Ads API Postmanコレクションのスナップショットフォルダーを使用してください。セットアップ手順については、Postmanのチュートリアルを参照してください。

ヘッダー

このチュートリアルで説明する各リクエストには、次の4つのヘッダーパラメーターが必要です。

パラメーター 説明
Amazon-Advertising-API-ClientId Login with Amazonアプリケーションに関連付けられているクライアントID。認証に使用されます。
Authorization アクセストークン。認証に使用されます。
Amazon-Advertising-API-Scope 特定のマーケットプレイスの広告アカウントに関連付けられたプロフィールID。
Content-Type application/jsonに設定します。

API認証の概要については、認可の概要を参照してください。

スナップショットのリクエスト

まず、必要なスナップショットのタイプを決定します。各スナップショットには、選択した広告タイプで、指定したキャンペーンエンティティのメタデータが含まれています。

  1. スナップショットの広告タイプを選択します。スポンサー広告のタイプごとに、仕様が異なる指定のエンドポイントがあります。以下の表から正しいエンドポイントを選択してください。

    広告タイプ エンドポイント ドキュメント
    スポンサープロダクト広告 /v2/sp/{recordType}/snapshot リンク
    スポンサーブランド広告 /v2/hsa/{recordType}/snapshot リンク
    スポンサーディスプレイ広告 /sd/{recordType}/snapshot リンク

  2. スナップショットのタイプを選択します。スナップショットのタイプによって、返される詳細情報のレベル（たとえば、広告グループレベルやキャンペーンレベルなど）が決まります。スポンサー広告タイプごとに、異なるスナップショットタイプがサポートされます。

    スポンサー広告のタイプごとに使用できるスナップショットのタイプについて詳しくは、スナップショットのタイプを参照してください。

    上記のパスのrecordTypeの代わりに、目的のスナップショットタイプを入力します。

  3. （オプション）フィルターを追加します。リクエスト本文にフィルターを追加し、stateFilterをenabled、paused、またはarchivedに設定して、特定のステータスのエンティティのみを返すことができます。複数のステータス（たとえば、"stateFilter": "enabled,paused"など）をリクエストできます。フィルターを指定しない場合、スナップショットにはステータスに関係なくすべてのエンティティが含まれます。

    注

    スポンサーディスプレイ広告のスナップショットの場合は、tacticに基づいてフィルタリングすることもできます。tactic（戦術）を使用すると、キャンペーンで使用されているターゲティングのタイプ（商品またはオーディエンス）に基づいてスナップショットをセグメント化できます。戦術を指定しない場合、スナップショットにはすべてのキャンペーンが含まれます。

    詳細については、スポンサーディスプレイ広告のスナップショットリファレンスを参照してください。

  4. スナップショットをリクエストするには、リクエスト本文を組み立て、目的のPOSTエンドポイント（手順1を参照）を呼び出します。リクエストには、空であってもリクエスト本文を含める必要があることに注意してください。

リクエストの例

以下のコードスニペットは、広告グループレベルでスポンサープロダクト広告のスナップショットをリクエストします。

リクエストの例をコピーする場合は、実際の地域の正しいURLとアカウントの有効な認証情報を必ず使用してください。

curl --request POST 'https://advertising-api.amazon.com/v2/sp/adGroups/snapshot' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxxxxx' \
--header 'Amazon-Advertising-API-ClientId: xxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxx' \
--data-raw '{}'

  1. 呼び出しが成功すると、snapshotIdと「IN_PROGRESS」のstatusを含むレスポンス202が返されます。次の手順で使用するために、snapshotIdをメモしておきます。

    成功時のレスポンスの本文は次のようになります。

    {
    "snapshotId":"amzn1.clicksAPI.v1.t1.xxxxxxxxxxxxx",
    "recordType":"campaign",
    "status":"IN_PROGRESS",
    "statusDetails":"snapshot is being generated."
}

スナップショットのステータスの確認

POST呼び出しが成功すると、スナップショットの生成に最大15分かかる場合があります。

スナップショットの生成ステータスを確認するには、スナップショットのリクエストの手順5で返されたsnapshotIdを使用して、該当するGET snapshotエンドポイントを呼び出します。

広告タイプ エンドポイント ドキュメント
スポンサープロダクト広告 /v2/sp/snapshots/(snapshotId) リンク
スポンサーブランド広告 /v2/hsa/snapshots/{snapshotId} リンク
スポンサーディスプレイ広告 /sd/snapshots/(snapshotId) リンク
リクエストの例 
<p>リクエストの例をコピーする場合は、実際の地域の正しい URL、アカウントの有効な認証情報、および固有のスナップショットIDを必ず使用してください。</p>

```shell
curl --request GET 'https://advertising-api.amazon.com/v2/sp/snapshots/amzn1.clicksAPI.xxxxxx' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Atza|xxxxxxxxx' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxx' \
```
</details>

スポンサーブランド広告とスポンサープロダクト広告のGET statusエンドポイントへの呼び出しが成功すると、ステータスコード200が返され、スポンサーディスプレイ広告のGET statusエンドポイントへの呼び出しがすべて成功すると、ステータスコード202が返されます。

スナップショットの生成が完了したかどうかを確認するには、レスポンス本文のstatusパラメーターを確認します。レポートがまだ生成中であれば、次のように、statusにIN_PROGRESSが設定されています。

{
    "snapshotId":"amzn1.clicksAPI.xxxxxx",
    "recordType":"ad Groups",
    "status":"IN_PROGRESS",
    "statusDetails":"In the process of generating Snapshot."
}

スナップショットをダウンロードできる状態になると、statusとしてSUCCESSが返されます。

{
    "snapshotId":"amzn1.clicksAPI.xxxxxx",
    "recordType":"ad Groups",
    "status":"SUCCESS",
    "statusDetails":"Snapshot has been successfully generated.",
    "location":"https://advertising-api.amazon.com/sd/snapshots/amzn1.amzn1.clicksAPI.xxxxxx/download","fileSize":371,
    "expiration":1643734785541
}

ヒント

スナップショットの生成には15分ほどかかる場合があります。スナップショットのステータスを確認する呼び出しを繰り返していると、リクエストが制限されたことを示すレスポンス429が生成される場合があります。プログラムでスナップショットを取得する場合は、アプリケーションロジックでリクエスト間隔を設定する必要があります。詳細については、指数関数的バックオフを使用した再試行ロジックを参照してください。

スナップショットのダウンロード

スナップショットの準備ができたら、snapshotIdを使用して、該当するダウンロードエンドポイントを呼び出します。

広告タイプ エンドポイント ドキュメント
スポンサープロダクト広告 /v2/sp/snapshots/{snapshotId}/download リンク
スポンサーブランド広告 /v2/hsa/snapshots/{snapshotId}/download リンク
スポンサーディスプレイ広告 /sd/snapshots/{snapshotId}/download リンク

呼び出しが成功すると、リダイレクトレスポンス307が返されます。このリダイレクトは、スナップショットファイルをダウンロードできるS3バケットを指しています。スナップショットファイルは、gzip形式で圧縮されたJSONとしてダウンロードされます。

リクエストの例 
<p>リクエストの例をコピーする場合は、実際の地域の正しい URL、アカウントの有効な認証情報、および固有のスナップショットIDを必ず使用してください。</p>

```shell
curl --request GET 'https://advertising-api.amazon.com/v2/sp/snapshots/amzn1.clicksAPI.xxxxxx/download' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Atza|xxxxxxxxx' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxx' \
--output "mySnapshot.json"
```
</details>

スナップショットのメタデータの使用

アプリケーションロジックでスナップショットを使用して、Amazon Ads APIへの他のリクエストの効率性を向上させることができます。たとえば、レポートを最も効率的に生成するには、レポートリクエストからキャンペーンメタデータを除外し、指定したreportTypeレベルでエンティティの固有のIDを使用して、レポート結果をスナップショットメタデータに結合することをおすすめします。

各タイプのスナップショットで返されるフィールドの詳細については、広告とスナップショットのタイプ別フィールドを参照してください。

Amazon Advertising logo