在庫の発見および更新

在庫の発見および更新ガイド

概要

Inventory Discovery API（在庫発見API）を使用すると、ユーザーはクエリ文字列やその他の高度な検索条件を通じてeBayの出品を検索し、その情報を取得できます。さらに、Inventory Refresh API（在庫更新API）を使用すると、追跡している出品の価格や在庫状況の変更、Promoted Listings（プロモーション出品）キャンペーンへの追加・削除を示すプッシュ通知を購読できます。

APIのユースケース

  • Browse APIを使用してeBayの商品を検索・取得する
  • 特定の商品との製品適合性を確認する
  • トップレベル（L1）カテゴリから出品をダウンロードする
  • プッシュ通知を購読して出品を追跡する

Browse APIを使用してeBayの商品を検索・取得する

Browse APIを使用すると、キーワード、カテゴリ、画像などのさまざまな条件でeBayの商品を検索したり、特定の商品（単一または複数）の詳細を取得したりできます。

以下は、Browse APIを使用して商品を検索・取得するための基本的なフローです：

Browse APIを使用した商品の発見

Browse APIを使用すると、キーワード、画像ID（Base64文字列）、eBayカテゴリID、チャリティID、eBayプロダクトID（EPID）、GTIN（Global Trade Item Number）、またはこれらの組み合わせなど、さまざまな条件で商品を検索・発見できます。

Browse APIには、バイヤーのニーズに基づいて商品を発見するための以下のメソッドがあります：

  • search: さまざまなクエリパラメータを使用してeBayの商品を検索し、一致する商品の概要を取得できます。
  • searchByImage: 画像に基づいてeBayの商品を検索し、一致する商品の概要を取得できます。この画像はBase64形式である必要があります。

これらのメソッドで商品の検索を絞り込むために、以下のクエリパラメータが利用可能です：

注意: searchByImageメソッドは、次のフィルタパラメータのみをサポートしています：charity_ids、fieldgroups、category_ids、filter、およびaspect_filter。
  • q: 1つ以上のキーワードに基づいて商品を検索します。
  • autocorrect: キーワードのオートコレクト（自動修正）を有効にします。
  • gtin: 製品のGlobal Trade Item Number（GTIN）に基づいて商品を検索します。
  • charity_ids: 指定されたチャリティ（慈善団体）に関連付けられた商品を検索します。
  • compatibility_filter: 指定された車両属性と適合するP&A（パーツ＆アクセサリー）カテゴリ内の商品を検索します。
  • category_ids: 指定されたカテゴリ内の商品を検索します。
  • filter: Buy API Field Filters テーブルに記載されている条件に基づいて商品を検索します。
  • aspect_filter: 色やサイズなど、商品の特定の側面（アスペクト）に基づいて商品を検索します。
  • epid: 製品のeBayプロダクトIDに基づいて商品を検索します。

さらに、fieldgroupsパラメータを使用して、レスポンスで返されるフィールドとコンテナを制御できます。デフォルトでは、この値は MATCHING_ITEMS に設定されており、指定された絞り込み条件（上記を参照）に一致する商品のみが返されます。以下の値も利用可能です：

  • ASPECT_REFINEMENTS: レスポンスに aspectDistributions コンテナを追加します。
  • BUYING_OPTIONS_REFINEMENTS: レスポンスに buyingOptionDistributions コンテナを追加します。
  • CATEGORY_REFINEMENTS: レスポンスに categoryDistributions コンテナを追加します。
  • CONDITION_REFINEMENTS: レスポンスに conditionDistributions コンテナを追加します。
  • EXTENDED: レスポンスに shortDescription および itemLocation.city フィールドを追加します。
  • FULL: 上記のすべての絞り込みフィールドとコンテナを返します。

sort パラメータを使用して、返される商品を並べ替える基準（昇順）を指定できます。商品は、価格（price）、バイヤーの位置からの距離（distance）、出品日（newlyListed）、または終了予定日時（endingSoonest）で並べ替えることができます。

以下のページネーションパラメータを使用して、レスポンスペイロードで返されるデータ量を制御できます：

  • limit: 1ページに返される結果セット内の商品数を指定します。
  • offset: 結果セット内でスキップする商品数を指定します。

以下の例は、300ドルから500ドルの間の新品のドローンの検索を示しています。呼び出しが成功すると、この条件に一致する最初の5つのドローン（limitパラメータを参照）が返されます： 

