針對 Azure 資料庫的數據 API 產生器使用量進行疑難解答

本文提供使用適用於 Azure 資料庫之資料 API 產生器時可能發生之常見錯誤的解決方案。

一般端點：HTTP 400「不正確的要求」錯誤

下列各節說明 HTTP 400「不正確的要求」錯誤的原因和解決方案。

無效的數據 API 產生器端點

URL 路徑元件的基底會對應至數據 API 產生器的 REST 或 GraphQL 端點。 當 URL 路徑元件的基底不符合 Data API 產生器的運行時間組態中所設定的值時，Data API 產生器會傳回 HTTP 400「不正確的要求」錯誤。

您可以在數據 API 產生器的運行時間組態區段中，設定 GraphQL 和 REST 端點 runtime 的根路徑。 您必須使用值來開始 REST 和 GraphQL 端點的 URL 路徑。

例如，下列組態會將 設定 /api 為 REST 端點的根路徑，以及 /graphql 設定為 GraphQL 端點的根目錄：

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

因此，您必須在 REST 和 GraphQL 端點 URL 路徑開頭使用的值如下：

/api/<entity>

/graphql

注意

使用數據 API 產生器搭配靜態 Web Apps 使用資料庫連線功能時，URL 路徑會 /data-api以 開頭。 您可以在此值之後新增所需端點的值。 例如， /data-api/api/<entity> 針對 REST 和 /data-api/graphql GraphQL。

靜態 Web Apps 資料庫連線設定問題

當您搭配靜態 Web Apps 資料庫連線功能使用數據 API 產生器時，在回應本文中遇到「回應狀態代碼未指出成功：400（不正確的要求）」錯誤：

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

此錯誤可能表示您在連結資料庫時所提供的設定有問題。

若要解決此問題，請依照下列步驟執行︰

1. 驗證您的資料庫認證在 Azure Data Studio 或 SQL Server Management Studio （SSMS） 等工具中是否有效。
2. 取消連結/重新連結連接的資料庫。

如果您仍然遇到錯誤，請確定您選取 [允許 Azure 服務和資源存取此伺服器 ]，以取得 Azure 資料庫資源網路頁面上的 [例外 狀況]。 此選項會設定防火牆，以允許從配置給任何 Azure 服務或資產的 IP 位址連線，包括來自其他客戶的訂用帳戶連線。

REST 端點：HTTP 404「找不到」錯誤

如果要求的 URL 指向未與任何實體相關聯的路由，則會傳回 HTTP 404 錯誤。 根據預設，實體的名稱也是路由名稱。 例如，如果您在組態檔中設定範例 Todo 實體，例如下列範例：

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

然後， Todo 實體可透過下列路由連線：

/<rest-route>/Todo

如果您將 rest.path 實體組態中的 屬性指定為 todo，如下列範例所示：

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

然後，實體的 Todo URL 路由為 todo，且所有小寫字元都符合運行時間組態中定義的確切值：

/<rest-route>/todo

GraphQL 端點：HTTP 400「不正確的要求」錯誤

每次建構 GraphQL 要求時，GraphQL 要求會產生 HTTP 400「不正確的要求」錯誤。 這可能是因為不存在的實體欄位或拼錯的實體名稱所造成。 數據 API 產生器會傳回響應承載中的描述性錯誤和錯誤詳細數據。

當您將要求傳送 GET 至 GraphQL 端點時，傳回錯誤狀態的回應本文會指出「必須設定參數查詢或參數識別碼」。請務必使用 HTTP POST傳送 GraphQL 要求。

GraphQL 端點：HTTP 404「找不到」錯誤

請確定 GraphQL 要求是使用 HTTP POST 方法傳送至已設定的 GraphQL 端點。 根據預設，GraphQL 端點路由為 /graphql。

GraphQL 端點：「物件類型 Query 必須至少定義一個字段才能有效」錯誤

當資料 API 產生器啟動無法根據您的執行時間組態產生 GraphQL 架構時，您會收到錯誤訊息：

