b2c-custom-api-development

カスタム API 開発スキル

このスキルでは、Salesforce B2C Commerce 向けのカスタム API 開発について説明します。カスタム API を使用すると、カスタムスクリプトコードを SCAPI フレームワークの REST エンドポイントとして公開できます。

ヒント： b2c CLI がグローバルにインストールされていない場合は、代わりに npx @salesforce/b2c-cli を使用してください（例：npx @salesforce/b2c-cli code deploy）。

対象範囲と根拠

このスキルでは、カスタム API 開発のための CLI 固有のワークフローとクイックスタートのパターンを紹介します。OpenAPI 3.0 コントラクトの構造、OAuth スコープの設定、カートリッジパスの解決ルール、サーキットブレーカーの動作を取り上げます。ただし、プラットフォーム固有の検証ルール、運用上の制限、セキュリティスキームの要件、Script API の統合パターンは、Commerce Cloud のリリースによって変わる可能性があります。特定の API バージョンやフレームワークの動作に関する質問に回答する場合、またはユーザーが実行するコードを出力する場合は、b2c docs search／b2c docs read（CLI）または docs_search／docs_read（MCP）を使って、公式ドキュメントで現在のプラットフォーム固有の情報を確認してください。公式ドキュメントは、ここで扱っていないカスタム API コントラクトの仕様、ランタイムの動作、B2C Commerce プラットフォームの詳細について、信頼できる情報源です。

基準となるドキュメント（これらでプラットフォーム固有の情報を確認してください）：

• commerce-api/custom-apis - 概要、カートリッジの解決、運用上の制限
• commerce-api/custom-api-components-references - schema.yaml と script.js の要件
• commerce-api/custom-api-authentication - OAuth スコープのルール、セキュリティスキーム
• commerce-api/custom-api-caching - キャッシュの動作と設定
• commerce-api/custom-api-remote-includes - リモートインクルードのパターン
• commerce-api/custom-api-circuit-breaker - 現在のしきい値と動作
• commerce-api/custom-api-troubleshooting - よくある問題と解決策
• commerce-api/custom-api-status-report - 登録ステータスの詳細
• dw.system.RESTResponseMgr - Script API レスポンスマネージャー
• dw.system.Request - Script API リクエストオブジェクト
• dw.system.RESTErrorResponse - Script API エラーレスポンス
• dw.system.RESTSuccessResponse - Script API 成功レスポンス

概要

カスタム API の URL は、次の構造です。

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

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

1. API コントラクト - OAS 3.0 スキーマファイル（YAML）
2. API 実装 - B2C Commerce Script API を使用するスクリプト
3. API マッピング - エンドポイントを実装に紐付ける api.json ファイル

カートリッジ構造

/my-cartridge
    /cartridge
        package.json
        /rest-apis
            /my-api-name              # API name (lowercase alphanumeric and hyphens only)
                api.json              # Mapping file
                schema.yaml           # OAS 3.0 contract
                script.js             # Implementation

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

コンポーネント 1：API コントラクト（schema.yaml）

最小限の例を示しています。現在のスキーマ検証ルール、セキュリティスキームの構造、スコープの命名要件は、b2c docs read commerce-api/custom-api-components-references および b2c docs read commerce-api/custom-apis で確認してください。

最小限の例：

openapi: 3.0.0
info:
  version: 1.0.0
  title: My Custom API
components:
  securitySchemes:
    ShopperToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
          scopes:
            c_my_scope: My custom scope
  parameters:
    siteId:
      name: siteId
      in: query
      required: true
      schema:
        type: string
        minLength: 1
paths:
  /my-endpoint:
    get:
      operationId: getMyData
      parameters:
        - $ref: '#/components/parameters/siteId'
      responses:
        '200':
          description: Success
security:
  - ShopperToken: ['c_my_scope']

主な要件：

• Shopper API には ShopperToken（siteId が必要）、Admin API には AmOAuth2 を使用します
• カスタムスコープは c_ で始める必要があり、最大 25 文字です
• カスタムパラメーターには c_ のプレフィックスが必要です

Cartridge パスの要件（プラットフォームが rest-apis/ フォルダーを検索する場所）

プラットフォームのカートリッジ解決ルールを示す例です。現在のランタイム動作とサイトコンテキストの処理については、b2c docs read commerce-api/custom-apis で確認してください。

呼び出し形式	検索されるカートリッジパス
Shopper API（ShopperToken）— 常にサイトスコープ	ストアフロントサイトのカートリッジパス（SLAS トークンを発行したサイト）
siteId=<storefront-site> を指定した Admin API（AmOAuth2）	そのストアフロントサイトのカートリッジパス
siteId=Sites-Site（特別な BM／組織サイト）を指定した Admin API（AmOAuth2）	Business Managerのカートリッジパス
siteId を省略した Admin API（AmOAuth2）	Business Managerのカートリッジパス

