フックによる拡張性

多くの Shopper API リソースは フック を通して拡張できます。フックを使用すると、Script API を使用して動作を拡張できます。

Script API について詳しくは、以下のドキュメントを参照してください。

フックは、デベロッパーがカスタムの B2C Commerce スクリプトコードでサーバー側のシステムロジックを強化するために使用します。カスタマイズ可能な各リソースには、beforeaftermodifyResponse の拡張ポイントが用意されています。拡張ポイント beforeafter をそれぞれ使用し、サーバーが処理を実行する前または後にカスタムコードを実行します。レスポンスドキュメントに最終変更を適用するには、modifyResponse 拡張ポイントを使用します。さらに、特殊なコンビニエンスフックを使用すると、買い物カゴの計算や特殊な注文手続き手順などの操作を実行できます。これらのコンビニエンスフックを使用すると、複数の after 拡張ポイントに重複するコードを含めなくても、買い物カゴ計算コードを 1 つの場所に配置できます。

  • before<HTTP_Method>
  • after<HTTP_Method>
  • modify<HTTP_Method>Response

利用可能なフック

GET リクエストでは、before-HooksmodifyResponse-Hooks を使用できます。POST、PATCH、PUT、DELETE フックではさらに after-Hooks を使用できます。後者は、それに応じてデータベースへのトランザクションの書き込みも行います。

代表的なユースケースには以下のものがあります。

  • before-Hooks: API 実行のための追加のフィルター条件を定義し、PATCH リクエストの前に特定のステータスチェックを実行します。
  • after-Hooks: サービスロジックの後に情報を追加して、手順を完了する方法を示し (支払方法のステータスを設定するなど)、サードパーティのシステムと統合します (発注など)。
  • modifyResponse-Hooks: オブジェクトに情報を追加して結果セットを拡張し (追加の商品詳細情報など)、不要なプロパティの結果セットをクリーンアップします。

フックは、買い物カゴ、注文、商品、カタログ、顧客、価格設定とプロモーション、検索など、すべてのコマース領域で使用できます。

新しい SCAPI エンドポイントが作成されたときには、カスタマイズできるフックが用意されます (買い物カゴのマージと転送のエンドポイント用のフックなど)。

該当するフックから SCAPI へのエンドポイントはフックリストで確認してください。

Commerce API のフックを使用するには、使用する eCom インスタンスごとに Business Manager で機能を有効にする必要があります。管理 > グローバル環境設定 > 機能スイッチの順に移動し、Salesforce Commerce API フック実行の有効化の機能スイッチにチェックを入れます。

機能スイッチを設定するには、Account Manager のユーザープロフィールに割り当てられたインスタンスに、「Business Manager Administrator」の Account Manager 役割が構成されている必要があります。

機能スイッチ

  1. スクリプトカートリッジの最上位ディレクトリに package.json ファイルを配置します。
  2. package.json ファイルの hooks プロパティに、hooks.json 構成ファイルのパスを定義します。このパスは、package.json ファイルを含むディレクトリの相対パスです。
  3. hooks.json ファイルに、フックからそのスクリプトファイルへのマッピングを示す配列を構成します。

    このパスは、hooks.json ファイルが配置されているディレクトリの相対パスです。

  4. サイト固有の用途の場合、Business Manager の適切なサイトにカートリッジを登録します。ライブラリなど、組織レベルのリソースを すべての サイト間でカスタマイズするには、組織レベルでカートリッジを Business Manager サイトに登録する必要があります。

フックスクリプトは CommonJS モジュールとして読み込まれます。すべてのフック関数をエクスポートする必要があります。エクスポートされた名前は、パッケージ修飾子なしの拡張ポイント関数名と同じである必要があります。たとえば、dw.ocapi.shop.basket.billing_address.beforePUT 拡張ポイントは beforePUT としてエクスポートされます。

Salesforce Commerce API でのフックの使用は、OCAPI でのフックの使用と似ていますが、違いもあるため、デベロッパーは注意する必要があります。フックを有効にして維持する場合、同じフック が SCAPI および関連する OCAPI エンドポイントの両方で呼び出されることに注意してください。これは、両方の API フレームワークをクライアントアプリケーションに使用する場合に重要です。

