Azure データベースのデータ API ビルダーの使用に関するトラブルシューティング

2024-07-30

この記事では、Azure データベースにデータ API ビルダーを使用するときに発生する可能性がある一般的なエラーの解決策について説明します。

汎用エンドポイント: HTTP 400 "無効な要求" エラー

次のセクションでは、HTTP 400 "Bad Request" エラーの原因と解決策について説明します。

無効なデータ API ビルダーエンドポイント

URL パスコンポーネントのベースは、データ API ビルダーの REST または GraphQL エンドポイントにマップされます。 URL パスコンポーネントのベースがデータ API ビルダーのランタイム構成で設定された値と一致しない場合、データ API ビルダーは HTTP 400 "Bad Request" エラーを返します。

GraphQL エンドポイントと REST エンドポイントのルートパスは、データ API ビルダーのランタイム構成の runtime セクションで構成できます。値を使用して、REST エンドポイントと GraphQL エンドポイントの URL パスを開始する必要があります。

たとえば、次の構成では、rest エンドポイントのルートパスとして /api を設定し、GraphQL エンドポイントのルートとして /graphql します。

"runtime": {
    "rest": {
      "enabled": true,
      "path": "/api"
    },
    "graphql": {
      "allow-introspection": true,
      "enabled": true,
      "path": "/graphql"
    },
    "...": "...",
}

そのため、REST エンドポイントと GraphQL エンドポイントの URL パスの先頭で使用する必要がある値は次のとおりです。

/api/<entity>

/graphql

Note

データベース接続機能を使用して静的 Web Apps でデータ API ビルダーを使用する場合、URL パスは /data-api で始まります。この値の後に目的のエンドポイントの値を追加できます。たとえば、REST の /data-api/api/<entity> や GraphQL の /data-api/graphql などです。

静的 Web Apps データベース接続の構成に関する問題

静的 Web Apps データベース接続機能で Data API ビルダーを使用すると、応答本文で "応答状態コードは成功を示していません: 400 (無効な要求)" というエラーが発生します。

{"Message":"{\u0022Message\u0022:\u0022Response status code does not indicate success: 400 (Bad Request).\u0022,\u0022ActivityId\u0022:\u0022<GUID>\u0022}","ActivityId":"<GUID>"}

このエラーは、データベースをリンクするときに指定した構成に問題があることを示している可能性があります。

この問題を解決するには、次の手順に従ってください。

Azure Data Studio や SQL Server Management Studio (SSMS) などのツールでデータベース資格情報が有効であることを確認します。
接続されているデータベースのリンクを解除/再リンクします。

それでもエラーが発生する場合は、Azure Database リソースのネットワークページ Exceptions に対してこのサーバーにアクセスする Azure サービスとリソースを選択してください。このオプションでは、他のお客様のサブスクリプションからの接続を含め、Azure サービスまたは資産に割り当てられた IP アドレスからの接続を許可するようにファイアウォールを構成します。

REST エンドポイント: HTTP 404 "Not Found" エラー

要求された URL がエンティティに関連付けられていないルートを指している場合は、HTTP 404 エラーが返されます。既定では、エンティティの名前もルート名です。たとえば、次の例のように、構成ファイルでサンプル Todo エンティティを構成する場合です。

"Todo": {
      "source": "dbo.todos",
      "...": "..."
    }

その後、 Todo エンティティに次のルートを介して到達できます。

/<rest-route>/Todo

次の例に示すように、todoするエンティティ構成で rest.path プロパティを指定する場合:

"Todo": {
    "source": "dbo.todos",
    "rest": {
      "path": "todo"
    },
    "...": "..."
  }

次に、 Todo エンティティの URL ルートが todoされ、すべての小文字がランタイム構成で定義された正確な値と一致します。

/<rest-route>/todo

GraphQL エンドポイント: HTTP 400 "無効な要求" エラー

GraphQL 要求では、GraphQL 要求が正しく構築されないたびに HTTP 400 "Bad Request" エラーが発生します。これは、既存のエンティティフィールドまたはスペルミスのエンティティ名が原因である可能性があります。データ API ビルダーは、応答ペイロードで説明的なエラーとエラーの詳細を返します。

GET要求を GraphQL エンドポイントに送信すると、返されたエラーの応答本文は"パラメータークエリまたはパラメーター ID を設定する必要があります" と表示されます。HTTP POSTを使用して GraphQL 要求を送信してください。

GraphQL エンドポイント: HTTP 404 "Not Found" エラー

HTTP POST メソッドを使用して、構成された GraphQL エンドポイントに GraphQL 要求が送信されていることを確認します。既定では、GraphQL エンドポイントルートは /graphql。

GraphQL エンドポイント: "オブジェクト型クエリでは、有効にするために少なくとも 1 つのフィールドを定義する必要があります" というエラー

データ API ビルダーのスタートアップがランタイム構成に基づいて GraphQL スキーマを生成できない場合は、次のエラーメッセージが表示されます。

有効にするには、オブジェクト型 Query で少なくとも 1 つのフィールドを定義する必要があります。

GraphQL 仕様では、GraphQL スキーマで少なくとも 1 つの Query オブジェクトを定義する必要があります。ランタイム構成が次のいずれかの条件を満たしていることを検証する必要があります。