物件類型 Query 必須至少定義一個字段才能有效。

GraphQL 規格需要在 GraphQL 架構中定義至少一個 Query 物件。 您必須驗證您的執行時間群組態是否符合下列其中一個條件：

• 此 read 動作會針對至少一個已啟用 GraphQL 的實體定義。 GraphQL 預設會在實體上啟用，因此請確定您 不會 將此風險降低套用至已設定的 {"graphql": false}實體。

• 當您只公開預存程式時，請在至少一個預存程式實體上定義 { "graphql": { "operation": query" } } ，這會覆寫預設預存程式 GraphQL 作業類型 mutation。

  您必須至少有一個預存程式只能讀取，而且不會修改數據。 否則，GraphQL 架構產生會因為架構中的空白 query 欄位而失敗。

GraphQL 端點：反省不適用於 GraphQL 端點

支援 GraphQL 的工具通常會利用 GraphQL 架構內省，而不需要額外的設定。 請務必在組態區段中將執行時間組態屬性 allow-introspection 設定為 true runtime.graphql 。 例如：

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

GraphQL 端點：「變更作業 <operation_name> 成功，但目前使用者因讀取許可權不足而未經授權檢視回應」錯誤

若要讓 GraphQL 突變作業接收有效的回應，除了個別的突變作業類型 - 建立、更新和刪除之外，也應該設定讀取許可權。 如錯誤所暗示，在資料庫層成功進行突變作業（create/update/delete），但缺少讀取許可權會導致數據 API 產生器傳回錯誤訊息。 因此，請務必在「匿名」角色或您要執行突變作業的角色中設定讀取許可權。

一般錯誤：要求傳回的 HTTP 500 錯誤

HTTP 500 錯誤表示數據 API 產生器無法在後端資料庫上正常運作。 請確定符合下列條件：

• 數據 API 產生器仍然可以連線到已設定的資料庫。
• 數據 API 產生器所使用的資料庫物件仍可供使用且可供存取。

若要允許 Data API 產生器傳回回應中的特定資料庫錯誤，請將組 runtime.host.mode 態屬性設定為 development：

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

根據預設，資料 API 產生器會執行 runtime.host.mode ，並將 它設定為 production。 在模式中 production ，數據 API 產生器不會傳回響應承載中的詳細錯誤。

development在和 production 模式中，數據 API 產生器會將詳細的錯誤寫入主控台，以協助進行疑難解答。

因未經驗證和未經授權的要求而發生的一般錯誤

HTTP 401「未經授權」錯誤

當存取的端點和實體需要驗證，且要求者在其要求中不提供有效的驗證元數據時，就會發生 HTTP 401 錯誤。

當您將數據 API 產生器設定為使用 Microsoft Entra ID 驗證時，您的要求會在提供的持有人（存取） 令牌無效時產生 HTTP 401 錯誤。 由於許多原因，存取令牌可能無效。 這裡列出其中一些：

• 存取令牌已過期。
• 存取令牌不適用於資料 API 產生器的 API（錯誤的存取權杖物件）。
• 存取令牌不是由預期的授權單位所建立（無效的存取令牌簽發者）。

若要解決此錯誤，請務必符合下列條件：

• 您可以使用執行時間組態區段中定義的authentication值來產生存取令牌issuer。

• 您的存取令牌會針對 audience 運行時間組態區 authentication 段中定義的值產生。

以下是範例設定：

"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 具有 值的 role1HTTP 標頭。

注意

角色名稱比對會區分大小寫。

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

參考資料

• 針對 Azure 資料庫的數據 API 產生器安裝進行疑難解答
• Azure/data-api-builder GitHub 存放庫中的已知問題

後續步驟

如果問題未解決，請在 data-api-builder 討論中提供意見反應或回報。

與我們連絡，以取得說明

如果您有問題或需要相關協助，請建立支援要求，或詢問 Azure community 支援。 您也可以向 Azure 意見反應社群提交產品意見反應。