azure-data-api-builder

Azure Data Api Builder 技能

此技能为 Azure Data Api Builder 提供专家指导，涵盖故障排除、最佳实践、决策制定、限制与配额、安全性、配置、集成与编码模式，以及部署。它结合了本地快速参考内容与远程文档获取功能。

如何使用此技能

IMPORTANT for Agent：使用下方的类别索引查找相关章节。对于标注了行范围的类别（例如 L35-L120），请使用 read_file 读取指定行。对于带有文件链接的类别（例如 [security.md](security.md)），请使用 read_file 读取链接指向的参考文件

IMPORTANT for Agent：如果 metadata.generated_at 距今已超过 3 个月，请建议用户从存储库拉取最新版本。如果无法使用 mcp_microsoftdocs 工具，请建议用户安装该工具：安装指南

此技能需要网络访问权限才能获取文档内容：

• 首选：使用 mcp_microsoftdocs:microsoft_docs_fetch，并将查询字符串设为 from=learn-agent-skill。返回 Markdown。
• 备用：使用 fetch_webpage，并将查询字符串设为 from=learn-agent-skill&accept=text/markdown。返回 Markdown。

类别索引

类别	行	说明
故障排除	L36-L48	诊断和修复 DAB 问题：配置/CLI 错误、REST/CORS 问题、GraphQL 架构/身份验证问题，以及 Cosmos DB、SQL（包括 MCP）、MySQL 和 PostgreSQL 特有的数据库问题。
最佳实践	L49-L55	关于安全、可靠地配置 Data API builder，向 SQL MCP 实体添加语义元数据，以及安全地将 SQL MCP Server 与本地大模型配合使用的指导。
决策制定	L56-L61	比较 Data API builder 在不同数据库/API 类型上的功能，并为你的设置选择安全的 Microsoft SQL 身份验证/授权模式。
限制与配额	L62-L69	配置 SQL 超时、设置和调整 REST/GraphQL 页面大小限制，以及了解 Data API builder 中特定于数据库的约束和功能要求。
安全性	L70-L90	配置 Data API builder 的身份验证、授权和行级安全性，包括 Entra ID、JWT、EasyAuth、托管标识、模拟器和 SQL 身份验证，以及安全最佳实践。
配置	L91-L133	配置 Data API builder：CLI 设置、JSON 架构、实体、数据源、安全性、缓存、遥测、日志记录、运行状况检查、OpenAPI，以及通过 REST/GraphQL 公开数据库对象。
集成与编码模式	L134-L149	DAB 中的 GraphQL/REST 查询模式：筛选、排序、分页、字段投影、导出架构、批量处理变更，以及通过 AI Agent 使用 SQL MCP 工具。
部署	L150-L158	如何从源代码或 Docker 构建并运行 Data API builder，以及如何将其部署到 Azure（App Service、Cosmos DB、隔离网络/本地 SQL），并提供配置和特定于环境的指导。

故障排查

主题	URL
验证 DAB 配置并解读 CLI 退出代码	https://learn.microsoft.com/en-us/azure/data-api-builder/command-line/dab-validate
解决 Data API builder 中的常见问题	https://learn.microsoft.com/en-us/azure/data-api-builder/faq
排查 Data API builder 中的 Azure Cosmos DB 问题	https://learn.microsoft.com/en-us/azure/data-api-builder/troubleshooting/cosmos
排查 DAB 中的 GraphQL 架构和授权问题	https://learn.microsoft.com/en-us/azure/data-api-builder/troubleshooting/graphql
排查 Data API builder 中的 SQL MCP Server 问题	https://learn.microsoft.com/en-us/azure/data-api-builder/troubleshooting/mcp
排查 Data API builder 中的 SQL Server 问题	https://learn.microsoft.com/en-us/azure/data-api-builder/troubleshooting/mssql
排查 Data API builder 中的 MySQL 问题	https://learn.microsoft.com/en-us/azure/data-api-builder/troubleshooting/mysql
排查 Data API builder 中的 PostgreSQL 问题	https://learn.microsoft.com/en-us/azure/data-api-builder/troubleshooting/postgresql
排查 DAB 中的 REST 终结点和 CORS 问题	https://learn.microsoft.com/en-us/azure/data-api-builder/troubleshooting/rest

最佳实践

主题	URL
在 Data API builder 中应用配置最佳实践	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/config/best-practices
为 SQL MCP Server 实体添加语义描述	https://learn.microsoft.com/en-us/azure/data-api-builder/mcp/how-to-add-descriptions
安全、可靠地将 SQL MCP Server 与本地 LLM 配合使用	https://learn.microsoft.com/en-us/azure/data-api-builder/mcp/use-local-models

决策

