你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。

Azure Functions Go 开发人员参考

Azure Functions是一种无服务器计算服务,可用于运行事件驱动代码,而无需预配或管理基础结构。 Go 工作进程使你能够使用 Go 原生编写 Azure Functions,并与 Azure Functions 触发器生态系统深度集成。

本指南可帮助你:

  • 了解 Go 编程模型
  • 创建和构建项目代码
  • 使用触发器
  • 在本地和Azure中部署和运行应用

若要了解一般Azure Functions开发的详细信息,请参阅 Azure Functions 开发人员参考。

入门

选择适合工作流的环境,开始使用 Azure Functions for Go:

先决条件

  • Go 1.24 或更高版本
  • Azure Functions Core Tools4.12 或更高版本。 运行 func --version 以验证已安装的版本。
  • 创建 Azure 资源或将包部署到 Azure 时,需要使用 Azure CLI 版本 2.87.0 或更高版本。 运行 az version 以验证已安装的版本。

编程模型

Go 工作器使用代码优先的编程模型。 使用惯用的 Go 处理程序定义无服务器函数及其触发器。

入口点

每个 Go 项目都以一个main()函数开头,该函数会创建一个FunctionApp、注册函数并启动工作器:

package main

import (
    "fmt"
    "net/http"

    "github.com/azure/azure-functions-golang-worker/sdk"
    "github.com/azure/azure-functions-golang-worker/worker"
)

func main() {
    app := sdk.FunctionApp()

    app.HTTP("hello", hello,
        sdk.WithMethods("GET", "POST"),
        sdk.WithAuth("anonymous"),
    )

    worker.Start(app)
}

func hello(w http.ResponseWriter, r *http.Request) {
    name := r.URL.Query().Get("name")
    if name == "" {
        name = "world"
    }
    fmt.Fprintf(w, "Hello, %s!", name)
}

函数注册

使用 Fluent Builder API 和功能选项模式注册函数。 每个触发器类型对 App 对象都有一个注册方法:

// HTTP trigger
app.HTTP("myHttpFunc", handler,
    sdk.WithMethods("GET", "POST"),
    sdk.WithAuth("anonymous"),
)

// Timer trigger
app.Timer("myTimerFunc", handler,
    sdk.WithSchedule("0 */5 * * * *"),
)

// Azure Cosmos DB trigger
app.CosmosDB("myCosmosFunc", handler,
    sdk.WithDatabase("mydb"),
    sdk.WithContainer("mycontainer"),
    sdk.WithConnection("CosmosDBConnection"),
)

// Azure Queue Storage trigger
app.Queue("myQueueFunc", handler,
    sdk.WithQueueName("myqueue"),
    sdk.WithConnection("AzureWebJobsStorage"),
)

// Azure Service Bus trigger
app.ServiceBusQueue("myServiceBusFunc", handler,
    sdk.WithQueueName("myqueue"),
    sdk.WithConnection("ServiceBusConnection"),
)

// Azure SQL trigger
app.SQL("mySqlFunc", handler,
    sdk.WithTable("dbo.Products"),
    sdk.WithConnection("SqlConnectionString"),
)

// Event Hubs trigger
app.EventHub("myEventHubFunc", handler,
    sdk.WithEventHubName("myeventhub"),
    sdk.WithConnection("EventHubConnection"),
)

// Event Grid trigger
app.EventGrid("myEventGridFunc", handler)

// Blob trigger (extension model)
app.Blob("myBlobFunc", handler,
    sdk.WithPath("mycontainer/{name}"),
    sdk.WithConnection("AzureWebJobsStorage"),
)

项目结构

Azure Functions的 Go 代码项目是标准的 Go 模块。 运行 func init --worker-runtime go时,将生成以下文件:

my-function-app/
├── host.json              # Host configuration
├── local.settings.json    # Local settings (connection strings, app settings)
├── go.mod                 # Go module file
├── go.sum                 # Go module checksums
└── main.go                # Entry point with function registrations

host.json

该文件 host.json 包含主机级配置选项。 有关详细信息,请参阅 host.json 参考。

local.settings.json

该文件 local.settings.json 存储本地开发期间使用的应用设置和连接字符串。 此文件未发布到Azure。 有关详细信息,请参阅本地设置文件。

触发器

Go Worker 为支持的触发器提供专用的注册方法。

类型化触发器有效负载

大多数受支持的触发器通过 gRPC 以内联方式接收有效载荷。 Azure Functions 主机将触发数据序列化为 gRPC 消息,工作者将其反序列化为类型化的 Go 值。 这些触发器具有:

  • 具备编译时安全性的类型化处理程序签名
  • 不需要外部Azure SDK依赖项:只需要encoding/json
  • 有限有效负载:更改源文档、消息和事件是离散的、大小有限的对象

