(Amazon MWS) 開発者ガイド

Amazon マーケットプレイスWebサー
ビス (Amazon MWS) 開発者ガイド
2
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
2
目次
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド.................................................. 3
Amazon MWS とは？..................................................................................................................................... 4
Amazon MWS 利用への登録...........................................................................................................................5
Amazon MWS アプリケーションの開発.........................................................................................................8
Amazon マーケットプレイス Web サービスエンドポイント.......................................................................10
スロットリング: リクエストを送信できる頻度を制限する........................................................................... 11
NextTokenを使用して追加ページをリクエストする.....................................................................................13
NextTokenの使い方................................................................................................................................................................................... 13
NextTokensのエラー処理について............................................................................................................................................................14
Amazon MWS のクライアントライブラリの使用.........................................................................................15
独自のクライアントライブラリを作成する場合....................................................................................................................................... 15
Content-MD5 ヘッダとMD5チェックサム.....................................................................................................23
必須リクエストパラメータ.............................................................................................................................25
レスポンスのフォーマット.............................................................................................................................27
エラーの対応について....................................................................................................................................28
関連リソース.................................................................................................................................................. 31
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
2
3
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
3
Amazon マーケットプレイスWebサービス
(Amazon MWS) 開発者ガイド
Copyright © 2010-2014 Amazon.com, Inc. またはその関係者。AMAZONおよびAMAZON.COMはAmazon.com,
Inc.またはその関係者の登録商標です。その他のすべての商標は、それぞれの所有者に帰属します。
最終更新 2014-08-19
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
3
4
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
4
Amazon MWS とは？
Amazon マーケットプレイスWebサービス (Amazon MWS)は統合されたWebサービス API で、これにより出
品者は出品、注文、支払い、レポートなどをプログラムでデータを交換することができます。Amazon と
データ統合することで、高レベルの販売自動化が可能となり、出品者がビジネスを成長させるのに役立ち
ます。Amazon MWSを使用することで、出品者は販売効率を高め、労働力を軽減し、カスタマーへの応答
時間を改善することができます。
Amazon MWSに関連付けられる手数料はありませんが、Amazon MWS API を使用するには、Amazon
MWSを利用するのに適した出品者アカウントを持っており、Amazon MWSに登録する必要があります。
Amazon MWSでできること
Amazon MWSにより、ご自身の Amazon 出品者アカウント用のアプリケーションを構築することができま
す。また、他の出品者のためにアプリケーションを構築し、彼らがオンラインビジネスを管理するのをサ
ポートすることができます。Amazon MWSを使用すれば、販売用の商品を検索、出荷用の注文をダウン
ロード、配送の確認、レポートのスケジュール化やレポートの受信を可能にするアプリケーションを作成
することができます。これらの API オペレーションには、REST のようなインターフェイスを使用してアク
セスすることができます。
Amazon MWSには以下のような機能があります。
•
在庫管理 - 在庫品の一括アップロードを行なったり、商品を追加したり、在庫レベルを確認したり、ま
た価格情報やその他の在庫管理タスクを調べることができます。
•
注文管理 - 注文情報をダウンロードし、支払いデータを取得して、注文を承認し、レポートのスケ
ジュール化ができます。
•
レポートの管理 - さまざまなレポートをリクエストできるだけでなく、これらのレポートのステータス
を問い合わせて(クエリして)ダウンロードすることができます。
フルフィルメント by Amazon (FBA)の出品者は、 Amazon MWSで以下の操作もおこなえます。
•
Amazon フルフィルメントセンターへの納品手続きを作成 - Amazon フルフィルメントセンターへ出荷す
るユニットのラベル作成プロセスを自動化することができます。
•
納品手続きのステータスを確認 - 発送した商品がフルフィルメントセンターに届けられたか、またその
場合、納品の手続きが処理されたかどうかを確認することができます。
•
注文を発送 - Amazon MWSでシステムを統合することにより、カスタマーはいつでもマルチチャネルの
出荷注文をすることができます。注文のプロセスまたはバッチに時間の遅れはありません。
•
商品の出荷リクエストの追跡と管理 - 注文された商品が Amazon フルフィルメントセンターを出た後
は、その配送を追跡でき、カスタマーに配達日を知らせることができます。
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
4
5
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
5
Amazon MWS 利用への登録
Amazon MWSを利用できる出品用アカウントに登録
Amazon MWSを利用する資格を得るには、次の Amazon アカウントのいずれかを持っている必要がありま
す。
•
•
•
•
•
•
小口出品ではない出品者アカウント
Amazon Webstore
Amazon Product Ads (商品広告)
Amazon Payments
Amazon Fresh
Amazon Supply
Amazon MWS利用への登録
Amazon MWSは、認証のために署名を使用し、Amazon MWS認証サービスを用いて出品者が呼び出す権限
を開発者に委託することのできる安全な環境です。Amazon MWSを利用するには、Amazon MWSを利用で
きる出品用アカウントを持ち、以下のサイトのいずれかでAmazon MWSの登録をする必要があります。
•
NA (North America)
•
• CA: https://developer.amazonservices.ca
• US: https://developer.amazonservices.com
EU (European Union)
•
• DE: https://developer.amazonservices.de
• ES: https://developer.amazonservices.es
• FR: https://developer.amazonservices.fr
• IN: https://developer.amazonservices.in
• IT: https://developer.amazonservices.it
• UK: https://developer.amazonservices.co.uk
FE (Far East)
•
• JP: https://developer.amazonservices.jp
CN (China)
•
CN: https://developer.amazonservices.com.cn
Amazon MWS利用のために登録する場合、3つの選択肢があります。
MWSで自分のAmazon出品用アカウントにアクセスする場合 — Amazon MWSをご自身のAmazon出品用
アカウントでご利用になる場合、Amazon MWSをデスクトップアプリケーションでご利用になる場合、
出品者向けのウェブアプリケーションを開発する場合は、このオプションを選択してください。Amazon
MWSによって、ご自身のアカウントに開発者アカウント ID が割り当てられます。Amazon MWSのリクエ
ストを行う際に、開発者アカウントに関連付けられた開発者アカウント認証情報に加え、出品用アカウン
ト用の出品者 ID を使用します。
MWSで自分のAmazon出品用アカウントにアクセスするアプリケーションを使用する場合 — Amazon
MWSでAmazon出品用アカウントにアクセスするウェブアプリケーションを使用する場合は、このオプショ
ンを選択してください。登録の際には、使用するウェブアプリケーションの開発者アカウント ID を入力す
る必要があります。Amazon MWS登録プロセスの最終ページに、出品者IDとMWS認証トークンが表示され
ます。あなたが使用するウェブアプリケーションでこれらのIDを使用します。
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
5
6
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
6
MWSで開発者が自分のAmazon出品者アカウントへアクセスすることを許可する場合—Amazon MWSで、
サードパーティの開発者がご自身のアカウントへアクセスすることを許可する場合は、このオプション
を選択してください。登録の際には、利用する開発者の開発者アカウント ID を入力する必要がありま
す。Amazon MWS登録プロセスの最終ページに、出品者IDとMWS認証トークンが表示されます。これら
のIDを開発者に付与する必要があります。
開発者として登録
MWSで自分のAmazon出品用アカウントにアクセスする場合を選択して登録が完了すると、重要な認証情
報がいくつか付与されます。ご自身の出品者 ID、マーケットプレイス ID、開発者アカウント ID、AWS ア
クセスキー ID、および秘密キーは、Amazon MWS登録プロセスの最終ページに表示されます。この情報
は、Eメールでは送信されません。このページを印刷するか、ハードドライブに保存しておいてください。
認証情報や ID を再度閲覧する必要がある場合は、Amazon MWS登録プロセスを繰り返します複数回登録を
行っても、最初の登録には影響せず、毎回同じ認証情報が返されます。
あなたがAmazon MWSウェブアプリケーションを開発中の場合、またはAmazon MWS関連の開発サービス
を他の出品者に提供している場合は、ご自身の開発者アカウント ID を出品者に提供する必要があります。
そうすれば、Amazon MWSで他のAmazon出品用アカウントにアクセスするときに、アクセスが許可されま
す。Amazon MWSデスクトップアプリケーションを開発中の場合は、アプリケーションに認証情報を組み
込まないでください。その代わりとして、Amazon MWSに登録する際に、MWSで自分のAmazon出品用ア
カウントにアクセスする場合を選択してあなたのアプリケーションにユーザーを開発者として登録させて
ください。デスクトップアプリケーションのユーザーは、リクエストをAmazon MWSに送信する際にユー
ザー自身の開発者の認証情報を使用してください。
次のリストは、Amazon MWSでご自身の出品用アカウントへのアクセスを登録した際に表示される認証情
報とIDの例です。
•
開発者アカウント ID(12桁の ID): 1234-3214-4321
•
AWSアクセスキー ID(20文字の英数字の ID): 022QF0EXAMPLEH9DHM02
•
秘密キー(40文字の ID): kWcrlEXAMPLEM/LtmEENI/aVmYvHNif5zB+d9+ct
アクセスキー ID は、あなたのAmazon MWSの登録に関連付けられています。これをAmazon MWSの全リク
エストに含めて、あなたがリクエストの送信者であることを証明します。アクセスキーIDは公開してもか
まいません。あなたがそのリクエストの送信者であることを証明するために、リクエストには電子署名を
含める必要があります。Amazon MWSクライアントライブラリを使用して生成された以外の全リクエスト
は、あなたの秘密キーを用いて署名を適合します。Amazonは、リクエスト内のアクセスキー ID を利用し
てあなたの秘密キーを参照し、キーで電子署名を適合します。Amazonが適合した電子署名が、あなたの送
信した署名と一致した場合は、そのリクエストは正当と考えられます。もし一致しない場合は、リクエス
トは認証されず、処理も行われません。
Note: ご自身の秘密キーは、あなたとAmazonのみが知っているべきで他に知られてはいけません。
ご自身のアカウントを保護するために、この情報は機密情報として扱っていただくことが重要で
す。Amazon MWSへのリクエストの中に決して秘密キーを含めないでください。デスクトップアプ
リケーションに組み込まないでください。また誰にもＥメールで送信しないでください。問い合わ
せがAmazon MWSから、または Amazon 関係者から来ているように見える場合でも、あなたの組織
以外の人々と秘密キーを共有しないでください。合法的に Amazon を代表する誰かが、あなたの秘
密キーを訊ねることは絶対にありません。
開発者やアプリケーションにアカウントへのアクセスを許可
サードパーティの開発者を認証するには、まず開発者がその人のAmazon MWS開発者アカウント ID をあな
たに与える必要があります。この開発者アカウント ID を入力することによって、開発者があなたのアカウ
ントにアクセスすることを許可する登録を行うことができます。そして、ご自身の出品者 ID とMWS認証
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
6
7
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
7
トークンを開発者に与える必要があります。これで、あなたに代わってAmazon MWSがリクエストを行う
ことができます。Amazon MWS登録プロセスの最終ページに、出品者ID、マーケットプレイスID、MWS認
証トークンが表示されます。詳細については、「Amazon MWS アプリケーションの開発」を参照してくだ
さい。
Customer APIとCart APIセクションの認証
Amazon MWSへの登録に加え、Customer APIセクション、またはCart APIセクションを使用するには、それ
ぞれに認証をリクエストする必要があります。あなたのアプリケーション、またはサードパーティにの開
発者に依頼してアプリケーションを開発するには、セラーセントラルの「Webstore API Management」(US)
(UK) を参照して認証をリクエストします。
Note: Customer APIセクションとCart APIセクションは、Seller-Branded チェックアウトを使用する
ウェブストアに情報を返します。購入者情報とカート情報は、Amazon.com チェックアウトを使用
するウェブストアには返されません。あなたのウェブストアが両方のチェックアウトオプションを
提供している場合、購入者情報、またはカート情報はSeller-Branded チェックアウトアカウントの
みに返されます。Seller-Branded チェックアウトについて詳しくは、Amazon ウェブストアヘルプの
「Your Amazon Webstore Checkout Options」(US) (UK)を参照してください。
Note: Customer APIセクションとCart APIセクションは、アメリカ合衆国(US)とイギリス(UK)のみで
ご利用いただけます。
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
7
8
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
8
Amazon MWS アプリケーションの開発
Amazon MWSクライアントライブラリを使用するアプリケーションを作成するには、Java、C#、または
PHP の開発環境が必要です。
ご自身のAmazon出品用アカウント用にソフトウェアを構築するのにAmazon MWSを使用している開発
者の場合は、Amazon MWSへの登録時にAmazon出品用アカウントのEメールアドレスを使用し、Amazon
MWSでご自身のAmazon MWSの出品用アカウントを使用するというオプションを選択してください。詳細
については、「Amazon MWS 利用への登録」を参照してください。
Amazon MWS の利用資格がある他のAmazon出品者のためにウェブアプリケーションを構築するの
にAmazon MWS を使用したい開発者は、まず自分自身のAmazon MWSの出品者アカウントでAmazon
MWSに登録する必要があります。あなたが開発したサービスまたはウェブアプリケーションを使用したい
出品者に開発者アカウントIDを提供する必要があるため、Amazon MWS登録の最終ページで、あなたの開
発者アカウント ID をメモするようにしてください。
あなたが開発したウェブアプリケーションを他の出品者アカウントでテストする準備が整ったら、出品者
にあなたの開発者アカウント ID を提供してください。これは出品者がAmazon MWSに登録するために使用
するものです。出品者は彼ら自身のAmazon MWS用出品用アカウントにログインし、あなたの開発者アカ
ウント ID を登録プロセス中に入力します。出品者は彼らのアカウントの出品者 ID および MWS認証トーク
ンをメモし、あなたにその情報を提供する必要があります。その後、彼らの出品者認証情報とあなたの開
発者認証情報を使用して、彼らに代わってあなたがAmazon MWSにリクエストを行うことができます。
Amazon MWSデスクトップアプリケーションを開発中の場合は、アプリケーションに認証情報を組み込ま
ないでください。その代わりとして、Amazon MWSに登録する際にMWSで自分のAmazon出品用アカウ
ントにアクセスする場合を選択してあなたのアプリケーションにユーザーを開発者として登録させてくだ
さい。あなたのデスクトップアプリケーションのユーザーは、Amazon MWSにリクエストを送信する際、
ユーザー自身の認証情報を使用する必要があります。詳細については、「Amazon MWS 利用への登録」を
参照してください。
Note: MWS認証トークンはデスクトップアプリケーションには必要ありません。
アプリケーション開発に関してさらにサポートが必要な場合は、Amazon MWSで利用可能なその他のリ
ソースを使用することをお勧めします。詳細については、「関連リソース」の項を参照してください。
Note: Amazon MWSポータルのよくある質問のページで、Amazon 出品者用Amazon MWSアプリケー
ションの開発および認証プロセスに関するその他の情報をご参照ください。
•
NA (North America)
•
• CA: https://developer.amazonservices.ca
• US: https://developer.amazonservices.com
EU (European Union)
•
• DE: https://developer.amazonservices.de
• ES: https://developer.amazonservices.es
• FR: https://developer.amazonservices.fr
• IN: https://developer.amazonservices.in
• IT: https://developer.amazonservices.it
• UK: https://developer.amazonservices.co.uk
FE (Far East)
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
8
9
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
•
9
• JP: https://developer.amazonservices.jp
CN (China)
•
CN: https://developer.amazonservices.com.cn
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
9
10
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
10
Amazon マーケットプレイス Web サービスエ
ンドポイント
Amazon マーケットプレイスごとのURLエンドポイントを介してAmazon マーケットプレイスWebサービス
(Amazon MWS)にアクセスします。次の表は、現在利用が可能となっているAmazon MWSのエンドポイント
を示しています。
Table 1: NA (North America)
Amazon マーケットプレイス
Amazon MWSエンドポイント
マーケットプレイスID
CA
https://mws.amazonservices.ca
A2EUQ1WTGCTBG2
US
https://mws.amazonservices.com
ATVPDKIKX0DER
Amazon マーケットプレイス
Amazon MWSエンドポイント
マーケットプレイスID
DE
https://mws-eu.amazonservices.com
A1PA6795UKMFR9
ES
https://mws-eu.amazonservices.com
A1RKKUPIHCS9HS
FR
https://mws-eu.amazonservices.com
A13V1IB3VIYZZH
IN
https://mws.amazonservices.in
A21TJRUUN4KGV
IT
https://mws-eu.amazonservices.com
APJ6JRA9NG5V4
UK
https://mws-eu.amazonservices.com
A1F83G8C2ARO7P
Amazon マーケットプレイス
Amazon MWSエンドポイント
マーケットプレイスID
JP
https://mws.amazonservices.jp
A1VC38T7YXB528
Amazon マーケットプレイス
Amazon MWSエンドポイント
マーケットプレイスID
CN
https://mws.amazonservices.com.cn
AAHKV2X7AFYLW
Table 2: EU (European Union)
Table 3: FE (Far East)
Table 4: CN (China)
インバウンド接続のSSL要件
Amazon MWSエンドポイントへのインバウンド接続は、SSL version 3、または SSL version 3.1で接続しま
す。SSL version 2 では接続できません。
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
10
11
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
11
スロットリング: リクエストを送信できる頻度
を制限する
Amazon マーケットプレイスWebサービス (Amazon MWS)を正常に使用するには、スロットルを理解する必
要があります。スロットルとは、一定時間内に送信できるリクエスト数を制限するプロセスのことです。
リクエストとは、在庫フィードを送信したとき、または注文レポートをリクエストしたときなどです。ス
ロットルは、リクエストがWebサービスに殺到するのを防ぎ、認証されたすべての開発者が確実にWebサー
ビスにアクセスできるようにするものです。
Amazon MWSでは、リーキー・バケット・アルゴリズムのバリエーションを使用して、Webサービスを測
定し、スロットルを実行します。このアルゴリズムは、下部にあいた穴から一定速度で水が流れ出すバケ
ツの例えに基づいています。断続的にバケツに水を追加することができますが、あまりにも多くの水を一
度に加えたり、速すぎる平均速度で水を加えたりした場合、水がバケツの容量を超えてしまいます。
バケツを最大リクエストクォータ、つまり一度に行うことができるリクエストの最大数と考え、Amazon
MWSにこの例えを適用してみてください。バケツの穴は回復レート、つまり新しいリクエストを行うこ
とができるようになるまでにかかる時間を表しています。したがって、一度に多すぎるリクエストを送信
するとバケツの水があふれます。これをAmazon MWSの場合に置き換えると、スロットルが起こります。
水はバケツから一定速度で漏れているため、バケツを満たしておくには、バケツに水を追加する前に少し
待たなければなりません。そのため、最大リクエストクォータに達した後のリクエスト実行能力は、回復
レート、つまり新しいリクエストを行えるようになるまでの時間によって管理されています。
Amazon MWSスロットルをコントロールする3つの値の定義は以下のとおりです。
•
リクエストクォータ - スロットルが発生せずに一度に送信できるリクエスト数。リクエストクォータは
リクエストを送信するごとに減少し、回復レートで増加します。リクエストは、Amazonの出品用アカウ
ントとAmazon MWS開発者アカウントの組み合わせごとに計算されます。
•
回復レート(リカバリーレートとも呼ばれる) - 最大リクエストクォータに達するまで、時間をかけてリ
クエストクォータが増加する率です。
•
最大リクエストクォータ(バーストレートとも呼ばれる) - リクエストクォータが達することができる最
大サイズです。
次の例を考え、これらのアイデアを適用してみてください。SubmitFeedオペレーションを使って、25の在
庫フィードを送信したいと考えてください。SubmitFeedオペレーションの最大リクエストクォータは15回
で、2分ごとに新規1リクエストの回復レートです。一度に25フィードのリクエストを送信すると、15回以
降のリクエストはスロットルされます。そのため、リクエストクォータが復元された後で、もう一度10個
のフィードのリクエストを再送信する必要があります。回復レートは2分ごとに1リクエストであるため、
残り10個のフィードのリクエストを送信できるようなるまでに20分かかります。そのため、すべてのリ
クエストを送信してスロットルされたリクエストを再送信する代わりに、プロセスを自動化して徐々に
フィードのリクエストを送信することができます。
例えば、(元の25フィードのうちの)10個のフィードのリクエストを送信すると、リクエストクォータには
まだ5リクエストが残っています。その後10分待つと、回復レートによりリクエストクォータが10回に増
加します(2分ごとにリクエスト1つが増えるので、10分で5つの新しいリクエストができます)。そして、も
う10個のフィードのリクエストを送信します。残りの5つのフィードのリクエストは、さらに10分待ってか
ら送信できます。万事がうまくいけば、25個すべてのインベントリフィードを約20分で送信できることに
なります。
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
11
12
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
12
リクエストを自動化すること考慮し、代替え処理ができるようにしてください。そうすれば、最大リクエ
ストクォータに達したか、またはWebサービスに高いトラフィック量が起きたかでスロットルが発生した場
合には、リクエストの数を減らして、最初に送信されなかったリクエストを再送信することができます。
スロットルを回避するためのヒント
フィードや送信したリクエストが正常に処理されるよう、以下の点をご確認ください。
•
送信する特定のリクエストのスロットル制限を理解しておいてください。
•
サービスが利用不可の場合に、自動的にリクエスト数を減らす「バックオフ」プランを立てておいてく
ださい。プランでは、回復レート値を使って、いつリクエストが再送信されるべきかを決めてくださ
い。
•
〇〇時0分ちょうど、〇〇時30分ちょうどでなく、それ以外の時刻を選んでリクエストを送信してくだ
さい。例えば、〇〇時11分、または〇〇時41分というような時刻でリクエストを送信してください。
•
夕方や早朝など、1日のうちで Amazon MWS のトラフィックが低くなりがちな時間をうまく活用してく
ださい。
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
12
13
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
13
NextTokenを使用して追加ページをリクエス
トする
Amazon マーケットプレイスWebサービス (Amazon MWS)は、ページごとに返されるレスポンスの最大数
より多くのレスポンス要素を生成した場合、リクエストを送信する際、「ByNextToken」オペレーション
でNextToken を送信し、追加ページをリクエストします。 NextTokenは、各Amazon MWSAPIセクションに
あるNextTokenの内容と異なる部分があります。
NextTokenの使い方
HasNextを返すオペレーションのNextTokenの使い方
1. オペレーションを呼び出します。
HasNext レスポンス要素が false を返した場合、他に返されるレスポンス要素はありません。タスクは完
了しています。
または、
HasNextレスポンス要素がtrueを返した場合、他に返されるレスポンス要素があることを示します。操
作2に進みます。
2. 操作1で呼び出したオペレーションと一致する「ByNextToken」オペレーションを呼び出します(例え
ば、GetReportList を呼び出した場合は GetReportListByNextToken を呼び出します)。呼び出す際に、
操作1で返された NextToken 値を指定します。
HasNext レスポンス要素が false を返した場合、他に返されるレスポンス要素はありません。タスクは完
了しています。
または、
HasNextレスポンス要素がtrueを返した場合、他に返されるレスポンス要素があることを示します。操
作3に進みます。
3. HasNext レスポンス要素が false を返すまで、「ByNextToken」オペレーションを呼び出し続けます。
MoreResultsAvailableを返すオペレーションのNextTokenの使い方
1. オペレーションを呼び出します。
MoreResultsAvailable レスポンス要素が false を返した場合、他に返されるレスポンス要素はありません
が、今後、返される結果が追加される予定です。それまでは操作2へ進みます。待ち時間はビジネスの
プロセスや、オペレーションが新しい結果を返す頻度により異なります。
または、
MoreResultsAvailableレスポンス要素がtrueを返した場合、他に返されるレスポンス要素があることを示
します。操作2に進みます。
2. 操作1で呼び出したオペレーションと一致する「ByNextToken」オペレーションを呼び出します(例え
ば、ListCustomersを呼び出した場合はListCustomersByNextTokenを呼び出します)。呼び出す際に、操
作1で返されたNextToken値を指定します。
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
13
14
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
14
MoreResultsAvailable レスポンス要素が false を返した場合、他に返されるレスポンス要素はありません
が、今後、返される結果が追加される予定です。それまでは操作3へ進みます。待ち時間はビジネスの
プロセスや、オペレーションが新しい結果を返す頻度により異なります。
または、
MoreResultsAvailableレスポンス要素がtrueを返した場合、他に返されるレスポンス要素があることを示
します。操作3に進みます。
3. HasNext レスポンス要素が false を返すまで、「ByNextToken」オペレーションを呼び出し続けます。そ
して、ByNextTokenオペレーションを再度呼び出す前にしばらく待ちます。待ち時間はビジネスのプロ
セスや、オペレーションが新しい結果を返す頻度により異なります。
HasNext、またはMoreResultsAvailableを返さないオペレーションのNextTokenの使い方
1. オペレーションを呼び出します。
NextTokenレスポンス要素が返されなかった場合、他に返されるレスポンス要素がないことを示してい
ます。タスクは完了しています。
または、
NextTokenレスポンス要素が返された場合、他に返されるレスポンス要素があることを示しています。
操作2に進みます。
2. 操作1で呼び出したオペレーションと一致する「ByNextToken」オペレーションを呼び出します(例え
ば、ListOrdersを呼び出した場合はListOrdersByNextTokenを呼び出します)。呼び出す際に、操作1で
返されたNextToken値を指定します。
NextTokenレスポンス要素が返されなかった場合、他に返されるレスポンス要素がないことを示してい
ます。タスクは完了しています。
または、
NextTokenレスポンス要素が返された場合、他に返されるレスポンス要素があることを示しています。
操作3に進みます。
3. NextTokenレスポンス要素が返されなくなるまで「ByNextToken」オペレーションを呼び出し続けます。
NextTokensのエラー処理について
ByNextTokenオペレーションにNextTokenを送信し、サービスがNextTokenCorruptedエラーを返したことが
ある場合は、同じNextTokenで呼び出しを繰り返さないでください。代わりに、NextTokenを最初に作成し
たオペレーションを呼び出し、新しいNextTokenを取得してください。
例えば、ListOrdersByNextTokenオペレーションを呼び出してNextTokenCorruptedエラーを受信
した場合は、ListOrdersオペレーションを呼び出して新しいNextTokenを生成してください。新し
いNextTokenをListOrdersByNextTokenへ渡します。
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
14
15
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
15
Amazon MWS のクライアントライブラリの使
用
各Amazon MWS API のセクションには、Amazon MWSで多くの一般的なタスクを実行するためのコードが
含まれているそれぞれのクライアントライブラリがあります。Amazon MWSのクライアントライブラリを
使用することで、時間が節約でき、送信するリクエストが正しくフォーマットされていることが分かりま
す。例えば、Amazon MWSのクライアントライブラリで以下のタスクが実行できます。
•
リクエストの署名 - リクエストの有効なHMAC-SHA 署名を作成します。各リクエストには、有効な署名
が含まれている必要があります。そうでない場合、リクエストは拒否されます。署名のリクエストは秘
密キーを使用して適合されます。これは、登録時に取得した、あなたとAmazon MWSしか知らない秘密
のキーです。
•
タイムスタンプ - 送信する各リクエストにタイムスタンプを追加します。各リクエストには、リクエス
トのタイムスタンプが含まれている必要があります。
•
リクエスト - 選択したオペレーションと入力したパラメータに基づいて、有効なリクエストを作成しま
す。
•
User-Agentヘッダ - User-Agentヘッダを作成します。
•
ストリーム - GetReportオペレーションを使用する際、ダウンロードされたレポートを受信するために使
用するストリームを作成します。
独自のクライアントライブラリを作成する場合
Amazon MWSで使用するための自分自身のクライアントライブラリを作成することができます。コードを
構築し、Amazon MWSが期待するフォーマットでリクエストに署名し、そして結果の XML レスポンスを解
析します。
以下の手順でAmazon MWSにアクセスします。
1. 使用する正しいAmazon MWSのエンドポイントを決定します。
2. 送信するオペレーションのスロットル制限を決定します。
3. リクエストのクエリ文字列を構築します。
4. クエリ文字列に署名し、リクエストを作成します。
5. 正しくフォーマットされたリクエストと、User-Agentヘッダを含む HTTP ヘッダを、Amazon マーケット
プレイスのエンドポイントへ送信します。
6. レスポンスを解析します。
リクエストのフォーマット
Amazon MWSは、Webサービスアクションの呼び出すために、クエリリクエストをサポートしています。
クエリリクエストはシンプルなHTTPリクエストです。GETまたはPOSTメソッドを使用し、クエリパラメー
タをURLまたはHTTPボディにそれぞれ含めます。第三者があなたと Amazon のコミュニケーションを盗聴
するのを防止するため、Amazon MWSでは HTTPS を使用する必要があります。
各HTTPヘッダ行の改行として、キャリッジリターンとラインフィードで終了する必要があります。クエリ
リクエストには、実行されるアクションを示すためActionを含める必要があります。レスポンスはXML形
式です。
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
15
16
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
16
クエリリクエストを作成する
Amazon MWSクエリリクエストを作成するには、まずクエリ情報が入ったクエリ文字列を構築します。次
に、このクエリ文字列に署名し、それをリクエストの送信に含めます。クエリ文字列には、空白や改行を
含めることができないことに注意してください。文字列は以下のように構成されています。
•
HTTP アクション。この値は、ほとんどの場合 POST です。
•
リクエストのドメイン名。例:https://mws.amazonservices.com/ 。各 Amazon マーケットプレイスのエンド
ポイントの一覧は、このガイドのAmazon MWSエンドポイントのセクションを参照してください。エン
ドポイントの後ろにはスラッシュ(/)が付いています。これはエンドポイントとパラメータを区別するも
のです。
•
AWSAccessKeyId - あなたのAmazon MWSアカウントはアクセスキー ID によって識別されます。これ
はAmazon MWSがあなたの秘密キーを調べるために使用します。
•
Action- エンドポイントで実行したいアクション。例: GetFeedSubmissionResultオペレーション。
•
•
Parameters - すべての必須および任意のリクエストパラメータ。
MWSAuthToken - この認証トークンは、特定のAmazonの出品者による各ウェブアプリケーション開発者
への認証を表しています。
Note: このパラメーターは2015年3月31日まで任意で使用でき、その後はウェブアプリケーショ
ンやサードパーティの開発者の認証時、必須となります。詳しくは、「Amazon MWSの認証トー
クンについて」を参照してください。
•
MarketplaceIdList - 複数のマーケットプレイスに出品用アカウントを登録して
いる出品者用の任意の構造化されマーケットプレイスIDのリスト。例えば、
マーケットプレイスIDが2つある場合、以下のようにフォーマットされます。
&MarketplaceIdList.Id.1=ATVPDKIKX0DER&MarketplaceIdList.Id.2=A1F83G8C2ARO7P MarketplaceIdListリ
クエストパラメータは日本と中国では使用できません。
•
SellerId または Merchant - 出品者 ID。
•
SignatureMethod - 署名の計算に使用するHMACハッシュアルゴリズム。HmacSHA256 と HmacSHA1は
ハッシュアルゴリズムに対応していますが、Amazonは HmacSHA256 を使用することを推奨していま
す。
•
SignatureVersion - 使用されている署名のバージョン。Amazon MWSに固有の情報であり、署名の元とな
る文字列を形成するのに使用したアルゴリズムをAmazon MWSに伝えるものです。Amazon MWSでは、
この値は現在SignatureVersion=2です。
•
Timestamp - 各リクエストには、リクエストのタイムスタンプが含まれている必要があります。使用中の
API 機能によっては、タイムスタンプの代わりに、リクエストの有効期限日と時間を指定することがで
きます。
•
Version - 呼び出された API セクションのバージョン。
以下の手順で署名するクエリ文字列を作成します。
1. UTF-8クエリ文字列コンポーネントを、パラメータ名で自然バイトオーダー順にソートします(natural
byte order)。パラメータは、GETの場合 URI または POSTの場合ボディから取得できます。(Content-Type
が application/x-www-form-urlencoded の場合)
2. パラメータ名と値を、以下のルールに従ってURLエンコードします。
•
RFC3986で規定された非予約文字はURLエンコードしてはいけません。非予約文字とは、A-Z、az、0-9、ハイフン(-)、アンダーバー(_)、ピリオド(.)、およびチルダ( ~ )です。
•
その他の文字は%XYパーセントエンコードが必要です (XおよびYには16進数のHEX文字の0-9および
大文字のA-Fが入る)。
•
拡張UTF-8文字については、%XY%ZA…のようにパーセントエンコードします。
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
16
17
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
•
17
スペース(空白)文字は、パーセントエンコードして%20と表記します。多くのエンコーディングで行
われる、+ では表現しないよう気をつけてください。
3. エンコードされたパラメータ名と、エンコードされた値と等号(=)(ASCIIコード61)で分離します(パラ
メータの値が空値の場合も含む)。
4. 名前と値のペアをアンパサンドで分離します ( & ) (ASCIIコード38)。
5. 文字列を作成し、以下の擬似文法に従って("\n" は ASCII 改行の意味)署名を作成します。
StringToSign = HTTPVerb + "\n" +
ValueOfHostHeaderInLowercase + "\n" +
HTTPRequestURI + "\n" +
CanonicalizedQueryString <from the preceding step>
HTTPRequestURI 要素はURIのHTTP絶対パス要素ですが、クエリ文字列は含みません。HTTPRequestURI
が空値の場合は、スラッシュ(/)を使用してください。
以下の例は、GetFeedSubmissionResultのクエリ文字列を示しています。ソートされたパラメーター文字列
にはスペースや改行を含めないでください。
POST
mws.amazonservices.com
/
AWSAccessKeyId=AKIAFJPPO5KLY6G4XO7Q&Action=GetFeedSubmissionResult&FeedSubm
issionId=4321011681&MWSAuthToken=amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAM
PLE&Marketplace=ATVPDKIKX0DER&SellerId=A3F1LGRLCQDI4D&SignatureMethod=HmacS
HA256&SignatureVersion=2&Timestamp=2011-02-04T23%3A08%3A19Z&Version=2009-01
-01
これが署名して文字列に含めるクエリリクエストです。クエリリクエストの署名の手順は、「クエリリク
エストに署名する」を参照してください。
タイムスタンプ
リクエストで使用されるタイムススタンプ(または有効期限)は、dateTimeオブジェクトである必要があり
ます。タイムスタンプは、「2009-03-03T18:12:22Z」または「2009-02-23T18:12:22.093-07:00」のように、
協定世界時(グリニッジ標準時)のタイムゾーンフォーマットで提供するのがベストです。タイムゾーンの
情報(協定世界時(UTC)を表す「Z」、またはタイムオフセット)をタイムスタンプに含めない場合、Amazon
MWSにより時間はUTCと仮定されます。Timestamp属性には、ISO8601フォーマットでクライアントマシン
の時刻が含まれている必要があります。受信されるマシン時計と著しく異なるタイムスタンプ(15分)のリ
クエストは、リプレイアタックを避けるために拒否されます。XML のタイムスタンプの詳細については、
http://www.w3.org/TR/xmlschema-2/#dateTimeを参照してください。
すべてのAmazon MWSレスポンスには、その HTTP レスポンスに、Date: Tue, 24 Mar 2009 20:34:28 GMT
のような日付ヘッダが含まれています。これで、あなたのローカルマシンの時間が当社のサーバー時
間と一致しているかどうかをチェックすることができます。また、Amazon MWSアドレス https://
mws.amazonservices.com/ を任意のウェブブラウザにロードして(リクエストの必要はありません)、現在
のAmazon MWSサーバー時間でレスポンスを受信することができます。
<?xml version="1.0"?>
<PingResponse>
<Timestamp timestamp="2009-03-24T20:29:19:22Z"/>
</PingResponse>
タイムスタンプに関する作業に関し、いくつか追加の注意事項があります。
•
Amazon MWSがピングレスポンスのコンテンツを拡張できるように、Timestampを解析する際に同レ
ベルのXMLエレメントが今後追加されることを前提でソフトウエアを組み込んでください。一般的
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
17
18
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
18
に、Amazon MWSがあなたに送信する XML 中の不明なタグは無視してください。このことは http://
www.w3.org/TR/webarch/ のセクション5.2にあるウェブアーキテクチャ原則で述べられています。
•
(有効期限の代わりに)タイムスタンプを指定した場合は、リクエストは自動的にタイムスタンプの
後15分で期限切れになります。言い換えれば、タイムスタンプがAmazon MWSサーバーの現在時間
よりも15分以上早い場合は、Amazon MWSはリクエストを処理しません。タイムスタンプがAmazon
MWSサーバーの現在時間より15分以上遅い場合は、Amazon MWSはリクエストを処理しません。あなた
のサーバー時刻が正しく設定されていることを確認してください。
•
.NET を使用している場合は、どのように余分時間の精度をドロップするかに解釈の違いがあるため、過
度に特定されたタイムスタンプを送らないようにしてください。過度に特定されたタイムスタンプを送
信しないようにするには、手動で dateTimeオブジェクトを作成し、ミリ秒を超える精度をもたせないよ
うにします。
クエリリクエストに署名する
署名のリクエストは、リクエストの送信者を識別して確認するための認証プロセスの一環です。あなたが
構築するリクエスト URL で、Signatureパラメータの値として使用されます。Amazon MWSは、送信者の認
証と、送信者がAmazon MWSを利用するのに登録しているかどうかを検証します。認証は、アクセスキー
ID を用いて、リクエストの署名を作成するために使用する秘密キーを特定することで行われます。検証が
失敗した場合、リクエストは処理されません。リクエストを送信するのにAmazon MWSのクライアントラ
イブラリのいずれかを使用している場合は、署名またはタイムスタンプを照合する必要がないことに注意
してください。
1. 前述の「クエリリクエストを作成する」を参照し、クエリリクエストを作成します。以下はクエリリク
エストの例を示しています。
POST
mws.amazonservices.com
/
AWSAccessKeyId=0PExampleR2&Action=SubmitFeed&FeedType=_POST_INVENTORY_AVAIL
ABILITY_DATA_&MWSAuthToken=amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE&Ma
rketplace=ATExampleER&SellerId=A1ExampleE6&SignatureMethod=HmacSHA256&Signa
tureVersion=2&Timestamp=2009-08-20T01%3A10%3A27.607Z&Version=2009-01-01
2. 作成したばかりの文字列を使い、あなたの秘密キーをキーとして、RFC 2104互換 HMAC を計算しま
す。HmacSHA256 と HmacSHA1はハッシュアルゴリズムに対応していますが、Amazonは HmacSHA256
を使用することを推奨しています。
3. 結果の値をbase64に変換します。
4. 結果として得られた値をリクエスト内のSignatureパラメータに含めて使用します。
以下はの例は、Javaを使用して署名を計算する方法を示しています。
import
import
import
import
import
import
import
import
import
import
import
import
import
import
import
java.io.UnsupportedEncodingException;
java.net.URI;
java.net.URISyntaxException;
java.net.URLEncoder;
java.security.InvalidKeyException;
java.security.NoSuchAlgorithmException;
java.security.SignatureException;
java.util.HashMap;
java.util.Iterator;
java.util.Map;
java.util.Map.Entry;
java.util.TreeMap;
javax.crypto.Mac;
javax.crypto.spec.SecretKeySpec;
org.apache.commons.codec.binary.Base64;
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
18
19
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
19
public class SignatureExample {
private static final String CHARACTER_ENCODING = "UTF-8";
final static String ALGORITHM = "HmacSHA256";
public static void main(String[] args) throws Exception {
// Change this secret key to yours
String secretKey = "Your secret key";
// Use the endpoint for your marketplace
String serviceUrl = "https://mws.amazonservices.com/";
// Create set of parameters needed and store in a map
HashMap<String, String> parameters = new HashMap<String,String>();
// Add required parameters. Change these as needed.
parameters.put("AWSAccessKeyId", urlEncode("Your Access Key Id"));
parameters.put("Action", urlEncode("GetFeedSubmissionList"));
parameters.put("MWSAuthToken", urlEncode("Your MWS Auth Token"));
parameters.put("SellerId", urlEncode("Your Seller Id"));
parameters.put("SignatureMethod", urlEncode(ALGORITHM));
parameters.put("SignatureVersion", urlEncode("2"));
parameters.put("SubmittedFromDate",
urlEncode("2013-05-01T12:00:00Z"));
parameters.put("Timestamp", urlEncode("2013-05-02T16:00:00Z"));
parameters.put("Version", urlEncode("2009-01-01"));
// Format the parameters as they will appear in final format
// (without the signature parameter)
String formattedParameters = calculateStringToSignV2(parameters,
serviceUrl);
String signature = sign(formattedParameters, secretKey);
}
// Add signature to the parameters and display final results
parameters.put("Signature", urlEncode(signature));
System.out.println(calculateStringToSignV2(parameters,
serviceUrl));
/* If Signature Version is 2, string to sign is based on following:
*
*
1. The HTTP Request Method followed by an ASCII newline (%0A)
*
*
2. The HTTP Host header in the form of lowercase host,
*
followed by an ASCII newline.
*
*
3. The URL encoded HTTP absolute path component of the URI
*
(up to but not including the query string parameters);
*
if this is empty use a forward '/'. This parameter is followed
*
by an ASCII newline.
*
*
4. The concatenation of all query string components (names and
*
values) as UTF-8 characters which are URL encoded as per RFC
*
3986 (hex characters MUST be uppercase), sorted using
*
lexicographic byte ordering. Parameter names are separated from
*
their values by the '=' character (ASCII character 61), even if
*
the value is empty. Pairs of parameter and values are separated
*
by the '&' character (ASCII code 38).
*
*/
private static String calculateStringToSignV2(
Map<String, String> parameters, String serviceUrl)
throws SignatureException, URISyntaxException {
// Sort the parameters alphabetically by storing
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
19
20
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
20
// in TreeMap structure
Map<String, String> sorted = new TreeMap<String, String>();
sorted.putAll(parameters);
// Set endpoint value
URI endpoint = new URI(serviceUrl.toLowerCase());
// Create flattened (String) representation
StringBuilder data = new StringBuilder();
data.append("POST\n");
data.append(endpoint.getHost());
data.append("\n/");
data.append("\n");
Iterator<Entry<String, String>> pairs =
sorted.entrySet().iterator();
while (pairs.hasNext()) {
Map.Entry<String, String> pair = pairs.next();
if (pair.getValue() != null) {
data.append( pair.getKey() + "=" + pair.getValue());
}
else {
data.append( pair.getKey() + "=");
}
}
}
// Delimit parameters with ampersand (&)
if (pairs.hasNext()) {
data.append( "&");
}
return data.toString();
/*
* Sign the text with the given secret key and convert to base64
*/
private static String sign(String data, String secretKey)
throws NoSuchAlgorithmException, InvalidKeyException,
IllegalStateException, UnsupportedEncodingException {
Mac mac = Mac.getInstance(ALGORITHM);
mac.init(new SecretKeySpec(secretKey.getBytes(CHARACTER_ENCODING),
ALGORITHM));
byte[] signature = mac.doFinal(data.getBytes(CHARACTER_ENCODING));
String signatureBase64 = new String(Base64.encodeBase64(signature),
CHARACTER_ENCODING);
return new String(signatureBase64);
}
private static String urlEncode(String rawValue) {
String value = (rawValue == null) ? "" : rawValue;
String encoded = null;
try {
encoded = URLEncoder.encode(value, CHARACTER_ENCODING)
.replace("+", "%20")
.replace("*", "%2A")
.replace("%7E","~");
} catch (UnsupportedEncodingException e) {
System.err.println("Unknown encoding: " + CHARACTER_ENCODING);
e.printStackTrace();
}
return encoded;
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
20
21
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
}
21
}
User-Agent ヘッダを作成する
User-Agent ヘッダは、アプリケーション、そのバージョン番号、およびプログラミング言語を識別するた
めに使用されます。Amazon MWSを最適に使用いただくために、Amazon MWSに送信する各リクエスト
にUser-Agent ヘッダを含めることをお勧めします。これは、Amazonがより効率良く問題を分析して修正
し、Amazon MWSをより快適に使用いただくことに役立ちます。
ソリューションプロバイダはアプリケーションの開発が特に重要になるため、各リクエストにUser-Agent
ヘッダを含めています。これはデスクトップアプリケーションの開発には特に重要になります。Amazonに
おいても、出品者がどのソリューションプロバイダを利用しているのかを特定でき、アプリケーションに
関連した問題を効率良く隔離できるようになります。
Amazon MWSのクライアントライブラリは、各Amazon MWSリクエストでUser-Agentヘッダを受け渡すた
めに使いやすい手段を提供します。Amazon MWSクライアントライブラリを初期化する際は、アプリケー
ションまたは会社名およびバージョン番号を追加します。その他の HTTP ライブラリもUser-Agentヘッダの
構築のために簡単な手段を提供しますが、ヘッダの作成が難しい場合は、Amazon MWSのサポートをリク
エストしてください。
User-Agentヘッダを作成するには、あなたのアプリケーション名から開始し、スラッシュ、アプリケーショ
ンのバージョン、スペース、左丸括弧、言語名の値ペア、右丸括弧の順に入力します。言語パラメータは
必須の属性です。ただしセミコロンで区切られたその他の属性を追加することができます。User-Agentは全
て半角で指定することをおすすめします。
以下の例は、受け付け可能な最小限度の条件を満たすUser-Agentのヘッダについて説明するものです。
AppId/AppVersionId (Language=LanguageNameAndOptionallyVersion)
あなたがサードパーティのアプリケーションインテグレータである場合は、User-Agentヘッダを以下のよう
に使用できます。
My Desktop Seller Tool/2.0 (Language=Java/1.6.0.11; Platform=Windows/XP)
自社の IT 部門を通じてインテグレーションを行っている大型の出品者である場合は、User-Agentヘッダを
以下のように使用することができます。そうすれば、Amazon MWSがHost属性を使用してあなたの問題解
決のお役に立てます
MyCompanyName/build1611 (Language=Perl; Host=jane.laptop.example.com)
その他の属性を指定するには、セミコロンで各名前と値のペアを分離して、フォーマット
AttributeName=Value; を使用してください。バックスラッシュ(\)を使用したい場合は、2つつなげて(\\)エス
ケープして使用してください。アプリケーション名内のスラッシュ(\/)、アプリケーションバージョン内の
左丸括弧(|()、属性名内の等号(\=)、右丸括弧(\))および属性値内のセミコロン(\;)についても同様にエスケー
プし使用してください。
User-Agentヘッダはすべてのリクエストで送信されるので、ヘッダのサイズを制限することをお勧めしま
す。それが500文字より長い場合は、Amazon MWSはUser-Agentヘッダを拒否します。
URLを作成する
URLには以下が含まれます。
•
https://
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
21
22
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
•
アクセスするマーケットプレイスのWebサービスエンドポイント
•
クエリリクエストの文字列、署名に含まれたパラメーター
•
User-Agentヘッダ
22
次の例はURLの作成のリクエスト内容を示しています。実際のリクエストには空白や改行を含めてはいけ
ません。
https://mws.amazonservices.com/AWSAccessKeyId=AKIAFJPPO5KLY6G4XO7Q&Action=G
etFeedSubmissionResult&FeedSubmissionId=4321011681&MWSAuthToken=amzn.mws.4e
a38b7b-f563-7709-4bae-87aeaEXAMPLE&Marketplace=ATVPDKIKX0DER&SellerId=A3F1L
GRLCQDI4D&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2011-02-0
4T23%3A08%3A19Z&Version=2009-01-0&Signature=WhateverTheSignatureWas1HTTP/1.
1Host:mws.amazonservices.comX-Amazon-User-Agent:AmazonJavascriptApp/1.0(Lan
guage=Javascript)Content-Type:text/xml
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
22
23
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
23
Content-MD5 ヘッダとMD5チェックサム
MD5は、データ内のすべての変更がダイジェストの変化に反映される、高い確信度を持つ任意の長さの
データの128ビット「ダイジェスト」(またはハッシュ)を計算するためのアルゴリズムです。フィードを
送信するため、Content-MD5ヘッダを付ける必要があります。Amazon MWSは送信されたフィード内容
でMD5チェックサムを計算し、送信者のつけたContent-MD5ヘッダの内容と比較し、受信されたデータの不
正検出を行います。Amazon MWSから送信されるレポートの場合はこのプロセスの逆を行います。レポー
トとともに送信されたContent-MD5ヘッダでMD5チェックサムを計算し、Amazonが送信したヘッダと比較
し、受信したレポートの不正検出を行います。
Amazon MWSにContent-MD5 ヘッダを含むフィードを送信するための基本的なプロセスは以下の通りです。
1. Amazon MWSにフィードを送信する前に、送信するフィードをディスクに保管します。
2. ファイルのコンテンツのMD5チェックサムを計算処理し、コンパニオンファイルにそれを保存します。
3. SubmitFeedリクエストを作成し、保管してあるMD5チェックサムをContent-MD5に設定し、ストリーム
にファイルのコンテンツを添付します。
4. リクエストを送信します。
以下の Java コードサンプルは、Amazonへのフィード送信の際のContent-MD5ヘッダの計算方法について説
明しています。
/**
* Calculate content MD5 header values for feeds stored on disk.
*/
public static String computeContentMD5HeaderValue( FileInputStream fis )
throws IOException, NoSuchAlgorithmException {
DigestInputStream dis = new DigestInputStream( fis,
MessageDigest.getInstance( "MD5" ));
byte[] buffer = new byte[8192];
while( dis.read( buffer ) > 0 );
String md5Content = new String(
org.apache.commons.codec.binary.Base64.encodeBase64(
dis.getMessageDigest().digest()) );
// Effectively resets the stream to be beginning of the file
// via a FileChannel.
fis.getChannel().position( 0 );
}
return md5Content;
以下の Java コードサンプルは、ダウンロードされるレポートのMD5チェックサムの計算方法について説明
しています。
/**
* Consume the stream and return its Base-64 encoded MD5 checksum.
*/
public static String computeContentMD5Header(InputStream inputStream) {
// Consume the stream to compute the MD5 as a side effect.
DigestInputStream s;
try {
s = new DigestInputStream(inputStream,
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
23
24
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
}
24
MessageDigest.getInstance("MD5"));
// drain the buffer, as the digest is computed as a side-effect
byte[] buffer = new byte[8192];
while(s.read(buffer) > 0);
return new String(
org.apache.commons.codec.binary.Base64.encodeBase64(
s.getMessageDigest().digest()),
"UTF-8");
} catch (NoSuchAlgorithmException e) {
throw new RuntimeException(e);
} catch (IOException e) {
throw new RuntimeException(e);
}
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
24
25
25
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
必須リクエストパラメータ
以下の表は、Amazon MWSのすべてのオペレーションに必須とされるリクエストパラメータを示していま
す。
名前
説明
必須
有効な値
AWSAccessKeyId
Amazon MWSアカウントはアクセス
キーIDによって識別され、Amazon
MWSが秘密キーを調べるために使
用します。
はい
Amazon MWS登録時に受信し
たAWSAccessKeyId。
はい
呼び出しているエンドポイントに有
効なアクション
ウェブアプリ
ケーションと
サードパーティ
の開発者の認証
のみに使用
Amazon MWS登録時に受信した認証
トークン。
はい
Amazon MWS登録時に受信した出品
者ID。
はい
署名の計算方法について詳しく
は、クエリリクエストに署名するを
参照してください。
はい
SignatureMethod 値:
タイプ: xs:string
Action
- エンドポイントで実行
したいアクション。例:
GetFeedSubmissionResultオペレー
ション。
タイプ: xs:string
MWSAuthToken
特定のAmazonの出品者による特定
の開発者への認証を表しています。
タイプ: xs:string
SellerId または Merchant
出品者 ID。
タイプ: xs:string
Signature
リクエストの送信者を識別して確
認するための認証プロセスの一環で
す。
Note: このパラメーター
は2015年3月31日まで任
意で使用でき、その後は
ウェブアプリケーション
やサードパーティの開発
者の認証時、必須となり
ます。詳しくは、を参照
してください。
タイプ: xs:string
SignatureMethod
署名の計算に使用するHMACハッ
シュアルゴリズム。HmacSHA256
と HmacSHA1はハッシュアルゴリズ
ムに対応していますが、Amazonは
HmacSHA256 を使用することを推奨
しています。
•
•
HmacSHA256 (推奨)
HmacSHA1
タイプ: xs:string
SignatureVersion
使用されている署名のバージョ
ン。Amazon MWSに固有の情報で
あり、署名の元となる文字列を形
成するのに使用したアルゴリズム
をAmazon MWSに伝えるものです。
はい
SignatureVersion値:
•
2
タイプ: xs:string
Timestamp
各リクエストには、リクエストのタ
イムスタンプが含まれている必要が
あります。使用中のAPI機能によっ
ては、タイムスタンプの代わりに、
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
はい
現在の日時またはリクエストのISO
8601形式の有効期限の日時。
25
26
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
名前
説明
必須
26
有効な値
リクエストの有効期限日と時間を指
定することができます。ISO 8601形
式。
タイプ: xs:dateTime
Version
呼び出された API セクションのバーはい
ジョン。
呼び出された API セクションのバー
ジョン。
タイプ: xs:string
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
26
27
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
27
レスポンスのフォーマット
アクションのリクエストに対するレスポンスには、Amazon MWSはリクエスト結果を含む XML ファイルを
返します。リクエストが成功すると、レスポンスにはリクエストされたデータが返されます。以下はレス
ポンスの成功例です。
<?xml version="1.0"?>
<RequestReportResponse xmlns="http://mws.amazonservices.com/doc/2009-01-01/">
<RequestReportResult>
<ReportRequestInfo>
<ReportRequestId>2291326454</ReportRequestId>
<ReportType>_GET_MERCHANT_LISTINGS_DATA_</ReportType>
<StartDate>2009-01-21T02:10:39+00:00</StartDate>
<EndDate>2009-02-13T02:10:39+00:00</EndDate>
<Scheduled>false</Scheduled>
<SubmittedDate>2009-02-20T02:10:39+00:00</SubmittedDate>
<ReportProcessingStatus>_SUBMITTED_</ReportProcessingStatus>
</ReportRequestInfo>
</RequestReportResult>
<ResponseMetadata>
<RequestId>88faca76-b600-46d2-b53c-0c8c4533e43a</RequestId>
</ResponseMetadata>
</RequestReportResponse>
Important: Amazon MWSに送信する各リクエストのRequestId と Timestampを30日間分記録、保管
するようにしてください。これにより、問題が発生した場合、Amazonが問題を調査して修正する
ことができるようになり、Amazon MWSの利用のしやすさを改善することができます。この情報が
ない場合は、Amazon MWSへサポートを依頼した際に解決までに通常より長くかかる場合がありま
す。
リクエストが失敗すると、リクエストされたアクションに関係なく、主なレスポンス要素は ErrorResponse
となります。この要素には、1つまたは2つ以上のErrorの子要素が含まれます。各Error には以下が含まれ
ます。
•
発生したエラータイプを特定するエラーコード
•
人が読める形式でエラー状況を説明するメッセージコード
•
エラーの発生元が受信者であるか送信者であるかを特定するエラータイプ
次の例は、エラーレスポンスを示しています。
<ErrorResponse xmlns="http://mws.amazonservices.com/doc/2009-01-01/">
<Error>
<Type>Sender</Type>
<Code>InvalidClientTokenId</Code>
<Message>
The AWS Access Key Id you provided does not exist in our records.
</Message>
<Detail>com.amazonservices.mws.model.Error$Detail@17b6643</Detail>
</Error>
<RequestID>b7afc6c3-6f75-4707-bcf4-0475ad23162c</RequestID>
</ErrorResponse>
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
27
28
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
28
エラーの対応について
Amazon MWSで問題が発生した場合は、リクエストのRequestIdとTimestampを記録してテクニカルサポー
トに連絡してください。 Amazonでは問題の特定にRequestIdとTimestampを使用します。
Important: Amazon MWSに送信する各リクエストのRequestIdとTimestampを30日間分記録、保管す
るようにしてください。これにより、問題が発生した場合、Amazonが問題を調査して修正すること
ができるようになり、Amazon MWSの利用のしやすさを改善することができます。この情報がない
場合は、Amazon MWSへサポートを依頼した際に解決までに通常より長くかかる場合があります。
500エラー、または503エラーを受信後、オペレーションの呼び出しをリトライする場合は、最初のエラー
レスポンス直後にリトライすることができます。複数回リトライする場合、Amazonでは最大リトライ回
数4回の「Exponential backoff」(指数関数的後退)によるアプロ―ディを推奨します。その後エラーを記録
し、手動のフォローアップと調査を進めます。の例えば、リトライの時間を、1秒、4秒、10秒、30秒の間
隔で計ることができます。実際の後退時間と制限は、あなたのビジネスプロセスによって異なります。
次の表は、共通するAmazon MWSエラーコードの例とエラーの解決策を示しています。
エラー
理由
"POST / ?
AWSAccessKeyId=AKIAJSTDR2444BJQ
&AWSAccountId=458080
&MWSAuthToken=amzn.mws.4ea38b7bf563-7709-4bae-87aeaEXAMPLE
&Marketplace=ATVPDKIKX0DER
&SellerId=AC28N11YUQ
&SignatureVersion=2 &Version=2009-01-01
&RequestId=2d093e-0408-4517-9685474d1a0a8e9e &CustomerId=A2AR6RWNQ
&NamespaceUri= http%3A%2F
%2Fmws.amazonservices.com
%2Fdoc%2F2009-01-01%2F
&ServiceName=MarketplaceWebService
&Action=GetReportList
&ErrorCode=ServiceUnavailable
&ErrorFault=Receiver HTTP/0.0" 503
296 "-" "UST/1.0 (Language=PHP/5.2.14;
MWSClientVersion=2009-07-02;
Platform=Linux infong 2.4 #1 SMP Wed Nov
4 21:12:12 UTC 2009 i686 GNU/Linux/Linux
infong 2.4 #1 SMP Wed Nov 4 21:12:12 UTC
2009 i686 GNU/Linux/Linux infong 2.4 #1
SMP Wed Nov 4 21:12:12 UTC 2009 i686
GNU/Linux)"
この503エラーは、Amazon MWS サービス前述にあるとおり、「Exponential
が利用できないことを示しています。クラ backoff」(指数関数的後退)の方法でリクエ
イアントライブラリを使用するときは、レストをリトライします。
スポンスがパースされ、すべてのデータが
含まれた MarketplacewebService の例外が
投げられます。
"POST / ?
AWSAccessKeyId=AKIVUUNIIMFTA
&AWSAccountId=7948
&MWSAuthToken=amzn.mws.4ea38b7bf563-7709-4bae-87aeaEXAMPLE
&Marketplace=ATVPDKIKX0DER
&SellerId=ASH1H4EF
&SignatureVersion=2 &Version=2009-01-01
&RequestId=260-0116-41fa-91d07bc98359c694 &CustomerId=ASH14EF
&NamespaceUri= http%3A%2F
%2Fmws.amazonservices.com
%2Fdoc%2F2009-01-01%2F
&ServiceName=MarketplaceWebService
&Action=GetReportRequestList
&ErrorCode=RequestThrottled
この503エラーは、リクエストがスロット
ルされていることを示します。クライアン
トライブラリを使用するときは、レスポン
スがパースされ、すべてのデータが含まれ
た MarketplacewebService の例外が投げら
れます。
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
トラブルシューティング方法
送信しているリクエストタイプのスロット
ル制限を確認してください。スロットルを
防止するため、適切な時間が経過したとき
にリクエストを再送信されるリトライロ
ジックを設定してください。
28
29
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
エラー
29
理由
トラブルシューティング方法
クライアントはAmazon MWSのエンドポ
イントと通信しようとしましたが、当社の
SSL 証明書を検証できなかった、もしくは
クライアントのマシンが検証に使用する証
明書ストアを見つけることができませんで
した。
この例外を取得する場合は、クライアント
のトラストストアにAmazon MWSの証明書
を追加する必要があります。Java でのトラ
ストストアの設定と構成に関しては、Java
の資料を参照してください。
<ErrorResponse xmlns="http://
リクエストで送信されたUser-Agentヘッダ
mws.amazonservices.com/doc/2009-01-01/">
は有効なフォーマットではありませんでし
<Error> <Type>Sender</Type>
た。
<Code>UserAgentHeaderMalformed</Code>
<Message> Problem with required MWS UserAgent header (e.g. "MyAppName/build123
(Language=Java/1.2)"): Encountered "<EOF>"
at column 116. Was expecting: "=" ... </
Message> <Detail/> </Error> <RequestID>
21f197f6-24b7-4b7b-94fc-55fa34056d34 </
RequestID> </ErrorResponse>
Amazon MWSクライアントライブラリか
らのコードを使用してUser-Agentヘッダを
作成、またはUser-Agentヘッダが許可する
フォーマットに関する資料を参照してくだ
さい。
&ErrorFault=Sender HTTP/0.0" 503 309 "-"
"null"
javax.net.ssl.SSLException:
java.lang.RuntimeException:
Unexpected error: java.security.
InvalidAlgorithmParameterException: the
trustAnchors parameter must be non-empty
The Content-MD5 HTTP
header you passed for your feed
(1B2M2Y8AsgTpgAmY7PhCfg==) did not
match the Content-MD5 we calculated for your
feed (3cldK7kqMxK6orwvXXdzSQ==)
Content-MD5 値
解決策として、ドキュメントをStringとし
1B2M2Y8AsgTpgAmY7PhCfg== は空の文てエクスポートし、このStringのバイトで
字列に相当します。Content-MD5 を計算す MemoryStream を構築してください。
るために使用される MD5 プロバイダのイ
MemoryStream stream =
ンスタンスで、ストリームからのバイトを
new MemoryStream(
new UTF8Encoding()
読み取ることができません。
.GetBytes(
xmlDocument.ToString()));
request.ContentMD5 =
MarketplaceWebServiceClient
.CalculateContentMD5(stream);
エラーコード
次の表は、Amazon MWSのエラーコードについて説明しています。フィードの問題が原因で返されるその
他のエラーについては、セラーセントラルのヘルプトピックで説明されています。
エラーコード
説明
AccessDenied
クライアントは、HTTPSではなくHTTPでへの接続を試みまし
た。Amazon MWS
AccessToFeedProcessingResultDenied
フィード処理結果へアクセスするには権限が不十分です。
AccessToReportDenied
リクエストされたレポートへアクセスするには権限が不十分で
す。
ContentMD5Missing
Content-MD5 のヘッダー値が欠如していました。
ContentMD5DoesNotMatch
計算された MD5 ハッシュ値は、提供されたContent-MD5 値と一
致しません。
FeedCanceled
キャンセルされたフィードの処理レポートをリクエストした際に
返されます。
FeedProcessingResultNoLongerAvailable
フィード処理結果をダウンロードできません。
FeedProcessingResultNotReady
まだ生成されていない処理レポートです。
InputDataError
エラーを含んだフィードコンテンツです。
InternalError
未特定のサーバーエラーが発生しました。
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
29
30
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
30
エラーコード
説明
InvalidAccessKeyId
AWSAccessKeyIdリクエストパラメータが無効、または有効期限
切れです。
InvalidFeedSubmissionId
提供されたフィード送信IDが無効です。
InvalidFeedType
送信されたフィードタイプが無効です。
InvalidParameterValue
提供されたクエリパラメータが無効でした。例えば、タイムスタ
ンプのパラメータが不正など。
InvalidQueryParameter
不必要なパラメータが送信されました。
InvalidReportId
無効なReportIdです。レポートIDが無効です。
InvalidReportType
無効なReportTypeです。
InvalidRequest
リクエストが見つからない、または無効なパラメータのため、
パース(解析)できません。
InvalidScheduleFrequency
送信されたスケジュール頻度が無効です。
MissingClientTokenId
出品者IDまたはマーチャントID パラメータの値が空、または欠
如しています。
MissingParameter
必要なパラメータがクエリから欠如しています。
ReportNoLongerAvailable
指定されたレポートをダウンロードすることができません。
ReportNotReady
レポートがまだ生成されていません。
SignatureDoesNotMatch
提供されたリクエストの署名が、サーバーが算出した署名の値と
一致しません。
UserAgentHeaderLanguageAttributeMissing
User-Agentのヘッダ言語属性が欠如しています。
UserAgentHeaderMalformed
User-Agentの値が正しい形式ではありません。
UserAgentHeaderMaximumLengthExceeded
User-Agentの値が500文字を超過しています。
UserAgentHeaderMissing
User-Agentのヘッダ値が欠如しています。
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
30
31
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
31
関連リソース
様々なフィードタイプのスキーマについて詳しくは、Amazon出品サービス XMLガイドを参照してくださ
い。
Amazon MWS に関する技術的な質疑応答の場として、コミュニティベースの開発者向けフォーラムがあり
ます。
•
英語: https://sellercentral.amazon.com/forums/forum.jspa?forumID=35
•
日本語：https://sellercentral.amazon.co.jp/forums/forum.jspa?forumID=14
•
中国語：https://mai.amazon.cn/forums/forum.jspa?forumID=15
Amazon マーケットプレイス Web サービスの詳細に関する主なウェブページです(開発者向け資料とクライ
アントライブラリへのリンクを含む)。
•
NA (North America)
•
• CA: https://developer.amazonservices.ca
• US: https://developer.amazonservices.com
EU (European Union)
•
• DE: https://developer.amazonservices.de
• ES: https://developer.amazonservices.es
• FR: https://developer.amazonservices.fr
• IN: https://developer.amazonservices.in
• IT: https://developer.amazonservices.it
• UK: https://developer.amazonservices.co.uk
FE (Far East)
•
• JP: https://developer.amazonservices.jp
CN (China)
•
CN: https://developer.amazonservices.com.cn
Amazon マーケットプレイスWebサービス (Amazon MWS) 開発者ガイド
31

Download Report