Referenční informace pro vývojáře Azure Functions Go

Azure Functions je bezserverová výpočetní služba, kterou můžete použít ke spouštění kódu řízeného událostmi bez zřizování nebo správy infrastruktury. Worker pro Go umožňuje psát Azure Functions nativně v jazyce Go s úzkou integrací s ekosystémem triggerů Azure Functions.

Tato příručka vám pomůže:

• Principy programovacího modelu Go
• Vytvoření a strukturování kódu projektu
• Práce s aktivačními událostmi
• Místní nasazení a spuštění aplikace v Azure

Další obecné informace o vývoji Azure Functions najdete v referenčních informacích pro vývojáře Azure Functions.

Začínáme

Zvolte prostředí, které vyhovuje vašemu pracovnímu postupu, a začněte s Azure Functions for Go:

• Rychlý start příkazového řádku

Předpoklady

• Přejít na verzi 1.24 nebo novější
• Azure Functions Core Tools verze 4.12 nebo novější. Spusťte func --version a ověřte nainstalovanou verzi.
• Azure CLI verze 2.87.0 nebo novější, když vytvoříte prostředky Azure nebo nasadíte balíčky do Azure. Spusťte az version a ověřte nainstalovanou verzi.

Programovací model

Worker Go používá programovací model typu code-first. Funkce bez serveru a jejich triggery definujete pomocí obslužných rutin idiomatic Go.

Vstupní bod

Každý projekt v Go začíná funkcí main(), která vytvoří FunctionApp, zaregistruje funkce a spustí 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)
}

Registrace funkce

Zaregistrujte funkce pomocí rozhraní API fluent builderu se vzorem funkčních možností. Každý typ triggeru má u objektu metodu App registrace:

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

Struktura projektu

Projekt kódu Go pro Azure Functions je standardní modul Go. Při spuštění func init --worker-runtime gose vygenerují následující soubory:

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

Soubor host.json obsahuje možnosti konfigurace na úrovni hostitele. Další informace najdete v host.json referenčních informacích.

local.settings.json

Soubor local.settings.json ukládá nastavení aplikace a připojovací řetězce používané při místním vývoji. Tento soubor není publikovaný do Azure. Další informace naleznete v tématu Místní soubor nastavení.

Spouštěče

Go worker poskytuje speciální metody registrace podporovaných spouštěčů.

Typované datové části triggerů

Většina podporovaných spouštěčů přijímá svůj payload inline přes gRPC. Hostitel Azure Functions serializuje spouštěcí data do gRPC zprávy a pracovník je deserializuje do typovaných hodnot Go. Tyto aktivační události mají:

• Typované signatury obslužných rutin s bezpečností v době kompilace
• Žádné externí závislosti na Azure SDK: je potřeba pouze encoding/json
• Datové části s omezenou velikostí: dokumenty z kanálu změn, zprávy a události jsou samostatné objekty s omezenou velikostí

Podporované triggery:

Trigger	Podpis obslužné rutiny	Metoda registrace
HTTP	func(http.ResponseWriter, *http.Request)	app.HTTP()
Timer	TimerHandler	app.Timer()
Azure Queue Storage	QueueHandler	app.Queue()
Azure Cosmos DB	func(context.Context, []bindings.CosmosDocument) error	app.CosmosDB()
Azure Service Bus (fronta)	ServiceBusHandler	app.ServiceBusQueue()
Azure Service Bus (téma)	ServiceBusHandler	app.ServiceBusTopic()
Centra událostí	EventHubHandler	app.EventHub()
Event Grid	EventGridHandler	app.EventGrid()
Azure SQL	func(context.Context, []bindings.SQLChange) error	app.SQL()

Event Hubs a Service Bus také podporují silně typované dávkové handlery prostřednictvím app.EventHubBatch(), app.ServiceBusQueueBatch(), a app.ServiceBusTopicBatch().

Vazby typu sady SDK

Vazby SDK poskytují autentizovaného klienta Azure SDK místo serializovaných spouštěcích dat. V jazyce Go spouštěče Blob Storage podporují vazby na typy SDK. Hostitel odesílá metadata, jako je název kontejneru a cesta k blobu, a pracovník vytváří klienta zaměřeného na konkrétní zdroj. Vazby typů SDK poskytují:

• Injektáž klienta sady SDK: Obslužná rutina obdrží klienta připraveného k použití.
• Izolované závislosti: balíčky Azure SDK jsou umístěny v triggers/<name>/
• Podpora streamování: Umožňuje čtení velkých datových částí bez ukládání do vyrovnávací paměti prostřednictvím gRPC

Pro použití vazby typu Blob Storage SDK je možné přidat prázdný import pro balíček triggeru Blob:

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

Trigger	Obslužná rutina přijímá	Metoda registrace
Blob Storage	*blob.Client	app.Blob()

Příklad spouštěče objektu 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
}

Obecné triggery hostitele

Použijte app.GenericTrigger() , když kompatibilní rozšíření hostitele poskytuje spouštěč, který nemá vyhrazenou metodu registrace v Go. Obecné triggery podporují surový text, byte slices a JSON-kompatibilní Go typy:

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

Je nutné nainstalovat kompatibilní hostitelské rozšíření. Generická registrace spouštěčů neposkytuje zpracování HTTP, injekci klientů SDK, přehrávání Durable Functions ani vypořádání zpráv specifických pro službu. Kompletní příklady najdete v ukázce obecných triggerů.

HTTP spouštěče