https://api.ebay.com/buy/browse/v1/item_summary/search?q=drone&limit=5&filter=price:[300..800],priceCurrency:USD,conditions:{NEW}

Browse APIを使用した商品の取得

Browse APIの search または searchByImage メソッドを使用して商品を発見した後、getItem 関連のメソッドを使用して特定の商品に関する詳細を取得できます。

getItem メソッドを使用すると、説明、価格、カテゴリ、アスペクト、状態など、特定の商品の詳細を取得できます。取得する商品は、RESTfulな item_id 値で指定します。この値の形式は v1|{item_id}|{variation_id} です。単一バリエーションの出品の場合、{variation_id} の値は 0 になります。RESTfulなItem IDの値は、前のセクションで詳述したBrowse APIの search メソッドを使用して取得できます。

fieldgroups クエリパラメータを使用して、レスポンスで返される内容を制御できます。以下の値が利用可能です：

  • PRODUCT: レスポンスに product コンテナを追加します。
  • COMPACT: ユーザーが商品の在庫状況や商品が改訂されたかどうかを素早く確認できるよう、一部のフィールドグループのみを返します。
  • ADDITIONAL_SELLER_DETAILS: レスポンスに seller.userId フィールドを追加します。この値は、すべてのeBayサイトにおけるeBayユーザーの一意の識別子です。ユーザーがユーザー名を変更しても、この値は変更されません。
  • CHARITY_DETAILS: 該当する場合、レスポンスに charityTerms コンテナを追加します。

以下は、Browse APIを使用して商品を取得する際に適用可能なその他のメソッドです：

  • getItemsByItemGroup: マルチバリエーション出品内の各バリエーションの詳細を取得します。
  • getItemByLegacyId: レガシー商品ID値（RESTful商品ID値の代わりに）を使用して商品の詳細を取得します。
  • getItems: RESTful商品ID値で指定された1つ以上の商品の詳細を取得します。これは、一部のパートナーのみが利用できる制限付きメソッドであることに注意してください。

指定された商品との適合性を確認する

商品の検索と取得に加えて、Browse API には、特定のパーツ＆アクセサリー商品が車両と適合するかどうかを確認する機能もあります。たとえば、バイヤーが自分の車用の新しいブレーキパッドを探したい場合、search メソッドを使用する際に車両のプロパティ情報（メーカー、モデル、タイヤサイズなど）を入力すると、適合する可能性のある商品のリストが返されます。その後、checkCompatibility 呼び出しを使用して、製品が自分の車両と適合することを確認できます。

特定のマーケットプレイスの有効な属性を見つけるには、Taxonomy API の compatibility メソッドを使用してください。

以下のフローにより、指定された商品の製品適合性を確認できます：

  1. 必要に応じて、search を使用して、特定の車両プロパティと適合する可能性のある製品を検索します。
    1. compatibility_filter クエリパラメータを使用して、キーワード（qパラメータで指定）およびこのパラメータに入力された車両プロパティに一致する商品を検索できます。たとえば、q=brakes および compatibility_filter=Year:2018;Make:BMW を設定した場合、タイトル、説明、またはアスペクトに「brakes」、「2018」、または「BMW」が含まれる商品のみがレスポンスで返されます。
    2. 指定された1つ以上の車両プロパティ（この場合は Year:2018 および Make:BMW）がレスポンス内の返された商品と適合する場合、その商品に対して compatibilityProperties コンテナが返され、その商品に適合する車両プロパティのセットがリストされます。このコンテナが返されない場合、指定された車両プロパティはいずれも返された商品と適合しません。
    3. compatibilityProperties の下にある車両がパーツ＆アクセサリー商品と完全に適合することが確認された場合、compatibilityMatch フィールドには EXACT の値が返されます。compatibilityProperties コンテナに車両プロパティの一部のみが返される場合、compatibilityMatch フィールドは POSSIBLE という値を返し、商品が車両と適合する可能性があることを意味します。この値が返された場合、checkCompatibility メソッドを使用して、商品が車両と適合するかどうかを検証できます（ステップ2を参照）。
  2. checkCompatibility を使用して、指定された製品が特定の車両と適合するかどうかを確認します。
    1. 適合性を確認したい商品の item_id をパスパラメータとして渡します。
    2. 適合性を確認したい車両のすべてのプロパティを compatibilityProperties コンテナに指定します。
    3. 呼び出しが成功すると、商品の製品適合性情報が compatibilityStatus フィールドに返されます。パーツが車両と適合する場合、COMPATIBLE が返されます。

