カスタム 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 という例を見ていきます。以下の図は、必要なコンポーネントとその関係を示しています。

Associated diagram

このページの一部のリンクにアクセスできるのは、既存のお客様のみです。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 の変更ポリシーのセクションを参照してください。

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

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

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

siteId が指定されていない場合、リクエストは SCAPI Admin API リクエストとして扱われ、Business Manager サイトが使用されます。リクエストで locale が指定されていない場合は、サイトのデフォルトの地域情報が使用されます。

siteId パラメーターはカスタム API の登録にも使用されます。つまり、カスタム API を含むカートリッジがサイトのカートリッジパスに追加されていない場合、その siteId を使用してリクエストすると、404 レスポンスが返されます。Admin API の場合、カートリッジを Business Manager サイトのカートリッジパスに追加する必要があります。

Admin API リクエストに買い物客トークンを使用することは許可されていません。このようなシナリオでは、AmOAuth2 トークンを使用します。

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

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

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

システムクエリパラメーターは、前に示したように、正しい schema フィールドで定義する必要があります。required を false に設定すると、この値は必須ではありません。required がtrue されている場合、パラメーターが欠落しているか空の場合、リクエストは拒否されます。

非カスタム B2C Commerce API (SCAPI) と同様に、各エンドポイントは Shopper または Admin API エンドポイントのいずれかです。これらの API グループを区別する方法の一般的な情報については、SCAPI グループを参照してください。

カスタム API の場合、Shopper エンドポイントと Admin エンドポイントには主に 3 つの違いがあります。

  1. Shopper のエンドポイントでは、リクエストランタイム、リクエストボディのサイズ、および API クォータに対してより厳しい制限が設定されています。特定の値については制限事項を参照してください。
  2. Shopper エンドポイントでは siteId クエリパラメーターが必要ですが、Admin エンドポイントではこのパラメーターを省略する必要があります。siteId のないリクエストは、Admin API リクエストとして扱われます。
  3. Shopper エンドポイントには ShopperToken セキュリティスキームが必要であり、Admin エンドポイントには AmOAuth2 セキュリティスキームが必要です。また、各エンドポイントに設定できるセキュリティスキームは 1 つだけです。これらの使用方法については、認証を参照してください。

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

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

次の例では、管理者がロイヤルティ情報を更新できる POST メソッドを使用して Loyalty Information API を拡張します。

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

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

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

不明なパラメーターをもつリクエストは拒否されるため、すべてのリクエストパラメーターをコントラクトで定義する 必要があります。カスタムクエリパラメーターには、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 コレクション) を参照してください。

以下の制限があります。

  • 全般:
    • GET リクエストの場合、トランザクションをコミットできません。
    • スキーマ属性 additionalProperties は使用できません。
    • Shopper API と Admin API は、該当する API クォータに従う必要があります。クォータの詳細については、API クォータのドキュメントを参照してください。
  • Shopper API:
    • リクエストの最大実行時間は 10 秒です。
    • リクエストボディの最大サイズは 5 MiB (5,242,880 バイト) です。
    • STOREFRONT アクティビティタイプ。ストアフロントのクォータ制限が適用されます。
  • SCAPI Admin API:
    • リクエストの最大実行時間は 60 秒です。
    • リクエストボディの最大サイズは 20 MB (20,000,000 バイト) です。
    • BUSINESS_MANAGER アクティビティタイプ。デフォルトのクォータ制限が適用されます。