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 以降、独自のカスタムコードを使用してサーバー側の基本的な処理を強化できるようになりました。以下が処理フローです:
処理ステップ | コメント |
---|---|
サーバーがリソース変更のリクエストを受信 | リソースを直接変更する代わりに、サーバーは登録済みの 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 以降、
レスポンス変更フックには、次のような特徴があります:
- カスタム情報でレスポンスドキュメントを強化するために、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 - 計算 (または再計算) される買い物カゴドキュメント null 以外の Status (ステータス) によってフックの実行が終了します |
このサンプルの呼び出しでは、パラメーターは次のとおりです:
"dw.order.calculate"
- 呼び出す拡張ポイント- "calculate" - 呼び出すスクリプト関数
basket
- 計算される買い物カゴ
SiteGenesis では、買い物カゴ計算ロジックに dw.order.calculate
フックのデフォルト実装が使用されます。