支持的触发器:

Trigger 处理程序签名 注册方法
HTTP func(http.ResponseWriter, *http.Request) app.HTTP()
Timer TimerHandler app.Timer()
Azure 队列存储 QueueHandler app.Queue()
Azure Cosmos DB func(context.Context, []bindings.CosmosDocument) error app.CosmosDB()
Azure 服务总线(队列) ServiceBusHandler app.ServiceBusQueue()
Azure 服务总线 (主题) ServiceBusHandler app.ServiceBusTopic()
事件中心 EventHubHandler app.EventHub()
事件网格 EventGridHandler app.EventGrid()
Azure SQL func(context.Context, []bindings.SQLChange) error app.SQL()

事件中心和服务总线还通过 app.EventHubBatch()、app.ServiceBusQueueBatch() 和 app.ServiceBusTopicBatch() 支持强类型批处理处理程序。

SDK 类型绑定

SDK 类型的绑定提供认证的 Azure SDK 客户端,而非序列化的触发数据。 对于 Go 来说,Blob 存储 触发器支持 SDK 类型的绑定。 主机发送元数据,如容器名称和 blob 路径,工作者构建一个针对特定资源的客户端。 SDK 类型绑定提供:

  • SDK 客户端注入:处理程序接收随时可用的客户端
  • 隔离的依赖项:Azure SDK 包位于 triggers/<name>/
  • 流式处理支持:支持在不通过 gRPC 缓冲的情况下读取大型有效负载

要使用 Blob 存储 SDK 类型的绑定,请为 Blob 触发包添加一个空白导入:

import _ "github.com/azure/azure-functions-golang-worker/triggers/blob"
Trigger 处理程序接收 注册方法
Blob 存储 *blob.Client app.Blob()

Blob 触发器示例

package main

import (
    "context"
    "fmt"
    "io"
    "log"

    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/blob"
    "github.com/azure/azure-functions-golang-worker/sdk"
    _ "github.com/azure/azure-functions-golang-worker/triggers/blob"
    "github.com/azure/azure-functions-golang-worker/worker"
)

func main() {
    app := sdk.FunctionApp()
    app.Blob("processBlobTrigger", processBlob,
        sdk.WithPath("samples-workitems/{name}"),
        sdk.WithConnection("AzureWebJobsStorage"),
    )
    worker.Start(app)
}

func processBlob(ctx context.Context, client *blob.Client) error {
    get, err := client.DownloadStream(ctx, nil)
    if err != nil {
        return fmt.Errorf("download error: %w", err)
    }
    data, _ := io.ReadAll(get.Body)
    get.Body.Close()
    log.Printf("Blob size: %d bytes", len(data))
    return nil
}

通用宿主触发器

当兼容的主机扩展提供没有专门的 Go 注册方法的触发器时,使用 app.GenericTrigger()。 通用触发器支持原始文本、字节切片和兼容 JSON 的 Go 类型:

app.GenericTrigger("echoTool", echoTool, &bindings.GenericTrigger{
    Type:     "mcpToolTrigger",
    Name:     "call",
    DataType: "string",
    Properties: map[string]any{
        "toolName":       "echo",
        "description":    "Echo text using a generic Go trigger",
        "toolProperties": `[{"propertyName":"text","propertyType":"string","description":"Text to echo","isRequired":true}]`,
    },
})

必须安装兼容的主机扩展。 通用触发器注册不提供HTTP处理、SDK客户端注入、Durable Functions重放或服务特定的消息处置。 完整示例请参见 通用触发示例。

HTTP 触发器

HTTP 触发器处理程序使用标准的 Go net/http 类型,因此 Go 开发者会立刻感到熟悉:

func myHandler(w http.ResponseWriter, r *http.Request) {
    name := r.URL.Query().Get("name")
    if name == "" {
        name = "world"
    }
    w.Header().Set("Content-Type", "application/json")
    fmt.Fprintf(w, `{"message": "Hello, %s!"}`, name)
}

注册带有方法和授权级别的 HTTP 函数:

app.HTTP("myApi", myHandler,
    sdk.WithMethods("GET", "POST"),
    sdk.WithAuth("anonymous"),
)

HTTP 流式传输

Go 工作器支持 HTTP 流式传输,适用于服务器发送事件或发送大量响应数据等场景:

