針對 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

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

當您使用搭配靜態 Web Apps 資料庫連線功能的 Data API Builder 時，在回應本文中遇到「回應狀態代碼未顯示成功：400（錯誤的請求）」錯誤：

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

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

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

1. 請用 像 sqlcmd 或 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 要求時，都會產生 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 設定為 trueruntime.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 模式中，Data API builder 不會傳回回應負載中的詳細錯誤。

development 和 production 模式中，Data API 建構器會將詳細的錯誤寫入主控台，以協助進行疑難解答。

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

HTTP 401「未經授權」錯誤

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

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

• 存取令牌已過期。
• 存取權杖不適用於 Data API builder 的 API（錯誤的取用對象）。
• 存取令牌不是由預期的授權單位所建立（無效的存取令牌簽發者）。

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

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

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

以下是範例設定：

"authentication": {
    "provider": "AzureAD",
    "jwt": {
        "issuer": "https://login.microsoftonline.com/24c24d79-9790-4a32-bbb4-a5a5c3ffedd5/v2.0/",
        "audience": "00001111-aaaa-2222-bbbb-3333cccc4444"
    }
}

您必須為定義的受眾生成有效的令牌。 使用 Azure CLI 時，您可以在參數resource中指定對象，以取得存取權杖：

az account get-access-token --resource "00001111-aaaa-2222-bbbb-3333cccc4444"

HTTP 403「禁止」錯誤

如果您使用 Static Web Apps 整合或Microsoft Entra ID 傳送已驗證的要求，您可能會收到 HTTP 403「禁止」錯誤。 此錯誤表示您嘗試使用組態檔中不存在的角色。

此錯誤的發生條件如下：

• 您未提供 X-MS-API-ROLE 指定角色名稱的 HTTP 標頭。

  由於 已驗證的請求預設在系統角色authenticated的環境中執行，因此這種情況僅適用於您使用非系統角色（不是authenticated也不是anonymous）時。

• 您在 X-MS-API-ROLE 標頭中定義的角色，未在 Data API 構建器的執行時期組態檔中進行設定。

• 您在 X-MS-API-ROLE 標頭中定義的角色不符合存取權杖中的角色。

例如，在下列執行階段配置檔案中，角色 role1 已被定義，因此您必須提供一個具有值 X-MS-API-ROLE 的 role1 HTTP 標頭。

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

參考資料

• 疑難排解 Azure 資料庫 Data API builder 的安裝問題
• Azure/data-api-builder GitHub 存放庫中的已知問題

後續步驟

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