Admin API はサイトコンテキストまたは組織コンテキストで呼び出すことができます。siteId パラメーターは省略可能で、組織コンテキストを明示的に指定する特別な値もあります。

• 実際のストアフロントサイト ID（例：siteId=RefArch）を渡すと、そのサイトのコンテキストで呼び出しが実行され、そのサイトのカートリッジパスを基にカートリッジが解決されます。
• siteId=Sites-Site を渡すと、Admin API をBusiness Manager／組織サイトに対して呼び出すことになります。Sites-Site は実際のストアフロントではなく、BM／組織レベルの操作を表すシステム定義のサイトです。プラットフォームは BM のカートリッジパスを通じてカートリッジを解決します。
• siteId を完全に省略すると、組織コンテキストと同じ扱いになり、BM のカートリッジパスを通じて解決されます。

BM のカートリッジパスは、よくある見落としポイントです。Admin API を組織レベルの操作（siteId=Sites-Site を指定するか、siteId を省略して呼び出す場合）に使用するなら、rest-apis/ を含むカートリッジを BM のカートリッジパスに含める必要があります。よくある症状は、「ストアフロントの siteId を指定して呼び出すと登録されるのに、組織コンテキストでは 404 になる」、または組織コンテキストで b2c scapi custom status に表示されないことです。

CLI でカートリッジパスを管理できます（BM の画面操作は不要です）。

# Inspect the current BM cartridge path
b2c sites cartridges list --bm

# Add a cartridge to BM for org-context Admin APIs
b2c sites cartridges add my_admin_api_cartridge --bm --position first

# Add a cartridge to a storefront site (for Shopper APIs or site-scoped Admin APIs)
b2c sites cartridges add my_api_cartridge --site-id RefArch --position first

カートリッジパスを更新した後は、コードバージョンを再度有効化して（b2c code deploy --reload または b2c code activate <version>）、プラットフォームにエンドポイントを再登録させてください。

Business Manager で BM のカートリッジパスを手動で設定するには、Administration > Sites > Manage Sites > Business Manager（ヘッダー内のリンク）> Settings > Cartridges に移動します。

スキーマの例の全体と Shopper API と Admin API の違いについては、コントラクトのリファレンスを参照してください。

コンポーネント 2：実装（script.js）

Script API の使用例です。現在の Custom API 統合パターン、RESTResponseMgr の要件、リクエストオブジェクトのメソッドについては、b2c docs read commerce-api/custom-api-components-references と、dw.system.RESTResponseMgr／dw.system.Request の Script API ドキュメントで確認してください。

var RESTResponseMgr = require('dw/system/RESTResponseMgr');

exports.getMyData = function() {
    var myParam = request.getHttpParameterMap().get('c_my_param').getStringValue();
    var result = { data: 'my data', param: myParam };
    RESTResponseMgr.createSuccess(result).render();
};
exports.getMyData.public = true;  // Required

主な要件：

• エクスポートする関数に .public = true を設定します
• レスポンスには RESTResponseMgr.createSuccess() を使用します
• エラーレスポンス（RFC 9457 形式）には RESTResponseMgr.createError() を使用します

キャッシュ、リモートインクルード、外部サービス呼び出しについては、実装のリファレンスを参照してください。

コンポーネント 3：マッピング（api.json）

{
  "endpoints": [
    {
      "endpoint": "getMyData",
      "schema": "schema.yaml",
      "implementation": "script"
    }
  ]
}

重要： 実装名にファイル拡張子を含めてはいけません。

開発ワークフロー

1. rest-apis/{api-name}/ 構造でカートリッジを作成します
2. エンドポイントとセキュリティを含むコントラクト（schema.yaml）を定義します
3. エクスポートする関数を含むロジック（script.js）を実装します
4. エンドポイントと実装を紐付けるマッピング（api.json）を作成します
5. コードバージョンをデプロイして有効化（--reload）し、エンドポイントを登録します。初回登録時およびコントラクト（schema.yaml／api.json）の変更時に必要です
6. 登録状況を確認してテストします
7. 登録済みのエンドポイントの script.js を以降編集する場合は、--reload なしで再デプロイします。実装のみの変更では再有効化は不要です

デプロイ

# Deploy and activate to (re-)register endpoints
b2c code deploy ./my-cartridge --reload

# Deploy without re-activation (fine for implementation-only edits to already-registered endpoints)
b2c code deploy ./my-cartridge

# Check registration status
b2c scapi custom status --tenant-id zzpq_013

# Show failed registrations with error reasons
b2c scapi custom status --tenant-id zzpq_013 --status not_registered --columns apiName,endpointPath,errorReason

コードバージョンを再アクティベートする必要がある場合（--reload）

カスタム API エンドポイントの登録は、ファイルをアップロードするたびではなく、コードバージョンのアクティベーション時に再構築されます。つまり、次のようになります。

