カスタム API (ベータ)

B2C コマースは買い物客の体験をカスタマイズするための強力なツールを提供していますが、REST ベースの API には長い間そのような機能がありませんでした。現在の SCAPI は、フックを介してカスタマイズが可能で、開発者はフィルターを追加したり、レスポンスが呼び出し側アプリケーションに送り返される前にレスポンスを変更したりできます。

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

ベータプログラムの質問とフィードバック

ベータプログラムに関するフィードバックや質問をぜひ積極的にご提供ください。そのためには、Commerce Cloud デベロッパーコミュニティにアクセスしてください。コミュニティに初めて参加する場合は、すでにメンバーになっている人に招待を依頼するか、フォーム経由で招待を依頼してください (詳細はこちらから確認してください)。始める前に、既知の問題のリストをよくお読みください。

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

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

API ファミリーには custom という用語を使用する必要があります。API nameAPI version および endpoint のパラメーターは、次のドキュメントで説明されているように定義できます。

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

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

カスタム 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.1v1)。

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

エンドポイントを保護するには、コンポーネントとエンドポイントの両方で有効なセキュリティスキームを定義する必要があります。詳細については、認証を参照してください。

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

schema.yaml:

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

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

script.js:

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

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

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

api.json:

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

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

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

登録を行う前に、機能スイッチの画面に移動し、SCAPI カスタム 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 の変更ポリシーのセクションを参照してください。

現在サポートされている認証メカニズムは、Shopper Login (SLAS) のみです。API アクセスを保護するには、まずコンポーネントのセクションで ShopperToken という名前のスキームを定義します。このセクションの目的は、再利用可能な要素を定義することです。

その後、この定義をエンドポイントに追加します。これはグローバルに実行することも、操作ごとに実行することもできます。

例 1: セキュリティスキームをグローバルに (つまり、スキーマで定義されているエンドポイントごとに) 定義する

例 2: セキュリティスキームを操作時に定義する

ShopperToken を使用しない場合、またはセキュリティをまったく使用しない場合は、エンドポイントを登録できません。

エンドポイントがコントラクトで正しく保護されている場合は、各リクエストとともに有効な SLAS トークンを取得してカスタム API に送信してください。

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

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

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

  • siteId - リクエストの現在のサイト。存在しない場合は、Business Manager サイトにフォールバックします。
  • locale - リクエストの現在の地域情報。存在しない場合は、デフォルトのサイト地域情報にフォールバックします。

Business Manager サイトのコンテキストで買い物客トークンを使用することは許可されていないことに注意してください。フォールバックのメカニズムにより、ShopperToken で認証する場合は、常に siteId パラメーターを設定する必要があります。

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

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

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

予期しない動作が発生する可能性があるため、フォールバックのメカニズムに依存することは推奨されません。必ずシステムクエリパラメーターを API コントラクトに追加し、それに応じて設定してください。

以下の制限があります。

  • リクエストの最大実行時間は 10 秒。
  • GET リクエストの場合、トランザクションはコミット不可。
  • ベータの段階では、HTTP GET リクエストのみサポート。

カスタム API エンドポイントに期待どおりにアクセスできない場合は、根本原因を見つけるために次のチェックリストを活用してください。このチェックリストは、カートリッジの構造 (フォルダー構造など) や、含まれている必要なファイルを確認することを目的としています。実装自体はチェックされません。

  1. 機能スイッチは有効になっていますか?
  2. カスタム API コンポーネントがアップロードされたコードバージョンは、有効なコードバージョンですか?
    1. 各コードバージョンの有効化では、機能スイッチが有効になっている場合にのみカスタム API エンドポイントが登録されます。
  3. カスタム API コンポーネントを含むカートリッジは正しい構造になっていますか?
    1. rest-apis フォルダーは含まれていますか?
    2. rest-apis フォルダーには少なくとも 1 つのサブフォルダーが含まれていますか?
    3. rest-apis のサブフォルダー名は英数字小文字またはハイフンのみで構成されていますか?
    4. rest-apis のサブフォルダーには、マッピングファイルと、少なくとも 1 つのスキーマファイルおよび実装スクリプトが含まれていますか?
  4. カスタム API コンポーネントを含むカートリッジは、正しい SFCC インスタンスにアップロードされていますか?
  5. カスタム API コンポーネントを含むカートリッジは、正しいサイトに割り当てられていますか?
  6. リクエストで使用されたバージョンは正しいですか?
    1. 対応する API バージョンは、スキーマファイルで定義されていますか?
    2. API バージョンは一致していますか? API バージョンと URL バージョンは形式が異なります (例: API バージョン 1.0.1 → URL バージョン v1)
  7. スキーマファイルは正しいですか?
    1. このファイルの構造は正しいですか?
    2. バージョンは指定されていますか?
    3. securitySchemes の部分は指定されていますか?
    4. 属性 operationId を含む、少なくとも 1 つのエンドポイントが指定されていますか?
    5. security の部分はグローバルに、またはエンドポイントごとに指定されていますか?
    6. ShopperToken がセキュリティスキームとして使用されていますか?
  8. 実装スクリプトは正しいですか?
    1. それぞれのエンドポイントはこの実装スクリプトでエクスポートされていますか? → このスクリプトファイルでどのエンドポイントをエクスポートする必要があるかについては、マッピングファイルとスキーマファイル (operationId 属性) を参照してください。
    2. エンドポイントは JSON 形式でレスポンスを返しますか?
  9. マッピングファイルは正しいですか?
    1. このファイルの構造は正しいですか?
    2. 実装スクリプト名にファイル拡張子は含まれていませんか?
    3. 使用されているスキーマファイルと実装スクリプトは、マッピングファイルと同じレベルにありますか?
    4. 使用されているスキーマファイルは存在していますか?
    5. 使用されている実装は存在していますか?
    6. 指定されたエンドポイントは、関連するスキーマファイルと実装スクリプトで参照されていますか?
    7. endpoint プロパティの値は、スクリプト内の機能名およびスキーマ内の operationId と一致していますか?
  10. このバージョンには実装スクリプトとスキーマファイルが存在しますか?
  11. マッピングファイルには正しい実装スクリプトと正しいスキーマファイルが含まれていますか?
  12. すべてのパスパラメーター (システムパラメーターとカスタムパラメーター) はスキーマファイルで定義されていますか?
    1. siteIdlocale のシステムパラメーターは、スキーマファイルで定義されていますか?
    2. カスタムパラメーターは c_ で始まっていますか?
    3. すべてのパラメータにはタイプが定義されていますか?
    4. すべてのパラメーターの定義は、パラメーター定義の予想される構造と一致していますか?
  13. リクエストには有効な SLAS トークンが含まれていますか?

現在、次の既知の問題があります。

  • OAS パス項目に無効な構文 (例: /customers/{{id}} のようなネストされた括弧) を使用すると、サーバーの起動やコードのバージョンの有効化が妨げられる可能性があるため、使用を避ける必要があります。