トラブルシューティング

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

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

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

  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. AmOAuth2セキュリティ スキームとしてShopperToken使用されているか、または使用されているか。
    7. 対応するセキュリティスキームでは、スコープが 1 つだけ定義されていますか?
    8. スコープ名が接頭辞c_で始まり、英数字、ハイフン、ピリオド、またはアンダースコアのみで構成されていますか?
    9. すべてのパラメーター (システム・パラメーターおよびカスタム・パラメーター) がスキーマ・ファイルで定義されていますか。
    10. siteId と locale のシステムパラメーターは、スキーマファイルで定義されていますか?
      1. システム・パラメーターに と のminLength: 1フィールドtype: stringがありますか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. クエリ ヒットのメッセージ テキストには、正しいファイルで問題を修正するのに十分な詳細が含まれている必要があります。

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

例

理由

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

解決策

答本文には、理由を明確に示す必要があります。

例

理由

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

解決策

の項目を確認します。

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

理由

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

解決策

の項目を確認します。

  1. トークンはカスタム スコープで正しく構成されていますか?
  2. トークン スコープの 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 になります。