Notification API

Notification API 概要 (Notification API Overview)

eBay Notification APIは、ユーザーが以下を行えるようにすることで、エンドツーエンドのeBay通知エクスペリエンス全体の管理を可能にします：

• サポートされている通知トピックの閲覧とトピック詳細の取得
• 通知宛先エンドポイントの作成、構成、および管理
• 通知購読（サブスクリプション）の構成、管理、およびテスト
• eBay通知の処理とメッセージペイロードの整合性の検証

技術概要 (Technical overview)

eBay Notification APIを使用すると、以下のセクションにリストされている主要なメソッドとフィールドを使用して通知を管理できます。

主要なメソッド

Notification APIには、以下のリソースとメソッドが含まれています：

• topic - このリソースを使用すると、ユーザーはサポートされている通知トピックを閲覧し、それらのトピックの詳細を取得できます。以下のメソッドが含まれています：
  • getTopic
  • getTopics
• config - このリソースを使用すると、ユーザーはアラート構成の詳細を作成、更新、および取得できます。以下のメソッドが含まれています：
  • updateConfig
  • getConfig
• destination - このリソースを使用すると、ユーザーは通知を受信する宛先エンドポイントを作成および管理できます。以下のメソッドが含まれています：
  • createDestination
  • updateDestination
  • getDestination
  • getDestinations
  • deleteDestination
• subscription - このリソースを使用すると、ユーザーは通知購読を作成、管理、フィルタリング、およびテストできます。以下のメソッドが含まれています：
  • createSubscription
  • updateSubscription
  • enableSubscription
  • disableSubscription
  • getSubscription
  • getSubscriptions
  • deleteSubscription
  • testSubscription
  • createSubscriptionFilter
  • getSubscriptionFilter
  • deleteSubscriptionFilter
• public_key - このリソースを使用すると、ユーザーは公開鍵IDを指定して公開鍵を取得でき、これを使用してeBayから送信された通知の検証を実行できます。以下のメソッドが含まれています：
  • getPublicKey

主要なフィールド

Notification APIで使用される主要なフィールドは以下の通りです：

• Alert email - アプリケーション用に設定されたアラートメールアドレス。
• Delivery configuration - 宛先用に設定されたエンドポイントとその関連する検証トークンを含む、配信構成に関する詳細。
• Topic ID - 購読を作成および管理できる、サポートされているeBay通知トピックのID。
• Destination ID - eBay通知を受信する構成済み宛先のID。
• Subscription ID - eBay通知トピックへの購読のID。購読により、ユーザーアプリケーションはビジネスに関連する通知と情報を受信できます。
• Filter ID - 購読に関連付けられたフィルタのID。フィルタを使用すると、ユーザーアプリケーションは提供された基準に一致する場合にのみ通知を受信できます。
• Public Key ID – getPublicKey メソッドから公開鍵を取得するために使用される一意の鍵ID。これは、eBayプッシュ通知と一緒に送信される X-EBAY-SIGNATURE ヘッダーから取得されます。

ビジネスユースケース (Business use cases)

以下のセクションでは、初期通知購読フローについて説明するビジネスユースケースの概要を示します：

• 通知トピックの選択
• アラート構成の作成
• エンドポイント宛先の作成
• 通知トピックへの購読
• トピックの購読フィルタの作成
• eBayプッシュ通知の検証

通知トピックの選択

ユーザーは、getTopic または getTopics メソッドを使用して、サポートされているeBay通知トピックを検索し、メタデータ詳細を取得できます。これらのメソッドによって返される情報には、サポートされているスキーマバージョン、フォーマット、およびトピックIDが含まれます。

現在サポートされている通知トピックは以下の通りです：

