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 のフックロジックと、システムロジックを実行します。このトランザクションによって、データベースにすべてがコミットされること (あるいは何もコミットされないこと) が保証されます。
Note
HTTP GET リクエストまたは modifyResponse で Script API オブジェクトを変更しないでください。これはトランザクションコンテキストで実行されないためです。変更すると、ORMTransactionException および HTTP 500 フォールトレスポンスを引き起こします。
Note
各拡張ポイントで、カスタムコードは Status オブジェクトをサーバーに返す必要があります。ステータスが OK の場合、サーバーは処理を続けます。ステータスが ERROR の場合 (処理された例外を表す) は、サーバーはすべての処理を中断し、HTTP 400 (Bad Request) フォールトのレスポンスを返します。ERROR が発生した場合、サーバーは OCAPI フォールトを呼び出し元に返します。これには、エラーコード、メッセージ、Status オブジェクトの詳細といった情報が含まれます。キャッチされないスクリプト例外がカスタムコードにあると、HTTP 500 (Internal Error) フォールトが発生します。この場合、サーバーはすべてのトランザクションをロールバックします。
18.3 以降、
レスポンス変更フックには、次のような特徴があります:
次の例は、Shop API カテゴリメソッドのカスタマイズスクリプトコードを示します:
1importPackage(dw.system);
2
3exports.modifyGETResponse = function (scriptCategory, categoryWO) {
4 if (!scriptCategory.online) {
5 categoryWO.c_modify_response_data = "modifyResponseData";
6 }
7
8 return new Status(Status.OK);
9};拡張ポイントの登録は、モジュールや package.json のように CommonJS 機能で構築されます。 package.json ファイルを作成して拡張ポイントを静的に登録します。このファイルは、カートリッジのトップレベルのディレクトリに配置する必要があります。package.json ファイルの hooks プロパティに、hooks.json 構成ファイルのパスを定義します。このパスは、package.json ファイルを含むディレクトリの相対パスです。
1{
2 ...
3 "hooks": "./cartridge/scripts/hooks.json"
4}hooks.json ファイルには、拡張ポイント名からスクリプトファイルへのマッピングを含む配列が含まれます。相対パスでスクリプトファイルを参照します。このパスは、hooks.json ファイルが配置されているディレクトリの相対パスです。
1{
2 "hooks": [
3 {
4 "name" : "dw.ocapi.shop.basket.billing_address.beforePUT",
5 "script" : "./basket_hook_scripts.js"
6 },
7 ...
8 ]
9}Business Manager の適切なサイトにカートリッジを登録します。ライブラリなど組織レベルのリソースをカスタマイズするには、カートリッジを Business Manager サイトに登録します。
拡張ポイント (またはフック) スクリプトは CommonJS モジュールとして読み込まれます。すべてのフック関数をエクスポートする必要があります。エクスポートされた名前は、パッケージ修飾子なしの拡張ポイント関数名と同じである必要があります。たとえば、dw.ocapi.shop.basket.billing_address.beforePUT 拡張ポイントは beforePUT としてエクスポートされます。
1/* basket_hook_scripts.js */
2
3importPackage( dw.order );
4importPackage( dw.system );
5
6exports.beforePUT = function(basket,doc)
7{
8 // verify address
9 ...
10
11 if( valid )
12 {
13 doc.companyName="Salesforce";
14 return new Status(Status.OK);
15 }
16
17 return new Status(Status.ERROR);
18}
19
20exports.afterPUT = function(basket,doc)
21{
22 // calculate basket by calling the convenience hook, which returns a status object
23 return dw.system.HookMgr.callHook( "dw.order.calculate", "calculate", basket );
24}
25
26exports.calculate = function(basket)
27{
28 // do calculation
29 ...
30
31 return new Status(Status.OK);
32}フックのサーキットブレーカー機能は、フックスクリプト実行の障害が過剰になったときにシステムを保護します。詳細については、フックのサーキットブレーカーを参照してください。
Calculate フック (dw.order.calculate) によって、カスタマイズした買い物カゴ計算ロジックを実装できます。これは、買い物カゴの計算と再計算を 1 か所で行うために使用できます。このフックはデフォルトの実装を提供しますが、これはいつでも上書きできます。次のフックのデフォルトのロジックで、暗黙的にこのフックを呼び出します:
以下の表で、このフックでどのようにカスタマイズがサポートされているかを示します:
| 拡張ポイント | メソッドの詳細 |
|---|---|
dw.order.calculate | リクエストで送信された買い物カゴを計算 (または再計算) します。
basket - 計算 (または再計算) される買い物カゴドキュメント null 以外の Status (ステータス) によってフックの実行が終了します |
1dw.system.HookMgr.callHook("dw.order.calculate", "calculate", basket);このサンプルの呼び出しでは、パラメーターは次のとおりです:
"dw.order.calculate" - 呼び出す拡張ポイントbasket - 計算される買い物カゴSiteGenesis では、買い物カゴ計算ロジックに dw.order.calculate フックのデフォルト実装が使用されます。
Note
j