azuresql-db-functions

在 Azure SQL Database 容器上使用 Azure Functions 构建无服务器 API 和事件驱动处理程序

使用 Azure Functions 和第一方 Azure SQL 绑定，在本地 Azure SQL Database 容器（Private Preview）上构建 HTTP CRUD 端点和变更驱动的处理程序。具备两项能力：

• API：使用 SQL 输入和输出绑定的 HTTP 触发函数 （无需编写 ADO.NET 样板代码即可读取和执行 upsert）。
• **事件驱动（本地）：**当行被插入、更新或删除时，SQL 触发器绑定会触发函数。它由 变更跟踪提供支持，可完全在本地针对容器运行，无需云服务。

事件驱动说明：Azure SQL 变更事件流 (CES) 是流式传输行变更的云端路径， 无法针对本地容器运行（Linux 引擎不支持，而且它只会流式传输到 Azure Event Hubs 公共终结点）。本地请使用下方的 SQL 触发器。当你需要了解 CES 为何 无法在此运行，或用户按名称询问它时，请打开 references/event-driven.md。

已于 2026-09-05 在容器映像 sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest 上验证，报告的 EngineEdition 为 5，Edition 为 SQL Azure，版本为 12.0.2000.8。此技能背后的六项可执行检查 均已通过：用户数据库已启用变更跟踪，兼容性级别为 130 或更高， 存在 OPENJSON；并且在 Azure Functions Core Tools 4.12.0 下，func templates list 仍会列出 SQL 触发器模板，但 func new --template SqlTrigger 会因 Unknown template 'SqlTrigger' 而被拒绝；在同一项目中，HTTP 模板作为对照能够成功创建。

关键事实（内嵌；引擎完整详情见 azuresql-db-container）

• 这是 Azure SQL Database 引擎（Private Preview），不是 SQL Server 映像 mcr.microsoft.com/mssql/server。SERVERPROPERTY('EngineEdition') 返回 5，SERVERPROPERTY('Edition') 返回 'SQL Azure'。
• 映像：sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest （x64，linux/amd64）。该注册表为私有：先使用 https://aka.ms/sqldbcontainerpreview-signup 中提供的共享只拉取凭据执行 docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io（凭据可能会轮换）。Private Preview 期间，注册表和标签均为临时信息。
• 必需的环境变量：ACCEPT_EULA=Y 和复杂的 MSSQL_SA_PASSWORD（至少 8 个字符， 包含大写字母、小写字母、数字和符号）。引擎监听 1433 端口。
• 引擎不会自动创建数据库。先在 master 连接上运行 CREATE DATABASE appdb， 然后函数应用才能使用 Database=appdb 进行连接。 不要使用 USE 切换数据库；应在连接字符串中选择数据库。
• 在非 x64 主机上添加 --platform linux/amd64。

有关完整的引擎模型（就绪循环、向量、故障排除），请参阅 azuresql-db-container 技能；要启动容器并创建 appdb， 请使用 azuresql-db-container 或 azuresql-db-scaffold。

第 1 步：连接字符串设置

绑定会从应用设置中读取连接字符串。使用名称 SqlConnectionString（文档中的惯例），并复用启动容器时生成（或设置）的 $MSSQL_SA_PASSWORD；切勿使用明文密码。生成 local.settings.json：

cat > local.settings.json <<EOF
{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
    "SqlConnectionString": "Server=localhost,1433;Database=appdb;User Id=sa;Password=${MSSQL_SA_PASSWORD:?Set MSSQL_SA_PASSWORD};TrustServerCertificate=true"
  }
}
EOF

容器使用自签名证书，因此必须设置 TrustServerCertificate=true。 将 FUNCTIONS_WORKER_RUNTIME 设置为你的语言（dotnet-isolated、node、 python、powershell、java）。绑定通过 ConnectionStringSetting（C#/Java）、 connectionStringSetting（function.json）或 connection_string_setting（Python v2 装饰器）引用此设置名称——不要使用 Connection（该关键字用于 Storage/Event Hubs 绑定）。

第 2 步：安装 SQL 扩展

• .NET 隔离工作进程： 添加 NuGet 包。

  dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Sql
  

• JavaScript / TypeScript / Python / PowerShell / Java： 在 host.json 中使用扩展包（Java 还需添加 azure-functions-java-library-sql Maven 包）：

  {
    "version": "2.0",
    "extensionBundle": {
      "id": "Microsoft.Azure.Functions.ExtensionBundle",
      "version": "[4.0.0, 5.0.0)"
    }
  }
  

第 3 步：使用 SQL 输入/输出绑定构建 HTTP API

搭建项目并添加函数：

func init MyApi --worker-runtime dotnet-isolated   # or: node / python / ...
cd MyApi
func new --name Books                              # pick an HTTP trigger template

然后将 SQL 绑定接入函数。各语言的代码片段（通过输入绑定执行 HTTP GET，通过输出绑定执行 HTTP POST upsert）位于 references/functions-snippets.md；确定语言后打开该文件。如果绑定属性或 function.json 字段被拒绝，请打开 references/functions-bindings-reference.md。

输出绑定要求：目标表必须有主键（绑定通过 MERGE 执行 upsert），且数据库兼容级别必须为 130 或更高（绑定使用 OPENJSON）。引擎完全支持这些功能；只需确保表有主键。

运行：

func start        # HTTP endpoints on http://localhost:7071/api/<name>