トップレベル（L1）カテゴリから出品をダウンロードする

ユーザーは Feed API を活用して、特定のマーケットプレイス上の特定のL1カテゴリ内の商品のフィードファイルをダウンロードすることで、eBayカテゴリをミラーリング（複製）できます。

注意: 利用可能なL1カテゴリのリストは、Taxonomy API の getCategoryTree メソッドを使用して取得できます。

eBayは2つのFeed APIを提供しています：Feed Beta API と Feed API です。これらのAPIはどちらもL1カテゴリからの出品をダウンロードすることを可能にしますが、以下に説明するいくつかの重要な違いがあります：

  • Feed Beta API を使用すると、ユーザーはカテゴリ内のすべての商品を含む日次および週次のブートストラップフィードファイルをダウンロードできます。また、そのカテゴリ内で1時間の間に変更があった商品の1時間ごとのファイルをダウンロードすることもできます。
  • Feed API を使用すると、ユーザーはアクセス可能なフィードタイプとフィードファイルに関する情報を取得し、それらのフィードファイルをダウンロードできます。

Feed Beta APIを使用して出品をダウンロードする

Feed Beta API を使用して、特定のマーケットプレイス上の特定のカテゴリの商品を含むTSVファイルをダウンロードできます。このAPIを使用してダウンロードできるフィードファイルの種類は以下の通りです：

  • Weekly Item Bootstrap Feed（週間商品ブートストラップフィード）: 特定のカテゴリ内のすべての固定価格商品をダウンロードします。
  • Daily Item Feed（日次商品フィード）: 特定のカテゴリ内で、特定の日に出品されたすべての固定価格商品をダウンロードします。
  • Hourly Snapshot Feed（時間単位スナップショットフィード）: 特定のカテゴリ内で、特定の時間、日に更新されたすべてのアクティブな固定価格商品をダウンロードします。

このAPIを使用することで、ユーザーは指定された週の指定されたカテゴリ内のすべての出品を含む「Weekly Item Bootstrap Feed」ファイルをダウンロードし、Bootstrapファイルがダウンロードされた日以降に出品された商品を取得するために「Daily Item Feed」ファイルをダウンロードし、1時間以内に変更または出品された商品を取得するために「Hourly Snapshot Feed」をダウンロードできます。これら3つのフィードタイプを併用することで、ユーザーはあらゆるeBayカテゴリの完全に最新なミラーを維持できます。

以下は、Feed Beta APIを使用してL1カテゴリ内の商品を検索およびダウンロードするためのメソッドです：

  • getItemFeed: 特定のカテゴリ内のすべての子カテゴリからのすべての商品を含むフィードファイルをダウンロードします。このメソッドを使用する場合、以下の feed_scope パラメータのいずれかを指定する必要があります：
    • NEWLY_LISTED: 指定された日および指定されたカテゴリに出品されたすべての商品を含む「Daily Item Feed」ファイルを返します。このスコープを使用する場合、date クエリパラメータが必要です。
    • ALL_ACTIVE: 指定されたカテゴリ内のすべての商品を含む「Weekly Item Bootstrap Feed」ファイルを返します。Weekly Item Bootstrapファイルは、週間フィードファイルが最後に生成された時点でのすべてのアクティブな出品を返すことに注意してください。
  • getItemGroupFeed: 特定のカテゴリ内のマルチバリエーション出品に関する情報を含むフィードファイルをダウンロードします。このメソッドを使用する場合、以下の feed_scope パラメータのいずれかを指定する必要があります：
    • NEWLY_LISTED: 特定の日、カテゴリ、およびマーケットプレイスの「Daily Item Feed」ファイルで返された商品に関連する商品バリエーション情報を含む「Daily Item Group Feed」ファイルを返します。このスコープを使用する場合、date クエリパラメータが必要です。
    • ALL_ACTIVE: 特定のカテゴリ内のすべての商品について、「Weekly Item Bootstrap Feed」ファイルで返された商品に関連するすべての商品バリエーション情報を含む「Weekly Item Group Bootstrap Feed」ファイルを返します。
  • getItemSnapshotFeed: 特定のカテゴリについて、指定された日および時間（snapshot_date クエリパラメータで指定）に変更があったすべての商品の詳細を含む「Hourly Snapshot Feed」ファイルをダウンロードします。

