カスタム API ステータスレポート

カスタム API ステータスレポートは、カスタム API の登録ステータスをリアルタイムで可視化することで、透明性を高め、トラブルシューティングにかかる時間を短縮します。カスタム API を含むコードバージョンをアクティブ化すると、登録プロセスによってエンドポイントごとに異なる結果が生じる可能性があります。以前は、問題を診断するためにデベロッパーがログを手作業で調べる必要がありましたが、カスタム API ステータスレポートでは、明確で実用的なフィードバックフィードバックを提供することで、この作業を簡素化します。

主なメリット

**リアルタイムのステータスレポート: **エンドポイントの登録ステータスに関するフィードバックを即座に取得できます。
**エラーの可視化: **エンドポイントの登録に失敗した理由を把握できます。
**デバッグ時間の短縮: **手動でログを検索する必要がありません。
**開発ワークフローの改善: **エンドポイントの問題を迅速に特定して解決できます。

エンドポイント登録ステータス

各カスタム API エンドポイントは、次のいずれかの登録ステータスになります。

ステータス	説明	アクセス可能?
`active`	エンドポイントは正常に登録されており、リクエストを処理する準備ができています。	はい
`not_registered`	構成または実装のエラーにより、エンドポイントを登録できませんでした。	いいえ

カスタム API ステータスレポートの使用

認証

カスタム API ステータスレポートでは、必要なスコープを指定した Account Manager OAuth 2.0 フローによる認証が必要です。

sfcc.custom-apis (読み取り専用)

エンドポイント URL

1GET https://{shortCode}.api.commercecloud.salesforce.com/dx/custom-apis/v1/organizations/{organizationId}/endpoints

パラメーター

パラメーター	型	必須	説明
`shortCode`	パス	はい	ルーティング用にレルムに割り当てられた 8 文字の文字列です。例: `kv7kzm78`
`organizationId`	パス	はい	B2C Commerce インスタンスを識別する短い文字列です。例: `f_ecom_zzte_053`
`status`	クエリ	いいえ	ステータス (`active` または `not_registered`) を指定して、エンドポイントをフィルタリングします。

レスポンス形式

このエンドポイントは、次の内容を含む JSON オブジェクトを返します。

activeCodeVersion: 現在アクティブなコードのバージョン
total: すべてのサイトとカートリッジで検出されたエンドポイントの合計数
limit: このレスポンスに含まれるエンドポイントの数。ここの件数はフィルター条件に一致する件数であり、フィルターが適用されていない場合は total と同じです。
data: 詳細情報を含むエンドポイントオブジェクトの配列
filter: 適用されたフィルターを含むオブジェクト。これは、リクエストでフィルターが使用されている場合にのみ含まれます。

各エンドポイントオブジェクトには、次のフィールドが含まれます。

