Dokumentacja deweloperów języka Azure Functions Go

Azure Functions to bezserwerowa usługa obliczeniowa, której można użyć do uruchamiania kodu sterowanego zdarzeniami bez aprowizacji infrastruktury ani zarządzania nią. Moduł roboczy Go umożliwia pisanie funkcji Azure Functions bezpośrednio w języku Go, z głęboką integracją z ekosystemem wyzwalaczy usługi Azure Functions.

Ten przewodnik ułatwia:

  • Omówienie modelu programowania Go
  • Utwórz i uporządkuj kod projektu
  • Praca z wyzwalaczami
  • Wdrażanie i uruchamianie aplikacji lokalnie i w Azure

Aby dowiedzieć się więcej na temat programowania Azure Functions ogólnie, zobacz dokumentację dla deweloperów Azure Functions.

Rozpoczęcie pracy

Wybierz środowisko pasujące do przepływu pracy i rozpocznij pracę z Azure Functions dla języka Go:

Prerequisites

  • Przejdź do wersji 1.24 lub nowszej
  • Azure Functions Core Tools w wersji 4.12 lub nowszej. Uruchom polecenie func --version , aby sprawdzić zainstalowaną wersję.
  • Azure CLI w wersji 2.87.0 lub nowszej podczas tworzenia zasobów Azure lub wdrażania pakietów w Azure. Uruchom polecenie az version , aby sprawdzić zainstalowaną wersję.

Model programowania

Worker Go wykorzystuje model programowania code-first. Funkcje bezserwerowe i ich wyzwalacze są definiowane przy użyciu idiotycznych procedur obsługi języka Go.

Punkt wejścia

Każdy projekt w języku Go rozpoczyna się od funkcji main(), która tworzy FunctionApp, rejestruje funkcje i uruchamia proces roboczy:

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

Rejestracja funkcji

Rejestruj funkcje przy użyciu interfejsu API typu fluent builder z zastosowaniem wzorca funkcjonalnych opcji. Każdy typ wyzwalacza ma metodę rejestracji w App obiekcie:

// 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 kodu języka Go dla Azure Functions jest standardowym modułem języka Go. Po uruchomieniu polecenia func init --worker-runtime gosą generowane następujące pliki:

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

Plik host.json zawiera opcje konfiguracji na poziomie hosta. Aby uzyskać więcej informacji, zobacz dokumentację pliku host.json.

local.settings.json

Plik local.settings.json przechowuje ustawienia aplikacji i parametry połączenia używane podczas programowania lokalnego. Ten plik nie jest publikowany w Azure. Aby uzyskać więcej informacji, zobacz Plik ustawień lokalnych.

Triggers

Go worker zapewnia dedykowane metody rejestracji obsługiwanych wyzwalaczy.

Typowane payloady wyzwalacza

Większość obsługiwanych wyzwalaczy otrzymuje swój ładunek danych bezpośrednio przez gRPC. Host Azure Functions serializuje dane wyzwalacza do wiadomości gRPC, a proces roboczy deserializuje je na wartości Go określonych typów. Te wyzwalacze mają:

  • Typowane sygnatury procedur obsługi z bezpieczeństwem typów na etapie kompilacji
  • Brak zewnętrznych zależności Azure SDK: wymagany jest tylko encoding/json
  • Ładunki o ograniczonym rozmiarze: dokumenty strumienia zmian, komunikaty i zdarzenia są odrębnymi obiektami o ograniczonym rozmiarze

Obsługiwane wyzwalacze:

Trigger Sygnatura procedury obsługi Metoda rejestracji
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 (kolejka) ServiceBusHandler app.ServiceBusQueue()
Azure Service Bus (temat) ServiceBusHandler app.ServiceBusTopic()
Centra zdarzeń EventHubHandler app.EventHub()
Event Grid EventGridHandler app.EventGrid()
Azure SQL func(context.Context, []bindings.SQLChange) error app.SQL()

Event Hubs i Service Bus obsługują również silnie typowane batch handlery przez app.EventHubBatch(), app.ServiceBusQueueBatch(), oraz app.ServiceBusTopicBatch().

