Azure Functions Go-Entwicklerreferenz

Azure Functions ist ein serverloser Computedienst, mit dem Sie ereignisgesteuerten Code ohne Bereitstellung oder Verwaltung der Infrastruktur ausführen können. Der Go-Worker ermöglicht es Ihnen, Azure Functions nativ in Go zu schreiben, mit einer tiefen Integration in das Azure Functions Trigger-Ökosystem.

Dieser Leitfaden hilft Ihnen bei:

• Grundlegendes zum Go-Programmiermodell
• Erstellen und Strukturieren des Projektcodes
• Mit Triggern arbeiten
• Bereitstellen und Ausführen Ihrer App lokal und in Azure

Weitere Informationen zur Azure Functions Entwicklung im Allgemeinen finden Sie in der Azure Functions Entwicklerreferenz.

Erste Schritte

Wählen Sie die Umgebung aus, die Ihrem Workflow entspricht, und beginnen Sie mit Azure Functions für Go:

• Schnellstart der Befehlszeile

Voraussetzungen

• Go 1.24 oder höher
• Azure Functions Core Tools Version 4.12 oder höher. Führen Sie func --version aus, um Ihre installierte Version zu überprüfen.
• Azure CLI Version 2.87.0 oder höher, wenn Sie Azure Ressourcen erstellen oder Pakete für Azure bereitstellen. Führen Sie az version aus, um Ihre installierte Version zu überprüfen.

Programmiermodell

Der Go-Worker verwendet ein Code-first-Programmiermodell. Sie definieren serverlose Funktionen und deren Trigger mithilfe von idiomatischen Go-Handlern.

Einstiegspunkt

Jedes Go-Codeprojekt beginnt mit einer main() Funktion, die eine FunctionAppFunktion erstellt, Funktionen registriert und den Worker startet:

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)
}

Funktionsregistrierung

Registrieren Sie Funktionen mithilfe der Fluent Builder-API mit dem Funktionsoptionenmuster. Jeder Triggertyp verfügt über eine Registrierungsmethode für das App Objekt:

// 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"),
)

Projektstruktur

Ein Go-Codeprojekt für Azure Functions ist ein Standardmäßiges Go-Modul. Wenn Sie ausführen func init --worker-runtime go, werden die folgenden Dateien generiert:

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

Die host.json Datei enthält Konfigurationsoptionen auf Hostebene. Weitere Informationen finden Sie in der host.json Referenz.

local.settings.json

In der local.settings.json Datei werden App-Einstellungen und Verbindungszeichenfolgen gespeichert, die während der lokalen Entwicklung verwendet werden. Diese Datei wird nicht in Azure veröffentlicht. Weitere Informationen finden Sie unter Datei für lokale Einstellungen.

Auslöser

Der Go-Worker bietet dedizierte Registrierungsmethoden für unterstützte Trigger.

Typisierte Abzugsnutzlasten

Die meisten unterstützten Trigger erhalten ihre Nutzlast inline über gRPC. Der Azure Functions-Host serialisiert die Trigger-Daten in die gRPC-Nachricht, und der Worker deserialisiert sie in typisierte Go-Werte. Diese Trigger haben:

• Typierte Handlersignaturen mit Kompilierungszeitsicherheit
• Keine externen Azure SDK-Abhängigkeiten: Es wird nur encoding/json benötigt
• Nutzlasten mit begrenzter Größe: Dokumente aus Änderungsfeeds, Nachrichten und Ereignisse sind diskrete Objekte mit begrenzter Größe.

Unterstützte Trigger:

Event Hubs und Service Bus unterstützen außerdem stark typisierte Batch-Handler über app.EventHubBatch(), app.ServiceBusQueueBatch(), und app.ServiceBusTopicBatch().

SDK-Typbindungen

SDK-Typbindungen bieten einen authentifizierten Azure SDK-Client anstelle serialisierter Triggerdaten. Für Go unterstützen Blob Storage-Trigger SDK-ähnliche Bindungen. Der Host sendet Metadaten, wie den Containernamen und den Blob-Pfad, und der Worker erstellt einen Client, der auf die spezifische Ressource zugeschnitten ist. SDK-Typbindungen bieten:

