開発者ガイドの概要

Amazon Ads APIの概要

DSPレポートを作成する

このチュートリアルでは、DSPキャンペーンのレポートを非同期でリクエストしてダウンロードする方法の概要を説明します。

レポートを生成するには：

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

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

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

ヘッダー

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

パラメーター 説明
Amazon-Advertising-API-ClientId Login with Amazonアプリケーションに関連付けられているクライアントID。認証に使用されます。
Authorization アクセストークン。認証に使用されます。
Accept レスポンスとして期待されるコンテンツを指定します。リクエストエンドポイントによって異なります。

レポートをリクエストする場合はapplication/vnd.dspcreatereports.v3+jsonに設定し、レポートのステータスを確認する場合はapplication/vnd.dspgetreports.v3+jsonに設定します。
Content-Type application/jsonに設定します。

API認証の概要については、認可の概要をご覧ください。

accountIdを取得する

レポートの生成または取得のどちらでも、accountIdが必要です。accountIdは 認証とレポートの範囲決定に使用されます。

accountIdを取得する方法は、管理アカウントとセルフサービスアカウントのどちらを使用しているかによって異なります。詳細については、アカウントタイプ別のレポートをご覧ください。

レポートを生成する

レポートをリクエストする

DSPレポートは、さまざまなレポートタイプと指標をサポートしています。サポートされている構成の詳細については、レポートタイプをご覧ください。

すべてのレポートリクエストは単一のエンドポイントを使用します： POST /accounts/{accountId}/dsp/reports。パラメーターの詳細については、APIリファレンスをご覧ください。

timeUnit

timeUnitはDAILYまたはSUMMARYに設定できます。DAILYは期間内の各日のデータを集計し、SUMMARYは期間全体のデータを集計します。DAILY timeUnitはAUDIENCEレポートタイプではサポートされていません。startDateからendDateまでの最大期間は31日です。endDateは本日の90日前まで指定できます。

サンプルリクエストボディ（timeUnitをDAILYに設定）

{
    "dimensions" ["ORDER", "LINE_ITEM"],
    "timeUnit": "DAILY",
    "startDate": "2022-12-05",
    "endDate": "2022-12-19"
}

サンプルリクエストボディ（timeUnitをSUMMARYに設定）

{
    "dimensions" ["ORDER", "LINE_ITEM"],
    "timeUnit": "SUMMARY",
    "startDate": "2022-12-05",
    "endDate": "2022-12-19"
}

dimensions

ディメンションによってレポートの集計レベルが決まります。ディメンションを追加すると、そのディメンションの指標がレポートに自動的に追加されます。複数のディメンションを追加すると、DSPレポーティングAPIはデータ集計に最下位レベルのディメンションを使用し、追加されたすべてのディメンションのディメンション指標をレポートに含めます。詳細については、ディメンションをご覧ください。

advertiserIds

セルフサービスDSPエンティティの所有者は、advertiserIdsフィールドを使用して特定の広告主のデータをリクエストできます。詳細については、アカウントタイプ別のレポートをご覧ください。

注

レポートごとにリクエストできる広告主は最大100個です。100個を超える広告主についてレポートする必要がある場合は、複数のレポートをリクエストしてください。

デフォルト値

デフォルトでは、POST /accounts/{accountId}/dsp/reportsリクエストボディでは以下のようになります。

リクエストにはstartDateとendDateを指定する必要があります。

サンプルリクエスト

このサンプルは、accountIdがID123456789の広告主について、2022年12月5日から2022年12月19日までのDSPキャンペーンの概要レポートをリクエストしたものです。

注

このチュートリアルのサンプル呼び出しでは、北米APIエンドポイント（https://advertising-api.amazon.com）を使用しています。マーケットプレイスに応じてどの地域のエンドポイントを使用するかについては、APIの概要をご覧ください。

