Azure Functions Go-referentiemateriaal voor ontwikkelaars

Important

Go-ondersteuning voor Azure Functions is momenteel beschikbaar als openbare preview. Tijdens de preview worden Go-functie-apps alleen ondersteund in het Flex Consumption-abonnement.

Azure Functions is een serverloze rekenservice die u kunt gebruiken om gebeurtenisgestuurde code uit te voeren zonder infrastructuur in te richten of te beheren. Met de Go-worker kunt u Azure Functions rechtstreeks in Go ontwikkelen, met diepgaande integratie met het ecosysteem van Azure Functions-triggers.

Deze handleiding helpt u bij het volgende:

• Meer informatie over het Go-programmeermodel
• Uw projectcode maken en structuren
• Werken met triggers
• Uw app lokaal en in Azure implementeren en uitvoeren

Voor meer informatie over de ontwikkeling van Azure Functions in het algemeen, zie de Azure Functions developer reference.

Aan de slag

Kies de omgeving die past bij uw werkstroom en ga aan de slag met Azure Functions voor Go:

• Quickstart voor opdrachtregel

Prerequisites

• Go 1.24 of hoger
• Azure Functions Core Tools versie 4.12 of hoger. Voer deze opdracht uit func --version om uw geïnstalleerde versie te controleren.
• Azure CLI versie 2.87.0 of hoger wanneer u Azure resources maakt of pakketten implementeert in Azure. Voer deze opdracht uit az version om uw geïnstalleerde versie te controleren.

Programmeermodel

De Go-worker gebruikt een codegericht programmeermodel. U definieert serverloze functies en hun triggers met behulp van idiomatische Go-handlers.

Ingangspunt

Elk Go-codeproject begint met een main()-functie die een FunctionApp maakt, functies registreert en de worker start:

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

Registratie van functies

Registreer functies met behulp van de Fluent Builder-API met het patroon functionele opties. Elk triggertype heeft een registratiemethode voor het App object:

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

Projectstructuur

Een Go-codeproject voor Azure Functions is een standaard Go-module. Wanneer u uitvoert func init --worker-runtime go, worden de volgende bestanden gegenereerd:

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

Het host.json bestand bevat configuratieopties op hostniveau. Zie de host.json-verwijzing voor meer informatie.

local.settings.json

In het local.settings.json bestand worden app-instellingen en verbindingsreeksen opgeslagen die tijdens lokale ontwikkeling worden gebruikt. Dit bestand wordt niet gepubliceerd naar Azure. Zie het bestand Met lokale instellingen voor meer informatie.

Triggers

De Go-worker organiseert triggers in twee niveaus op basis van de vereisten voor afhankelijkheden:

Kernactivatoren

Kerntriggers ontvangen hun payload inline via gRPC. De Azure Functions-host serialiseert de triggergegevens naar het gRPC-bericht, en de worker deserialiseert deze naar getypeerde Go-structs. Deze triggers hebben:

• Getypte handler-signatures met compile-time-veiligheid
• Geen externe Azure SDK afhankelijkheden: alleen encoding/json is nodig
• Payloads met beperkte omvang: change-feed-documenten, berichten en gebeurtenissen zijn afzonderlijke objecten met een beperkte omvang

Ondersteunde kerntriggers:

Aanleiding	Handlersignatuur	Registratiemethode
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 (wachtrij)	ServiceBusHandler	app.ServiceBusQueue()
Azure Service Bus (onderwerp)	ServiceBusHandler	app.ServiceBusTopic()
Event Hubs	EventHubHandler	app.EventHub()
Event Grid	EventGridHandler	app.EventGrid()

Triggers voor extensies

Extensietriggers bieden een geverifieerde Azure SDK-client in plaats van onbewerkte gegevens. De host stuurt alleen metagegevens (zoals containernaam en blobpad) en het workerproces stelt een client samen die is toegespitst op de specifieke resource. Deze triggers hebben:

• SDK-clientinjectie: de handler ontvangt een kant-en-klare client
• Geïsoleerde afhankelijkheden: Azure SDK-pakketten bevinden zich in triggers/<name>/
• Streaming-ondersteuning: maakt het mogelijk om grote nettoladingen te lezen zonder te bufferen via gRPC

Als u een extensietrigger wilt gebruiken, voegt u een lege import toe voor het extensiepakket:

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

Aanleiding	Verwerker ontvangt	Registratiemethode
Blob Storage	*blob.Client	app.Blob()

Voorbeeld van 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
}

HTTP-triggers

HTTP-triggerhandlers maken gebruik van standaard Go-typen net/http , zodat ze onmiddellijk bekend zijn met Go-ontwikkelaars:

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-functies registreren met methoden en autorisatieniveau:

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

HTTP-streaming

De Go-werkrol ondersteunt HTTP-streaming voor scenario's zoals door de server verzonden gebeurtenissen of het verzenden van grote antwoordgegevens:

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

Timeractivatie