出品を含むTSVファイルをダウンロードできるメソッドに加えて、このAPIには getItemPriorityFeed メソッドも含まれており、ユーザーは Daily Item Priority Feed ファイルをダウンロードできます。このタイプのフィードファイルを使用すると、ユーザーはPromoted Listingsキャンペーンへの追加や削除など、優先商品のステータスの変更を追跡できます。このメソッドのクエリパラメータとして、追跡対象の商品を含むL1カテゴリの category_id が必要です。

Feed APIを使用して出品をダウンロードする

Feed API を使用すると、利用可能なフィードタイプとアクセス可能なフィードファイルに関する情報を取得し、それらのファイルをダウンロードできます。

以下のフローにより、利用可能なフィードファイルを検索してダウンロードできます：

  1. getAccess を使用して、アプリケーションがフィードをダウンロードできるマーケットプレイスやカテゴリなど、アプリケーションのフィードファイルアクセス構成の詳細を取得します。
  2. getFeedTypes および getFeedType を使用して、スキーマ、サポートされているマーケットプレイス、必要な認証スコープなど、これらの各フィードタイプに関する追加情報を取得します。以下のフィードタイプが Feed API でサポートされています：
    • CURATED_ITEM_FEED: このフィードタイプは、カテゴリと日付に基づいた厳選された（キュレーションされた）商品のコレクションを提供し、それらの商品を説明するために使用されるフィールドのセットを返します。
    • PRODUCT_FEED: このフィードタイプは、一意のeBay Product Identifier (ePID)および商品の状態ごとに単一のオファーのみを含む商品のコレクションを提供し、商品を説明するために使用されるフィールドのセットを返します。
    • PROMOTION: このフィードタイプは、ライブ割引とそれらに関連付けられている商品の時間単位のスナップショットを提供し、割引を説明するために使用されるフィールドのセットを返します。
    • CBT_ITEM_ALL_ACTIVE: このフィードタイプは仕向け地市場向けに設計されており、国際的な可視性のための商品のコレクションを提供します。これらのフィードは、ドイツ（DE）からオーストリア（AT）への発送など、特定の市場から調達され、仕向け地市場へ発送可能な在庫で構成されています。このフィードファイルの出力は、TSVではなくAVROであることに注意してください。
  3. getFiles または getFile を使用して、ダウンロード可能なフィードファイルに関する詳細を取得します。生成日、フィードタイプ、サポートされているマーケットプレイスなど、フィードファイルに関する詳細が各ファイルについて返されます。ファイルをダウンロードするために必要な各ファイルの fileId 値も返されます。
  4. downloadFile を使用し、fileId を使って指定されたフィードファイルのGZIPファイルをダウンロードします。

プッシュ通知を購読して出品を追跡する

eBayの Notification API と統合することで、サードパーティのプラットフォームは、eBayがユーザーの宛先エンドポイントに送信するさまざまな種類の通知を購読して受信できます。以下の通知トピックは、ユーザーが価格や在庫状況が変更された出品、またはPromoted Listingsキャンペーンに追加または削除された出品を追跡するのに役立ちます：

注意: 現在、これらのトピックはCA、AU、HK、SG、MY、およびPHを除くすべてのマーケットプレイスのeBay Partner Network（ePN）パートナーが利用できます。
  • Item Availability（商品の在庫状況）: 固定価格商品の在庫状況タイプが変更されたときに開発者に送信される通知です。
  • Item Price Revision（商品価格の改定）: 固定価格商品の価格が変更されたときに開発者に送信される通知です。
  • Priority Listing Revision（優先出品の改定）: Promoted Listingが改定されたときにセラーに送信される通知です。

以下のフローにより、設定されたエンドポイントへのこれらの通知の受信を開始できます：

  1. createDestination を使用して、eBayからの通知を受信するためのエンドポイントを設定します。このエンドポイントは、着信する通知データを安全に処理するために必要です。
  2. getTopics を使用して、利用可能な通知トピックの完全なリストを取得します。authorizationScopes 配列内のOAuthスコープに注意してください。一部のトピックには特別なスコープが必要です。必要なスコープがない場合、そのトピックを購読することはできません。また、topicId 値はそれらのトピックを購読するために必要となるため、メモしておいてください。
  3. createSubscription を使用してトピックを購読します。トピックの topicId 値、これらの通知を受信するエンドポイントを指定し、status 値を ENABLED に設定します。
  4. エンドポイントに送信されるすべての通知について、eBay通知に含まれるBase64エンコードされた X-EBAY-SIGNATURE ヘッダーを抽出します。この値をパスパラメータとして getPublicKey メソッドに渡します。レスポンスで返されるキー値は、eBayプッシュ通知メッセージのペイロードを検証するために使用されます。
  5. 通知に基づいて必要なアクションを実行します。