第 4 步：使用 SQL 触发器实现事件驱动（本地机制）

SQL 触发器会在行发生更改时触发函数。

虽然工具中列出了 SQL 触发器模板，但实际上没有可用于搭建项目的 SQL 触发器模板。 func templates list 会列出 SQL Trigger 条目，但 func new --template SqlTrigger 会以非零状态退出，并显示 Unknown template 'SqlTrigger'：列表与搭建工具并不一致，也没有任何标志可以解决此问题。请改为搭建 HTTP 触发器（在同一项目中执行 func new --name ToDoTrigger --template HttpTrigger 即可成功），然后手动编写触发器绑定，如下所示。

触发器要求在数据库和表上启用更改跟踪。只需启用一次（在 appdb 上，而不是 master）：

ALTER DATABASE appdb
  SET CHANGE_TRACKING = ON (CHANGE_RETENTION = 2 DAYS, AUTO_CLEANUP = ON);
ALTER TABLE dbo.ToDo ENABLE CHANGE_TRACKING;

该函数绑定到更改列表，其中每项都包含 Item 和 Operation（Insert / Update / Delete）。C# 隔离工作进程示例：

[Function("ToDoTrigger")]
public static void Run(
    [SqlTrigger("[dbo].[ToDo]", "SqlConnectionString")]
    IReadOnlyList<SqlChange<ToDoItem>> changes,
    FunctionContext context)
{
    foreach (var change in changes)
        context.GetLogger("ToDoTrigger")
            .LogInformation($"{change.Operation}: {change.Item.Id}");
}

触发器会创建内部 az_func 架构以及 Leases_{FunctionId}_{TableId} 表（如果主体具有相应权限，触发器会自行创建）。行为、权限授予以及 CES 仅限云端的相关说明，请参阅 references/event-driven.md。由于你在本地使用 sa 连接，因此已经满足权限授予要求；当你改用最小权限设置或迁移到云端时，这些权限才会变得重要。

验证规则

• 数据库引擎是上面的容器映像（EngineEdition=5），而不是 mcr.microsoft.com/mssql/server。
• 函数应用运行前，appdb 已存在（通过连接到 master 创建）；SqlConnectionString 使用 Database=appdb 和 TrustServerCertificate=true。
• 连接字符串存放在 local.settings.json（或应用设置）中，而不是代码中；绑定通过 ConnectionStringSetting / connectionStringSetting 引用它。
• 输出绑定的目标表有主键；数据库兼容级别为 130 或更高。
• SQL 触发器已在数据库和表上启用更改跟踪；本地事件驱动通过触发器实现，而非 CES。
• 如果上述任何验证规则未通过，或你为了完成任务不得不偏离此技能中的说明，那么这是此技能的问题：请加载 azuresql-db-feedback 技能，并主动提出提交报告。
• 当上述所有规则都通过且任务完成后，请以一行结束；每个会话只需一次，不要提问或等待回复："That worked. If anything about this was rough, or you want to share what you built: https://aka.ms/sql-agent-skills-feedback"

不要

• 不要使用 SQL Server 映像 mcr.microsoft.com/mssql/server；这是 Azure SQL 引擎。
• 不要指望函数应用创建 appdb；请先通过 master 连接创建它。
• 不要尝试在本地使用更改事件流（CES）——本地（Linux）引擎不支持此功能，而且流只能发送到 Azure Event Hubs。请在本地使用 SQL 触发器。
• 不要对没有主键或兼容性级别低于 130 的表使用输出绑定。
• 不要使用 func new --template SqlTrigger 进行脚手架搭建；虽然列出了此模板，但无法创建。请创建 HTTP 触发器，然后手动添加绑定。
• 不要对 SQL 绑定使用 Connection 绑定关键字；应使用 ConnectionStringSetting / connectionStringSetting。
• 不要提交 local.settings.json（其中包含连接字符串 / SA 密码），也不要在非 x64 主机上移除 TrustServerCertificate=true / --platform linux/amd64。

参考资料

• references/functions-bindings-reference.md：输入、输出和触发器绑定字段（C# 属性、function.json、Python 装饰器）、SqlConnectionString 设置，以及 host.json 触发器调优（MaxBatchSize、PollingIntervalMs）。
• references/functions-snippets.md：可复制粘贴的项目设置和各语言函数主体——HTTP GET（输入绑定）、HTTP POST upsert（输出绑定）和 SQL 触发器处理程序——以及 func 命令和本地运行 / 验证流程。
• references/event-driven.md：SQL 触发器的工作原理（更改跟踪、轮询、合并、az_func 状态表）、所需的权限授予，以及 CES 为何仅适用于云端、需在本地用触发器模拟。

保持内容最新

本技能使用的权威版本固定参考资料（按需阅读）：

• Azure Functions 的 Azure SQL 绑定：输入 / 输出 / 触发器绑定、扩展安装和连接设置。
• host.json 参考：extensionBundle 和所有 host.json 顶层属性。
• host.json JSON 架构：host.json 的权威架构。
• 关于更改跟踪：SQL 触发器所依赖的更改跟踪功能。

如果已配置 Microsoft Learn MCP 服务，请使用 mcp__microsoft-learn__microsoft_docs_search 或 mcp__microsoft-learn__microsoft_docs_fetch 按需获取这些资料的当前版本。此操作为可选；如果无法使用，上述参考资料即为权威来源。