7. ツールを使ってみよう：PostmanでTrading APIを体験

前回の記事はこちら

前回は、eBay販売管理の中核をなすTrading APIの全体像と、その主要な機能について学びましたね。APIという「言葉」の種類と意味が分かったところで、いよいよ実践に移ります。

今回は、プログラミングを一切行わずにAPIを呼び出すことができる、非常に強力で初心者にも優しいツール「Postman」をご紹介します。これを使って、Trading APIとの初めての本格的な対話を体験してみましょう。

その前に：APIとの対話の基本ルール「HTTPリクエスト」

Postmanを使い始める前に、私たちがAPIと対話する際の基本的なルール、「HTTPリクエスト」について少しだけお話しします。難しく考えず、「レストランでの注文の仕方」を思い出してください。

私たちがAPIに何かを依頼することは、ウェブの世界では「HTTPリクエストを送る」と言います。これは、あなたがウェイターに渡す一枚の「注文伝票」のようなものです。この伝票は、いくつかの重要なパートで構成されています。

• メソッド (Method): これは「注文の種類」です。

• GET: 「情報を取得したい (Get)」時に使います。「メニューを見せてください」というような、読み取り専用の依頼です。

• POST: 「情報を提出したい (Post)」時に使います。「この内容で料理を作ってください」というように、何かを新しく作成したり、更新したりする依頼です。eBayのTrading APIでは、たとえ情報を取得する場合でも、リクエスト内容が複雑なため、主にこのPOSTを使います。

• URL: これは「宛先」です。「厨房（eBayのAPIサーバー）の住所」に当たります。この宛先を間違えると、注文は届きません。

• ヘッダー (Headers): これは伝票の「ヘッダー情報」です。注文内容そのものではなく、「誰からの注文か（認証キー）」「どんな形式で書かれているか（データ形式）」といった、配送伝票のラベルのような補足情報が含まれます。

• ボディ (Body): これが「注文内容の本体」です。POSTメソッドの場合、ここに「どんな商品情報を取得したいか」や「どんな商品を出品したいか」といった、具体的な依頼内容を書き込みます。Trading APIでは、このボディにXML形式で指示を記述します。

• パラメータ (Parameters): ボディやURLの中に含まれる、個々の具体的な指示内容です。「どの商品の？（ItemID）」や「どれくらい詳しく？（DetailLevel）」といった、詳細な指定がこれにあたります。

これらの要素を正しく組み立ててAPIサーバーに送ることで、初めてAPIとの対話が成立します。そして、これから紹介するPostmanは、この「注文伝票」を簡単かつ正確に作成するための、非常に優れたツールなのです。

Postmanとは？ API初心者の心強い味方

Postmanは、先ほど説明したHTTPリクエストを、グラフィカルな画面で直感的に組み立てて、送受信できるツールです。コーディングは一切不要で、APIの動きを目で見て理解できるため、初心者にとって最高の学習パートナーとなります。

まずは公式サイト（postman.com）から、お使いのPCに合わせたアプリケーションをインストールしておきましょう。

事前準備：ヘッダーの設定とURLの入力

前の内容が書いたように、API呼び出しを行う前に、私たちは相手に「自分が誰であるか」を伝える必要があります。これは、まるでレストランに入って注文する前に、店員に自分の身元（例えば予約者名）を伝えるようなものです。APIの世界では、この「私が誰か」という情報やその他の重要な情報は、「HTTPヘッダー」を介して伝達されます。

ヘッダーには、リクエストを送信する形式や認証情報（APIキーやトークンなど）といったメタデータが含まれます。これらの情報は、APIサーバーがリクエストを正しく理解し、応答するために不可欠です。ここで第五回の記事で紹介したAPI Explorerはまだ覚えていますでしょうか、

画像のようにAPI ExplorerでAPIを呼び出した際に、Trading APIでよく使用され、設定が必須となるヘッダーは以下です：

