排查 Azure 数据库的数据 API 生成器使用情况问题

项目
07/30/2024

本文提供了使用 Azure 数据库的数据 API 生成器时可能发生的常见错误的解决方案。

通用终结点：HTTP 400“错误请求”错误

以下部分介绍 HTTP 400“错误请求”错误的原因和解决方案。

数据 API 生成器终结点无效

URL 路径组件的基数映射到数据 API 生成器的 REST 或 GraphQL 终结点。当 URL 路径组件的基数与数据 API 生成器的运行时配置中设置的值不匹配时，数据 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 应用使用数据库连接功能时，URL 路径以/data-api开头。可以在此值后添加所需终结点的值。例如， /data-api/api/<entity> 对于 REST 和 /data-api/graphql GraphQL。

静态Web 应用数据库连接配置问题

将数据 API 生成器与静态Web 应用数据库连接功能配合使用时，在响应正文中遇到错误“响应状态代码不指示成功：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 服务和资源访问此服务器”，以便在 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 生成器在响应有效负载中返回描述性错误和错误详细信息。

向 GraphQL 终结点发送 GET 请求时，返回的错误的响应正文表示“必须设置参数查询或参数 ID”。请确保使用 HTTP POST发送 GraphQL 请求。

GraphQL 终结点：HTTP 404“找不到”错误

请确保使用 HTTP POST 方法将 GraphQL 请求发送到配置的 GraphQL 终结点。默认情况下，GraphQL 终结点路由为 /graphql。

GraphQL 终结点：“对象类型查询必须至少定义一个字段才能有效”错误

当数据 API 生成器启动无法基于运行时配置生成 GraphQL 架构时，会收到错误消息：

对象类型 Query 必须至少定义一个字段才能有效。

GraphQL 规范要求在 GraphQL 架构中至少定义一个 Query 对象。必须验证运行时配置是否满足以下条件之一：

为至少一个已启用 GraphQL 的实体定义该 read 操作。 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 生成器使用的数据库对象仍然可用且可访问。

若要允许数据 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（访问令牌受众错误）。
访问令牌不是由预期颁发机构（无效访问令牌颁发者）创建的。

若要解决此错误，请确保满足以下条件：

使用 issuer 运行时配置部分中定义的 authentication 值生成访问令牌。
为运行时配置部分中定义的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“禁止”错误

如果使用静态Web 应用集成或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": [ "*" ]
}

参考

下一步

如果问题未解决，请在 data-api-builder 讨论中提供反馈或报告。

联系我们寻求帮助

如果你有任何疑问或需要帮助，请创建支持请求或联系 Azure 社区支持。你还可以将产品反馈提交到 Azure 反馈社区。

通过