read アクションは、少なくとも 1 つの GraphQL 対応エンティティに対して定義されます。 GraphQL は既定でエンティティで有効になっているため、{"graphql": false}で構成されたエンティティにこの軽減策を適用しないでください。
ストアドプロシージャのみを公開する場合は、少なくとも 1 つのストアドプロシージャエンティティに対して { "graphql": { "operation": query" } } を定義します。このエンティティは、既定のストアドプロシージャ GraphQL 操作の種類 mutationオーバーライドします。

データの読み取りと変更のみを行うストアドプロシージャが少なくとも 1 つ必要です。それ以外の場合、スキーマ内の空の query フィールドが原因で GraphQL スキーマの生成が失敗します。

GraphQL エンドポイント: イントロスペクションが GraphQL エンドポイントで機能しない

GraphQL をサポートするツールでは、通常、追加のセットアップを必要とせずに GraphQL スキーマのイントロスペクションを使用します。 runtime.graphql構成セクションで、ランタイム構成プロパティのallow-introspectionをtrueに設定してください。例えば次が挙げられます。

"runtime": {
    "...": "...",
    "graphql": {
      "allow-introspection": true,
      "enabled": true,
      "path": "/graphql"
    },
    "...": "..."
}

GraphQL エンドポイント: "変更操作 <operation_name> は成功しましたが、現在のユーザーは読み取りアクセス許可がないために応答を表示できません" エラー

GraphQL の変更操作が有効な応答を受け取る場合は、それぞれの変更操作の種類 (作成、更新、削除) に加えて読み取りアクセス許可を構成する必要があります。エラーが示すように、データベースレイヤーで変更操作 (作成/更新/削除) は成功しましたが、読み取りアクセス許可がないため、Data API ビルダーはエラーメッセージを返しました。そのため、"匿名" ロールまたは変更操作を実行するロールのいずれかで、読み取りアクセス許可を構成してください。

一般的なエラー: 要求によって返される HTTP 500 エラー

HTTP 500 エラーは、データ API ビルダーがバックエンドデータベースで適切に動作できないことを示します。次の条件を満たしていることを確認します。

データ API ビルダーは、構成済みのデータベースに引き続き接続できます。
Data API ビルダーで使用されるデータベースオブジェクトは引き続き使用でき、アクセスできます。

Data API ビルダーが応答で特定のデータベースエラーを返せるようにするには、 runtime.host.mode 構成プロパティを developmentに設定します。

"runtime": {
    [...]
    "host": {
        "mode": "development",
        [...]
    }
}

既定では、データ API ビルダーは、productionに設定されたruntime.host.modeで実行されます。 production モードでは、Data API ビルダーは応答ペイロードに詳細なエラーを返しません。

developmentモードとproductionモードの両方で、データ API ビルダーはトラブルシューティングに役立つ詳細なエラーをコンソールに書き込みます。

認証されていない要求と未承認の要求による一般的なエラー

HTTP 401 "Unauthorized" エラー

HTTP 401 エラーは、アクセスされるエンドポイントとエンティティが認証を必要とし、要求者が要求に有効な認証メタデータを提供しない場合に発生します。

Microsoft Entra ID 認証を使用するように Data API ビルダーを構成すると、指定されたベアラー (アクセス) トークンが無効な場合、要求によって HTTP 401 エラーが発生します。アクセストークンは、さまざまな理由で無効になる可能性があります。次にそのいくつかを挙げます。

アクセストークンの有効期限が切れています。
アクセストークンは、データ API ビルダーの API (間違ったアクセストークン対象ユーザー) 用ではありません。
アクセストークンは、予期される機関 (無効なアクセストークン発行者) によって作成されません。

このエラーを解決するには、次の条件を満たしていることを確認します。

アクセストークンは、ランタイム構成の authentication セクションで定義されているissuer値を使用して生成します。
アクセストークンは、ランタイム構成の authentication セクションで定義されているaudience値に対して生成されます。

構成のサンプルを次に示します。

"authentication": {
    "provider": "AzureAD",
    "jwt": {
        "issuer": "https://login.microsoftonline.com/24c24d79-9790-4a32-bbb4-a5a5c3ffedd5/v2.0/",
        "audience": "b455fa3c-15fa-4864-8bcd-88fd83d686f3"
    }
}

定義済みの対象ユーザーに対して有効なトークンを生成する必要があります。 Azure CLI を使用する場合は、 resource パラメーターで対象ユーザーを指定することで、アクセストークンを取得できます。

az account get-access-token --resource "b455fa3c-15fa-4864-8bcd-88fd83d686f3"

HTTP 403 "禁止" エラー

Static Web Apps 統合または Microsoft Entra ID を使用して認証済み要求を送信すると、HTTP 403 "禁止" エラーが発生する可能性があります。このエラーは、構成ファイルに存在しないロールを使用しようとしていることを示します。

このエラーは、次の場合に発生します。

ロール名を指定する X-MS-API-ROLE HTTP ヘッダーは指定しません。

認証要求は既定でシステムロール authenticatedのコンテキストで実行されるため、このシナリオはシステム以外のロール (authenticatedやanonymousではなく) を使用する場合にのみ適用されます。
X-MS-API-ROLE ヘッダーで定義したロールは、データ API ビルダーのランタイム構成ファイルで構成されていません。
X-MS-API-ROLE ヘッダーで定義したロールが、アクセストークンのロールと一致しません。

たとえば、次のランタイム構成ファイルでは、ロール role1 が定義されているため、 X-MS-API-ROLE HTTP ヘッダーに値 role1を指定する必要があります。

Note

ロール名の一致では、大文字と小文字が区別されます。

"Todo": {
    "role": "role1",
    "actions": [ "*" ]
}

次のステップ

問題が解決しない場合は、フィードバックを提供するか、 data-api-builder ディスカッションで報告してください。

お問い合わせはこちらから

質問がある場合やヘルプが必要な場合は、サポート要求を作成するか、Azure コミュニティサポートにお問い合わせください。 Azure フィードバックコミュニティに製品フィードバックを送信することもできます。