Wiązania typu SDK

Powiązania typu SDK zapewniają uwierzytelnionego klienta Azure SDK zamiast serializowanych danych wyzwalacza. W przypadku Go wyzwalacze Blob Storage obsługują powiązania typów SDK. Host wysyła metadane, takie jak nazwa kontenera i ścieżka blob, a pracownik tworzy klienta przypisanego do konkretnego zasobu. Powiązania typów SDK zapewniają:

  • Iniekcja klienta zestawu SDK: program obsługi odbiera gotowego do użycia klienta
  • Izolowane zależności: pakiety Azure SDK znajdują się w triggers/<name>/
  • Obsługa przesyłania strumieniowego: umożliwia odczytywanie dużych ładunków bez buforowania za pośrednictwem gRPC

Aby użyć przypisania typu Blob Storage SDK, dodaj pusty import dla pakietu Blob Trigger:

import _ "github.com/azure/azure-functions-golang-worker/triggers/blob"
Trigger Program obsługi odbiera Metoda rejestracji
Blob Storage *blob.Client app.Blob()

Przykład użycia wyzwalacza obiektu 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
}

Ogólne wyzwalacze hosta

Używaj, app.GenericTrigger() gdy kompatybilne rozszerzenie hosta zapewnia wyzwalacz, który nie ma dedykowanej metody rejestracji w Go. Generyczne wyzwalacze obsługują surowy tekst, wycinki bajtów oraz kompatybilne z JSON typy Go:

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

Należy zainstalować zgodne rozszerzenie hosta. Ogólna rejestracja wyzwalaczy nie zapewnia obsługi HTTP, wstrzyknięcia klienta SDK, odtwarzania Durable Functions ani obsługi potwierdzania wiadomości specyficznej dla usługi. Pełne przykłady można znaleźć w przykładowym projekcie z ogólnymi wyzwalaczami.

Wyzwalacze HTTP

Programy obsługi wyzwalaczy HTTP używają standardowych typów języka Go net/http , dzięki czemu są natychmiast znane deweloperom języka Go:

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

Rejestrowanie funkcji HTTP przy użyciu metod i poziomu autoryzacji:

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

Przesyłanie strumieniowe HTTP

Proces roboczy Go obsługuje strumieniowanie HTTP w przypadkach takich jak zdarzenia wysyłane z serwera lub przesyłanie dużych ilości danych w odpowiedzi:

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

Wyzwalacz czasomierza

Wyzwalacze czasomierza są uruchamiane zgodnie z harmonogramem zdefiniowanym przez wyrażenie 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 wspiera orkiestracje i aktywności Durable Functions za pośrednictwem pakietu middleware/durabletask. Zarejestruj swoje aranżatory i aktywności w middleware Durable przed dodaniem middleware do aplikacji funkcji:

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

Durable Functions for Go wymaga rozszerzenia Durable Task w wersji 3.15.0 lub nowszej. Obecnie encje nie są obsługiwane. Pełną aplikację można znaleźć w przykładzie Durable Functions.

Zarządzanie zależnościami

Projekty kodu języka Go używają standardowych modułów języka Go do zarządzania zależnościami.

  1. Zainicjuj nowy moduł:

    go mod init myapp

  2. Dodaj zestaw SDK workera Go dla Azure Functions:

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

    W przypadku obsługi wyzwalacza obiektu blob zależność jest uwzględniana automatycznie za pośrednictwem pustego importu elementu triggers/blob.

  3. Uporządkuj zależności:

    go mod tidy

Uruchom lokalnie

Użyj Azure Functions Core Tools, aby uruchomić projekt lokalnie:

func start

