Azure Functions Go-utvecklarreferens

Important

Go-stöd för Azure Functions finns för närvarande i offentlig förhandsversion. Under förhandsversionen stöds Go-funktionsappar endast i Flex Consumption-planen.

Azure Functions är en serverlös beräkningstjänst som du kan använda för att köra händelsedriven kod utan att etablera eller hantera infrastruktur. Med Go-worker kan du skriva Azure Functions direkt i Go, med djup integration i ekosystemet för utlösare i Azure Functions.

Den här guiden hjälper dig:

• Förstå Go-programmeringsmodellen
• Skapa och strukturera din projektkod
• Arbeta med utlösare
• Distribuera och köra appen lokalt och i Azure

Om du vill veta mer om Azure Functions-utveckling i allmänhet kan du läsa utvecklarreferensen för Azure Functions.

Komma igång

Välj den miljö som passar ditt arbetsflöde och kom igång med Azure Functions för Go:

• Snabbstart för kommandoraden

Förutsättningar

• Go 1.24 eller senare
• Azure Functions Core Tools version 4.12 eller senare. Kör func --version för att verifiera den installerade versionen.
• Azure CLI version 2.87.0 eller senare när du skapar Azure resurser eller distribuerar paket till Azure. Kör az version för att verifiera den installerade versionen.

Programmeringsmodell

Go-arbetaren använder en kod-första programmeringsmodell. Du definierar serverlösa funktioner och deras utlösare med hjälp av idiomatiska Go-hanterare.

Startpunkt

Varje Go-kodprojekt börjar med en main() funktion som skapar en FunctionApp, registrerar funktioner och startar arbetaren:

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

Registrering av funktion

Registrera funktioner med hjälp av api:et fluent builder med funktionsalternativsmönstret. Varje utlösartyp har en registreringsmetod för App objektet:

// 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 Service Bus trigger
app.ServiceBusQueue("myServiceBusFunc", handler,
    sdk.WithQueueName("myqueue"),
    sdk.WithConnection("ServiceBusConnection"),
)

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

Projekt-struktur

Ett Go-projekt för Azure Functions är en standardmodul i Go. När du kör func init --worker-runtime gogenereras följande filer:

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

Filen host.json innehåller konfigurationsalternativ på värdnivå. Mer information finns i referensen förhost.json.

local.settings.json

Filen local.settings.json lagrar appinställningar och anslutningssträngar som används under lokal utveckling. Den här filen publiceras inte till Azure. Mer information finns i Filen Lokala inställningar.

Utlösare

Go-arbetaren organiserar utlösare i två nivåer baserat på deras beroendekrav:

Grundläggande utlösare

Core-utlösare tar emot sin nyttolast direkt via gRPC. Värdprocessen för Azure Functions serialiserar triggardata i gRPC-meddelandet, och worker-processen deserialiserar den till typade Go-strukturer. Dessa utlösare har:

• Typade hanterarsignaturer med säkerhet vid kompilering
• Inga externa Azure SDKs beroenden: endast encoding/json behövs
• Begränsade nyttolaster: ändringsflödesdokument, meddelanden och händelser är diskreta, storleksbegränsade objekt

Kärnutlösare som stöds:

Trigger	Hanterarsignatur	Registreringsmetod
HTTP	func(http.ResponseWriter, *http.Request)	app.HTTP()
Timer	TimerHandler	app.Timer()
Azure Cosmos DB	func(context.Context, []bindings.CosmosDocument) error	app.CosmosDB()
Azure Service Bus (kö)	ServiceBusHandler	app.ServiceBusQueue()
Azure Service Bus (ämne)	ServiceBusHandler	app.ServiceBusTopic()
Event Hubs	EventHubHandler	app.EventHub()
Event Grid	EventGridHandler	app.EventGrid()

Tilläggsutlösare

Tilläggsutlösare tillhandahåller en autentiserad Azure SDKs klient i stället för rådata. Värden skickar endast metadata (till exempel containernamn och blobsökväg) och arbetaren skapar en klient som är begränsad till den specifika resursen. Dessa utlösare har:

• SDK-klientinmatning: hanteraren tar emot en färdig klient
• Isolerade beroenden: Azure SDKs-paket ligger i triggers/<name>/
• Stöd för strömning: möjliggör läsning av stora nyttolaster utan buffring via gRPC

Om du vill använda en tilläggsutlösare lägger du till en tom import för tilläggspaketet:

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

Trigger	Hanteraren tar emot	Registreringsmetod
Blob Storage	*blob.Client	app.Blob()

Exempel på blobutlösare

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
}

HTTP-utlösare

HTTP-utlösarhanterare använder Standard Go-typer net/http , vilket gör dem omedelbart bekanta för Go-utvecklare:

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