フィールド	説明
`id`	エンドポイントの一意の識別子 (コードバージョンのアクティブ化をまたいで一貫しています)。
`apiName`	API の名前。例: `loyalty-info`
`apiVersion`	API のバージョン。例: `v1`
`cartridgeName`	エンドポイントを含むカートリッジの名前。
`endpointPath`	エンドポイントパス。例: `/customers`
`httpMethod`	HTTP メソッド。例: `GET`、`POST`
`operationId`	OpenAPI スキーマ内の操作識別子。
`implementationScript`	実装スクリプトファイルの名前。
`schemaFile`	OpenAPI スキーマファイルの名前。
`siteId`	エンドポイントが登録されているサイトの識別子。
`securityScheme`	エンドポイントで使用されるセキュリティスキーム。
`status`	登録ステータス (`active` または `not_registered`)。
`errorReason`	エラーの説明 (ステータスが `not_registered` の場合にのみ含まれます。

使用例

すべてのエンドポイントの一覧表示

組織内のすべてのカスタム API エンドポイントの情報を取得します。

1curl -X GET \
2  'https://{{shortCode}}.api.commercecloud.salesforce.com/dx/custom-apis/v1/organizations/{{organizationId}}/endpoints' \
3  -H 'Authorization: Bearer {{access_token}}'

レスポンス:

1{
2  "activeCodeVersion": "version1",
3  "limit": 3,
4  "data": [
5    {
6      "id": "10bd7f2dc40ab7aede7f0d60e5c3a783",
7      "apiName": "loyalty-info",
8      "apiVersion": "v1",
9      "cartridgeName": "my_custom_cartridge",
10      "endpointPath": "/customers",
11      "httpMethod": "GET",
12      "implementationScript": "customers.js",
13      "operationId": "getLoyaltyInfo",
14      "securityScheme": "ShopperToken",
15      "schemaFile": "loyalty-schema.yaml",
16      "siteId": "Sites-MyStore-Site",
17      "status": "active"
18    },
19    {
20      "id": "fd2e726fc9e23dac4951bfe325146c24",
21      "apiName": "loyalty-info",
22      "apiVersion": "v1",
23      "cartridgeName": "my_custom_cartridge",
24      "endpointPath": "/rewards",
25      "httpMethod": "POST",
26      "implementationScript": "rewards.js",
27      "operationId": "addReward",
28      "securityScheme": "AmOAuth2",
29      "schemaFile": "loyalty-schema.yaml",
30      "siteId": "Sites-MyStore-Site",
31      "status": "active"
32    },
33    {
34      "id": "7f8cfdf0534476b858d080b9059bc07e",
35      "apiName": "loyalty-info",
36      "apiVersion": null,
37      "cartridgeName": "my_custom_cartridge",
38      "endpointPath": null,
39      "errorReason": "Schema file ../broken-schema.yaml in API folder loyalty-info must not be a relative path.",
40      "httpMethod": null,
41      "implementationScript": "broken-endpoint.js",
42      "operationId": "brokenOperation",
43      "securityScheme": null,
44      "schemaFile": "../broken-schema.yaml",
45      "siteId": "Sites-Site",
46      "status": "not_registered"
47    }
48  ],
49  "total": 3
50}

ステータスによるフィルタリング

登録に失敗したエンドポイントを取得します。

1curl -X GET \
2  'https://{{shortCode}}.api.commercecloud.salesforce.com/dx/custom-apis/v1/organizations/{{organizationId}}/endpoints?status=not_registered' \
3  -H 'Authorization: Bearer {{access_token}}'

レスポンス:

1{
2  "activeCodeVersion": "version1",
3  "limit": 1,
4  "data": [
5    {
6      "id": "7f8cfdf0534476b858d080b9059bc07e",
7      "apiName": "loyalty-info",
8      "apiVersion": null,
9      "cartridgeName": "my_custom_cartridge",
10      "endpointPath": null,
11      "errorReason": "Schema file ../broken-schema.yaml in API folder loyalty-info must not be a relative path.",
12      "httpMethod": null,
13      "implementationScript": "broken-endpoint.js",
14      "operationId": "brokenOperation",
15      "securityScheme": null,
16      "schemaFile": "../broken-schema.yaml",
17      "siteId": "Sites-Site",
18      "status": "not_registered"
19    }
20  ],
21  "filter": {
22    "status": "not_registered"
23  },
24  "total": 3
25}

レスポンス

API は、次の標準 HTTP ステータスコードを返します。

200: リクエスト成功
400: フィルターパラメーターが無効です。たとえば、サポートされていないステータス値などです。
401: 認証が必要です
403: アクセス許可が不十分です (必要なスコープがありません)

一般的なエラーシナリオ

エンドポイントのステータスが not_registered の場合、一般的なエラーには次のようなものがあります。

無効なファイルパス: スキーマファイルまたは実装ファイルが見つかりません。
無効なファイル: スキーマファイルまたは実装ファイルを読み取れません。
構成エラー: API マッピングに問題があります。
検証エラー: セキュリティスキームまたはパラメーター定義に問題があります。
スキーマファイルエラー: OpenAPI 仕様の形式または構造が無効です。
スキーマ参照エラー: 外部依存関係の検証に問題があります。
パスパターンエラー: URL パターンの解析に失敗しました。

トラブルシューティングワークフロー

全体のステータスを確認: フィルターを指定せずにステータスレポートを使用して、すべてのエンドポイントの概要を確認します。
コードバージョンを確認: activeCodeVersion フィールドのアクティブなコードバージョンが想定どおりであることを確認します。
失敗したエンドポイントを特定: status=not_registered でフィルタリングして、問題のあるエンドポイントに絞り込みます。
エラーを分析: errorReason フィールドを確認し、具体的な対処の手掛かりを得ます。
問題を修正: カートリッジ内で特定された問題に対処します。
再アクティブ化: 新しいコードバージョンをアップロードしてアクティブ化します。
検証: ステータスレポートを再度呼び出して、正常に登録されたことを確認します。