Reporting API


Reporting API

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

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

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

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

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

    [APIアクセス] ページ

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

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

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

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

これで、クライアント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セキュリティプロファイルの作成方法の手順5で保存したクライアントID
    • client_secretセキュリティプロファイルの作成方法の手順7で保存したクライアントシークレット
    • grant_typeclient_credentialsに設定
    • scopeappstore::apps:readwrite(Reporting APIの場合はadx_reporting::appstore:marketer)に設定

JSONコンテンツの例:

{
    "grant_type": "client_credentials",
    "client_id": "amzn1.application-oa2-client.ae941846cdd745e9a53319f7bb98d435",
    "client_secret": "41d135b2b02ce5f2fbf7643a66477c089fcc1d88d11f69d3e4a6285b917ca35d",    
    "scope": "appstore::apps:readwrite"
}

cURLリクエストの例:

curl -k -X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=amzn1.application-oa2-client.5c1462ee102c4a57a5224d0c72118741&client_secret=15d1829ddf4f12d1c5d425e57e5ca081d0f7a63bd94c9e142ff8b20d9de880a4&scope=appstore::apps:readwrite' https://api.amazon.com/auth/O2/token

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

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

{"access_token":"Atc|MAEBIBav2tvCbJOA9Jv5sRpej6xY_qzHFuCpbWT-Z94nRqVWVcfmZVNPEhZiet-H3vdQcORqE5pO4fCKEi6kfvzzPtxHIoPIte-ZbKB1XgfjfJnciJHqnbV1UF4WJ_an1g9y7yvWKWJddQ2NLPO-C-Y71BPxJ0KDWOPonn_2qFLY5OJo3BhHKIwNHteQAwkCA9iko8d5tosS7fo3dvS-PFmiBk3OMUmr1AdYtuOnq1RVrX7-C14oWzfACudykTn5cDb48Qy2k6R70__GzHG3fC_-Rfzt7zwhfdBWpwoQk-GbV4Bes457oZwHz89Tj-AAf3DouYQ","scope":"appstore::apps:readwrite","token_type":"bearer","expires_in":3600}
  • access_token: アクセストークン
  • expires_in: アクセストークンの有効期限が切れるまでの秒数
  • scopeappstore::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 -k -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 -k -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コマンドの範囲がマーケティング担当者と定義されているのはなぜですか?

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

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

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

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

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

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

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

CSVファイル形式

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

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

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

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

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

フィールド 概要
Marketplace String Amazonマーケットプレイス。 Amazon.com
Country/Region Code String トランザクション元を表す標準的な2桁のISO国/地域コード。このリストを参照してください。 US
Invoice Id String 請求書の一意のID。このフィールドは2017年およびそれ以前のサマリーデータではNAに設定されています。 8dd921637-b092f385a7ee4- 62c6494b3ed702
Transaction Id Integer このトランザクションに関連付けられている一意のID。売上情報にはある特定の日のすべてのトランザクションが含まれているため、このフィールドは2017年およびそれ以前のサマリーデータではNAに設定されています。 21854260140446
Purchaser Id String 匿名化された購入者ID。ベンダーアカウント内のカスタマーに対する一意のIDです。 amzn1.account.AGMODJOGUIUO TR6DSVASQ5UX
Transaction Time String トランザクションの日付と時刻。MM/DD/YY HH:MM:SS XSTの形式で、時間の範囲には00~23を使用します。XSTは、トランザクションのマーケットプレイスに関連付けられたタイムゾーンです。2017年およびそれ以前のデータでは、このフィールドは売上が発生した日を示します。 05/21/18 14:39 PST
Transaction Type String トランザクションタイプはChargeまたはRefundのどちらかです。 Charge
Adjustment YesまたはNo 調整トランザクションの場合、このフィールドはYesに設定されます。2017年およびそれ以前のデータでは、トランザクションタイプがRefundの場合、このフィールドにはnull値が表示されます。 Yes
ASIN Alphanumeric String アプリ/アプリ内課金/定期購入型アイテムのASIN(Amazon Standard Identification Number)。Amazonグループが取り扱う、書籍以外の商品を識別する10桁の番号。 C00006M4PF
Vendor SKU String 150文字までの文字列。使用可能な文字は、a~z、A~Z、0~9、アンダースコア、ピリオド、ダッシュです。SKUでは大文字と小文字が区別されます。 com.gamevendor.fungame
Title String アプリまたはゲームのタイトル。 Smashemup Truck Game
Item Name String アプリ、ゲーム、定期購入型アイテム、アプリ内課金(IAP)アイテム、ゲーム内アイテムのいずれかの名前。 Smashemup Truck Game
Item Type String アイテムのタイプ。値は、SubscriptionAppIn-AppGameIn-Gameのいずれか。 App
In-App Subscription Term String 定期購入の期間。期間は1週間ごと、2週間ごと、1か月ごと、2か月ごと、3か月ごと、6か月ごと、1年ごとのいずれかを指定できます。このフィールドは、アイテムのタイプがSubscriptionの場合にのみ適用されます。
このフィールドはTwitchには適用されません。
Weekly
In-App Subscription Status String ステータスにはTrialPaidのどちらかを指定できます。このフィールドは、アイテムのタイプがSubscriptionの場合にのみ適用されます。
このフィールドはTwitchには適用されません。
Trial
Units Integer このトランザクションに含まれるユニット数。 1
Usage Time String Undergroundアプリの使用時間(秒単位)。このフィールドは、AmazonアプリストアのUnderground商品にのみ適用されます。使用時間を60で除算すれば、ユニット数を計算できます。たとえば、使用時間1200は20ユニットです。
このフィールドはTwitchには適用されません。
1200
Marketplace Currency String トランザクションの通貨はマーケットプレイスで決まります。マーケットプレイス別タイムゾーン表を参照してください。 USD
Sales Price Marketplace Currency 割引後にユーザーに表示される販売価格。消費税は含まれません。Undergroundアプリの場合、販売価格はアプリの使用時間数(分単位)に基づく収益を表します。Undergroundアプリの場合、売上と収益は同じです。調整と返金の場合は、元のアイテムの販売価格が表示されます。実際の調整額または返金額は、販売価格と異なることがあります(一部返金など)。 4.99
Estimated Earnings Marketplace Currency このトランザクションからAmazonのロイヤリティを差し引いた後の収益の見積もりです。調整や返金の場合は、調整額または返金額に基づく収益が表示されます。ベンダーのアカウントから差し引かれた返金は、11月19日以降の期間に対応する収益があるレポートには負の値として表示されます。 3.49

  • 売上データは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
CN CHY 人民元 Amazon.cn
DE 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アクセスをサードパーティと共有する場合は、以下のガイドラインに従ってください。

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

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