フックによるカスタマイズ

フックにより、Script API を使用して既存の Shopper API リソースの動作を変更したり拡張したりできます。

このページの一部のリンクにアクセスできるのは、既存のお客様のみです。Commerce Cloud リポジトリにアクセスする方法については Salesforce Commerce Cloud GitHub リポジトリとアクセスを参照してください。

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

リソースは、次のフックを提供できます。

before:カスタム検証 (検証したいアドレスを送信する場合など) に便利です。
after:たとえば、外部システムで検証して保持する必要がある支払情報を送信する場合など、データを変更する場合に便利です。
modifyResponse:応答に含まれる内容を変更できます。不要な属性や必要な追加の属性がある場合は、応答フックを使用して、外部システムから取得した内容を変更できます。

利用可能なフック

GET リクエストでは、before と modifyResponse のフックを使用できます。POST、PATCH、PUT、DELETE などのステータスを変更する HTTP メソッドでは、さらに after フックを使用できます。後者は、それに応じてデータベースへのトランザクションの書き込みも行います。

フックはすべての Shopper API に適用されるわけではありません。たとえば、Shopper Experience API を使用すれば、ページやコンポーネントタイプで独自のカスタマイズ機能を利用できます。

Hook Method Details (フック方法の詳細) には、使用可能なフックが含まれています。

Commerce API のフックを使用するには、まず Business Manager で B2C Commerce インスタンスのフックを有効にします。

管理 > グローバル環境設定 > 機能スイッチの順に移動し、Salesforce Commerce Cloud API フック実行の有効化にチェックを入れます。

有効にするには、インスタンスの Account Manager での役割が Business Manager Administrator でなければなりません。

package.jsonカートリッジの最上位ディレクトリにファイルを配置します。
package.json ファイルの hooks プロパティに、hooks.json 構成ファイルのパスを定義します。このパスは、ファイルを含むディレクトリからの相対パスですpackage.json。
hooks.jsonファイルで、ファイルからのhooks.json相対パスを持つスクリプトファイルへのフックのマッピングを含む配列を構成します。
サイト固有の使用の場合は、Business Manager で適切な各サイトにカートリッジを登録します。ライブラリなどすべてのサイトで組織レベルのリソースをカスタマイズするには、カートリッジを Business Manager サイトに登録します。

フックスクリプトは CommonJS モジュールとして読み込まれます。フック関数はエクスポートする必要があります。エクスポートされる名前は、パッケージ修飾なしで、フックの名前と一致する必要があります。たとえば、dw.ocapi.shop.basket.billing_address.beforePUTフックは次のようにbeforePUTエクスポートされます。

フックごとに、あなたのコード**はStatusサーバーにオブジェクトを返すことができます(MAY ** )。ステータスが OK の場合、サーバーは処理を続けます。ステータスERRORが処理された例外を表すの場合、サーバーはそれ以上の処理を停止し、トランザクションをロールバックして、 HTTP 400 Bad Request エラーで応答します。が発生するERRORと、サーバーは、エラーコード、メッセージ、オブジェクトからStatusの詳細などの情報を含むエラーを呼び出し元に返します。スローしたエラーを含め、コード内でキャッチされない例外は、HTTP 500 Internal Error エラーエラーの原因となります。この場合、サーバーはトランザクションをロールバックします。

値を返す Shopper API 拡張ポイントのフックは、フックのシステム実装と、その拡張ポイントの後続の登録済みフックをスキップします。フックのシステム実装と、拡張ポイントの後続の登録済みフックがスキップされないようにするには、Shopper API フックが何も返さず、買い物カゴ計算フックなどの重要な関数を実行できるようにすることをお勧めします。

カスタム拡張ポイントのフックは、戻り値に関係なく、登録されているすべてのフックポイントを常に実行します。

が発生するERRORと、サーバーは、エラーコード、メッセージ、オブジェクトからStatusの詳細などの情報を含む RFC IETF rfc7807** ErrorResponse **を呼び出し元に返します。

