Add the #DF24 Developer Keynote to your agenda. Join us in-person on 9/18 at 2:30 p.m. PT or on Salesforce+ at 5 p.m. PT for the must-see session built just for developers.

カスタム API

B2C Commerce には、買い物客の体験をカスタマイズするための強力なツールが用意されています。現在、SCAPI はフックを使用してカスタマイズでき、開発者は B2C Commerce Script APIを使用してフィルターを追加したり、応答を変更したりしてから、呼び出し元のアプリケーションに送り返すことができます。

既存の開発ツールをさらに活用するために、開発者がコントローラーなどのカスタムスクリプトコードを作成し、この機能を SCAPI フレームワークの下でカスタム* REST API *として公開できるフレームワークが提供されるようになりました。

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

カスタム API URL の構造形式は次のとおりです。

https://{shortCode}.api.commercecloud.salesforce.com/custom/{apiName}/{apiVersion}/organizations/{organizationId}/{endpointPath}

この用語customは API ファミリとして使用する必要があります。パラメータapiName , apiVersion , , は、以下endpointPathで説明するように定義できます。

カスタム API を作成するには、次の 3 つのコンポーネントが必須です。

OAS 3.0スキーマファイルとしての API コントラクト。
B2C Commerce Script API を使用したスクリプトとしての API 実装。
ファイルで定義されているapi.json API マッピング。

このガイドでは、特定の顧客のロイヤルティステータスを取得するために使用できるロイヤルティ情報 API と呼ばれる例を見ていきます。以下の図は、必要なコンポーネントとその関係を示しています。

関連ダイアグラム

コンポーネントについては、次のセクションで詳しく説明します。今のところ、図の次の詳細に注意してください。

破線は、この URL セグメントが定義されている場所を示しています。
青色のパラメータはエンドポイント識別子です。これは、エンドポイントを実装にバインドするために使用され、3 つのコンポーネントすべてに表示されます。

カスタム API はカスタムコードカートリッジ内で定義されます。cartridge ディレクトリに、そのカートリッジ内のすべての API のルートフォルダーである rest-apis という新規フォルダーを作成する必要があります。

rest-apis フォルダーのサブディレクトリは、実際の API を表します。これらのディレクトリ名は、URL によってアドレス指定される API 名を表します。各ディレクトリには、この API を表す 3 つのコンポーネントのファイルが含まれています。

**例:**呼び出されるloyalty-info API の例の構造は、次のようになります。

API ディレクトリ名に使用できるのは、英数字、小文字、ハイフンのみです。

登録プロセスのため、新しいコードのバージョンでカスタム API エンドポイントの実装を開始することをおすすめします。

API コントラクトは、YAML 形式の OAS 3.0 スキーマファイルによって提供する必要があります。OAS 3.0 について詳しくは、OAS 3.0 仕様を参照してください。

このスキーマファイルでは、API バージョンと エンドポイント が定義されます。API バージョンは info.version フィールドにあり、メジャーバージョンのセグメントを使用して先頭に v を追加することで URL バージョンに変換されます (例: 1.0.1 → v1)。

エンドポイントはオブジェクトの一部としてpaths定義され、複数の操作 (HTTP メソッドなど) を実装できます。各操作には、というoperationIdプロパティが必要です。このプロパティは、スキーマファイル内で一意である必要があります。このプロパティはエンドポイントを実装にマッピングするために使用されます。エンドポイントの path は、URL 構造の endpointPath になります。

エンドポイントを保護するには、共有コンポーネントで有効なセキュリティスキームを定義し、エンドポイントまたはグローバルレベルで適用する必要があります。詳細については、認証を参照してください。

例: バージョン v1 の /customers?c_customer_id={id} エンドポイントのスキーマは、次のようになると予想されます。

API 実装は、B2C Commerce Script API を使用するスクリプトファイルによって提供されます。機能名は、コントラクト内のエンドポイントの operationId の値と一致する 必要があり ます。

例: コントラクトの定義に基づいた /customers?c_customer_id={id} の有効な実装は次のようになります。

レスポンスは、常に JSON 形式で返すことを強く推奨します。さらに、エラーは RFC 9457に記述されている SCAPI エラー形式に準拠し、少なくともtypeフィールドが存在する必要があります。回答機関は今後検証の対象となり、これらの要件を満たさない場合は拒否される可能性があります。

実装に、十分なエラー処理を備えた高品質で十分にテストされたコードが含まれていることを確認してください。プラットフォームを保護するために、カスタム API は、実装がスローするエラーが多すぎる場合に API 要求をブロックするサーキットブレーカーメカニズムを使用します。詳細については、サーキットブレーカーを参照してください。

スクリプトで JSON レスポンスを簡単に作成する方法については、 Script API クラスのRESTResponseMgrドキュメントを参照してください。

API マッピングは、api.json ファイルで提供されます。このファイルにはエンドポイントのリストが含まれており、各エントリに対してエンドポイント名、そのスキーマファイル、および実装スクリプト名が定義されています。

例: コントラクトと実装の定義に基づいた /customers?c_customer_id={id} の有効なマッピングは、次のようになると予想されます。

相対パスはサポートされていません。スキーマと実装は、対応する api.json と同じレベルに配置する必要があります。

実装名はファイル拡張子を付けずに指定してください。

カスタム API エンドポイントを前述のように正しく定義したら、アクセスできるようにするために登録する必要があります。

登録は、新しい API 定義を含むコード・バージョンをアクティブ化することによってトリガーされます。API の変更が必要な場合は、新しいコードのバージョンで作業をし、準備が完了した時点でバージョンを切り替えることを推奨します。