Timertriggers worden uitgevoerd volgens een schema dat is gedefinieerd door een cron-expressie:

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
}

Beheer van afhankelijkheden

Go-codeprojecten maken gebruik van standaard Go-modules voor afhankelijkheidsbeheer.

1. Initialiseer een nieuwe module:

   go mod init myapp
   

2. Voeg de Azure Functions Go Worker SDK toe:

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

   Voor ondersteuning van blob-triggers wordt de afhankelijkheid automatisch opgenomen via de lege import van triggers/blob.

3. Nette afhankelijkheden:

   go mod tidy
   

Lokaal uitvoeren

Gebruik Azure Functions Core Tools om uw project lokaal uit te voeren:

func start

Core Tools automatisch:

1. Detecteert FUNCTIONS_WORKER_RUNTIME = "native" uit local.settings.json.
2. Hiermee wordt de systeemeigen werkruntime omgezet naar Go wanneer een go.mod bestand aanwezig is.
3. Voert go build -o bin/app . uit om uw project voor uw eigen besturingssysteem te compileren.
4. Start de Azure Functions host, die communiceert met het gecompileerde binaire bestand via gRPC.
5. Geeft uw functie-eindpunten weer (bijvoorbeeld http://localhost:7071/api/hello).

Gebruik local.settings.json dit om omgevingsvariabelen te configureren voor lokale ontwikkeling:

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

De gegenereerde AzureWebJobsStorage waarde is leeg voor Go-projecten. Stel dit in op een verbindingsreeks voor een opslagaccount of UseDevelopmentStorage=true wanneer u triggers gebruikt waarvoor hostopslag is vereist tijdens lokale ontwikkeling.

Uitrol

Compilatie en verpakking

Azure Functions Core Tools-versie 4.12 of hoger verwerkt Go-builds voor de algemene lokale en Azure-implementatiestromen:

• func start bouwt uw project als bin/app voor uw lokale besturingssysteem voordat u de lokale Functions-host start.
• func azure functionapp publish bouwt, verpakt en implementeert uw project naar een bestaande functie-app in Azure.
• func pack bouwt uw project als bin/app voor Linux x64 en maakt een implementeerbaar .zip pakket.

Bij het verpakken van Azure bevat het gegenereerde .zip-bestand de bestanden die nodig zijn voor de Linux Functions-host. Het gecompileerde binaire bestand wordt opgeslagen als bin/app in uw lokale project, maar Core Tools plaatst het in de hoofdmap van het implementatiepakket als app.

Als u gebruikt func pack --no-build, moet u het binaire Linux x64-bestand bouwen voordat u het pakket verpakt:

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

Implementeren met Core Tools

Gebruik func azure functionapp publish om uw Go-project te implementeren in een bestaande functie-app in Azure:

func azure functionapp publish <APP_NAME>

Vervang door <APP_NAME> de naam van uw functie-app.

Een zip-pakket implementeren

Gebruik func pack dit wanneer u een implementatiepakket afzonderlijk van publicatie moet maken:

1. Maak een implementeerbaar zip-artefact:

   func pack
   

2. Implementeer het pakket met behulp van de Azure CLI:

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

Het pakket dat wordt geproduceerd door func pack is klaar om in Azure te worden uitgevoerd, dus vraag geen externe build aan wanneer u het implementeert.

Docker-ondersteuning

U kunt Go-codeprojecten uitvoeren in containers. Initialiseer een project met Docker-ondersteuning:

func init --worker-runtime go --docker

Met de opdracht wordt een Dockerfile samen met de standaardprojectbestanden gegenereerd.

Telemetrie en waarneembaarheid

De Azure Functions Go-werkrol ondersteunt gestructureerde logboekregistratie en op OpenTelemetry gebaseerde waarneembaarheid. Gebruik contextbewuste methoden uit het standaardpakket log/slog , zoals slog.InfoContext, om logboeken te correleren met de huidige functie-aanroep. Als u OpenTelemetry wilt inschakelen, configureert u de Functions-host en registreert u de OpenTelemetry-middleware van de Go-worker in uw app. Zie Use OpenTelemetry with Azure Functions (OpenTelemetry gebruiken met Azure Functions

Bekende beperkingen (preview)

Tijdens de openbare preview gelden de volgende beperkingen:

• func new wordt niet ondersteund. Voeg functies toe door rechtstreeks te bewerken main.go .
• Durable Functions wordt niet ondersteund voor Go tijdens de openbare preview.
• Go-functie-apps worden alleen uitgevoerd op Linux in Azure.
• Alleen de triggers die in Triggers worden vermeld, worden ondersteund tijdens de preview.
• Het verpakken van Go-apps in de Core Tools is momenteel gericht op Linux x64-toepassingen.

Volgende stappen 

• Uw eerste Go-functie maken
• Triggers en bindingen van Azure Functions
• OpenTelemetry gebruiken met Azure Functions
• Azure Functions Go-werkrolvoorbeelden
• Ontwikkelaarshandleiding voor Azure Functions