フックコードがオブジェクトをStatus返さない場合、オーバーライドされた基本実装を含め、複数の登録済みフックスクリプトが実行される可能性があります。Statusこれらのフックによって返されたオブジェクトまたは値が代わりに返されます。

1 つのリクエストで複数のフックを呼び出すことができます。たとえば、新しい支払手段を買い物カゴに追加すると、以下が呼び出されます。

dw.ocapi.shop.basket.payment_instrument.beforePOST
dw.ocapi.shop.basket.payment_instrument.afterPOST
dw.ocapi.shop.basket.payment_instrument.modifyPOSTResponse

フック間でデータを渡すには、request.custom .リクエストに追加された JavaScript オブジェクトは、後続のフックで使用できます。

たとえば、買い物カゴに新しい支払手段を追加するトランザクション内でサードパーティの支払処理業者を呼び出すには、フック内でdw.ocapi.shop.basket.payment_instrument.afterPOSTこの呼び出しを行うことができます(エラーがトランザクションをロールバックするようにするため)。決済サービスプロバイダーを呼び出して支払いリクエストを初期化した後、フックでdw.ocapi.shop.basket.payment_instrument.modifyPOSTResponse関連データをクライアントに返すことができます。これを行うには、フックでmodifyPOSTResponse処理するコンテナにrequest.custom関連データを追加します。

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

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

Calculate フックを使用すると、dw.order.calculateカスタマイズされた買い物カゴ計算ロジックを実装できます。これは、買い物カゴの計算と再計算を 1 か所で行うために使用できます。このフックはデフォルトの実装を提供し、オーバーライドできます。

次のフックの既定のロジックは、このフックを暗黙的に呼び出します。

dw.ocapi.baskets.actions.afterMerge
dw.ocapi.baskets.actions.afterTransfer
dw.ocapi.shop.basket.afterPATCH
dw.ocapi.shop.basket.afterPOST
dw.ocapi.shop.basket.agent.afterPUT
dw.ocapi.shop.basket.billing_address.afterPUT
dw.ocapi.shop.basket.coupon.afterDELETE
dw.ocapi.shop.basket.coupon.afterPOST
dw.ocapi.shop.basket.customer.afterPUT
dw.ocapi.shop.basket.gift_certificate_item.afterDELETE
dw.ocapi.shop.basket.gift_certificate_item.afterPATCH
dw.ocapi.shop.basket.gift_certificate_item.afterPOST
dw.ocapi.shop.basket.item.afterDELETE
dw.ocapi.shop.basket.item.afterPATCH
dw.ocapi.shop.basket.items.afterPOST
dw.ocapi.shop.basket.payment_instrument.afterDELETE
dw.ocapi.shop.basket.payment_instrument.afterPATCH
dw.ocapi.shop.basket.payment_instrument.afterPOST
dw.ocapi.shop.basket.price_adjustment.afterDELETE
dw.ocapi.shop.basket.price_adjustment.afterPATCH
dw.ocapi.shop.basket.price_adjustment.afterPOST
dw.ocapi.shop.basket.reference.afterPOST
dw.ocapi.shop.basket.shipment.afterDELETE
dw.ocapi.shop.basket.shipment.afterPATCH
dw.ocapi.shop.basket.shipment.afterPOST
dw.ocapi.shop.basket.shipment.shipping_address.afterPUT
dw.ocapi.shop.basket.shipment.shipping_method.afterPUT
dw.ocapi.shop.basket.storefront.afterPUT
dw.ocapi.shop.order.beforePOST
dw.ocapi.shop.order.beforePUT

次のコードスニペットはサンプルの呼び出しを示します:

このサンプルの呼び出しでは、パラメーターは次のとおりです:

"dw.order.calculate" - 呼び出す拡張ポイント
"calculate" - 呼び出すスクリプト関数
basket - 計算される買い物カゴ

SiteGenesis では、買い物カゴ計算ロジックに dw.order.calculate フックのデフォルト実装が使用されます。

B2C Commerce API (SCAPI) でのフックの使用は OCAPI でのフックの使用と似ていますが、デベロッパーが注意しなければならない違いがあります。フックを有効にして維持すると、* SCAPI と関連する OCAPI エンドポイントの両方に対して同じフック*が呼び出されるため、両方に使用するフックを記述できます。これは、両方の API フレームワークをクライアントアプリケーションに使用する場合に重要です。

