OCAPI カスタマイズ 23.1

Customer や Basket リソースなど、サーバー側で変更を行う Shop API リソースをカスタマイズできます。これらのリソースは、独自のスクリプトコードでサーバー側のロジックを強化できる拡張ポイント、あるいはフックを提供します。

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

拡張ポイントとサポートされているリソースについての詳細は、Data API 23.1 の OCAPI フックと Shop API 23.1 の OCAPI フックを参照してください。

13.6 以前では、サーバーは、リソース変更のリクエストを受け取ると、そのリソースを直接変更し、次に呼び出し元に直接レスポンスを送信していました。13.6 以降、独自のカスタムコードを使用してサーバー側の基本的な処理を強化できるようになりました。以下が処理フローです:

Shop API - カスタマイズ - 詳細

処理ステップコメント
サーバーがリソース変更のリクエストを受信リソースを直接変更する代わりに、サーバーは登録済みの before 拡張ポイントを確認します。
サーバーが登録済みの before 拡張ポイントコードを呼び出すサーバーがリクエストドキュメントと Script API オブジェクト (変更されるリソースを表す) を渡します。カスタムコードで両方を操作できますが、通常リクエストドキュメントで入力の検証が行われます。
サーバーがリソースを変更サーバーは、before 拡張ポイントで処理されたリクエストドキュメントを使用して、Script API オブジェクトに適用します。
サーバーが登録済みの after 拡張ポイントコードを呼び出すサーバーは、(before 拡張ポイントによる変更が行われた後) リクエストドキュメントと Script API オブジェクトを渡します。ここでカスタムコードで変更の追跡を行うか、Script API オブジェクトを変更できます。たとえば、買い物カゴを再計算できます。リクエストドキュメントは再処理されないため変更しないでください。ここでは通知の目的で提供されています。
サーバーがレスポンスドキュメントを作成するサーバーは、(afterafter 拡張ポイントによる変更が行われた後) Script API オブジェクトの値をレスポンスドキュメントにコピーします。
サーバーが登録済みの modifyResponse 拡張ポイントコードを呼び出すサーバーは、(after 拡張ポイントによる変更が行われた後) 前のレスポンスドキュメントと Script API オブジェクトを渡します。このフックタイプは、レスポンスドキュメントに最終変更を加えることのみを目的としています。このフックタイプで Script API オブジェクトを変更しないでください。これはトランザクションコンテキストで実行されないためです。変更すると、ORMTransactionException および HTTP 500 フォールトを引き起こします。
サーバーが呼び出し元にレスポンスを送信サーバーは、(after 拡張ポイントによる変更が行われた後) リクエストされた形式でレスポンスドキュメントを表示します。次に、サーバーは呼び出し元にレスポンスを返します。

状態を変更する HTTP メソッド (DELETE、PATCH、POST、PUT) の場合、サーバーはデータベーストランザクションのコンテキストで before および after のフックロジックと、システムロジックを実行します。このトランザクションによって、データベースにすべてがコミットされること (あるいは何もコミットされないこと) が保証されます。

HTTP GET リクエストまたは modifyResponse で Script API オブジェクトを変更しないでください。これはトランザクションコンテキストで実行されないためです。変更すると、ORMTransactionException および HTTP 500 フォールトレスポンスを引き起こします。

各拡張ポイントで、カスタムコードは Status オブジェクトをサーバーに返す必要があります。ステータスが OK の場合、サーバーは処理を続けます。ステータスが ERROR の場合 (処理された例外を表す) は、サーバーはすべての処理を中断し、HTTP 400 (Bad Request) フォールトのレスポンスを返します。ERROR が発生した場合、サーバーは OCAPI フォールトを呼び出し元に返します。これには、エラーコード、メッセージ、Status オブジェクトの詳細といった情報が含まれます。キャッチされないスクリプト例外がカスタムコードにあると、HTTP 500 (Internal Error) フォールトが発生します。この場合、サーバーはすべてのトランザクションをロールバックします。

18.3 以降、 レスポンス変更カスタマイズフックが Shop API で使用できるようになりました。このフックは、POST、PUT、PATCH、および GET の各メソッドをサポートし、以前の afterGET フックを置換します。

レスポンス変更フックには、次のような特徴があります:

  • カスタム情報でレスポンスドキュメントを強化するために、GET、POST、PUT、および PATCH メソッドをサポート。
  • カスタマイズコードを使用して、ドキュメント属性の変更と設定解除を行い、返されたドキュメントでカスタム属性の追加、削除、および変更が可能。
  • カスタマイズされたスクリプトコード内でのデータベーストランザクションを禁止し、コードが永続的データを変更できないようにする。
  • キャッシングがある場合、キャッシュが空または古い場合にのみキャッシングを実行。ただし、毎回の GET や HEAD の呼び出しでは実行されません。

次の例は、Shop API カテゴリメソッドのカスタマイズスクリプトコードを示します:

拡張ポイントの登録は、モジュールや package.json のように CommonJS 機能で構築されます。 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 としてエクスポートされます。

フックのサーキットブレーカー機能は、フックスクリプト実行の障害が過剰になったときにシステムを保護します。詳細については、フックのサーキットブレーカーを参照してください。

Calculate フック (dw.order.calculate) によって、カスタマイズした買い物カゴ計算ロジックを実装できます。これは、買い物カゴの計算と再計算を 1 か所で行うために使用できます。このフックはデフォルトの実装を提供しますが、これはいつでも上書きできます。次のフックのデフォルトのロジックで、暗黙的にこのフックを呼び出します:

  • 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

計算 (買い物カゴ: Basket): ステータス

リクエストで送信された買い物カゴを計算 (または再計算) します。

dw.order.calculate 拡張ポイントでこの関数を呼び出します。

パラメーター:

basket - 計算 (または再計算) される買い物カゴドキュメント
戻り値:

null 以外の Status (ステータス) によってフックの実行が終了します

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

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

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

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