• X-EBAY-API-SITEID: 0  // このヘッダーは、APIリクエストの対象となるeBayサイトIDを指定します。`0`は通常、米国サイト（US）を指し、異なる数字はeBayの異なるグローバルサイトに対応します。これにより、リクエストが正しいeBayの地域サーバーに送信されることが保証されます。

• X-EBAY-API-COMPATIBILITY-LEVEL: 967         // このヘッダーは、使用しているAPIバージョンの互換性レベルを示します。これは、サーバーがあなたのアプリケーションがどのAPIバージョン向けに設計されているかを認識し、互換性のある方法でリクエストを処理し、該当するバージョンのデータ構造を返すために役立ちます。APIの更新に伴い、この数値は変更される可能性があります。

• X-EBAY-API-CALL-NAME: GetItem        // このヘッダーは、実行したい特定のAPI操作名を指定します。この例では、`GetItem`は特定の商品（Item）の詳細情報を取得したいことを意味します。異なるAPI呼び出し（例：商品出品、注文変更など）を行うたびに、この値はそれに応じて変更されます。

• X-EBAY-API-IAF-TOKEN: （トークンを入力）        // これはAPI認証トークンであり、あなたの身元と権限を検証するために使用されます。eBay APIにアクセスし、指定された操作を実行する権限があることを証明します。ここに、eBay開発者センターで取得したOAuthトークンまたはレガシー認証トークンを入力する必要があります。このトークンがないと、リクエストは認証されません。

どうでしょうか？難しいそうな設定のように見えますが、実際は”身分証明証”を持って、０番の役所に行き、967室でGetItemの業務をしたいとほぼ同じの意味です。ヘッダーの設定が完了すると、URLにhttps://api.sandbox.ebay.com/ws/api.dllを入力しましょう。 (Memo:  入力が分からない場合は、API Explorerでコピー＆ペーストをしましょう）、設定済みの画像は以下です。

これから見ていくように、API呼び出しのたびにこれらのヘッダーを入力するのは手間がかかります。Postmanには、「Environment（環境）」機能があり、これらの共通情報を変数として保存し、後で簡単に再利用できます。このチュートリアルではEnvironment機能の詳細には触れませんが、興味のある方はPostmanの公式ウェブサイトで学習することをお勧めします。

ハンズオン：GetItemリクエストを送信してみよう

準備が整いました。サンドボックスに出品したテスト商品の情報を取得するGetItemコールを送信してみましょう。

簡単な方法（ショートカット）

本格的にリクエストを組み立てる前に、素晴らしいお知らせです。eBay Japanでは、主要なAPIコールをすぐに試せるPostmanのコレクションファイルを準備中です。これをダウンロードしてPostmanにインポートすれば、APIの設定の大部分が完了した状態からスタートできます。手っ取り早く試したい方は、ぜひリリースを楽しみにお待ちください。詳細はeBay Japanのデベロッパーサイトのニュースにご注目ください。

GetItemリクエストを送信

準備が整いました。サンドボックスに出品したテスト商品の情報を取得するGetItemコールを送信してみましょう。

今回は学習のため、あえて手動でリクエストを組み立てることで、その仕組みを深く理解していきましょう。先ほど学んだHTTPリクエストの知識を思い出しながら、各項目を設定してみてください。

1. ボディの設定
   「Body」タブを開き、「raw」と「XML」を選びますと、ボディの入力ボックスが現れます。下の画像をチェックしてください。

2. ボディの入力ボックスに以下のXMLリクエストを貼り付けます。ItemIDが、このリクエストにおける重要なパラメータの一つです。

<?xml version="1.0" encoding="utf-8"?>

<GetItemRequest xmlns="urn:ebay:apis:eBLBaseComponents">    

<ErrorLanguage>en_US</ErrorLanguage>

<WarningLevel>High</WarningLevel>

      <!--Enter an ItemID-->

  <ItemID>110583461480</ItemID>

</GetItemRequest>

注意: ここにあなたのサンドボックス商品のItemIDを入力 の部分を、第五回の記事でサンドボックスに作成した、実在するテスト商品のItemIDに書き換えるのを忘れないでください。設定完了の画面は下のように見えます。

