Large Merchant Service

eBayのLarge Merchant Servicesは、大規模の在庫を持つセラーが大量データをeBayに送受信できるよう手段として用意されています。 この仕組は、eBayのプラットフォームにおいて並列処理やエラー時の自動再開などを使って、大規模マーチャントのワークフローを効率化できるように設計されています。 Large Merchant Serviceは、Trading APIの膨大なトランザクションを効率的に一括処理できる仕組みとして構成されています。 通常のAPIのように、アプリケーションがAPIリクエストを発行してそのレスポンスを待つ同期方式と異なり、次のような非同期な処理になります。
  • アプリケーションはリクエストを発行してそれに対する識別子をもらう
  • もらった識別子をつかて、アプリケーションがリクエストの完了状態を定期的にチェック
  • リクエストが完了状態になった後、アプリケーションがレスポンスを取得する
Large Merchant Serviceは、Bulk Data Exchange API、File Transfer API、マーチャントデータAPIの3つから構成されています。

Bulk Data Exchange API(API)

このAPIは、データ処理の開始・停止・ステータスチェックなど、マーチャントのワークフロー管理を定義します。このAPIでは、非同期で実行される処理単位、「ジョブ」という概念を導入しています。 Large Merchant Service では、処理が非同期に実行される(大量データ処理のリクエストを受け付けるため)ので、リクエストに対する結果は処理が完了したタイミングで受け取る必要があります。

プロトコル、リクエスト・レスポンス形式

Bulk Data Exchange APIは、SOAPとXMLのHTTP POST方式をサポートしています。

サービスURI

Bulk Data Exchange APIリクエストは、サンドボックスまたはプロダクション環境のURIに送信します。
環境 URI
Sandbox https://webservices.sandbox.ebay.com/BulkDataExchangeService
Production https://webservices.ebay.com/BulkDataExchangeService

HTTPヘッダー、URLパラメータ

Bulk Data Exchange APIは、次のHTTPヘッダーがあります。
パラメータ名 必須有無 説明
CONTENT-TYPE このヘッダーを指定した場合、次の値からを設定する必要があります。 XMLの場合は、text/xml、SOAP12の場合、application/soap+xml、SOAP11の場合、text/xml (SOAPActionヘッダーと一緒に)
X-EBAY-SOA-MESSAGE-PROTOCOL 条件による SOAPリクエストの場合必須。どのSOAPプロトコルを利用するかを指定。1.1の場合、SOAP11、1.2の場合、SOAP12をセット。
X-EBAY-SOA-OPERATION-NAME 必須 呼び出すAPIコール名。
X-EBAY-SOA-SERVICE-NAME 呼び出すAPIの名前。Bulk Data Exchange APIコールの場合、”BulkDataExchangeService”をセット。
X-EBAY-SOA-SECURITY-TOKEN 必須 認証済みユーザを識別するトークン(ユーザトークン)。
X-EBAY-SOA-SERVICE-VERSION 利用するAPIバージョン(1.0.0など)

スキーマ

次のURLより、Bulk Data Exchange のWSDLを[こちら]からダウンロードできます。
http://developer.ebay.com/webservices/bulk-data-exchange/latest/BulkDataExchangeService.wsd 
特定のバージョンのWSDLの場合、latestの代わりにバージョン番号を指定することができます。
http://developer.ebay.com/webservices/bulk-data-exchange/1.0.0/BulkDataExchangeService.wsdl

File Transfer API(API)

このAPIは、データファイルをeBayに送受信します。 各APIコールの詳細情報は、Large Merchant Services API Referencesを参照下さい。

プロトコル、リクエスト・レスポンス形式

File Transfer APIは、SOAPとXMLのHTTP POST方式をサポートしています。

サービスURI

File Transfer APIリクエストは、サンドボックスまたはプロダクション環境のURIに送信します。
環境 URI
Sandbox https://storage.sandbox.ebay.com/FileTransferService
Production https://storage.ebay.com/FileTransferService

HTTPヘッダー、URLパラメータ

File Transfer APIは、次のHTTPヘッダーがあります。
パラメータ名 必須有無 説明
CONTENT-TYPE このヘッダーを指定した場合、次の値からを設定する必要があります。 XMLの場合は、text/xml、SOAP12の場合、application/soap+xml、SOAP11の場合、text/xml (SOAPActionヘッダーと一緒に)
X-EBAY-SOA-MESSAGE-PROTOCOL 条件による SOAPリクエストの場合必須。どのSOAPプロトコルを利用するかを指定。1.1の場合、SOAP11、1.2の場合、SOAP12をセット。
X-EBAY-SOA-OPERATION-NAME 必須 呼び出すAPIコール名。
X-EBAY-SOA-SERVICE-NAME 呼び出すAPIの名前。File Transfer APIコールの場合、”FileTransferService”をセット。
X-EBAY-SOA-SECURITY-TOKEN 必須 認証済みユーザを識別するトークン(ユーザトークン)。
X-EBAY-SOA-SERVICE-VERSION 利用するAPIバージョン(1.0.0など)