• SDK-Clienteinfügung: Der Handler empfängt einen einsatzbereiten Client
• Isolierte Abhängigkeiten: Azure SDK Pakete leben in triggers/<name>/
• Streamingunterstützung: Ermöglicht das Lesen großer Nutzlasten ohne Pufferung über gRPC

Um die Blob Storage SDK-Typbindung zu verwenden, fügen Sie einen leeren Import für das Blob-Triggerpaket hinzu:

import _ "github.com/azure/azure-functions-golang-worker/triggers/blob"

Beispiel für Blob-Trigger

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
}

Generische Host-Trigger

Verwenden app.GenericTrigger() , wenn eine kompatible Host-Erweiterung einen Trigger bereitstellt, der keine dedizierte Go-Registrierungsmethode hat. Generische Trigger unterstützen Rohtext, Byte Slices und JSON-kompatible Go-Typen:

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}]`,
    },
})

Die kompatible Host-Erweiterung muss installiert werden. Generische Trigger-Registrierung bietet keine HTTP-Behandlung, keine SDK-Client-Injektion, keine Durable Functions-Wiedergabe oder dienstspezifische Nachrichtenabwicklung. Für vollständige Beispiele siehe das Beispiel für generische Triggers.

HTTP-Trigger

HTTP-Trigger-Handler verwenden Go-Standardtypen net/http und sind Go-Entwicklern daher sofort vertraut:

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)
}

Registrieren von HTTP-Funktionen mit Methoden und Autorisierungsstufe:

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

HTTP-Datenstromübertragung

Der Go-Worker unterstützt HTTP-Streaming für Szenarien wie vom Server gesendete Ereignisse oder das Senden großer Antwortdaten:

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()
    }
}

Trigger mit Timer

Timertrigger werden in einem zeitplan ausgeführt, der durch einen Cron-Ausdruck definiert wird:

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 unterstützt Durable Functions-Orchestrierungen und -Aktivitäten über das middleware/durabletask Paket. Registrieren Sie Ihre Orchestratoren und Aktivitäten beim Durable Middleware, bevor Sie die Middleware zur Funktions-App hinzufügen:

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

Durable Functions für Go benötigt die Durable Task-Erweiterung Version 3.15.0 oder neuer. Entitäten werden derzeit nicht unterstützt. Für eine vollständige Anwendung siehe das Durable Functions-Beispiel.

Abhängigkeitsverwaltung

Go-Codeprojekte verwenden standardmäßige Go-Module für die Abhängigkeitsverwaltung.

1. Initialisieren eines neuen Moduls:

   go mod init myapp
   

2. Fügen Sie das Azure Functions Go Worker SDK hinzu:

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

   Für die Unterstützung von Blob-Triggern wird die Abhängigkeit automatisch über den Leerimport von triggers/blob eingebunden.

3. Aufräumen von Abhängigkeiten:

   go mod tidy
   

Lokal ausführen

Verwenden Sie Azure Functions Core Tools, um Ihr Projekt lokal auszuführen:

func start

Kerntools automatisch:

1. Erkennt FUNCTIONS_WORKER_RUNTIME = "native" von local.settings.json.
2. Legt die native Worker-Runtime auf Go fest, wenn eine go.mod-Datei vorhanden ist.
3. Führt go build -o bin/app . aus, um Ihr Projekt für das lokale Betriebssystem zu kompilieren.
4. Startet den Azure Functions-Host, der mit der kompilierten Binärdatei über gRPC kommuniziert.
5. Zeigt Ihre Funktionsendpunkte an (z. B http://localhost:7071/api/hello. ).

Dient local.settings.json zum Konfigurieren von Umgebungsvariablen für die lokale Entwicklung:

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

Der generierte AzureWebJobsStorage Wert ist für Go-Projekte leer. Legen Sie diesen Wert auf eine Verbindungszeichenfolge für ein Speicherkonto oder UseDevelopmentStorage=true fest, wenn Sie Trigger verwenden, die bei der lokalen Entwicklung Hostspeicher benötigen.

Einsatz

Kompilierung und Verpackung

Azure Functions Core Tools Version 4.12 oder höher verwaltet Go-Builds für die gemeinsamen lokalen und Azure-Bereitstellungs-Flows:

• func start erstellt Ihr Projekt als bin/app für Ihr lokales Betriebssystem, bevor der lokale Functions-Host gestartet wird.
• func azure functionapp publish erstellt, verpackt und stellt Ihr Projekt in einer vorhandenen Funktions-App in Azure bereit.
• func pack erstellt Ihr Projekt als Bin/App für Linux x64 und erstellt ein bereitstellungsfähiges .zip Paket.

Beim Packen für Azure enthält die generierte .zip Datei die vom Linux Functions-Host benötigten Dateien. Die kompilierte Binärdatei wird als Bin/App in Ihrem lokalen Projekt gespeichert, die Kerntools platzieren sie jedoch im Stammverzeichnis des Bereitstellungspakets als App.

Wenn Sie verwenden func pack --no-build, müssen Sie die Linux x64-Binärdatei vor dem Verpacken erstellen:

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

Bereitstellen mit Core Tools

Verwenden Sie func azure functionapp publish, um Ihr Go-Projekt in einer vorhandenen Funktions-App in Azure bereitzustellen:

func azure functionapp publish <APP_NAME>

Ersetzen Sie <APP_NAME> durch den Namen der Funktions-App.

Bereitstellen eines ZIP-Pakets

Verwenden Sie func pack, wenn Sie ein Bereitstellungspaket getrennt vom Veröffentlichen erstellen müssen:

1. Erstellen sie ein bereitstellungsfähiges ZIP-Artefakt:

   func pack
   

2. Stellen Sie das Paket mithilfe der Azure CLI bereit:

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

Das von func pack erstellte Paket kann in Azure ausgeführt werden. Fordern Sie daher keinen Remotebuild an, wenn Sie es bereitstellen.

Docker-Unterstützung

Sie können Go-Codeprojekte in Containern ausführen. Initialisieren eines Projekts mit Docker-Unterstützung:

func init --worker-runtime go --docker

Der Befehl generiert eine Dockerfile zusammen mit den Standardprojektdateien.

Telemetrie und Observierbarkeit

Der Go-Worker von Azure Functions unterstützt strukturierte Protokollierung und OpenTelemetry-basierte Beobachtbarkeit. Verwenden Sie kontextbezogene Methoden aus dem Standardpaket log/slog, wie slog.InfoContext, um Protokolle mit dem aktuellen Funktionsaufruf zu korrelieren. Um OpenTelemetry zu aktivieren, konfigurieren Sie den Funktionenhost, und registrieren Sie die Go Worker OpenTelemetry Middleware in Ihrer App. Anweisungen zum Einrichten finden Sie unter Use OpenTelemetry with Azure Functions.

Bekannte Einschränkungen

• func new wird nicht unterstützt. Fügen Sie Funktionen hinzu, indem Sie main.go direkt bearbeiten.
• Go Function Apps laufen nur unter Linux im Flex Consumption-Plan.
• Nur die dedizierten Trigger, die in Triggers aufgeführt sind, sowie kompatible generische Host-Trigger, werden unterstützt.
• Zusätzliche Eingabebindungen und Nicht-HTTP-Ausgabebindungen werden derzeit nicht unterstützt.
• Das Verpacken von Go-Anwendungen in Core Tools zielt derzeit auf Linux x64-Apps ab.

Nächste Schritte

• Erstellen Ihrer ersten Go-Funktion
• Trigger und Bindungen in Azure Functions
• Verwenden Sie OpenTelemetry mit Azure Functions
• Azure Functions Beispiele für Go Worker
• Azure Functions: Entwicklerhandbuch