トピック	トピックID	トピックの説明
Authorization Revocation	AUTHORIZATION_REVOCATION	eBayユーザーがeBay Developers Programアプリケーションの権限を取り消したときに、開発者に通知が送信されます。
Buyer Question	BUYER_QUESTION	バイヤーがアクティブな出品について質問したときに、セラーに通知が送信されます。
Buyer Requested Purchase Quote	BUYER_REQUESTED_PURCHASE_QUOTE	バイヤーが支払いの前に注文の合計金額をリクエストしたときに、セラーまたはセラーによって承認されたサードパーティアプリケーションに通知が送信されます。
Feedback Left	FEEDBACK_LEFT	ユーザーが他のユーザーにフィードバックを残したときに、そのユーザーに通知が送信されます。
Feedback Received	FEEDBACK_RECEIVED	ユーザーが他のユーザーからフィードバックを受け取ったときに、そのユーザーに通知が送信されます。
Feedback Star Rating	FEEDBACK_STAR_RATING	ユーザーのフィードバックの星評価が変更されたときに、そのユーザーに通知が送信されます。
Item Availability	ITEM_AVAILABILITY	固定価格商品の在庫状況タイプが変更されたときに、開発者に通知が送信されます。サポートされている在庫状況タイプは AVAILABLE、UNAVAILABLE、TEMPORARILY_UNAVAILABLE です。 注: 現在、このトピックはCA、AU、HK、SG、MY、PHを除くすべてのマーケットプレイスのeBay Partner Network（ePN）パートナーが利用できます。
Item Marked Shipped	ITEM_MARKED_SHIPPED	セラーが商品を発送済みとしてマークしたときに、ユーザーに通知が送信されます。
Item Price Revision	ITEM_PRICE_REVISION	固定価格商品の価格が変更されたときに、開発者に通知が送信されます。 注: 現在、このトピックはCA、AU、HK、SG、MY、PHを除くすべてのマーケットプレイスのeBay Partner Network（ePN）パートナーが利用できます。
Listing Preview Creation Task Status	LISTING_PREVIEW_CREATION_TASK_STATUS	出品プレビュー作成タスクが完了したときに、セラーに通知が送信されます。 注: この通知トピックは、制限付きのInventory Mapping APIにアクセスできる開発者のみが使用できます。
Marketplace Account Deletion	MARKETPLACE_ACCOUNT_DELETION	eBayユーザーが個人データの削除とアカウントの閉鎖をリクエストしたときに、開発者に通知が送信されます。詳細については、eBay Marketplace Account Deletion ページを参照してください。
New Message	NEW_MESSAGE	eBayまたは他のeBayユーザーから新しいメッセージを受信したときに、ユーザーに通知が送信されます。
Order Confirmation	ORDER_CONFIRMATION	バイヤーがオークションまたは固定価格商品のチェックアウトプロセスを完了したときに、セラーに通知が送信されます。
Priority Campaign Strategy Budget Status	PLA_CAMPAIGN_BUDGET_STATUS	Promoted Listingsプライオリティストラテジー広告キャンペーン（旧Promoted Listings Advanced (PLA)）の日次予算が完全に使い果たされたときに、セラーに通知が送信されます。
Priority Listing Revision	PRIORITY_LISTING_REVISION	優先出品（Priority Listing）が改定されたときに、セラーとバイヤーに通知が送信されます。 注: 現在、このトピックはCA、AU、HK、SG、MY、PHを除くすべてのマーケットプレイスのeBay Partner Network（ePN）パートナーが利用できます。
Seller Customer Service Metric Rating	SELLER_CUSTOMER_SERVICE_METRIC_RATING	カスタマーサービス指標のパフォーマンスに重大な変更があったときに、セラーに通知が送信されます（「非常に高い（very high）」に向かっている場合の事前警告を含む）。
Seller Standards Profile Metrics	SELLER_STANDARDS_PROFILE_METRICS	セラーパフォーマンス指標とセラーレベルに重大な変更があったときに、セラーに通知が送信されます（セラーの標準レベルを変更する可能性のあるしきい値に近い場合の事前警告を含む）。

アプリケーションは、トピックの購読に必要な認可スコープによって制限される、サポートされているスキーマバージョンおよび形式の任意のトピックを購読できます。トピックは、受信する情報のタイプとイベントに関連付けられたデータタイプを指定します。

アラート構成の作成

通知を受信するためのエンドポイント宛先を設定する前に、まずアラート構成を作成する必要があります。updateConfig メソッドを使用すると、ユーザーは新しいアラート構成を作成（または既存の構成を更新）し、アプリケーションのアラートメールを指定できます。

アラート構成がすでに作成されている場合は、getConfig メソッドを使用して既存の構成データを取得および確認できます。

エンドポイント宛先の作成

eBay通知を購読して受信する前に、ユーザーはエンドポイント宛先を準備してeBayからのチャレンジコードを受信し、このチャレンジコードを使用してエンドポイントURLの正当性を検証する必要があります。eBayは、ユーザーが提供されたエンドポイントURLを所有/アクセスできることを確認する必要があります。

createDestination メソッドを使用してプロセスを開始し、その時点でユーザーは宛先エンドポイントと検証トークンを指定する必要があります。開発者がエンドポイントURLと検証トークンを提供して保存した直後に、eBayはGET呼び出しの形式でそのURLにチャレンジコードを送信します。このGET呼び出しは次の形式を使用します：

GET https://?challenge_code=123

この一意のチャレンジコードを受信すると、エンドポイントはチャレンジコード、検証トークン、およびエンドポイントURLをハッシュ化し、JSON形式の challengeResponse フィールドを通じて 200 OK とハッシュ値でeBayに応答するように設定する必要があります：

