Reporting API
開発者はReporting APIを使用して、売上レポートや定期購入型アイテムレポートをダウンロードすることができます。
- セキュリティプロファイルの作成方法
- セキュリティプロファイルをAPIに関連付ける方法
- LWAアクセストークンのリクエスト方法
- アクセストークンの使用方法
- Reporting APIのURL
- 売上/定期購入型アイテムのレポート用URLをリクエストする方法
- S3 URLを使用してレポートをダウンロードする方法
- Reporting APIに関するよくある質問(FAQ)
- 売上レポートのフィールド
- APIデータセキュリティ
開発者コンソールのAPIを使用するには、セキュリティプロファイルを作成し、それを開発者コンソールのAPIに関連付ける必要があります。セキュリティプロファイルは、APIアクセス用のアクセストークンを生成するためのメカニズムです。
セキュリティプロファイルの作成方法
セキュリティプロファイルを作成するには、次の手順に従います。
- Amazon開発者コンソールアカウントにログインします。アカウントがない場合は、アカウントの作成を求められます。
- メインナビゲーションで、[アプリ&サービス] をクリックします。
- サブメニューで、[APIアクセス] を選択します。
-
APIの名前をクリックします。
- [セキュリティプロファイルを新規作成] ボタンをクリックします。
- 新しいプロファイルの [セキュリティプロファイル名] と [セキュリティプロファイルの説明] を入力し、[保存] をクリックします。
- [ウェブ設定] タブを開き、表示されているクライアントIDとクライアントシークレットを保存します。この情報はSales Reporting APIにアクセスする際に必要になります。
セキュリティプロファイルをAPIに関連付ける方法
セキュリティプロファイルをAPIに関連付けるには、次の手順に従います。
- [APIアクセス] ページに戻ります。
- 先ほどクリックしたAPIの名前を再度クリックします。
- 新たに作成したセキュリティプロファイルをドロップダウンリストから選択します。
- [関連付ける] をクリックして、セキュリティプロファイルをこの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.エラーレスポンスを処理する
トークンリクエストでエラーが発生した場合、レスポンスのメッセージ本文には次のエラーメッセージのいずれかが含まれます。
エラーメッセージ本文 | 詳細 |
---|---|
{"error_description":"Client authentication failed", "error":"invalid_client"} | 無効なシークレットキー |
{"error_description":"The request has an invalid parameter : scope", "error":"invalid_scope"} | 無効な範囲の値 |
{"error_description":"The authorization grant type is not supported by the authorization server", "error":"unsupported_grant_type"} | 無効な認可グラントタイプ |
{"error_description":"The Content-Type is not supported by the authorization server", "error":"invalid_request"} | サポート対象外のContent-Type |
アクセストークンの使用方法
有効なアクセストークンを取得したら、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>
パラメーター
<year> | ダウンロードするレポートファイルの年度(4桁) |
<month> | レポートファイルの月の値(2桁) |
例
以下は、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
エラー
トークンリクエストでエラーが発生した場合、レスポンスのメッセージ本文には次のエラーメッセージのいずれかが含まれます。
エラー | 詳細 |
---|---|
{"Message":"Request is not authorized."} | 不適切なアクセスキー、または範囲外のレポートのリクエスト(例:マーケティング担当者が支払いレポート/エージェンシーレポートをリクエストした場合)。 |
{"Message":"Unable to fetch the request scope for uri = (URL Entered) and verb = GET"} | 無効なURLまたはメソッド。 |
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ファイルの各行のフィールドについて説明しています。
フィールド | 型 | 説明 | 例 |
---|---|---|---|
Marketplace | 文字列 | Amazonマーケットプレイス。 | Amazon.com |
Country/Region Code | 文字列 | トランザクション元を表す標準的な2桁のISO国/地域コード。このリストを参照してください。 | US |
Invoice Id | 文字列 | 請求書の一意のID。このフィールドは2017年およびそれ以前のサマリーデータではNAに設定されています。 | 8dd921637-b092f385a7ee4- 62c6494b3ed702 |
Transaction Id | 整数 | このトランザクションに関連付けられている一意のID。売上情報にはある特定の日のすべてのトランザクションが含まれているため、このフィールドは2017年およびそれ以前のサマリーデータではNAに設定されています。 | 21854260140446 |
Transaction Time | 文字列 | トランザクションの日付と時刻。MM/DD/YY HH:MM:SS XSTの形式で、時間の範囲には00~23を使用します。XSTは、トランザクションのマーケットプレイスに関連付けられたタイムゾーンです。2017年およびそれ以前のデータでは、このフィールドは売上が発生した日を示します。 | 05/21/18 14:39 PST |
Transaction Type | 文字列 | トランザクションタイプは、Charge、Refund、Chargeback、Chargeback reversalのいずれかです。 | Charge |
Adjustment | YesまたはNo | 調整トランザクションの場合、このフィールドはYesに設定されます。2017年およびそれ以前のデータでは、トランザクションタイプがRefundの場合、このフィールドにはnull値が表示されます。 | Yes |
ASIN | 英数字の文字列 | アプリ/アプリ内課金/定期購入型アイテムのASIN(Amazon Standard Identification Number)。Amazonグループが取り扱う、書籍以外の商品を識別する10桁の番号。 | C00006M4PF |
Vendor SKU | 文字列 | 150文字までの文字列。使用可能な文字は、a~z、A~Z、0~9、アンダースコア、ピリオド、ダッシュです。SKUでは大文字と小文字が区別されます。 | com.gamevendor.fungame |
Title | 文字列 | アプリまたはゲームのタイトル。 | Smashemup Truck Game |
Item Name | 文字列 | アプリ、ゲーム、定期購入型アイテム、アプリ内課金(IAP)アイテム、ゲーム内アイテムのいずれかの名前。 | Smashemup Truck Game |
Item Type | 文字列 | アイテムのタイプ。値は、Subscription、In-App、Game、In-Game、Applicationのいずれかです。Applicationは、アプリの購入を指します。これは新規アプリのインストールのことで、Amazonアカウントに固有です。Applicationアイテムには、アプリのアップデートは含まれません。 | Application |
In-App Subscription Term | 文字列 | 定期購入の期間。期間は、Weekly(1週間ごと)、BiWeekly(2週間ごと)、Monthly(1か月ごと)、BiMonthly(2か月ごと)、Quarterly(3か月ごと)、SemiAnnually(6か月ごと)、Annually(1年ごと)のいずれかです。このフィールドは、アイテムのタイプがSubscriptionの場合にのみ適用されます。 このフィールドはTwitchには適用されません。 |
Weekly |
In-App Subscription Status | 文字列 | ステータスは、TRIAL(無料体験)、PAID(有料)、Introductory Price - All Customers(導入価格 - すべてのユーザー)、Promotional Price - Lapsed Customers(プロモーション価格 - 休眠中のユーザー)のいずれかです。このフィールドは、アイテムのタイプがSubscriptionの場合にのみ適用されます。詳細については、定期購入のステータスを参照してください。 このフィールドはTwitchには適用されません。 |
TRIAL |
Units | 整数 | このトランザクションに含まれるユニット数。 | 1 |
Usage Time | 文字列 | Undergroundアプリの使用時間(秒単位)。このフィールドは、AmazonアプリストアのUnderground商品にのみ適用されます。使用時間を60で除算すれば、ユニット数を計算できます。たとえば、使用時間1200は20ユニットです。 このフィールドはTwitchには適用されません。 |
1200 |
Marketplace Currency | 文字列 | トランザクションの通貨はマーケットプレイスで決まります。マーケットプレイス別タイムゾーン表を参照してください。 | USD |
Sales Price | マーケットプレイスの通貨 | 割引後にユーザーに表示される販売価格。消費税は含まれません。Undergroundアプリの場合、販売価格はアプリの使用時間数(分単位)に基づく収益を表します。Undergroundアプリの場合、売上と収益は同じです。調整の場合は、元のアイテムの販売価格が表示されます。実際の調整額または最終的な返金額は、販売価格と異なることがあります(一部返金など)。返金およびチャージバック(トランザクションタイプがRefundおよびChargeback)の場合、相当する販売価格はマイナスになります。 | 4.99 |
Estimated Earnings | マーケットプレイスの通貨 | このトランザクションからAmazonのロイヤリティを差し引いた後の収益の見積もりです。調整や返金の場合は、調整額または返金額に基づく収益が表示されます。ベンダーのアカウントから差し引かれた返金は、11月19日以降の期間に対応する収益があるレポートには負の値として表示されます。 | 3.49 |
App User ID | 文字列 | トランザクションの一意のユーザーID。App User IDは、次のシナリオでは表示されません。
|
hQygC+MjonyR2Z0TMY03nyxeVxqIHq3+rK39TGzhkk0= |
Receipt ID | 文字列 | トランザクションの一意のレシートID。Receipt IDは、次のシナリオでは表示されません。
|
EgL-HstEAXhMfTuQ5_NkhQicjp_sRpJ5Lic78cF-3HY=:1:13 |
Digital Order ID | 文字列 | トランザクションの一意の注文ID。 | d01-6680198-0475238 |
Device Type | 文字列 | ユーザーが購入に使用したデバイスのタイプ。「Others」というタイプカテゴリーには、未分類のデバイスタイプで行われたアプリ購入(ウェブ経由のアプリ購入など)が含まれます。 | Fire TV |
注
- 売上データは24時間ごとに更新されます。データのプルを自動化する場合、24時間ごとにスクリプトを実行して最新情報を取得することをお勧めします。なお、報告された情報には最大48時間の遅れが生じる場合もあります。
- APIは1秒あたり最大3つのリクエストをサポートします。API呼び出しの頻度がそれより高い場合、パフォーマンス低下につながることがあります。
- 収益はこのファイルで見積もられます。これは、月末の収益レポートと正確に一致しないことがあります。収益レポートには、ここに含まれない追加調整が含まれる可能性があります。
- すべての調整は、元のトランザクションが発生した月ではなく、調整が行われた月に表示されます。
- テストASINで「Title」と「Item Name」にnull値が表示されます。これは既知の問題であり、今後のリリースで修正される予定です。
定期購入型アイテムレポートのフィールド
CSVファイルは、.csvという拡張子が付いたテキストファイルです。ローカライズされた文字列をサポートするには、CSVファイルにUTF-8エンコードを使用する必要があります。
CSVファイルの1行目は、列名を表示するヘッダーです。2行目以降は、1行に1つのレポートアイテムの情報が含まれています。
次の表は、ファイルの各行のフィールドについて説明しています。Amazonマーケットプレイス、ベンダーSKU、定期購入型アイテムのタイトル、定期購入型アイテムの期間は、開発者コンソールでこの定期購入型アイテムを設定したときに入力した値です。
フィールド | 説明 | 例 |
---|---|---|
Date | このレコードの定期購入型アイテムのデータが収集された日付。 | 12/29/18 |
Marketplace | このレコードのデータに関連付けられているAmazonマーケットプレイス。 | Amazon.com |
App Title | 定期購入型アイテムのアプリのタイトル。 | My Test App |
ASIN | 定期購入型アイテムのASIN(Amazon Standard Identification Number)。Amazonグループが取り扱う、書籍以外の商品を識別する10桁の番号。 | C00006M4PF |
Vendor SKU | 定期購入型アイテムのSKU。 | com.test.monthly |
Subscription Title | 定期購入型アイテムのタイトル。 | Test Monthly Subscription |
Subscription Duration | 定期購入型アイテムの期間。 | Monthly |
Subscription Type | 定期購入型アイテムのタイプ。値は trialまたはpaidです。 | paid |
Active | 指定した日付の終了時(協定世界時の午後11:59)にアクティブな定期購入型アイテムの合計数。 | 7261 |
Started | 指定した日付に使用が開始された定期購入型アイテムの数。 | 163 |
Ended | 指定した日付にキャンセルされるか、更新されずに終了した定期購入型アイテムの数。 | 163 |
Refunded | 指定した日付に返金された定期購入型アイテムの数。 | 163 |
マーケットプレイス情報
各マーケットプレイスの国/地域コードと通貨の種類は次の表のとおりです。
国/地域 コード |
通貨 コード |
通貨 | マーケットプレイス |
---|---|---|---|
AU | AUD | オーストラリアドル | Amazon.com.au |
BR | BRL | レアル | Amazon.com.br |
CA | CAN | カナダドル | Amazon.ca |
ドイツ | EUR | ユーロ | Amazon.de |
ES | EUR | ユーロ | Amazon.es |
FR | EUR | ユーロ | Amazon.fr |
GB | GBP | ポンド | Amazon.co.uk |
IN | INR | インドルピー | Amazon.in |
IT | EUR | ユーロ | Amazon.it |
JP | JPY | 日本円 | Amazon.co.jp |
US | USD | ドル | Amazon.com |
APIデータセキュリティ
Reporting APIを通じてアクセスできるデータはすべてAmazonの機密情報であり、開発者による使用のみを目的としています。
開発者がAPIアクセス権限を(日々の運用サポートのために)信頼するサードパーティに付与する場合、この情報の共有は開発者自身の責任で行うことに同意するものとみなされます。この情報を共有することによって生じるどのような損失や損害についても、Amazonは一切の責任を負いません。
APIアクセスをサードパーティと共有する場合は、以下のガイドラインに従ってください。
- サードパーティ専用のセキュリティプロファイルを作成する。
- セキュリティプロファイルの名前にサードパーティの商号を含める(例:
ReportingAPI_<会社名>_<サードパーティ名>
)。 - セキュリティプロファイルの説明フィールドに、セキュリティプロファイルの使用者を明記する。
ご自身のデータ保護のため、6か月ごとにセキュリティプロファイルを更新することを強くお勧めします(Sales Reporting APIに関連付けられているすべてのセキュリティプロファイル)。
Last updated: 2023年12月13日