Azure Functions Go 開發人員參考

Azure Functions 是一個無伺服器運算服務,你可以用它來執行事件驅動的程式碼,而不需要配置或管理基礎設施。 Go worker 讓您能以 Go 原生撰寫 Azure Functions,並與 Azure Functions 的觸發程序生態系統深度整合。

本指南能幫助你:

  • 了解 Go 程式設計模型
  • 建立並結構化你的專案程式碼
  • 使用觸發程序
  • 部署並執行你的應用程式,無論是在本地還是在 Azure 裡

想了解更多Azure Functions開發的一般知識,請參閱 Azure Functions 開發者參考。

入門指南

選擇適合你工作流程的環境,開始使用 Azure Functions for Go:

Prerequisites

  • 升級到 1.24 或更新版本
  • Azure Functions Core Tools版本4.12或更新版本。 執行 func --version 以確認已安裝的版本。
  • Azure CLI 版本 2.87.0 或更高版本,當你建立 Azure 資源或部署套件到 Azure 時。 執行 az version 以確認已安裝的版本。

程式設計模型

Go 工作者採用以程式碼為先的程式設計模型。 你可以使用符合 Go 慣例的處理常式來定義無伺服器函式及其觸發程序。

入口

每個 Go 程式專案都是從一個 main() 函式開始,該函式會建立一個 FunctionApp、註冊函式,並啟動 worker:

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 建構器 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()

Event Hubs 與 服務匯流排 也支援強型別的批次處理程序,透過 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)

Durable Functions for Go 需要 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"
    }
}

對於 Go 專案來說,產生 AzureWebJobsStorage 的值是空的。 當您在本機開發期間使用需要主機儲存體的觸發程序時,請將其設定為儲存體帳戶連接字串或 UseDevelopmentStorage=true。

Deployment

合輯與包裝

Azure Functions Core Tools 版本 4.12 或更新版本可處理 Go 編譯,適用於常見的本地及Azure部署流程:

  • func start 在啟動本地 Functions 主機之前,先將你的專案建置為本地作業系統的 bin/app 。
  • 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 .

使用核心工具部署

使用 func azure functionapp publish 將您的 Go 專案部署至 Azure 中現有的函式應用程式:

func azure functionapp publish <APP_NAME>

以函式應用程式的名稱取代 <APP_NAME>。

部署一個 zip 套件

當你需要建立部署套件,而非透過發佈時,請使用 func pack:

  1. 建立可部署的壓縮壓縮件件:

    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 Worker OpenTelemetry 中介軟體。 關於設定說明,請參見 使用 OpenTelemetry with Azure Functions。

已知的限制

  • 不支援 func new。 直接編輯 main.go 來新增功能。
  • Go 功能應用程式只能在 Linux 上以 Flex Consumption 方案運行。
  • 僅支援 Triggers 中列出的專用觸發器及相容的 通用主機觸發器。
  • 目前不支援額外的輸入綁定和非 HTTP 輸出綁定。
  • Core Tools 中的 Go 封裝目前主要針對 Linux x64 應用程式。

下一步