Reporting API

開発者はReporting APIを使用して、売上レポートや定期購入型アイテムレポートをダウンロードすることができます。

• セキュリティプロファイルの作成方法
• セキュリティプロファイルをAPIに関連付ける方法
• LWAアクセストークンのリクエスト方法
  • 1.トークンリクエストを送信する
  • 2.レスポンスを保存する
  • 3.エラーレスポンスを処理する
• アクセストークンの使用方法
• Reporting APIのURL
• 売上／定期購入型アイテムのレポート用URLをリクエストする方法
  • 構文
  • 例
  • エラー
• S3 URLを使用してレポートをダウンロードする方法
  • エラーメッセージ：
• Reporting APIに関するよくある質問（FAQ）
• 売上レポートのフィールド
  • 定期購入型アイテムレポートのフィールド
  • マーケットプレイス情報
• APIデータセキュリティ

開発者コンソールのAPIを使用するには、セキュリティプロファイルを作成し、それを開発者コンソールのAPIに関連付ける必要があります。セキュリティプロファイルは、APIアクセス用のアクセストークンを生成するためのメカニズムです。

セキュリティプロファイルの作成方法

セキュリティプロファイルを作成するには、次の手順に従います。

1. Amazon開発者コンソールアカウントにログインします。アカウントがない場合は、アカウントの作成を求められます。
2. メインナビゲーションで、[アプリ＆サービス] をクリックします。
3. サブメニューで、[APIアクセス] を選択します。

4. APIの名前をクリックします。

   

5. [セキュリティプロファイルを新規作成] ボタンをクリックします。
6. 新しいプロファイルの [セキュリティプロファイル名] と [セキュリティプロファイルの説明] を入力し、[保存] をクリックします。
7. [ウェブ設定] タブを開き、表示されているクライアントIDとクライアントシークレットを保存します。この情報はSales Reporting APIにアクセスする際に必要になります。

   

セキュリティプロファイルをAPIに関連付ける方法

セキュリティプロファイルをAPIに関連付けるには、次の手順に従います。

1. [APIアクセス] ページに戻ります。
2. 先ほどクリックしたAPIの名前を再度クリックします。
3. 新たに作成したセキュリティプロファイルをドロップダウンリストから選択します。
4. [関連付ける] をクリックして、セキュリティプロファイルをこのAPIに関連付けます。API名と、関連付けられたセキュリティプロファイルが、[使用中のセキュリティプロファイル] パネルに追加されます。

   

これで、クライアントIDとクライアントシークレットを使用して、Login with Amazon（LWA）アクセストークンをリクエストできるようになりました。

LWAアクセストークンのリクエスト方法

クライアントIDおよびクライアントシークレットと共にLogin with Amazon APIを使用して、Login with Amazonアクセストークンをリクエストするには、次の手順に従います。

1.トークンリクエストを送信する

次のヘッダーとコンテンツでhttps://api.amazon.com/auth/o2/tokenにPOSTリクエストを送信します。

• ヘッダー： Content-Type: application/x-www-form-urlencoded
• コンテンツ：
  • client_id： セキュリティプロファイルの作成方法に記載の手順7で保存したクライアントIDです。
  • client_secret： セキュリティプロファイルの作成方法の手順7で保存したクライアントシークレットです。
  • grant_type： 値をclient_credentialsに設定します。
  • scope： 値をappstore::apps:readwrite（Reporting APIの場合はadx_reporting::appstore:marketer）に設定します。

JSONコンテンツの例：

{
    "grant_type": "client_credentials",
    "client_id": "amzn1.application-oa2-client.<クライアントID>",
    "client_secret": "<クライアントシークレット>",    
    "scope": "appstore::apps:readwrite"
}

cURLリクエストの例：

curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=amzn1.application-oa2-client.<クライアントID>&client_secret=<クライアントシークレット>=appstore::apps:readwrite' https://api.amazon.com/auth/O2/token

2.レスポンスを保存する

レスポンスは、たとえば次のようになります。

{
    "access_token": "Atc|MAEBI...",
    "scope": "appstore::apps:readwrite",
    "token_type": "bearer",
    "expires_in": 3600
}

• access_token： アクセストークン
• expires_in： アクセストークンの有効期限が切れるまでの秒数
• scope： appstore::apps:readwrite（Reporting APIの場合はadx_reporting::appstore:marketer）とします。
• token_type： 常にbearerとします。

3.エラーレスポンスを処理する

トークンリクエストでエラーが発生した場合、レスポンスのメッセージ本文には次のエラーメッセージのいずれかが含まれます。

アクセストークンの使用方法

