Azure Functions Go-referentiemateriaal voor ontwikkelaars

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:

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

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 biedt speciale registratiemethoden voor ondersteunde triggers.

Getypeerde triggerpayloads

De meeste ondersteunde triggers ontvangen hun payload inline via gRPC. De Azure Functions-host serialiseert de triggergegevens in het gRPC-bericht, en de worker deserialiseert deze in getypte Go-waarden. 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 triggers:

Aanleiding Handlersignatuur Registratiemethode
HTTP func(http.ResponseWriter, *http.Request) app.HTTP()
Timer TimerHandler app.Timer()
Azure Queue Storage (opslagservice voor wachtrijen) QueueHandler app.Queue()
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()
Azure SQL func(context.Context, []bindings.SQLChange) error app.SQL()

Event Hubs en Service Bus ondersteunen ook sterk getypeerde batchhandlers via app.EventHubBatch(), app.ServiceBusQueueBatch(), en app.ServiceBusTopicBatch().

SDK-typebindingen

SDK-typebindings bieden een geauthenticeerde Azure SDK-client in plaats van geserialiseerde triggergegevens. Voor Go worden SDK-typebindings ondersteund voor Blob Storage-triggers. De host stuurt metadata, zoals de containernaam en het blobpad, en de worker construeert een client die is gescoped op de specifieke resource. SDK-type bindings bieden:

  • 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

Om de Blob Storage SDK-typebinding te gebruiken, voeg je een blanco import toe voor het Blob trigger-pakket:

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
}

Generieke host-triggers

Gebruik app.GenericTrigger() wanneer een compatibele hostextensie een trigger biedt die geen speciale Go-registratiemethode heeft. Generieke triggers ondersteunen ruwe tekst, byte slices en JSON-compatibele Go-types:

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

De compatibele hostextensie moet worden geïnstalleerd. Generieke triggerregistratie biedt geen HTTP-afhandeling, SDK-clientinjectie, Durable Functions replay of service-specifieke berichtafwikkeling. Voor volledige voorbeelden, zie het voorbeeld van generieke triggers.

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
}

Durable Functions

Go ondersteunt Durable Functions-orkestraties en -activiteiten via het middleware/durabletask pakket. Registreer je orchestrators en activiteiten bij de Durable middleware voordat je de middleware toevoegt aan de functie-app:

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

Durable Functions voor Go vereist de Durable Task-extensie versie 3.15.0 of later. Entiteiten worden momenteel niet ondersteund. Voor een volledige toepassing, zie het voorbeeld van Durable Functions.

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

  • func new wordt niet ondersteund. Voeg functies toe door rechtstreeks te bewerken main.go .
  • Go-functie-apps draaien alleen op Linux in het Flex Consumption-plan.
  • Alleen de specifieke triggers die in Triggers staan en compatibele generieke hosttriggers worden ondersteund.
  • Extra inputbindings en niet-HTTP outputbindings worden momenteel niet ondersteund.
  • Het verpakken van Go-apps in de Core Tools is momenteel gericht op Linux x64-toepassingen.

Volgende stappen 

  • Laatst bijgewerkt om