スキーマ

次のURLより、Bulk Data Exchange のWSDLを次のURLからダウンロードできます。
http://developer.ebay.com/webservices/file-transfer/latest/FileTransferService.wsdl
特定のバージョンのWSDLの場合、latestの代わりにバージョン番号を指定することができます。http://developer.ebay.com/webservices/file-transfer/1.0.0/FileTransferService.wsdl

Merchant Data API(データファイル)

このAPIは、eBayにデータやレポートをファイルで送受信する仕組みを提供します。利用できるAPIコールは、Merchant Data API Referenceに定義されています。 このページで、一部のAPIコールが「Related」として乗っていますが、これはTrading APIでも存在するAPIコールであり、定義はTrading APIでされています。 Merchant Data APIコールでは、同じコールの複数のインスタンス(複数商品に対する同じ処理)を記述したデータファイルを用意します。データファイルには、1種類のコールしか記述できません。 例えば、AddFixedPriceItemの複数回コールは同じファイルに記述できますが、AddFixedPriceItemとReviseFixedPriceItemのコールを同じファイルに含めることはできません。 データファイルは、出品に関する情報を含んでいます。リクエストとレスポンスは、Trading APIと類似した形です。ほとんどのMerchant Data APIは、処理を実行するAPIコールを直接呼び出すのではなく、実行するAPIコールを記述したファイルを送信する方式になっています。 直接処理を呼び出したい場合は、関連API(Trading API)のコールを呼び出すことになります。 このAPIでは、リクエストした処理の実行結果が分かるよう、「レポート」という概念を導入しています。レポートは、出品中商品、販売済み商品など、在庫管理に必要な情報を提供します。 Merchant Data APIは、単体でコールされることはありません。

データファイル構造

データファイルは、eBayへのリクエスト(AddFixedPriceItemRequest, ReviseInventoryStatusRequest, OrderAckRequestなど)、eBayからのはレスポンス、リポート(AddFixedPriceItemResponse, OrderReportなど)を含みます。 データファイルは、次のように部品化された構造をもっています。
  • XML定義 ファイル転送でアップロード、ダウンロードするファイルはXMLであり、XML定義部分が必要です。エンコーディング属性はUTF-8である必要があります。
  • リクエスト又はレスポンスコンテナ データファイルをアップロードする際、個々のリクエストはBulkDataExchangeRequestsコンテナ内である必要があります。ダウンロードしたデータファイルのペイロードは、BulkDataExchangeResponsesコンテナ内である必要があります(レスポンスコンテナは、ネームスペース定義も含みます)。 データファイルは、BulkDataExchangeRequestsとBulkDataExchangeResponsesのどれかのコンテナを含むことができます。
  • ヘッダー フィルをアップロードする際、BulkDataExchangeRequestsコンテナ内にヘッダーを入れる必要があります。ヘッダーは次の2つのフィールがあります。
    • SiteID : ペイロードにあるリクエストを送信するeBayサイトのID
    • Version : ペイロードにあるリクエストの互換バージョン番号。このバージョン番号は、ペイロードの個々のリクエスト(AddFixedPriceItemリクエストなど)にも指定する必要があります。
  • ペイロード データファイルペイロードは、一つまたは複数のリクエスト、レスポンス、リポートを含みます。Merchant Data API Referenceに、リクエストの入力フィールド、レスポンスとリポートの出力フィールドが定義されています。 ペイロード内のリクエストは、全て同じ種類でなければなりません。つまり、AddFixedPriceItemとReviseFixedPriceItemリクエストを同じデータファイルに混ぜることはできません。
Data file structue

スキーマ

Merchant Data XSD fileを使用して、データファイルペイロードの有効性チェックができます。 各リリースの変更情報は、Merchant Data API Release Notesから参照できます。

Large Merchant Serviceのテスト

Large Merchant Serviceは、統合されたソリューションです。商品の出品・更新などの機能をテストするためには、この3つのAPIを組み合わせて使う必要があります。つまり、File Transfer APIを使うには、先にBulk Data Exchange APIでジョブを作成し、Merchant Data APIまたはTrading APIで有効なデータファイルの作成が必要になります。 この3つのAPIは、サンドボックス環境でテスト可能です。テスト時の制限とベストプラクティスについては、Testing and Troubleshootingに情報があります。