カスタム API のバージョンは、API バージョン と URL バージョン という異なる 2 つの形式で表されます。

API バージョンはコントラクト内で info.version フィールドの一部として定義され、このファイルで定義されたすべてのエンドポイントに適用されます。値は数値である必要がありますが、ドットで区切られた複数のセグメントを含めることもできます。

URL では、バージョンはメジャーバージョンのセグメントを使用し、先頭に v を追加することによって変換されます。たとえば、次のリストは有効な API バージョンと、それに対応する URL バージョンを示しています。

1 → v1
1.0 → v1
2.0 → v2
2.1.1 → v2

破壊的変更 (breaking change) は、新規のメジャーバージョンで導入することを推奨します。詳細については、SCAPI の変更ポリシーのセクションを参照してください。

カスタム API でサポートされているメソッドは次のとおりです。

B2C Commerce 24.4 では:

POST
PUT
PATCH
削除
HEAD
OPTIONS

次の例では、ロイヤルティ情報 API を POST メソッドで拡張し、ロイヤルティ情報を更新します。

このエンドポイントの実装例を次に示します。

前の例では、path パラメーターcustomerIdは、object の新しいRequest Script API メソッドgetSCAPIPathParametersを使用して簡単に取得できます。httpParameterMap要求本文を文字列として提供し、それをに解析jsonObjectします。RESTResponseMgrからの応答jsonObjectを構築します。

SCAPI パス解析の新しい便利なメソッドの詳細については、「Script API」のクラスを参照してくださいRequest。

この属性additionalPropertiesは、要求本文スキーマを定義するときには許可されません。要求本文の検証を利用し、堅牢な API を構築するには、要求本文スキーマを詳細に定義します。エンドポイントadditionalPropertiesの要求本文スキーマにが含まれている場合、エンドポイントは登録されません。

コントラクトで定義されている場合、次のシステムクエリパラメーターは存在し、使用できます。

siteId - 現在のリクエストのサイト
locale - 現在のリクエストの地域情報

これらのパラメーターの意味と使用する状況を把握しておいてください。siteId は、サイトのコンテキストを識別するために使用され、システムではそのように処理されます。したがって、このパラメーターは、買い物客コンテキストで使用する場合にのみ意味があります。サイトを必要とするマーチャントコンテキスト (たとえば、サイトでフィルタリングされたオブジェクトを返す API) では、c_siteId などのカスタムクエリパラメーターを使用します。さらに、サイトがパスパラメーターではなくクエリパラメーターであることも重要です。これは、コントローラーやフックを使用するなどの、他のカスタマイズ方法とは異なるためです。パラメーター locale はリクエストの地域情報を設定するために使用され、Script API メソッド dw.system.Request#setLocale と同じように動作します。

を指定しsiteIdない場合は、デフォルトで Business Manager サイトが使用されます。また、がlocaleリクエストに存在しない場合は、デフォルトでサイトのデフォルトの地域情報が設定されます。

このパラメーターsiteIdは、カスタム API の登録にも使用されます。つまり、カスタム API を含むカートリッジがサイトのカートリッジパスに追加されていない場合、それsiteIdを含むリクエストは応答になります404。

また、Business Manager サイトコンテキストでは買い物客トークンを使用できません。このようなシナリオでは、AmOAuth2トークンを使用する必要があります。

例 1: 名前 siteId とタイプ string を使用してシステムクエリパラメーターを定義します。パラメーターが有効な文字列でない場合、リクエストは拒否されます。

例 2: 名前 locale とタイプ string を使用してシステムクエリパラメーターを定義します。パラメーターが有効な文字列でない場合、リクエストは拒否されます。

例 3: システムクエリパラメーターを使用してカスタム API リクエストを作成します。

システムクエリパラメータは、上記のように正しいschemaフィールドで定義する必要があります。to falseに設定するrequiredと、値は省略可能ですが、trueパラメーターが欠落しているか空の場合、要求は拒否されます。

不明なパラメータを持つ要求は拒否されるため、すべての要求パラメータをコントラクトで定義する必要があります。カスタムクエリパラメーターには、c_ という接頭辞を付ける必要があります。システムクエリパラメーターを使用する場合は、コントラクトに追加する必要があります。

例: 名前 c_status とタイプ integer を使用して必須のクエリパラメーターを定義します。パラメーターが存在しない、または有効な整数ではない場合、リクエストは拒否されます。

このリポジトリにアクセスするには、Trail Tools & Resources for Salesforce B2C Commerce Developers (Salesforce B2C Commerce デベロッパー用のツールとリソース) を完了してください。

私たちのコミュニティは、サンプルフックコレクション内のカスタム API コレクションを維持しており、以前にフックで提供されていた機能を新しいカスタム API として提供しています。このコレクションで使用できる API をいくつか次に示します。

URL Resolution (URL 解決)
URL List (URL リスト) API
Guest Order Look Up (ゲスト注文検索)
Customer Groups (顧客グループ) API
Mini Product (ミニ商品)
Send Mail (メール送信) API
Geo IP API

詳細については、Salesforce Commerce Cloud GitHub リポジトリのCustom APIs Collection (カスタム API コレクション) を参照してください。

以下の制限があります。

リクエストの最大実行時間は 10 秒。
GET リクエストの場合、トランザクションはコミット不可。
カスタム API 要求にはアクティビティの種類がありますSTOREFRONT。実装は、Storefront に対応する API クォータに従う必要があります。詳細については、API クォータのドキュメントを参照してください。