func streamHandler(w http.ResponseWriter, r *http.Request) {
    flusher, ok := w.(http.Flusher)
    if !ok {
        http.Error(w, "streaming not supported", http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "text/event-stream")
    for i := 0; i < 10; i++ {
        fmt.Fprintf(w, "data: message %d\n\n", i)
        flusher.Flush()
    }
}

定时触发器

计时器触发器按 cron 表达式定义的计划运行:

app.Timer("myScheduledFunc", timerHandler,
    sdk.WithSchedule("0 */5 * * * *"),
)

func timerHandler(ctx context.Context, timer bindings.TimerInfo) error {
    log.Printf("Timer trigger executed at: %s", timer.ScheduleStatus.Next)
    return nil
}

Durable Functions

Go 通过 软件包支持 middleware/durabletask 的编排和活动。 在将中间件添加到函数应用之前,先用 Durable 中间件注册编排器和活动:

durable := durabletask.Middleware()
durable.Orchestrator("HelloCities", helloCities)
durable.Activity("SayHello", sayHello)
app.Use(durable)

Go 版 Durable Functions 需要 Durable Task 扩展版本 3.15.0 或更高版本。 当前不支持实体。 完整应用请参见Durable Functions示例。

依赖管理

Go 代码项目使用标准 Go 模块进行依赖项管理。

  1. 初始化新模块:

    go mod init myapp
    
  2. 添加 Azure Functions Go 工作器 SDK:

    go get github.com/azure/azure-functions-golang-worker
    

    对于 Blob 触发器的支持,依赖项会通过 triggers/blob 的空白导入自动包含。

  3. 整理依赖项:

    go mod tidy
    

在本地运行

使用 Azure Functions Core Tools 在本地运行项目:

func start

Core Tools 会自动:

  1. 从 FUNCTIONS_WORKER_RUNTIME = "native" 中检测 local.settings.json。
  2. 当存在 go.mod 文件时,将原生工作器运行时解析为 Go。
  3. 运行 go build -o bin/app . 以根据您的本地操作系统编译项目。
  4. 启动Azure Functions主机,该主机通过 gRPC 与编译的二进制文件通信。
  5. 显示函数终结点(例如 http://localhost:7071/api/hello)。

使用 local.settings.json 配置用于本地开发的环境变量:

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "",
        "FUNCTIONS_WORKER_RUNTIME": "native"
    }
}

AzureWebJobsStorage生成的值对于 Go 项目为空。 在本地开发期间使用需要主机存储的触发器时,请将其设置为存储帐户连接字符串或 UseDevelopmentStorage=true。

部署

编译和打包

Azure Functions Core Tools 版本 4.12 或更高版本可处理常见本地和 Azure 部署流程中的 Go 构建:

  • func start 会先将你的项目构建为适用于你的本地操作系统的 bin/app,然后再启动本地 Functions 主机。
  • func azure functionapp publish生成、打包项目并将其部署到Azure中的现有函数应用。
  • func pack 将你的项目构建为适用于 Linux x64 的 bin/app,并创建可部署的 .zip 包。

打包Azure时,生成的 .zip 文件包含 Linux Functions 主机所需的文件。 编译的二进制文件作为 bin/app 存储在本地项目中,但 Core Tools 将其放在部署包的根目录中作为 应用。

如果使用 func pack --no-build,则必须在打包之前生成 Linux x64 二进制文件:

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o bin/app .

使用 Core Tools 进行部署

使用 func azure functionapp publish 将 Go 项目部署到 Azure 中的现有函数应用:

func azure functionapp publish <APP_NAME>

将 <APP_NAME> 替换为你的函数应用的名称。

部署 zip 包

当需要单独创建部署包与发布时使用 func pack :

  1. 创建可部署的 ZIP 构件:

    func pack
    
  2. 使用Azure CLI部署包:

    az functionapp deployment source config-zip --resource-group <RESOURCE_GROUP> --name <APP_NAME> --src <ZIP_FILE_PATH>
    

func pack 生成的包已准备好在 Azure 中运行,因此在部署它时不要请求远程构建。

Docker 支持

可以在容器中运行 Go 代码项目。 初始化一个支持 Docker 的项目:

func init --worker-runtime go --docker

该命令会生成一个 Dockerfile 以及标准项目文件。

遥测和可观测性

Azure Functions Go 工作器支持结构化日志记录和基于 OpenTelemetry 的可观测性。 使用标准 log/slog 包中的上下文感知方法(例如 slog.InfoContext)将日志与当前函数调用相关联。 若要启用 OpenTelemetry,请在应用中配置 Functions 主机并注册 Go 辅助角色 OpenTelemetry 中间件。 有关设置说明,请参阅 将 OpenTelemetry 与 Azure Functions。

已知的限制

  • 不支持 func new。 通过直接编辑 main.go 来添加函数。
  • Go 函数应用只能在 Linux 上以 Flex Consumption 计划运行。
  • 仅支持 Triggers 中列出的专用触发器和 兼容的通用主机触发器。
  • 目前不支持额外的输入绑定和非HTTP输出绑定。
  • Core Tools 中的 Go 打包目前面向 Linux x64 应用。

后续步骤