トラブルシューティング

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

エンドポイント登録時の問題 

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

1{
2  "title": "Resource Not Found",
3  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
4  "detail": "Could not find requested resource"
5}

推奨されるアプローチ: エンドポイント登録の問題を調査するには、カスタム API ステータスレポートを使用します。このステータスレポートは、登録できなかったエンドポイントについて詳細なエラー情報を提供します。これには、問題の迅速な特定と解決に役立つ具体的なエラーコードが含まれます。

カスタム API ステータスレポートで問題を解決するための十分な情報が得られない場合は、次の項目を手動で確認します。

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

登録エラーの調査 

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

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

リクエスト処理中の問題 

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

400 - Bad Request (不正なリクエスト) 
例

1{
2  "title": "Bad Request",
3  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/undefined-query-parameter",
4  "detail": "Found query parameter(s) not defined in the schema: 'c_type'"
5}
理由

このタイプのエラーは、通常、リクエストパラメーターの欠落や不明、パラメーターの長さの無効など、コントラクト違反が原因で発生します。

解決策

レスポンスボディには、理由を明確に示す必要があります。

401 - Unauthorized (許可されていません) 
例

1{
2  "title": "Unauthorized",
3  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
4  "detail": "Invalid token provided."
5}
理由

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

解決策

次の項目を確認します。

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

403 - Forbidden (許可されていません) 
例

1{
2  "title": "Forbidden",
3  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
4  "detail": "Request path is not allowed, because of missing or invalid permissions."
5}
理由

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

解決策

次の項目を確認します。

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

405 - Method Not Allowed (メソッドが許可されていません) 
例

1{
2  "title": "Method Not Allowed",
3  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/method-not-allowed",
4  "detail": "The request method is not allowed for the requested resource"
5}
理由

このタイプのエラーは、エンドポイントパスが存在するが、リクエストメソッドがコントラクトで定義されていない場合に返されます。

解決策

このメソッドが有効な場合は、対応する操作をコントラクトに追加します。そうでない場合は、別の方法を使用するようにリクエストを変更します。

406 - Not Acceptable (許容できません) 
例

1{
2  "title": "Unsupported Media Type",
3  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unsupported-media-type",
4  "detail": "The media type 'application/xml' in the Accept header isn't supported.",
5  "mediaType": "application/xml"
6}
理由

この種類のエラーは、コントラクトで定義されているレスポンスメディアの種類がクライアントによって受け入れられない場合に返されます (たとえば、エンドポイントは常に application/json を返しますが、クライアントは Accept ヘッダーで定義されている application/xml のみを受け入れる場合)。

解決策

リクエストされたメディアの種類が有効な場合は、コントラクト内の対応する操作に追加します。そうでない場合は、ワイルドカードなどを使用して、サポートされているメディアの種類を使用するようにリクエストを変更します。詳細については、仕様を参照してください。

415 - Unsupported Media Type (サポートされていないメディアの種類) 
例

1{
2  "title": "Unsupported Content Type",
3  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unsupported-content-type",
4  "detail": "The media type 'application/xml' in the Content-Type header isn't supported. Note: Only the UTF-8 charset is supported.",
5  "contentType": "application/xml"
6}
理由

このタイプのエラーは、リクエストペイロードのメディアの種類がコントラクトで定義されているメディアの種類と一致しない場合に返されます(たとえば、ペイロードは Content-Type ヘッダーで示されているとおり application/xml だが、エンドポイントは application/json を期待する場合)。

解決策

指定されたメディアの種類が有効な場合は、コントラクト内の対応する操作に追加します。そうでない場合は、サポートされているメディアの種類を使用するようにリクエストを変更します。詳細については、仕様を参照してください。

500 - Internal Server Error (内部サーバーエラー) 
例

1{
2  "title": "Custom API Internal Server Error",
3  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/custom-api-internal-server-error"
4}
理由

このタイプのエラーは、リクエスト処理中の一般的なサーバーエラーを示している可能性があります。ただし、実装スクリプトから発生したエラーは、上記の例のように custom-api-internal-server-error タイプでエラーも返します。

解決策

ここで説明するように、ログメッセージを調べて、これらのエラーの理由を見つけてください。

503 - Service Unavailable (サービス利用不可) 
例

1{
2  "title": "Custom API Circuit Breaker Error",
3  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/custom-api-circuit-breaker-error"
4}
理由

このタイプのエラーは、多数のスクリプトエラーが原因でサーキットブレーカーがオープンになっていることを示します。

解決策

この保護メカニズムの詳細と、これらのエラーに対処する方法については、サーキットブレーカーを参照してください。

リモートインクルードに関する問題 

  • SCAPI エラーレスポンス:

    • 含まれているリソースから 404 レスポンスコードを受け取った場合、空の JSON オブジェクト ’{}’ が最終的な JSON で提供されます。
    • 含まれているリソースから受信したその他の 4xx または 5xx レスポンスコードの場合、最終的なレスポンスステータスは 500 ‘Internal Server Error’ です。

  • コントローラーのエラーレスポンス:

  • エラーレスポンスコードは、結果の JSON に直接埋め込まれます。エラーレスポンスが有効な JSON でない場合、最終的なレスポンスは無効な JSON になります。

入門ガイド
クイックスタート
開発
拡張
カスタム API
認証と認可
キャッシング
サーキットブレーカー
リモートインクルード
共有コンポーネントと参照
カスタム API ステータスレポート
トラブルシューティング
フックによる拡張性
サイトの保護
パフォーマンスの最適化
トラブルシューティング
Ask the Community