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

Important

Podpora go pro Azure Functions je aktuálně ve verzi Public Preview. V předběžné verzi jsou aplikace funkcí v jazyce Go podporovány pouze v plánu Flex Consumption.

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

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

Pracovní proces Go uspořádá triggery do dvou úrovní na základě jejich požadavků na závislost:

Základní triggery

Aktivační události jádra přijímají svou datovou zátěž přímo přes gRPC. Hostitel Azure Functions serializuje data triggeru do zprávy gRPC a pracovní proces je deserializuje do typovaných struktur 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é základní triggery:

Trigger	Podpis obslužné rutiny	Metoda registrace
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 (fronta)	ServiceBusHandler	app.ServiceBusQueue()
Azure Service Bus (téma)	ServiceBusHandler	app.ServiceBusTopic()
Centra událostí	EventHubHandler	app.EventHub()
Event Grid	EventGridHandler	app.EventGrid()

Spouštěče rozšíření

Aktivační události rozšíření poskytují autentizovaného klienta Azure SDK namísto nezpracovaných dat. Hostitel odesílá pouze metadata (například název kontejneru a cestu k blobu) a pracovní proces vytvoří klienta omezeného na daný konkrétní prostředek. Tyto aktivační události mají:

• 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

Pokud chcete použít trigger rozšíření, přidejte prázdný import balíčku rozšíření:

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
}

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
}

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í (Preview)

Ve verzi Public Preview platí následující omezení:

• func new není podporováno. Přidejte funkce přímo úpravou main.go .
• Durable Functions není pro Go během veřejné verze Preview podporováno.
• Aplikace funkcí Go běží jenom v Linuxu v Azure.
• Během náhledu jsou podporovány pouze aktivační události uvedené v Triggerech.
• 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