カスタム API

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

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

SCAPI カスタム API のビデオでは、カスタム API を使用してカートリッジを作成する方法を順を追って説明しています。ビデオで提供されているコードサンプルにアクセスできない場合は、Salesforce Commerce Cloud GitHub リポジトリとアクセスを参照してください。

SCAPI Custom APIs
undefined

カスタム 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 マッピング**。

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

関連ダイアグラム

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

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

  • 破線は、この 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 でサポートされているメソッドは次のとおりです。

  • GET

B2C Commerce 24.4 では:

  • POST
  • PUT
  • PATCH
  • DELETE
  • HEAD
  • OPTIONS

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

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

前の例では、パスパラメーター customerId は、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 フィールドで定義する必要があります。required を false に設定すると、値はオプションであることを示しますが、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 アクティビティタイプがあります。実装は、ストアフロントに対応する API クォータに従う必要があります。詳細については、API クォータのドキュメントを参照してください。