トラブルシューティング

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

これらの問題によりエンドポイントが登録されないため、受信リクエストは次のペイロードを含む 404 - Not Found レスポンスになります。

原因を見つけるには、次の項目を確認します。

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

上記のチェックリストでエラーが判別できない場合は、ログメッセージを確認します。登録に失敗するたびに、対応するログメッセージが作成されます。

Business Manager で、管理 > サイトの開発 > 開発セットアップの順に移動します。
ログファイル セクションで、Log Center をクリックします。
「Day of Year (年間通算日)」を選択します。
LCQL フィールドに「CustomApiRegistry」と入力します。
クエリヒットのメッセージテキストには、正しいファイルで問題を修正するのに十分な詳細が含まれている必要があります。

受信リクエストは処理され、コントラクトに照らして検証されるため、次のエラーが発生する可能性があります。

例
理由: このタイプのエラーは、通常、リクエストパラメーターの欠落や不明、パラメーターの長さの無効など、コントラクト違反が原因で発生します。
解決策: レスポンスボディには、理由を明確に示す必要があります。

例

理由

このタイプのエラーは、認証トークンの欠落や無効など、認証の失敗が原因で発生します。

解決策

次の項目を確認します。

リクエストの Authorization ヘッダーに認証トークンがありますか?
トークンは (まだ) 有効ですか?

例

理由

このタイプのエラーは、認可の失敗 (通常はスコープエラー) が原因で発生します。

解決策

次の項目を確認します。

トークンはカスタムスコープで正しく構成されていますか?
トークンスコープの 1 つがコントラクトのエンドポイントに定義されていますか?

例
理由: このタイプのエラーは、エンドポイントパスが存在するが、リクエストメソッドがコントラクトで定義されていない場合に返されます。
解決策: このメソッドが有効な場合は、対応する操作をコントラクトに追加します。そうでない場合は、別の方法を使用するようにリクエストを変更します。

例
理由: この種類のエラーは、コントラクトで定義されているレスポンスメディアの種類がクライアントによって受け入れられない場合に返されます (たとえば、エンドポイントは常に application/json を返しますが、クライアントは Accept ヘッダーで定義されている application/xml のみを受け入れる場合)。
解決策: リクエストされたメディアの種類が有効な場合は、コントラクト内の対応する操作に追加します。そうでない場合は、ワイルドカードなどを使用して、サポートされているメディアの種類を使用するようにリクエストを変更します。詳細については、仕様を参照してください。

例
理由: このタイプのエラーは、リクエストペイロードのメディアの種類がコントラクトで定義されているメディアの種類と一致しない場合に返されます(たとえば、ペイロードは Content-Type ヘッダーで示されているとおり application/xml だが、エンドポイントは application/json を期待する場合)。
解決策: 指定されたメディアの種類が有効な場合は、コントラクト内の対応する操作に追加します。そうでない場合は、サポートされているメディアの種類を使用するようにリクエストを変更します。詳細については、仕様を参照してください。

例
理由: このタイプのエラーは、リクエスト処理中の一般的なサーバーエラーを示している可能性があります。ただし、実装スクリプトから発生したエラーは、上記の例のように custom-api-internal-server-error タイプでエラーも返します。
解決策: ここで説明するように、ログメッセージを調べて、これらのエラーの理由を見つけてください。

例
理由: このタイプのエラーは、多数のスクリプトエラーが原因でサーキットブレーカーがオープンになっていることを示します。
解決策: この保護メカニズムの詳細と、これらのエラーに対処する方法については、サーキットブレーカーを参照してください。

SCAPI エラーレスポンス:
- 含まれているリソースから 404 レスポンスコードを受け取った場合、空の JSON オブジェクト '{}' が最終的な JSON で提供されます。
- 含まれているリソースから受信したその他の 4xx または 5xx レスポンスコードの場合、最終的なレスポンスステータスは 500 'Internal Server Error' です。
コントローラーのエラーレスポンス:
エラーレスポンスコードは、結果の JSON に直接埋め込まれます。エラーレスポンスが有効な JSON でない場合、最終的なレスポンスは無効な JSON になります。