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

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

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

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

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

このチュートリアルは、PostmanのAmazon Ads APIコレクションのReportingフォルダーを使用して進めることができます。セットアップ手順については、Postmanチュートリアルをご覧ください。

ヘッダー

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

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

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

レポートのリクエスト

バージョン3のレポートは、さまざまなレポートタイプ、期間、指標に対応しています。サポートされている構成の詳細については、「レポートタイプ」をご覧ください。

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

`timeUnit`とサポートされている列

timeUnitはDAILYまたはSUMMARYに設定できます。timeUnitをDAILYに設定する場合は、列リストにdateを含める必要があります。timeUnitをSUMMARYに設定する場合は、列リストにstartDateとendDateを含めることができます。

リクエスト本文の例： Summary

{
    "name":"SP campaigns report 7/5-7/10",
    "startDate":"2022-07-05",
    "endDate":"2022-07-10",
    "configuration":{
        "adProduct":"SPONSORED_PRODUCTS",
        "groupBy":["campaign"],
        "columns":["impressions","clicks","cost","campaignId","startDate","endDate"],
        "reportTypeId":"spCampaigns",
        "timeUnit":"SUMMARY",
        "format":"GZIP_JSON"
    }
}

リクエスト本文の例： Daily

{
    "name":"SP campaigns report 7/5-7/10",
    "startDate":"2022-07-05",
    "endDate":"2022-07-10",
     "configuration":{
        "adProduct":"SPONSORED_PRODUCTS",
        "groupBy":["campaign"],
        "columns":["impressions","clicks","cost","campaignId","date"],
        "reportTypeId":"spCampaigns",
        "timeUnit":"DAILY",
        "format":"GZIP_JSON"
    }
}

`groupBy`

すべてのレポートリクエストには、レポート設定にgroupBy パラメーターが必要となります。groupByはレポートの精度レベルを決定します。各レポートタイプで使用可能なgroupByの値を確認するには、「レポートタイプ」をご覧ください。レポートタイプで複数のgroupByの値がサポートされている場合は、リクエストに複数の値を使用できます。

フィルター

フィルターは、リクエストのGroupByレベルで決まります。使用できるフィルターについては、「レポートタイプ」をご覧ください。

注

レポート設定に指定したすべてのgroupBy値でサポートされるフィルターのみを使用できます。

フィルターを使用したリクエスト本文の例

{
    "name":"SP campaigns report 7/5-7/10",
    "startDate":"2022-07-05",
     "endDate":"2022-07-10",
    "configuration":{
        "adProduct":"SPONSORED_PRODUCTS",
        "groupBy":["campaign"],
        "columns":["impressions","clicks","cost","campaignId","startDate","endDate"],
        "reportTypeId":"spCampaigns",
        "timeUnit":"SUMMARY",
        "format":"GZIP_JSON",
         "filters": [
            {
                "field": "campaignStatus",
                "values": ["ENABLED","PAUSED"]
            }
        ]
    }
}

サンプルリクエスト

このサンプルは、スポンサープロダクト広告キャンペーンにおける7月5日から7月21日までの概要レポートの要求リクエストです。

注

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

curl --location --request POST 'https://advertising-api.amazon.com/reporting/reports' \
--header 'Content-Type: application/vnd.createasyncreportrequest.v3+json' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxx' \
--data-raw '{
    "name":"SP campaigns report 7/5-7/10",
    "startDate":"2022-07-05",
    "endDate":"2022-07-10",
    "configuration":{
        "adProduct":"SPONSORED_PRODUCTS",
        "groupBy":["campaign","adGroup"],
        "columns":["campaignId","adGroupId","impressions","clicks","cost","purchases1d","purchases7d","purchases14d","purchases30d","startDate","endDate"],
        "reportTypeId":"spCampaigns",
        "timeUnit":"SUMMARY",
        "format":"GZIP_JSON"
    }
}'

レスポンス

リクエストが成功すると、リクエストしたレポート設定、reportId、およびstatusを含むレスポンス200が返されます。次の手順で使用するために、reportIdをメモしておきます。

{
    "configuration": {
        "adProduct": "SPONSORED_PRODUCTS",
        "columns": [
            "campaignId",
            "adGroupId",
            "impressions",
            "clicks",
            "cost",
            "purchases1d",
            "purchases7d",
            "purchases14d",
            "purchases30d",
            "startDate",
            "endDate"
        ],
        "filters": null,
        "format": "GZIP_JSON",
        "groupBy": [
            "campaign",
            "adGroup"
        ],
        "reportTypeId": "spCampaigns",
        "timeUnit": "SUMMARY"
    },
    "createdAt": "2022-07-19T14:03:00.853Z",
    "endDate": "2022-07-05",
    "failureReason": null,
    "fileSize": null,
    "generatedAt": null,
    "name": "SP campaigns report 7/5-7/21",
    "reportId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
    "startDate": "2022-07-05",
    "status": "PENDING",
    "updatedAt": "2022-07-19T14:03:00.853Z",
    "url": null,
    "urlExpiresAt": null
}

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

POST呼び出しの完了後、レポートの生成には最大3時間を要する場合があります。

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

リクエストの例

curl --location --request GET 'https://advertising-api.amazon.com/reporting/reports/xxxxx-xxxxx-xxxxx' \
--header 'Content-Type: application/vnd.createasyncreportrequest.v3+json' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxxxx'  \

GET statusエンドポイントへの呼び出しが成功すると、ステータスコード200が返されます。レポート生成が完了したか否かを確認するには、レスポンス本文のstatusパラメーターを確認します。レポートがまだ生成中であれば、statusにはPENDINGまたはPROCESSINGが設定されています。

レポートがダウンロード可能な状態になると、statusとしてCOMPLETEDが返され、urlフィールドにアドレスが表示されます。

ヒント

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

レポートのダウンロード

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

レポートの確認

レポートファイルを解凍すると、レポートの未加工のJSONが表示されます。このチュートリアルで使用している例のサンプルレポートは以下のようになります。


[
    {
        "purchases7d":2,
        "cost":14.5,
        "purchases30d":3,
        "endDate":"2022-07-10",
        "campaignId":158410630682987,
        "clicks":13,
        "purchases1d":1,
        "impressions":2216,
        "adGroupId":72320882861500,
        "startDate":"2022-07-05",
        "purchases14d":3
    },
    {
        "purchases7d":2,
        "cost":9.45,
        "purchases30d":2,
        "endDate":"2022-07-10",
        "campaignId":158410630682987,
        "clicks":10,
        "purchases1d":2,
        "impressions":3721,
        "adGroupId":55720282058882,
        "startDate":"2022-07-05",
        "purchases14d":2
    }
]

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

ヒント

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

レポートの生成方法を学んだ後は、以下をご確認ください。

開発者ガイドの概要

Amazon Ads APIの概要

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

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

ヘッダー

レポートのリクエスト

`timeUnit`とサポートされている列

`groupBy`

フィルター

注

サンプルリクエスト

注

レスポンス

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

ヒント

レポートのダウンロード

レポートの確認

ヒント

開発者ガイドの概要

Amazon Ads APIの概要

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

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

ヘッダー

レポートのリクエスト

timeUnitとサポートされている列

groupBy

フィルター

注

サンプルリクエスト

注

レスポンス

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

ヒント

レポートのダウンロード

レポートの確認

ヒント

`timeUnit`とサポートされている列

`groupBy`