Amazon MWS から SP-API への移行 [Postmanによるテスト接続編]

前々回の「きっかけ編」、前回の「準備編」にてMWSからSP-APIへの移行のきっかけや準備しなければならないアカウントについて記載しました。

今回は、「準備編」で用意したアカウントをもとにPostmanを用いてSelling Partner API(以下、SP-API)の接続確認を実施してみたいと思います。

この記事でできるようになること

  • Postman のアカウントが取得できる
  • Postman の超基礎的な使い方が習得できる
  • Postman を用いてSP-APIへのアクセスができるようになる

必要となる知識

  • PCやWebブラウザの基本的な操作方法
  • Webサービスのアカウント作成の知識
  • GETやPOSTといったHTTPプロトコルの仕組みの知識(ググればなんとかなる)

Postmanを用いたSP-APIへの接続までの流れ

  1. Postmanアカウント作成/ログイン
  2. PostmanでWorkspaceを準備
  3. PostmanにてSP-APIへRequestを送信し、Responseを取得
    1. リフレッシュトークンを用いてアクセストークンを取得
    2. アクセストークンを用いて情報を取得したいAPIへRequestを送信し、Responseを取得

こんな流れになります。

そもそもPostmanとは?

Postman とは、WebAPIに対してRequestを送信し、Responseを受取ってすぐに確認することができるテストクライアントアプリケーションです。Requestを送信する際の細かいパラメータ設定についても柔軟に操作できるのでAPIを開発する人、APIを活用する人、双方にとって大変有用なツールとして存在しています。

Postmanは、APIを構築および使用するためのAPIプラットフォームです。 Postmanは、APIライフサイクルの各ステップを簡素化し、コラボレーションを合理化するため、より優れたAPIをより迅速に作成できます。
(公式ページの「What is Postman?」をGoogle翻訳で和訳。)

https://www.postman.com/

Postmanのアカウント準備

アカウント作成はいたって簡単です。

公式ページ「https://www.postman.com」にアクセスし、右上にある「Create Account」ボタンを押してアカウントを新規作成します。


以下の画面から作成します。アカウント準備はすぐ終わりますね。


ログインすると、以下のトップページが表示されます。これでPostmanのアカウント準備は完了です。

PostmanでWorkspaceを準備

まず、PostmanでAPIへアクセスするためのワークスペース(作業場所)を作成します。

画面赤枠部分の「Workspace」を選択し、「+ Nes Workspace」を選択します。


次に、ワークスペースの名前、要約、アクセス設定を実施します。

今回は、ワークスペース名を「SPAPI_Access_Workspace」とし、アクセスは自身のみのため「Personal」と設定しました。

内容を確認し、問題なければ「Create Workspace」を選択します。


ワークスペースの作成が完了すると、下記の画面に遷移するので「Create request」(赤枠部分)を選択し、リクエスト作成に進みます。

Postmanを使ったSP-API接続

SP-APIの利用マニュアル(公式)はこちらにあります。

出品パートナーAPIへの接続(公式)

https://github.com/amzn/selling-partner-api-docs/blob/main/guides/ja-JP/developer-guide/SellingPartnerApiDeveloperGuideForVendors(%E6%97%A5%E6%9C%AC%E8%AA%9E).md#%E5%87%BA%E5%93%81%E3%83%91%E3%83%BC%E3%83%88%E3%83%8A%E3%83%BCapi%E3%81%B8%E3%81%AE%E6%8E%A5%E7%B6%9A

慣れている方は、このブログよりも公式マニュアルを見てサクッとアクセスした方が速いかもしれません。が、私は全く慣れておらず、公式マニュアルを見ながら四苦八苦して何とかアクセスできるようになりました。あの苦労を今後また味わうのは避けたいので、以下にやり方をまとめています。(公式マニュアル難しすぎでは...)

リフレッシュトークンからアクセストークンを取得する

まずは、SP-APIの各APIへアクセスする際に必要となる「アクセストークン」を取得します。