Obslužné funkce triggerů HTTP používají standardní typy Go net/http, takže jsou vývojářům v Go okamžitě povědomé:

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

Registrace funkcí HTTP pomocí metod a úrovně autorizace:

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

Streamování HTTP

Pracovní proces Go podporuje streamování HTTP pro scénáře, jako jsou události odeslané serverem nebo odesílání velkých dat odpovědí:

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

Aktivátor časovače

Aktivační události časovače se spouštějí podle plánu definovaného pomocí výrazu 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 podporuje orchestrace a aktivity Durable Functions prostřednictvím balíčku middleware/durabletask. Zaregistrujte své orchestrátory a aktivity v middlewaru Durable před přidáním middlewaru do aplikace funkcí:

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

Durable Functions pro Go vyžaduje rozšíření Durable Task verze 3.15.0 nebo novší. Entity momentálně nejsou podporovány. Pro kompletní aplikaci viz ukázka Durable Functions.

Správa závislostí

Projekty kódu Go používají standardní moduly Go pro správu závislostí.

1. Inicializace nového modulu:

   go mod init myapp
   

2. Přidejte sadu SDK pracovního procesu Azure Functions Go:

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

   Pro podporu triggeru blobu se závislost automaticky zahrne prostřednictvím prázdného importu triggers/blob.

3. Uspořádat závislosti:

   go mod tidy
   

Spustit lokálně

K místnímu spuštění projektu použijte nástroje Azure Functions Core Tools:

func start

Core Tools automaticky:

1. Rozpozná FUNCTIONS_WORKER_RUNTIME = "native" z local.settings.json.
2. Určí nativní runtime pracovního procesu jako Go, pokud je přítomen soubor go.mod.
3. Spustí go build -o bin/app . ke kompilaci vašeho projektu pro váš lokální operační systém.
4. Spustí Azure Functions hostitele, který komunikuje s kompilovaným binárním souborem přes gRPC.
5. Zobrazí koncové body vaší funkce (například http://localhost:7071/api/hello).

Slouží local.settings.json ke konfiguraci proměnných prostředí pro místní vývoj:

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

Vygenerovaná AzureWebJobsStorage hodnota je pro projekty Go prázdná. Nastavte ho na připojovací řetězec účtu úložiště nebo UseDevelopmentStorage=true, když při místním vývoji používáte aktivační události, které vyžadují hostitelské úložiště.

Deployment

Kompilace a balení

Azure Functions Core Tools verze 4.12 nebo novější zajišťuje sestavení Go pro běžné postupy místního nasazení a nasazení do Azure:

• func start před spuštěním místního hostitele Functions sestaví váš projekt jako bin nebo aplikaci pro místní operační systém.
• func azure functionapp publish sestaví, zabalí a nasadí váš projekt do existující aplikace funkcí v Azure.
• func pack sestaví projekt jako bin/app pro Linux x64 a vytvoří nasaditelný balíček .zip.

Při balení pro Azure obsahuje vygenerovaný soubor .zip soubory potřebné hostitelem Linux Functions. Zkompilovaný binární soubor se uloží jako bin/aplikace v místním projektu, ale Nástroje Core Tools ho umístí do kořenového adresáře balíčku pro nasazení jako aplikaci.

Pokud používáte func pack --no-build, musíte před balením sestavit binární soubor x64 s Linuxem:

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

Nasaďte pomocí nástroje Core Tools

Pomocí příkazu func azure functionapp publish nasaďte projekt Go do existující aplikace funkcí v Azure:

func azure functionapp publish <APP_NAME>

Nahraďte <APP_NAME> názvem vaší funkční aplikace.

Nasazení balíčku ZIP

Použijte func pack , když potřebujete vytvořit balíček nasazení odděleně od publikování:

1. Vytvoření nasaditelného artefaktu zip:

   func pack
   

2. Nasaďte balíček pomocí Azure CLI:

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

Balíček vytvořený func pack je připravený ke spuštění v Azure, takže při nasazení nepožádejte o vzdálené sestavení.

Podpora Dockeru

Projekty kódu Jazyka Go můžete spouštět v kontejnerech. Inicializace projektu s podporou Dockeru:

func init --worker-runtime go --docker

Příkaz vygeneruje Dockerfile společně se standardními soubory projektu.

Telemetrie a pozorovatelnost

Pracovní proces Azure Functions Go podporuje strukturované protokolování a pozorovatelnost založená na OpenTelemetry. Ke korelaci protokolů s voláním aktuální funkce použijte metody podporující kontext ze standardního log/slog balíčku, například slog.InfoContext. Chcete-li povolit OpenTelemetry, nakonfigurujte hostitele Functions a ve své aplikaci zaregistrujte middleware OpenTelemetry pro worker Go. Pokyny k nastavení najdete v tématu Use OpenTelemetry with Azure Functions.

Známá omezení

• func new není podporováno. Přidejte funkce přímo úpravou main.go .
• Aplikace funkcí Go běží na Linuxu pouze v rámci plánu Flex Consumption.
• Podporovány jsou pouze dedikované spouštěče uvedené v Triggers a kompatibilní obecné hostitelské spouštěče .
• Další vstupní vazby a výstupní vazby mimo HTTP nejsou v současnosti podporovány.
• Go packaging in Core Tools v současné době cílí na linuxové aplikace x64.

Další kroky

• Vytvoření první funkce Go
• Spouště a vazby funkcí Azure
• Použijte OpenTelemetry s Azure Functions
• Azure Functions ukázky pracovních procesů Go
• Azure Functions příručka pro vývojáře