Core Tools automatycznie:

  1. Wykrywa FUNCTIONS_WORKER_RUNTIME = "native" z local.settings.json.
  2. Ustawia natywne środowisko uruchomieniowe procesu roboczego na Go, gdy obecny jest plik go.mod.
  3. Uruchamia polecenie go build -o bin/app . , aby skompilować projekt dla lokalnego systemu operacyjnego.
  4. Uruchamia host Azure Functions, który komunikuje się ze skompilowanym plikiem binarnym za pośrednictwem gRPC.
  5. Wyświetla punkty końcowe funkcji (na przykład http://localhost:7071/api/hello).

Użyj local.settings.json polecenia , aby skonfigurować zmienne środowiskowe na potrzeby programowania lokalnego:

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

Wygenerowana AzureWebJobsStorage wartość jest pusta dla projektów języka Go. Ustaw tę wartość na parametry połączenia konta magazynu lub UseDevelopmentStorage=true, jeśli podczas programowania lokalnego używasz wyzwalaczy, które wymagają magazynu hosta.

Deployment

Kompilacja i pakowanie

Azure Functions Core Tools w wersji 4.12 lub nowszej obsługuje kompilacje Języka Go dla typowych przepływów wdrażania lokalnych i Azure:

  • func start Kompiluje projekt jako bin/app dla lokalnego systemu operacyjnego przed uruchomieniem lokalnego hosta usługi Functions.
  • func azure functionapp publish kompiluje, pakuje i wdraża projekt do istniejącej aplikacji funkcji na platformie Azure.
  • func pack kompiluje projekt jako bin/app dla systemu Linux x64 i tworzy wdrażalny pakiet .zip.

Podczas tworzenia pakietów dla Azure wygenerowany plik .zip zawiera pliki wymagane przez hosta usługi Linux Functions. Skompilowany plik binarny jest przechowywany jako bin/aplikacja w projekcie lokalnym, ale narzędzia Core Tools umieszcza je w katalogu głównym pakietu wdrożeniowego jako aplikację.

Jeśli używasz programu func pack --no-build, przed opakowaniem musisz skompilować plik binarny x64 systemu Linux:

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

Wdrażanie przy użyciu narzędzi Core Tools

Użyj func azure functionapp publish, aby wdrożyć projekt Go w istniejącej aplikacji funkcji w Azure:

func azure functionapp publish <APP_NAME>

Zastąp <APP_NAME> nazwą swojej aplikacji funkcji.

Wdrażanie pakietu zip

Użyj polecenia func pack, jeśli chcesz utworzyć pakiet wdrożeniowy oddzielnie od publikowania:

  1. Utwórz wdrażalny artefakt zip:

    func pack

  2. Wdróż pakiet przy użyciu Azure CLI:

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

Pakiet utworzony przez func pack jest gotowy do uruchomienia w Azure, więc nie żądaj kompilacji zdalnej podczas wdrażania.

Obsługa platformy Docker

Projekty kodu Języka Go można uruchamiać w kontenerach. Inicjowanie projektu przy użyciu obsługi platformy Docker:

func init --worker-runtime go --docker

Polecenie generuje element Dockerfile razem ze standardowymi plikami projektu.

Telemetria i możliwość obserwacji

Moduł roboczy Go dla Azure Functions obsługuje ustrukturyzowane rejestrowanie oraz obserwowalność opartą na OpenTelemetry. Użyj metod obsługujących kontekst z pakietu standardowego log/slog , takich jak slog.InfoContext, aby skorelować dzienniki z wywołaniem bieżącej funkcji. Aby włączyć OpenTelemetry, skonfiguruj host funkcji i zarejestruj w aplikacji składnik pośredniczący OpenTelemetry dla procesu roboczego Go. Instrukcje konfiguracji znajdziesz w artykule Korzystanie z OpenTelemetry z Azure Functions.

Znane ograniczenia

  • func new nie jest obsługiwany. Dodaj funkcje, edytując main.go bezpośrednio.
  • Aplikacje funkcji Go działają tylko w systemie Linux w planie Flex Consumption.
  • Obsługiwane są tylko dedykowane wyzwalacze wymienione w Triggers oraz kompatybilne generyczne wyzwalacze hostów .
  • Dodatkowe powiązania wejściowe i powiązania wyjściowe inne niż HTTP nie są obecnie obsługiwane.
  • Pakowanie aplikacji Go w narzędziu Core Tools jest obecnie przeznaczone dla aplikacji systemu Linux x64.

Następne kroki

  • Ostatnia aktualizacja o