変更	再アクティベーションが必要ですか？
新しいエンドポイント、新しい API、または初回登録	はい
schema.yaml の編集（パス、パラメーター、セキュリティ、スコープ、リクエスト／レスポンスの形式）	はい
api.json の編集（エンドポイントから実装へのマッピング）	はい
サイトまたは BM カートリッジパスへのカートリッジの追加／削除	はい
すでに登録済みのエンドポイントに対する script.js（または実装／ライブラリコード）の編集	いいえ — 新しいコードはライブで反映されます。--reload を指定せずにデプロイするだけです

そのため、すでに登録されているエンドポイントの実装を通常どおり反復している間は、再アクティベーションのコストをかけずに繰り返しデプロイできます。--reload（または b2c code activate <version>）を使うのは、コントラクトが変更された場合、またはエンドポイントがまだ登録されていない場合に限ります。

認証の設定

Shopper API の場合

1. カスタムスコープを指定して SLAS クライアントを作成します。

   b2c slas client create --default-scopes --scopes "c_my_scope"
   

2. SLAS クライアントのクレデンシャルを使ってトークンを取得します
3. すべてのリクエストに siteId を含めます

Admin API の場合

1. Account Manager API Client（ロール：「Salesforce Commerce API」）にカスタムスコープ（c_my_admin_scope）を設定します
2. Account Manager OAuth を使い、両方の必須スコープタイプを指定してトークンを取得します。
   • テナントスコープ：SALESFORCE_COMMERCE_API:<tenant_id> — テナントへのアクセスを許可します
   • カスタム Admin スコープ：c_my_admin_scope — schema.yaml で宣言したスコープです
3. 組織コンテキストでは、リクエストから siteId を省略するか、siteId=Sites-Site を使用します

# b2c auth token accepts multiple scopes (repeat --auth-scope or comma-separate).
# It does NOT auto-inject the tenant scope, so list it explicitly:
TOKEN=$(b2c auth token \
  --auth-scope "SALESFORCE_COMMERCE_API:zzpq_013" \
  --auth-scope c_my_admin_scope)

テナントスコープが重要な理由： SCAPI サブコマンド（b2c scapi custom status、b2c scapi schemas list）は、SALESFORCE_COMMERCE_API:<tenant_id> を自動的に追加します。しかし、b2c auth token と生の curl コマンドでは、指定したスコープのみが送信されます。テナントスコープを含まないトークンでは、カスタム API、システム API を問わず、すべての Admin API に対して 403 が返されます。

curl の例と認証の設定については、テストリファレンスを参照してください。

トラブルシューティング

エラー	原因	解決策
400 Bad Request	無効または不明なパラメーター	すべてのパラメーターをスキーマで定義します
401 Unauthorized	無効なトークン	トークンの有効性を確認します
403 Forbidden	スコープが不足しています	トークンのスコープを確認します。Admin API では、トークンに SALESFORCE_COMMERCE_API:<tenant_id> とカスタムスコープの両方が必要です
404 Not Found	登録されていません	b2c scapi custom status を確認します
500 Internal Error	スクリプトエラー	b2c logs get --level ERROR を確認します
503 Service Unavailable	サーキットブレーカーが開いています	エラーを修正し、リセットを待ちます

登録に関する問題

• Shopper API のエンドポイントが表示されない場合： カートリッジがサイトのカートリッジパスにあることを確認し（b2c sites cartridges list --site-id <site>）、コードバージョンを再アクティベートします。
• Admin API のエンドポイントがストアフロントの siteId で呼び出される場合： カートリッジがそのサイトのカートリッジパスにあることを確認します。
• Admin API のエンドポイントが siteId=Sites-Site で呼び出されたとき（または siteId が省略されたとき）に 404 が返される、または登録されない場合： カートリッジはBusiness Manager のカートリッジパスに配置する必要があります。b2c sites cartridges list --bm で確認し、b2c sites cartridges add <cartridge> --bm --position first で追加します。その後、コードバージョンを再アクティベートします。上記のカートリッジパスの要件を参照してください。
• ログを確認する場合： b2c logs get を使用するか、Log Center で CustomApiRegistry をフィルターします

関連スキル

• b2c-cli:b2c-code - カートリッジのデプロイとコードバージョンのアクティベート
• b2c-cli:b2c-scapi-custom - Custom API の登録ステータスの確認
• b2c-cli:b2c-slas - Shopper API のテスト用 SLAS クライアントの作成
• b2c:b2c-webservices - 外部呼び出し用のサービス設定

リファレンスドキュメント

• 契約リファレンス - schema.yaml の完全な例、Shopper API と Admin API
• 実装リファレンス - script.js のパターン、キャッシュ、リモートインクルード
• テストリファレンス - 認証の設定、curl の例