アクセストークンの取得は、公式マニュアル(上↑)に記載の通り以下(↓)となります。

アクセストークン取得のためのリクエスト設定

LWA(Login with Amazon)認証サーバーに対して、必要なパラメータをセットしてRequestを送信します。

  • LWA認証サーバURL
    • https://api.amazon.com/auth/o2/token
  • HTTP メソッド
    • POST
  • POSTリクエストのBodyパラメータ
    • grant_type:「refresh_token」という文字列を設定
    • refresh_token:「リフレッシュトークン」の値を設定
    • client_id:「LWA 認証情報 クライアントID」を設定
    • client_secret:「LWA 認証情報 クライアント機密情報」を設定

これらをPostmanに設定すると以下の画面になります。

  • HTTPメソッドを「POST」に修正(デフォルトはGETになってる。)
  • URL部分に、LWA認証サーバURLをコピペ
  • 「Body」タブを選択
  • 「x-www-form-urlencoded」のラジオボタンを選択
  • 「KEY」部分に4つのKEYを記載
  • 「VALUE」部分に、上にある「アクセストークン取得のためのリクエスト設定」のBodyパラメータ情報を設定

以上を入力し、画面右側にある「Send」(赤枠部分)を押す。


アクセストークンが問題なく取得できた場合、以下の画面になります。

「Status: 200 OK」となっているので、正常なResponseということになります。

赤枠内にある「access_token」の値を用いて、SP-APIの各APIへリクエストを送信することが可能になります。アクセストークンの有効期間は「expires_in」に表示のある「3,600秒(60分)」です。この有効期間が過ぎるとアクセストークンは無効になるため、再度アクセストークンを取得する必要があります。


参考:有効期間が切れた場合のレスポンス

Status : 403

{
    "errors": [
        {
            "message": "Access to requested resource is denied.",
            "code": "Unauthorized",
            "details": "The access token you provided has expired."
        }
    ]
}

こんな内容のエラーが出ます。

SP-APIのAPIへアクセス

アクセストークンの取得ができたので、SP-APIのAPIをたたいて情報を取得する準備が整いました。今回テスト接続するのは「getCatalogItem」というAPIです。

Selling Partner API for Catalog Items

Overview:The Selling Partner API for Catalog Items provides programmatic access to information about items in the Amazon catalog.
[Google和訳]概要:Selling Partner API 「Catalog Items」は、Amazonカタログ内のアイテムに関する情報へのプログラムによるアクセスを提供します。

Description:Retrieves details for an item in the Amazon catalog.
[Google和訳]説明:Amazonカタログの商品の詳細を取得します。

https://github.com/amzn/selling-partner-api-docs/blob/4b53b4e38bcb5745266f53cdf65feed2b56e0ddc/references/catalog-items-api/catalogItems_2020-12-01.md#getcatalogitem

上記の公式リファレンス(と、SellingPartnerApiDeveloperGuide)を読み解いて、「getCatalogItem」へのAPIアクセス用情報をPostmanに設定できるようにすると以下のようになります。

この「読み解き」が慣れるまで意外と大変です。慣れると「あれ、どうしてこんなんで苦労してたんだっけ?」になります。

getCatalogItem 情報取得のためのリクエスト設定
  • HTTPメソッド
    • GET
  • SP-API エンドポイント
    • https://sellingpartnerapi-fe.amazon.com
  • Path
    • /catalog/2020-12-01/items/{asin}
      ※{asin} には Amazon の商品に付与されているASINコードを入れる
    • asin:SP-APIから情報を取得したいASINコードを入力する
      ※今回は「B07WXL5YPW」(Nintendo Switch)を入力
  • GETリクエストのパラメータ(クエリ部分)
    • marketplaceIds:「A1VC38T7YXB528」を設定
      ※今回、「includedData」と「locale」は任意のため省略
  • ヘッダー情報作成のためのパラメータ
    • user-agent:アクセスした際に識別可能なUserAgent情報を記載する
      ※例:Zats-SPAPI-App/Ver1.0 (Tool=Postman;Platform=Windows10)
    • x-amz-access-token:リフレッシュトークンから取得した「アクセストークン」を設定
  • 認証情報(Authorization)作成のためのパラメータ
    • AccessKey:「AWS IAMユーザー アクセスキーID」を設定
    • SecretKey:「AWS IAMユーザー シークレットアクセスキー」を設定
    • AWS Region:「us-west-2」を設定
    • Service Name:「execute-api」を設定
    • Session Token:※指定しない(空白でOK)