有効なアクセストークンを取得したら、Authorizationヘッダーを設定してReporting APIにリクエストを送信します。Authorizationヘッダーの値はBearer<YOUR_ACCESS_TOKEN>です。ここで<YOUR_ACCESS_TOKEN>は、LWAアクセストークンのリクエスト方法で説明したレスポンス内のaccess_tokenフィールドの値です。アクセストークンは、「Atc|」で始まる長い文字列です。

cURLリクエストの例：

curl -v -X GET "<see below for URL format>"   -H  "Authorization: Bearer Atc|MAEBIKfsULrH7jSzvJTV8UmiHWr9M86O3JRmv4t1hqoCBriSMEP5Gsey_FiBxteZ8oxGd6abGuOFga8fwnMhmSD_Sg4MI4odXLPgB2IVs8M1uswjuWjnsMcvehpWvf9tzQT8HTWiBigInJLB8BrMg5J3O02hlTvcF441XxXDXthyj993COJ2u5swOTKjC_dcijiN8amuzrj32rh9Fr3CNgCpoZ0WqXnBhoHUVMYSOBV-owA5rI4-OfysXC71Zbtv1hb8igk"  

アクセストークンの有効期限が切れたら、LWAアクセストークンのリクエスト方法の手順に従って新しいトークンを取得し、それを使用してリクエストを送信します。アクセストークンを最後にリクエストしてから1時間以上経過すると、403 Forbidden HTTPエラーとなり、「Request is not authorized（リクエストが認可されていません）」というメッセージが表示されるようになります。これは、アクセストークンの有効期限が切れたことを示します。

Reporting APIのURL

Reporting APIのリクエストを送信するには、次のベースURLを使用します。

developer.amazon.com

売上／定期購入型アイテムのレポート用URLをリクエストする方法

Reporting APIを使用すれば、売上や定期購入型アイテムのレポートファイルをダウンロードすることができます。このAPIリクエストを送信すると、安全なS3ストレージからレポートファイルをダウンロードするためのURLが返されます。

構文

/api/appstore/download/report/sales/<year>/<month>

/api/appstore/download/report/subscription/<year>/<month>

パラメーター

例

以下は、2018年1月の売上レポートをリクエストする方法の例です。

リクエスト：

curl -v -X GET "https://developer.amazon.com/api/appstore/download/report/sales/2018/04" -H "Authorization: Bearer Atc|MQEBIDdrcC586BxhFBdS7FQVS454oUO-fo90H5gUYVMZB1UVsPFoOPLj_zrpkf9BuMrx-PksU_qDJHL-PJ5suEQTigL1tv7A6AKlyoJJaoyzyzKhd0dwWw3LWUGrlxXxW459nJJH66F89GSBolrmlfuNONly8Cbts2Fy_KHI9YwvzwSVcgf_nvefss_H1O8tsvoYpORVuL8IXBrzT7bHxU0Xj5VjiaxDtU6N4oOQafefT8AcdN0IOYnh3Us8uEeeur3_OH473JwO3SjA4NRaS61Aq37UyhvM9pK3ccGOO5JoMkw1V9kDQQVhKiGWfCoTUBlaVkU"

レスポンス：

https://appstore-adx-reporting.s3.amazonaws.com/85923/sales/sales_2018_01.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20180405T060912Z&X-Amz-SignedHeaders=host&X-Amz-Expires=299&X-Amz-Credential=AKIAJMFYXPVLQKTRRB7Q%2F20180405%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=adab43be54631565d330727383341d56989d129e4dea151411cf7a802b9e5e12

エラー

トークンリクエストでエラーが発生した場合、レスポンスのメッセージ本文には次のエラーメッセージのいずれかが含まれます。

S3 URLを使用してレポートをダウンロードする方法

Reporting APIではS3のURLが返されます。これを使用してレポートをダウンロードできます。

エラーメッセージ：

次のいずれかのエラーメッセージがReporting APIから返される場合があります。

Report Not Available（レポートが入手できません）： ファイルをコピーしようとして、指定した名前のファイルがS3フォルダに存在しなかった場合に返されるメッセージです。fatal error: An error occurred (403) when calling the HeadObject operation: Forbidden

User not authorized（ユーザーに権限がありません）： 有効なアクセストークンなしでReporting APIを使用した場合に返されるメッセージです。

Server Unavailable（サーバーが利用できません）： リクエスト送信時にAPIサーバーが利用不可だった場合、またはレポートのダウンロード時にS3バケットが利用不可だった場合に、HTTP 404エラーコードが返されます。

詳細については、S3のError Responses（英語のみ）を参照してください。

Reporting APIに関するよくある質問（FAQ）

Q： APIを使用して取得できるレポートはいつ以降のものですか？