主题	URL
按数据库和 API 比较 Data API builder 的功能	https://learn.microsoft.com/en-us/azure/data-api-builder/feature-availability
为 Data API builder 选择 Microsoft SQL 安全模式	https://learn.microsoft.com/en-us/azure/data-api-builder/quickstart/microsoft-sql-security

限制和配额

主题	URL
为 Data API builder 配置 SQL 命令超时	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/database/timeout
使用 DAB 中的 first 限制 GraphQL 页面大小	https://learn.microsoft.com/en-us/azure/data-api-builder/keywords/first-graphql
使用 DAB 中的 $first 控制 REST 页面大小	https://learn.microsoft.com/en-us/azure/data-api-builder/keywords/first-rest
Data API builder 的数据库特定功能要求	https://learn.microsoft.com/en-us/azure/data-api-builder/reference-database-specific-features

安全性

主题	URL
在 Data API builder 中选择并配置身份验证模型	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/security/
为 Data API builder 配置自定义 JWT 身份验证	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/security/authenticate-custom
在 Data API builder 中使用 Azure App Service EasyAuth	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/security/authenticate-easy-auth
为 Data API builder 配置 Microsoft Entra ID 身份验证	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/security/authenticate-entra
为 DAB SQL 访问配置代表身份验证	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/security/authenticate-on-behalf-of
使用 Simulator 身份验证进行本地 DAB 测试	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/security/authenticate-simulator
在 Data API builder 中配置 Unauthenticated 提供程序	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/security/authenticate-unauthenticated
在 Data API builder 中应用安全最佳实践	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/security/best-practices
为 DAB 中的行级筛选配置数据库策略	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/security/database-policies
使用 DAB 会话上下文实现 SQL 行级安全性	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/security/row-level-security
为 SQL MCP Server 和数据库配置身份验证	https://learn.microsoft.com/en-us/azure/data-api-builder/mcp/how-to-configure-authentication
为 Data API builder 访问 Azure SQL 使用托管标识	https://learn.microsoft.com/en-us/azure/data-api-builder/quickstart/authentication-managed-identity
向 Data API builder 添加 Microsoft Entra 身份验证提供程序	https://learn.microsoft.com/en-us/azure/data-api-builder/quickstart/authentication-microsoft-entra-provider
配置从 Data API builder 到 Azure SQL 的代表身份验证	https://learn.microsoft.com/en-us/azure/data-api-builder/quickstart/authentication-on-behalf-of
为 Data API builder 终结点配置 SQL 身份验证	https://learn.microsoft.com/en-us/azure/data-api-builder/quickstart/authentication-sql-credentials
使用 Entra ID 和 DAB 策略保护 Data API builder	https://learn.microsoft.com/en-us/azure/data-api-builder/quickstart/authorization-database-policies
使用 Data API builder 应用 SQL 行级安全性	https://learn.microsoft.com/en-us/azure/data-api-builder/quickstart/authorization-sql-row-level-security

配置