{
"challengeResponse":"52161ff4651cb71888801b47bae62f44d7f6d0aab17e70d00f64fc84368ca38f"
}

このレスポンスの content-type ヘッダーは application/json に設定する必要があり、3つのパラメータは次の順序でハッシュ化する必要があります。そうしないと検証に失敗します：

challengeCode + verificationToken + endpoint

eBayは、エンドポイントが正式に通知を購読できるようになる前に、16進文字列を検証します。エンドポイントと検証トークンは宛先に固有の値ですが、チャレンジコード変数は challenge_code クエリパラメータの形式でeBayから提供され、ランダムに生成されリクエストに固有です。

通知トピックへの購読

ユーザーがコードと宛先エンドポイントをテストし、エンドポイントがeBayのチャレンジコードを処理して応答する準備ができていると確信したら、eBay通知トピックへの購読を確立できます。

createSubscription メソッドを使用して購読を作成します。購読により、アプリケーションとユーザーはビジネスに関連する情報を受信できます。

各アプリケーション/ユーザーとトピックのペアリングは、購読に対して1対1のカーディナリティを持つ必要があります。新しいバージョンの通知に対して新しい購読を作成し、新しいバージョンへの移行が完了したら、古い購読を削除できます。ユーザーは 無効 (disabled) モードで購読を作成してテストし（test メソッドを参照）、準備ができたら購読を 有効 (enable) にすることができます（enableSubscription メソッドを参照）。

新しい購読を作成する際は、購読のタイプに適したスコープを含めることが重要です：

• アプリケーションベースの購読の場合、以下のスコープを含め、クライアントクレデンシャル付与フローを使用してOAuthトークンを作成する必要があります：

  https://api.ebay.com/oauth/api_scope

• ユーザーベースの購読の場合、以下のスコープを含め、認可コード付与フローを使用してOAuthトークンを作成する必要があります：

  https://api.ebay.com/oauth/api_scope/commerce.notification.subscription

トピックの購読フィルタの作成

ユーザーがエンドポイント宛先を作成し、通知トピックを購読したら、購読に購読フィルタを追加できます。これにより、アプリケーションは提供された基準に一致する通知のみを受信し、一致しない通知は宛先に送信されません。

createSubscriptionFilter メソッドを使用して購読フィルタを作成します。購読フィルタが以下に準拠していることを確認してください：

• フィルタ要求は、ユーザーが所有する有効な購読に対するものである必要があります
• 購読はフィルタ可能なトピックに対するものである必要があります。トピックがフィルタ可能でない場合、フィルタは拒否され、DISABLED になり、195032 エラーコードが返されます
• 提供される filterSchema 値は有効な JSON Core document (バージョン 2020-12 以降) であり、購読の通知をフィルタリングするための有効な基準を提供するように購読の通知ペイロードを記述する必要があります。提供されたJSONがトピックの通知に存在しないフィールドを指定している場合、フィルタは拒否され、DISABLED になり、195033 エラーコードが返されます

eBayプッシュ通知の検証

eBay通知プラットフォームからHTTPプッシュ通知を受信するようにサインアップしたユーザーは、通知ペイロードとともに X-EBAY-SIGNATURE ヘッダーを含むプッシュ通知を受信します。このヘッダーは、以下の構造を使用するBase64エンコードされたパックヘッダーです：

{
"alg":"{_ECDSA_}",
"kid":"{_public key ID_}",
"signature":"{_signature_}",
"digest":"{_SHA1_}"
}

通知ペイロードとヘッダーを受信した後、ユーザーは通知が実際にeBayから来たものであることを確認する必要があります。通知は、Event Notification SDKを使用するか、以下に概説する手動検証手順を完了することで検証できます。

Event Notification SDKs

eBayは、各通知の有効性を検証するためのSDKを作成しました。

• Java SDK
• .NET SDK
• Node.js SDK
• PHP SDK
• Go SDK

手動検証

以下の手順を使用して、通知を手動で処理し、メッセージペイロードの整合性を検証できます：

1. Base64関数を使用して X-EBAY-SIGNATURE ヘッダーをデコードし、公開鍵IDと署名を取得します。
2. デコードされた署名ヘッダーから取得した公開鍵ID ("kid") を渡して、getPublicKey Notification APIメソッドを呼び出します。
3. getPublicKey メソッドから返された公開鍵を使用して検証を実行するために、暗号化ライブラリを初期化します。

API制限 (API restrictions)

以下のCommerce Notification APIイベントにはスコープ https://api.ebay.com/oauth/api_scope/buy.item.stream が必要であり、承認されたePNパートナーのみが利用できます。

• ITEM_AVAILABILITY
• ITEM_PRICE_REVISION