SCAPI や OCAPI の用途を判断する場合、request.isSCAPI() を使用します。特に、すでにコントローラーのコンテキストで計算フックを使用していて、そのフックでトランザクションを使用すると、SCAPI が破損してしまいます。

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

SCAPI は、診断と情報提供の目的で、カスタムの HTTP 要求ヘッダーと応答ヘッダーをサポートしています。

カスタムヘッダーには、先頭に . c_を付ける必要があります。
カスタムヘッダーはキャッシュキーの構築時に考慮されないため、条件付き動作を実装するためにカスタムヘッダーを使用しないでください。詳細については、「サーバー側の Web 層キャッシュ」を参照してください。
カスタム要求ヘッダーは、応答本文に影響を与える方法で使用しないでください。カスタムヘッダーは、ログ記録などの診断または情報提供のみを目的としています。

次の例では、要求ヘッダーに欠落している必須パラメーター値のエラーメッセージをログに記録します。

次の例は、サンプルのカスタム応答ヘッダーを示しています。

SCAPI および OCAPI フックを使用して、エラーを解析および処理するカスタム検証ロジックを実装できます。

たとえば、フックを使用して配送先住所のカスタム検証を追加するには、次のようにします。

クライアントが解析して使用できる詳細をエラーに追加するために使用しますStatus.addDetail(key, value)。詳細については、「クラスのステータス」を参照してください。

が false の場合isValidAddress、SCAPI はコンテンツタイプが次の HTTP 400 応答を返します。application/problem+json

フックが未処理の例外またはエラー (ネットワークエラー、コード構文エラー) を発生させた場合、HTTP 500 応答が返されます。

フックサーキットブレーカーは、過度のフック実行の失敗からシステムを保護します。フックが生成するエラーが多すぎると、サーキットブレーカーがアクティブになり、HTTP 503 応答が返されます。

詳細については、フックのサーキットブレーカーを参照してください。

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

タイムアウトが 30 秒の Shopper Products を除き、すべての Shopper API のタイムアウトは 10 秒です。この時間より長い時間が経過すると、応答はエラーを返します。

modifyResponse フックは、アプリケーションのニーズに最適なレスポンスを作成するための強力な手段です。オブジェクトに情報を追加したり、UI で使いやすいプロパティセットを提供することで、クライアントアプリケーションでの消費を改善できます。

追加のプロパティは、カスタムプロパティ (c_ プロパティ) としてのみ追加します。

SCAPI フックを使用するエンドポイントのキャッシュを有効にすると、フックロジックがアプリケーションサーバーによって実行され、結果がキャッシュされます。アプリケーション・サーバー・ロジックもカスタム・フック・ロジックも、オブジェクトがキャッシュから期限切れになるまで再実行されません。詳細については、サーバー側の Web 層キャッシュを参照してください。

B2C Commerce バックエンドに組み込まれている買い物カゴ計算は、買い物カゴ情報の決定に有効です。SCAPI エンドポイントを使用すると、買い物カゴの税務情報を操作できます。

B2C Commerce 24.5 では、フックが有効な場合、以下のエンドポイントがサポートされます。

/checkout/baskets/{}/taxes
/checkout/orders/{}/taxes
/checkout/baskets/{}/items/{}/taxes

以下の Script API メソッドを使用して、フックで SCAPI 外部課税 API をサポートできます。

dw.order.LineItemCtnr#isExternallyTaxed:true買い物カゴtaxMode = externalが .
dw.order.TaxMgr#applyExternalTax:指定された買い物カゴに外部で設定された税率を適用します。dw.order.LineItemCtnr#isExternallyTaxedが返された場合trueに使用します。

次のエンドポイントは、フックが有効な状態ではサポートされません。フックを有効にしてこのエンドポイントを呼び出すと、リクエストから HTTP 409エラーレスポンスが返されます。

/checkout/baskets/{basketId}/price-books