主题	URL
使用 DAB CLI 命令管理配置和运行时	https://learn.microsoft.com/en-us/azure/data-api-builder/command-line/
使用 OpenTelemetry 和 App Insights 配置 DAB 遥测	https://learn.microsoft.com/en-us/azure/data-api-builder/command-line/dab-add-telemetry
通过 dab auto-config 创建和管理自动实体	https://learn.microsoft.com/en-us/azure/data-api-builder/command-line/dab-auto-config
使用 dab auto-config-simulate 模拟自动实体匹配	https://learn.microsoft.com/en-us/azure/data-api-builder/command-line/dab-auto-config-simulate
配置 DAB 运行时和数据源设置	https://learn.microsoft.com/en-us/azure/data-api-builder/command-line/dab-configure
使用 DAB CLI 初始化 Data API builder 配置	https://learn.microsoft.com/en-us/azure/data-api-builder/command-line/dab-init
通过 CLI 更新 Data API builder 实体配置	https://learn.microsoft.com/en-us/azure/data-api-builder/command-line/dab-update
通过 HTTP 标头控制 Data API builder 缓存	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/cache/http-headers
在 Data API builder 中配置基于 Redis 的二级缓存	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/cache/level-2
在 DAB 中将 @akv 函数与 Azure Key Vault 配合使用	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/config/akv-function
在 Data API builder 中使用自动配置模式	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/config/auto-config
使用 @env 函数配置 DAB 密钥	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/config/env-function
按环境变体管理 DAB 配置	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/config/environments
为混合 DAB 终结点配置多个数据源	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/config/multi-config
为 DAB 配置 Azure Cosmos DB for NoSQL	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/database/set-up-cosmosdb
在 DAB 中配置 GraphQL 实体关系	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/graphql/relationships
在 DAB 中将存储过程公开为 GraphQL 操作	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/graphql/stored-procedures
在 DAB 中将数据库视图公开为 GraphQL 类型	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/graphql/views
为 DAB 监视配置 Azure Application Insights	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/monitor/application-insights
在 DAB 中配置运行状况检查和 /health 终结点	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/monitor/health-checks
为 DAB 日志记录配置 Azure Log Analytics	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/monitor/log-analytics
配置 Data API builder 日志级别和筛选器	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/monitor/log-levels
在 DAB 中设置 OpenTelemetry 跟踪和指标	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/monitor/open-telemetry
为 DAB upsert 配置 If-Match 标头	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/rest/http-if-match
了解 DAB REST 中 Location 标头的行为	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/rest/http-location
为 DAB REST 配置 OpenAPI 和 Swagger UI	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/rest/openapi
在 DAB 中将存储过程公开为 REST 终结点	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/rest/stored-procedures
在 DAB 中将数据库视图公开为 REST 终结点	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/rest/views
配置 Data API builder 中的角色继承	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/security/role-inheritance
配置完整的 Data API builder JSON 架构	https://learn.microsoft.com/en-us/azure/data-api-builder/configuration/
配置完整的 Data API builder JSON 架构	https://learn.microsoft.com/en-us/azure/data-api-builder/configuration/
配置 Data API builder 自动实体规则	https://learn.microsoft.com/en-us/azure/data-api-builder/configuration/autoentities
配置 Data API builder 数据库数据源部分	https://learn.microsoft.com/en-us/azure/data-api-builder/configuration/data-source
配置 Data API builder 实体部分架构	https://learn.microsoft.com/en-us/azure/data-api-builder/configuration/entities
配置 Data API builder 实体定义	https://learn.microsoft.com/en-us/azure/data-api-builder/configuration/entities
配置 Data API builder 的运行时部分	https://learn.microsoft.com/en-us/azure/data-api-builder/configuration/runtime
配置 Data API builder 运行时行为	https://learn.microsoft.com/en-us/azure/data-api-builder/configuration/runtime
为 SQL MCP Server 中的存储过程配置自定义 MCP 工具	https://learn.microsoft.com/en-us/azure/data-api-builder/mcp/how-to-configure-custom-tools
在 stdio 传输模式下运行 SQL MCP Server	https://learn.microsoft.com/en-us/azure/data-api-builder/mcp/stdio-transport

集成与编码模式

主题	URL
使用 DAB CLI 导出 GraphQL 架构	https://learn.microsoft.com/en-us/azure/data-api-builder/command-line/dab-export
在 Data API builder 中通过 GraphQL 查询聚合数据	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/graphql/aggregate-data
在 Data API builder 中执行多个 GraphQL 变更	https://learn.microsoft.com/en-us/azure/data-api-builder/concept/graphql/multiple-mutations
在 DAB 中使用 after 游标进行 GraphQL 分页	https://learn.microsoft.com/en-us/azure/data-api-builder/keywords/after-graphql
在 DAB REST 中使用 $after 实现游标分页	https://learn.microsoft.com/en-us/azure/data-api-builder/keywords/after-rest
使用 DAB 专用运算符筛选 GraphQL 查询	https://learn.microsoft.com/en-us/azure/data-api-builder/keywords/filter-graphql
在 DAB 中使用 $filter 筛选 REST 查询	https://learn.microsoft.com/en-us/azure/data-api-builder/keywords/filter-rest
在 DAB 中使用 orderBy 对 GraphQL 结果排序	https://learn.microsoft.com/en-us/azure/data-api-builder/keywords/orderby-graphql
在 DAB 中使用 $orderby 对 REST 结果排序	https://learn.microsoft.com/en-us/azure/data-api-builder/keywords/orderby-rest
在 DAB 中调整 GraphQL 选择项和内部列	https://learn.microsoft.com/en-us/azure/data-api-builder/keywords/select-graphql
在 DAB 中使用 $select 投影 REST 字段	https://learn.microsoft.com/en-us/azure/data-api-builder/keywords/select-rest
在 AI Agent 中使用 SQL MCP Server DML 工具	https://learn.microsoft.com/en-us/azure/data-api-builder/mcp/data-manipulation-language-tools

部署

主题	URL
在 Azure 中选择 Data API builder 部署选项	https://learn.microsoft.com/en-us/azure/data-api-builder/deployment/
在隔离网络环境中部署 Data API builder	https://learn.microsoft.com/en-us/azure/data-api-builder/deployment/air-gapped
将 Data API builder 部署到 Azure App Service	https://learn.microsoft.com/en-us/azure/data-api-builder/deployment/azure-app-service
从源代码构建并运行 Data API builder	https://learn.microsoft.com/en-us/azure/data-api-builder/deployment/run-from-source
使用 Azure Cosmos DB NoSQL 部署 Data API builder	https://learn.microsoft.com/en-us/azure/data-api-builder/quickstart/basic-nosql
使用 Docker 部署带本地 SQL 的 Data API builder	https://learn.microsoft.com/en-us/azure/data-api-builder/quickstart/basic-sql