SCAPI で有効化されたフックは、引き続き SCAPI エンドポイントのタイムアウト定義に従って実行されます。フックの実行にかかる時間は全体の処理時間およびフックの実行を加えたレスポンス全体に加算されますが、フック実行は引き続きタイムアウト時間内に完了する必要があります。

すべての Shopper API は 10 秒のタイムアウトをもちます。例外 として、Shopper-Products エンドポイントのタイムアウトは 30 秒です。

SCAPI の利点の 1 つは、コントラクトベースで API を定義できることです。これにより、SCAPI からのレスポンスが予測可能になり、ドキュメント化でき、SCAPI 用の SDK を利用できます。

modifyResponse フックは、アプリケーションのニーズに最適なレスポンスを作成するための強力な手段です。オブジェクトに情報を追加したり、UI で使いやすいプロパティセットを提供することで、クライアントアプリケーションでの消費を改善できます。ただし、レスポンスの変更は、確立された API コントラクトの範囲内で行う必要があります。

modifyResponse フックを使用する際には、以下を念頭に置いてください。

  • 追加のプロパティは、カスタムプロパティ (c_ プロパティ) としてのみ追加します。
  • その他の変更 (プロパティの削除や変更) は、API コントラクトの範囲内でしか行ってはなりません。

SCAPI のフックが有効になると、B2C Commerce のバックエンドに組み込まれた買い物カゴの計算が、買い物カゴ情報の決定に反映されるようになります。SCAPI には、 (フックなしで) 買い物カゴの税金情報を操作できるようにするために専用に作成されたエンドポイントがあります。

  • /checkout/baskets/{}/taxes
  • /checkout/orders/{}/taxes
  • /checkout/baskets/{}/items/{}/taxes
  • /checkout/baskets/{basketId}/price-books

これらのエンドポイントは、フックを有効にすると動作しなくなります。これらのエンドポイントを呼び出すと、リクエストから HTTP 409 エラーレスポンスが返されます。

フックロジックを作成する際には、フックを呼び出す API のコンテキストを念頭に置くことが重要です。OCAPI と SCAPI は同じフックを共有しているため、その両方に使用するフックを作成することが可能です。SCAPI や OCAPI の用途を判断する場合、request.isSCAPI() を使用します。特に、すでにコントローラーのコンテキストで計算フックを使用していて、そのフックでトランザクションを使用すると、SCAPI が破損してしまいます。

条件付き動作をフックに追加するには、カスタムクエリ文字列パラメーターを使用します。パラメーターには、c_ という接頭辞を付ける必要があります。

ヘッダー値はリソースのキャッシュキーの構築には使用されないため、条件付き動作に HTTP ヘッダーを使用しないでください。

フックの処理中にエラーが発生すると、リクエストは失敗します。フックエラーは Log Center で追跡できます。検索は、LCQL クエリ category: ( com.demandware.wapi.servlet.ShopRestServlet ) AND stackTrace: ( HookInvocationException ) を使用して構成します。

Salesforce のコミュニティでは、顧客との多数のプロジェクトを通して、機能を拡張したり、新しい機能を提供したりするための、多くの有用な実装をもつフックコレクションが管理されています。コミュニティコレクションのフックは、実用的なユースケースを幅広くカバーしています。コレクションに含まれる SCAPI 対応フックには以下のものがあります。

  • Order-Hooks
  • OrderPaymentInstruments-Hooks
  • Search-Hooks
  • Basket-Hooks
  • BasketPayments-Hooks

詳細については、Salesforce Commerce Cloud GitHub リポジトリの OCAPI Hooks Collection (OCAPI フックコレクション) を参照してください。

OCAPI Hooks Collection GitHub リポジトリは、オープンソースではありません。これは、Salesforce Commerce Cloud の顧客用プライベートリポジトリコレクションの一部です。リポジトリにアクセスできない場合は、Salesforce B2C Commerce Infocenter の Salesforce Commerce Cloud GitHub Repositories and Access (Salesforce Commerce Cloud GitHub リポジトリとアクセス) のドキュメントを参照してください。