Registrera HTTP-funktioner med metoder och auktoriseringsnivå:

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

HTTP-direktuppspelning

Go-arbetaren stöder HTTP-strömning för scenarier som serverutskickade händelser eller sändning av stora svarsdata:

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

Timer-utlösare

Utlösare för timer körs enligt ett schema som definieras av ett cron-uttryck:

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
}

Beroendehantering

Go-kodprojekt använder Standard Go-moduler för beroendehantering.

1. Initiera en ny modul:

   go mod init myapp
   

2. Lägg till Azure Functions Go Worker SDK:

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

   För stöd för Blob Trigger inkluderas beroendet automatiskt genom blankimporten av triggers/blob.

3. Prydliga beroenden:

   go mod tidy
   

Kör lokalt

Använd Azure Functions Core Tools för att köra projektet lokalt:

func start

Core Tools automatiskt:

1. Identifierar FUNCTIONS_WORKER_RUNTIME = "native" från local.settings.json.
2. Löser den interna arbetskörningen till Go när en go.mod fil finns.
3. Kör go build -o bin/app . för att kompilera projektet för det lokala operativsystemet.
4. Startar värdprocessen för Azure Functions, som kommunicerar med den kompilerade binären via gRPC.
5. Visar funktionsslutpunkterna (till exempel http://localhost:7071/api/hello).

Använd local.settings.json för att konfigurera miljövariabler för lokal utveckling:

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

Det genererade AzureWebJobsStorage värdet är tomt för Go-projekt. Ange det till ett lagringskonto reťazec pripojenia eller UseDevelopmentStorage=true när du använder utlösare som kräver värdlagring under den lokala utvecklingen.

Deployment

Kompilering och paketering

Azure Functions Core Tools-versionen 4.12 eller senare hanterar Go-versioner för vanliga lokala och Azure distributionsflöden:

• func start skapar projektet som bin/app för ditt lokala operativsystem innan du startar den lokala Functions-värden.
• func azure functionapp publish bygger, paket och distribuerar projektet till en befintlig funktionsapp i Azure.
• func pack skapar projektet som bin/app för Linux x64 och skapar ett distributionsbart .zip-paket.

När du skapar paket för Azure innehåller den genererade .zip-filen de filer som behövs för Linux Functions-värden. Den kompilerade binärfilen lagras som bin/app i ditt lokala projekt, men Core Tools placerar den i roten på distributionspaketet som app.

Om du använder func pack --no-buildmåste du skapa linux x64-binärfilen innan du paketerar:

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

Driftsätt med Core Tools

Använd func azure functionapp publish för att distribuera Ditt Go-projekt till en befintlig funktionsapp i Azure:

func azure functionapp publish <APP_NAME>

Ersätt <APP_NAME> med namnet på funktionsappen.

Distribuera ett zip-paket

Använd func pack när du behöver skapa ett distributionspaket separat från publicering:

1. Skapa en distributionsbar zip-artefakt:

   func pack
   

2. Distribuera paketet med hjälp av Azure CLI:

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

Paketet som produceras av func pack är redo att köras i Azure, så begär inte en fjärrversion när du distribuerar det.

Docker-stöd

Du kan köra Go-kodprojekt i containrar. Initiera ett projekt med Docker-stöd:

func init --worker-runtime go --docker

Kommandot genererar en Dockerfile tillsammans med standardprojektfilerna.

Telemetri och observerbarhet

Azure Functions Go-worker stöder strukturerad loggning och OpenTelemetry-baserad observabilitet. Använd sammanhangsmedvetna metoder från standardpaketet log/slog , till exempel slog.InfoContext, för att korrelera loggar med den aktuella funktionsanropet. För att aktivera OpenTelemetry konfigurerar du Functions-värden och registrerar Go-workerns OpenTelemetry-mellanprogram i din app. Installationsinstruktioner finns i Använd OpenTelemetry med Azure Functions.

Kända begränsningar (förhandsversion)

Under den offentliga förhandsversionen gäller följande begränsningar:

• func new stöds inte. Lägg till funktioner genom att redigera main.go direkt.
• Durable Functions stöds inte för Go under den offentliga förhandsversionen.
• Go-funktionsappar körs endast på Linux i Azure.
• Endast utlösare som anges i Utlösare stöds under förhandsversionen.
• Go-paketering i Core Tools riktar sig för närvarande till Linux x64-appar.

Nästa steg

• Skapa din första Go-funktion
• Azure Functions-utlösare och bindningar
• Använd OpenTelemetry med Azure Functions
• Azure Functions Go-arbetsexempel
• Utvecklarguide för Azure Functions