入手できるのは2018年1月以降のレポートです。現在のところ、2017年およびそれ以前のレポートは入手できません。

Q： セキュリティプロファイルを削除するにはどうすればよいですか？

セキュリティプロファイルを削除できるのは管理者レベルのユーザーのみです。[アプリ＆サービス] の下の [セキュリティプロファイル] タブに移動して、該当するセキュリティプロファイルを選択して削除します。

Q： cURLコマンドの範囲がMarketer（マーケティング担当者）と定義されているのはなぜですか？

範囲はAPIアクセスのための必須フィールドです。マーケティング担当者は、Sales Reporting APIのデフォルトの範囲として定義されています。

Q： アクセストークンと署名済みS3 URLは永続的に使用できますか？

いいえ、アクセストークンの有効期間は1時間のみです。署名済みS3 URLは5分間のみ有効です。これらのタイムアウトはセキュリティ上の理由によります。

Q： セキュリティプロファイルのクライアントIDとクライアントシークレットは永続的に使用できますか？

はい。これらは、セキュリティプロファイルが開発者コンソールから削除されるまで使用できます。ただし、セキュリティ上の理由から、APIに関連付けられたセキュリティプロファイルを、少なくとも6か月間に1回は更新することを強くお勧めします。

Q： チームに5人の管理者がいます。管理者全員がセキュリティプロファイルを作成することは可能ですか？ 可能な場合、それはどのように管理されますか？

はい、5人の管理者全員がセキュリティプロファイルを作成できます。各管理者は、すべてのセキュリティプロファイルを閲覧できます（ほかの管理者によって作成されたプロファイルであっても）。

売上レポートのフィールド

CSVファイルは、.csvという拡張子が付いたテキストファイルです。ローカライズされた文字列をサポートするには、CSVファイルにUTF-8エンコードを使用する必要があります。

CSVファイルの1行目は、列名を表示するヘッダーです。2行目以降は、1行に1つのレポートアイテムの情報が含まれています。請求書IDフィールドでは、レポートの各明細項目の一意識別子が定義されます。

次の表は、CSVファイルの各行のフィールドについて説明しています。

注

• 売上データは24時間ごとに更新されます。データのプルを自動化する場合、24時間ごとにスクリプトを実行して最新情報を取得することをお勧めします。なお、報告された情報には最大48時間の遅れが生じる場合もあります。
• APIは1秒あたり最大3つのリクエストをサポートします。API呼び出しの頻度がそれより高い場合、パフォーマンス低下につながることがあります。
• 収益はこのファイルで見積もられます。これは、月末の収益レポートと正確に一致しないことがあります。収益レポートには、ここに含まれない追加調整が含まれる可能性があります。
• すべての調整は、元のトランザクションが発生した月ではなく、調整が行われた月に表示されます。
• テストASINで「Title」と「Item Name」にnull値が表示されます。これは既知の問題であり、今後のリリースで修正される予定です。

定期購入型アイテムレポートのフィールド

CSVファイルは、.csvという拡張子が付いたテキストファイルです。ローカライズされた文字列をサポートするには、CSVファイルにUTF-8エンコードを使用する必要があります。

CSVファイルの1行目は、列名を表示するヘッダーです。2行目以降は、1行に1つのレポートアイテムの情報が含まれています。

次の表は、ファイルの各行のフィールドについて説明しています。Amazonマーケットプレイス、ベンダーSKU、定期購入型アイテムのタイトル、定期購入型アイテムの期間は、開発者コンソールでこの定期購入型アイテムを設定したときに入力した値です。

マーケットプレイス情報

各マーケットプレイスの国／地域コードと通貨の種類は次の表のとおりです。

APIデータセキュリティ

Reporting APIを通じてアクセスできるデータはすべてAmazonの機密情報であり、開発者による使用のみを目的としています。

開発者がAPIアクセス権限を（日々の運用サポートのために）信頼するサードパーティに付与する場合、この情報の共有は開発者自身の責任で行うことに同意するものとみなされます。この情報を共有することによって生じるどのような損失や損害についても、Amazonは一切の責任を負いません。

APIアクセスをサードパーティと共有する場合は、以下のガイドラインに従ってください。

1. サードパーティ専用のセキュリティプロファイルを作成する。
2. セキュリティプロファイルの名前にサードパーティの商号を含める（例：ReportingAPI_<会社名>_<サードパーティ名>）。
3. セキュリティプロファイルの説明フィールドに、セキュリティプロファイルの使用者を明記する。

ご自身のデータ保護のため、6か月ごとにセキュリティプロファイルを更新することを強くお勧めします（Sales Reporting APIに関連付けられているすべてのセキュリティプロファイル）。

Last updated: 2023年12月13日