カスタム API

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

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

カスタム 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 コントラクトは、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} の有効な実装は次のようになります。

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

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

カスタム 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 でサポートされているメソッドは次のとおりです。

• GET

B2C Commerce 24.4 では:

• POST
• PUT
• PATCH
• 削除
• HEAD
• OPTIONS

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

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

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

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

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

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

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

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

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

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

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

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

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

私たちのコミュニティは、サンプルフックコレクション内のカスタム 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 クォータのドキュメントを参照してください。