リクエストを送信して結果を確認！

右上にある青い「Send」ボタンをクリックします。成功すれば、下のレスポンス画面に商品の詳細情報がXML形式で返ってくるはずです。

おめでとうございます！HTTPリクエストの基本を学び、Postmanを使ってAPIとの対話を成功させました。

次回からは、いよいよデータの「読み取り（Read）」「作成（Create）」「更新（Update）」「削除（Delete）」に挑戦します。引き続きPostmanを使い、商品管理の一連の流れをハンズオンで体験します。ぜひ、ご期待ください。

APIは難しくない！あなたのビジネスを加速させる魔法の杖です。

リファレンス１：XMLとは？API応答のXMLデータをどう読み解く？

XMLの基本的な形：

eBay Trading APIでは、APIにお願いするデータ（リクエスト）や、APIから返ってくるデータ（レスポンス）を作るのに、XMLがよく使われています。

XMLの文書は、いくつかの部分が入れ子になった形でできています。それぞれの部分は、始まりの印（タグ）と終わりの印（タグ）で囲まれています。例えば：

<要素名>

  <子要素名>内容</子要素名>

  <別の要素名 属性="値">もっと内容</別の要素名>

</要素名>

• タグ（Tags）：`<>`で囲まれた部分、例えば`<GetItemRequest>`。始まりのタグと終わりのタグ（`/`がついている、例えば`</GetItemRequest>`)で一つの「要素」が決まります。

• 要素（Elements）：タグとその中の内容全体、例えば`<ItemID>110583461480</ItemID>`。

• 属性（Attributes）：始まりのタグの中に書かれた追加の情報。「名前="値"」の形、例えば`<別の要素名 属性="値">`。

• ルート要素（Root Element）：XML文書の一番上の部分。他のすべての要素はこの中に入っています。GetItemRequestの例では、`<GetItemRequest>`がルート要素です。

API応答のXMLデータをどう読み解く？

APIへのリクエストが成功すると、eBayのサーバーからXML形式の応答が返ってきます。この応答を読み解くのは、階層のある報告書を読むようなものです。

1. ルート要素を見つける：応答の一番上の要素は、たいてい`Response`で終わります。例えば`GetItemResponse`。これは、あなたが行ったお願いに対する応答だということを示しています。

2. 一つずつ下の要素を見ていく：

• 一番上の状態情報：ルート要素のすぐ下には、リクエストがうまくいったかどうか（`Ack`：`Success`、`Failure`、`Warning`など）といった、リクエストの状態に関する要素があります。

• お願いした内容のデータ：次に、あなたのお願いした具体的な内容に関する要素が出てきます。例えば、`GetItemResponse`の中には、お願いした商品の詳しい情報がすべて入った`<Item>`要素があります。

• さらに中の要素と属性：`<Item>`要素の中には、もっと細かい要素があります。例えば`<Title>`（商品のタイトル）、`<CurrentPrice>`（今の価格）、`<EndTime>`（終了時間）などです。これらは具体的な商品データを含んでいます。データによっては、タグの中に属性として書かれていることもあります。

3. 名前空間に注意：`xmlns="urn:ebay:apis:eBLBaseComponents"`のようなものを見かけるかもしれません。これはXMLの名前空間と言って、同じ名前の要素が他のXML文書とぶつからないように、要素や属性の集まりを定義しています。データを読み解く上では、通常気にしなくても大丈夫です。

4. エラーや警告の情報：もしリクエストがうまくいかなかったり、警告があったりすると、応答の中に`<Errors>`や`<Warnings>`要素が含まれます。これらには、何が問題だったのか、エラーコードは何なのかなどが詳しく書かれています。

このように、階層をたどっていくことで、必要なデータをはっきり見つけることができます。例えば、`GetItemResponse`から商品のタイトルを知りたい場合は、`GetItemResponse`の下にある`Item`要素、さらにその下の`Title`要素を見つければ、その中のテキストが商品のタイトルです。

リファレンス２：eBay Trading API (XML) 共通HTTPヘッダー設定リスト