スポンサー広告レポートの使用を開始する

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

Amazon Ads APIレポートは非同期であるため、レポートを生成するには次の3つの呼び出しが必要です。

1. レポートをリクエストする
2. レポートが生成されるのを待つ
3. レポートをダウンロードする

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

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

警告

2023年3月30日現在、バージョン2のレポートではスポンサープロダクト広告レポートはサポートされません。詳細については、バージョン3のレポートの使用を開始するを参照してください。

ヘッダー

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

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

レポートのリクエスト

まず、広告とレポートタイプ、日付、指標を含むレポートの仕様を決定します。

1. レポートの広告タイプを選択します。スポンサー広告のタイプごとに指定のリクエストエンドポイントがあるので、必要なスポンサー広告タイプに応じた正しいエンドポイントを使用するようにしてください。

   スポンサーブランド広告キャンペーンとスポンサーディスプレイ広告キャンペーンの両方のパフォーマンスデータを取得するには、タイプごとに別々にリクエストしてください。

   注

   エンドポイントごとにリクエスト本文のパラメーターには違いがあります。詳細についてはリファレンスを確認してください。

   広告タイプ	エンドポイント	リファレンス
   スポンサープロダクト広告	POST /v2/sp/{recordType}/report	[廃止されました]
   スポンサーブランド広告	POST /v2/hsa/{recordType}/report	リンク
   スポンサーディスプレイ広告	POST /sd/{recordType}/report	リンク

2. レポートタイプを選択します。レポートタイプによって、レポートのデータの分析方法（広告グループレベルやキャンペーンレベルなど）が決まります。スポンサー広告のタイプごとに、異なるレポートタイプがサポートされます。上記のパスのrecordTypeの代わりに、目的のレポートタイプを入力します。

   レポートタイプの詳細をご覧ください。

3. リクエスト本文を作成します。すべての広告タイプにreportDate（レポート日付）とmetrics（指標）が必要です。

   • レポート日付： 各レポートには、1日分のデータが含まれます。より長い期間のデータが必要な場合は、レポートリクエストを複数回実行してください。
   • 指標： 指標はレポートのキーと値のペアを表します。広告タイプとレポートタイプの組み合わせごとに異なる指標がサポートされます。指標は、スペースを入れずにカンマ区切りリスト形式で入力します。利用可能な指標の詳細をご覧ください。

   注

   スポンサーディスプレイ広告のレポートリクエストでは、リクエスト本文のパラメーターtacticも必要です。これは、キャンペーンで使用されているターゲティングのタイプ（商品またはオーディエンス）に基づいてレポートデータをセグメント化します。商品ターゲティングとオーディエンスターゲティングの両方を使用してキャンペーンを実施している場合に、すべてのデータを受け取るには、各レポートの2つのバージョンをリクエストするようにしてください。
   
   詳細については、スポンサーディスプレイ広告のレポートリファレンスを参照してください。

   作成するレポートのタイプによっては、レポートをさらにセグメント化するために指定できるオプションまたは必須のパラメーターが他にもある場合があります。エンドポイントリファレンスに、使用可能なすべてのパラメーターが記載されています。

4. レポートをリクエストするには、リクエスト本文を組み立て、目的のPOSTエンドポイント（手順1の表を参照）を呼び出します。

curl --request POST 'https://advertising-api.amazon.com/v2/sd/campaigns/report' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxxxxx' \
--header 'Amazon-Advertising-API-ClientId: xxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxx' \
--data-raw '{
"reportDate": "20211102",
"metrics": "campaignId,impressions,clicks,cost"
}'

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

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

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

レポートのステータスの確認

POST呼び出しが成功すると、レポートの生成には最大15分かかる場合があります。

レポートの生成ステータスを確認するには、手順4で返されたreportIdを使用して、GET reportエンドポイントを呼び出します。

GET /v2/reports/{reportId}

リクエストの例

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

```shell
curl --request GET 'https://advertising-api.amazon.com/v2/reports/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が返されます。レポート生成が完了したかどうかを確認するには、レスポンス本文のstatusパラメーターを確認します。レポートがまだ生成中であれば、次のように、statusにIN_PROGRESSが設定されています。

{
    "reportId":"amzn1.xxxxxxxxxx",
    "status":"IN_PROGRESS",
    "statusDetails":"Report generation is in progress."
}

レポートをダウンロードできる状態になると、statusとしてSUCCESSが返されます。

{
    "reportId":"amzn1.xxxxxxxxxx",
    "status":"SUCCESS",
    "statusDetails":"Report has been successfully generated.",
    "location":"https://ad-api.integ.amazon.com/v1/reports/amzn1.xxxxxxxxxx/download",
    "fileSize":150,
    "expiration":1651536000000
}

ヒント

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

レポートのダウンロード

レポートが準備できたら、reportIdを使用してダウンロードエンドポイントを呼び出します。

GET /v2/report/{reportId}/download

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

リクエストの例

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

<p>cURLリクエストを使用する場合は、「--output」フラグを使用してレポートデータ用のファイルを指定する必要があります。</p>

```shell
curl --request GET 'https://advertising-api.amazon.com/v2/reports/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 "myReport.json"
```
</details>

レポートの確認

レポートファイルを解凍すると、レポートの未加工のJSONが現れます。このチュートリアルで使用している例の場合、次のようなレポートになります。

[
    {
        "campaignId":123456789,
        "impressions":55,
        "clicks":2,
        "cost":3.5
    },
    {
        "campaignId":123456780,
        "impressions":32,
        "clicks":3,
        "cost":5.3
    }
]

この例では、2つのスポンサーディスプレイ広告キャンペーンのインプレッション数、クリック数、コストのデータが返されています。

ヒント

キャンペーンのメタデータを取得するには、スナップショットをリクエストしてから、campaignIdを使用して2つのデータセットを結合してください。

レポートを生成できるようになったので、以下についてさらに詳しく説明します。

• 指標
• APIと広告コンソールのレポートの違い
• レポートタイプ

• © 2023 Amazon.com, Inc. or its affiliates.
• Conditions of Use
• Privacy Notice
• License Agreement
• Data Policies