curl --location --request POST 'https://advertising-api.amazon.com/accounts/ID123456789/dsp/reports' \
     --header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxxxxx' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer Atza|xxxxxxxxxxx' \
     --header 'Accept: application/vnd.dspcreatereports.v3+json' \
     --data-raw '{
         "metrics": ["totalFee", "totalCost", "clickThroughs", "purchasesClicks14d", "eCPM", "impressions", "ROAS14d"],
         "dimensions": ["ORDER", "LINE_ITEM"],
         "startDate": "2022-12-05",
         "endDate": "2022-12-19"
     }'

サンプルレスポンス

成功したリクエストレスポンスには、reportIdフィールドとstatusフィールドが含まれます。

{
    "reportId": "b2230738-5b81-2423-a3a6-380d5522ba78",
    "type": "CAMPAIGN",
    "format": "JSON",
    "status": "IN_PROGRESS",
    "statusDetails": "In progress",
    "location": "",
    "expiration": "2023-02-01T20:25:13.356Z"
}

レポートが生成されるのを待つ

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

レポート生成ステータスを確認するには、最初のリクエストで返されたreportIdを使用して、GET reportsエンドポイントを呼び出します： GET /accounts/{accountId}/dsp/reports/{report-id}。

サンプルリクエスト

curl --location --request GET /accounts/{accountId}/dsp/reports/{report-id} \
     --header 'Content-Type: application/vnd.dspgetreports.v3+json' \
     --header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxx' \
     --header 'Authorization: Bearer Atza|xxxxxxxxxxx'  \

GET statusエンドポイントの呼び出しが成功すると、200ステータスコードが返されます。レポートの生成が完了したかどうかを確認するには、レスポンスボディのstatusパラメーターを確認します。レポートがまだ生成中の場合、statusはPENDINGまたはPROCESSINGに設定されます。

レポートをダウンロードできる状態になると、statusがSUCCESSとして返され、locationフィールドにアドレスが表示されます。

サンプルレスポンス（レポート生成中）

{
    "reportId": "TEST123",
    "type": "CAMPAIGN",
    "format": "JSON",
    "status": "IN_PROGRESS",
    "statusDetails": "In progress",
    "location": "",
    "expiration": "2022-12-28T19:30:25.632Z"
}

サンプルレスポンス（レポート生成完了）

{
    "reportId": "TEST123",
    "type": "INVENTORY",
    "format": "JSON",
    "status": "SUCCESS",
    "statusDetails": "Success",
    "location": "https://corvo-reports.s3.amazonaws.com/DSP_API/2023-02-13/TEST123/inventory-report-TEST123.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230213T231410Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=TEST123%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=TEST123",
    "expiration": "2023-02-14T00:14:10.562Z"
}

レポートをダウンロードする

レポートの準備が整うと、GET /accounts/{accountId}/dsp/reports/{report-id}のlocationフィールドに、レポートをダウンロードできるS3バケットへのリンクが含まれます。cURLを使用してGET呼び出しを行うか、ブラウザにURLを入力できます。

レポートを確認する

レポートの未加工のJSONファイルを表示します。レポート内のデータの集計レベルは、指定したディメンションによって異なります。サンプルのJSON、ORDERレベルのレポートは以下のようになります。

[
  {
    "orderExternalId": "6677889900",
    "orderEndDate": 1690862340000,
    "orderId": 123042566401569500,
    "orderStartDate": 1633562280000,
    "orderCurrency": "USD",
    "intervalEnd": 1674432000000,
    "orderBudget": 10000,
    "entityId": "TEST123",
    "intervalStart": 1674345600000,
    "advertiserName": "Test Account One",
    "advertiserId": 123123123,
    "orderName": "One Test Order"
  },
  {
    "orderExternalId": null,
    "orderEndDate": 1702627140000,
    "orderId": 123582641277101200,
    "orderStartDate": 1650265200000,
    "orderCurrency": "USD",
    "intervalEnd": 1674432000000,
    "orderBudget": 50000,
    "entityId": "TEST123",
    "intervalStart": 1674345600000,
    "advertiserName": "Test - Audio",
    "advertiserId": 123456789,
    "orderName": "Audio test order"
  }
]

詳細はこちら

Amazon Advertising logo