コードサンプル

キーワードで商品を検索する 

curl -X GET "https://api.ebay.com/buy/browse/v1/item_summary/search?q=drone"
-H "Authorization:Bearer OAUTH_token"
-H "X-EBAY-C-MARKETPLACE-ID:EBAY_US"

サポートされているトピックを取得する 

curl -X GET "https://api.ebay.com/commerce/notification/v1/topic"
-H "Authorization:Bearer OAUTH_token"

エラーハンドリング

  • Browse APIを使用して商品を取得する際、指定された商品IDが無効であるというエラーメッセージが表示される場合があります。これは、レガシーAPIとRESTful APIの間で「商品（item）」の識別子の定義や商品IDが表す内容に違いがあるためである可能性があります。Browse APIの使用時にeBayのレガシー商品識別子を使用したい場合は、getItemByLegacyId メソッドを使用して商品を取得できます。詳細については、Buying Integration Guideの Legacy API compatibility を参照してください。
  • Feed APIを使用してフィードファイルをダウンロードしようとした際に、フィードファイルが存在しない、または期限切れの可能性があるというエラーが表示される場合は、getFeedType を使用して、ダウンロードしようとしているフィードタイプに関連付けられている marketplaceIds および lookBack の値を確認してください。
  • Feed APIを使用してフィードファイルをダウンロードしようとした際に「権限不足（insufficient permissions）」エラーが表示される場合は、getFeedType を使用して、そのフィードタイプに関連付けられている authorizationScopes を確認してください。各フィードタイプには、フィードタイプへのアクセスを許可するために必要なOAuth認証スコープがあります。
  • Feed Beta APIはサンドボックス環境で使用可能ですが、特定のカテゴリに制限されています。さらに、ブートストラップフィードはサンドボックス環境ではサポートされていません。詳細については、Sandbox limitations and support を参照してください。
  • Item Availability または Item Price Revision 通知を購読しようとしてエラーが発生した場合は、必要なスコープを提供しているか確認してください。これら2つの通知には、次のスコープが必要です：https://api.ebay.com/oauth/api_scope/buy.item.stream

ベストプラクティス

  • 必須ではありませんが、Browse APIを呼び出す際には、contextualLocation 属性を持つ X-EBAY-C-ENDUSERCTX ヘッダーを使用することを強くお勧めします。このヘッダーにより、ユーザーは位置情報を指定でき、配送予定期間情報の精度が向上し、計算済み配送料情報には必須となります。このヘッダーは、ePNアフィリエイト情報を提供するためにも使用できます。
  • Browse APIを使用すると、セラーはアスペクト絞り込みコンテナ（aspectDistributions）で返されたデータを使用してヒストグラムを作成し、バイヤーが各絞り込み項目をドリルダウンして検索結果を絞り込むことを可能にできます。
  • 様々な Feed API および Feed Beta API メソッドを通じて大きなフィードファイルを「チャンク（分割）」で取得する代わりに、オープンソースの Feed V1 SDK（または Feed Beta API 用の Feed SDK）を使用してフィードファイルを取得できます。これらのSDKは、必要に応じてフィードファイルをダウンロードして単一のファイルに結合し、フィードファイル全体を解凍します。また、フィールドフィルタを指定してファイル内の商品をキュレーションすることもできます。
  • Feed Beta APIを使用する場合、ブートストラップファイルは木曜日にダウンロードすることをお勧めします。これは、ブートストラップファイルは毎週火曜日に生成され、通常水曜日に入手可能になりますが、ファイルが入手可能になる正確な時間は変動する可能性があるためです。
  • Feed Beta APIを使用してカテゴリをミラーリングする際にダウンロードした出品を最新の状態に保つには、ブートストラップファイルをダウンロードした日から、ファイルの Last-Modified レスポンスヘッダーの日付までの各日について、Daily Item Feedファイルをダウンロードすることをお勧めします。たとえば、金曜日にブートストラップファイルをダウンロードし、ファイルの Last-Modified 日付が日曜日である場合、前日（月曜日から木曜日）ごとに feed_scope=NEWLY_LISTED で getItemFeed を使用して、新規出品商品をダウンロードする必要があります。
トップに戻る