これらをPostmanに設定していきます。


まずはHTTPメソッド(赤下線)、エンドポイント(緑下線)、Path(青下線)、クエリパラメータ(URLの後ろに「?」でくっつくやつ)(下段の赤枠)についての入力例です。

ピンクの破線部分は、「Query params」部分に入力すると自動でURLに追加されるので、手動で入力する必要はありません。


次に、ヘッダー情報を設定します。

user-agent」と「x-amz-access-token」を設定します。「x-amz-access-token」には、リフレッシュトークンから取得したアクセストークンの値を設定します。取得期限(3,600秒)に注意する必要があります。


次に、認証情報(Authorization)を設定します。

Postmanには、AWS用の認証情報を作成するためのプリセット「Type:AWS Signature」が準備されています。何と便利なことでしょうか!開発者の方、ありがとうございます。大変感謝です。こちらのプリセットを利用することで、認証情報や、認証情報への署名情報がサクッと作成できます。

これで全ての準備が整いました。


最後に、画面右側の「Send」(青いボタン)を選択し、SP-APIへRequestを送信します。問題なくResponseが返ってくると、以下の表示画面(下の赤枠部分)になります。

「Status: 200 OK」となっているので、正常なResponseということになります。

無事、任天堂スイッチの情報が取得できていますね。JSON見やすい。

上記の任天堂スイッチの情報は、全てAmazonのWeb上から確認が可能なのでモザイクなしで載せていますが、顧客情報等の管理には十分注意したうえでデータを扱ってください。

こんなエラーが出たら

なお、アクセス権限の設定(IAMユーザへの権限ロール設定、Amazon Seller Central での権限ロール設定、その他権限設定まわり、等々)で何れかの設定が誤っていると、下記のエラーが出ます。

Status : 403

{
    "errors": [
        {
            "message": "Access to requested resource is denied.",
            "code": "Unauthorized",
            "details": "The access token you provided has expired."
        }
    ]
}

このエラーの厄介な点は、どこが間違っているのかをエラーメッセージ内容から容易に特定できない点にあります。私はこのエラーメッセージのせいで試行錯誤の嵐となりました。今回、ブログを書きながらPostmanでのテスト接続まで進めていますが、流れ通りにやれば上記エラーは出ないと思います。

流れ通りにやっても上記エラーが出たんだが!?という場合は、私の手には負えないのでAmazonのテクニカルサポートのプロフェッショナルの方々に問い合わせを実施して、解決する必要があります。

まとめ

本ページの手順に従うことで、PostmanによるSP-APIのAPIテスト接続、ASINコードによる情報の取得が出来るようになったと思います。

Postmanでテスト接続ができている諸々のアカウント情報を使えば、自身で開発するアプリケーションでの接続時も基本的にはエラーは出ません。もしエラーが出てしまった場合は、プログラム実装部分を疑えばいいだけなので大変気持ちが楽になります。

一番厄介なのは、プログラム実装が悪いのか権限設定周りが悪いのか、どちらなのか判断がつかない状態です。その状態にならないためには、一度Postmanにてテスト接続をして諸々のアカウントが正常であることを確認してからプログラムを開発する、ということになるかと思います。

次回は、今回の実装をベースに Python コードにてSP-APIをたたく!という内容です。

今日はここまでです。お疲れさまでした。

この記事が気に入ったら
フォローしよう

最新情報をお届けします

Twitterでフォローしよう

おすすめの記事