Dokumentacja deweloperów języka Azure Functions Go

Important

Obsługa języka Go w usłudze Azure Functions jest obecnie w fazie publicznej wersji zapoznawczej. W wersji zapoznawczej aplikacje funkcji języka Go są obsługiwane tylko w planie Flex Consumption.

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:

• Szybki start z wierszem polecenia

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

Proces roboczy języka Go organizuje wyzwalacze w dwie warstwy na podstawie wymagań dotyczących zależności:

Wyzwalacze podstawowe

Podstawowe wyzwalacze otrzymują swoje dane bezpośrednio przez gRPC. Host usługi Azure Functions serializuje dane wyzwalające do komunikatu gRPC, a proces roboczy deserializuje je do typowanych struktur Go. 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 podstawowe wyzwalacze:

Trigger	Sygnatura procedury obsługi	Metoda rejestracji
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 (kolejka)	ServiceBusHandler	app.ServiceBusQueue()
Azure Service Bus (temat)	ServiceBusHandler	app.ServiceBusTopic()
Centra zdarzeń	EventHubHandler	app.EventHub()
Event Grid	EventGridHandler	app.EventGrid()

Wyzwalacze rozszerzeń

Wyzwalacze rozszerzeń zapewniają uwierzytelniony klient Azure SDK zamiast danych pierwotnych. Host wysyła tylko metadane (takie jak nazwa kontenera i ścieżka obiektu blob), a proces roboczy tworzy klienta dla konkretnego zasobu. Te wyzwalacze mają:

• 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ć wyzwalacza rozszerzenia, dodaj pusty import dla pakietu rozszerzenia:

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
}

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
}

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 (wersja zapoznawcza)

W publicznej wersji zapoznawczej obowiązują następujące ograniczenia:

• func new nie jest obsługiwany. Dodaj funkcje, edytując main.go bezpośrednio.
• Durable Functions nie jest obsługiwana w języku Go w publicznej wersji zapoznawczej.
• Aplikacje funkcji języka Go działają tylko w systemie Linux w Azure.
• Tylko wyzwalacze wymienione w wyzwalaczach są obsługiwane w okresie obowiązywania wersji zapoznawczej.
• Pakowanie aplikacji Go w narzędziu Core Tools jest obecnie przeznaczone dla aplikacji systemu Linux x64.

Następne kroki

• Tworzenie pierwszej funkcji języka Go
• Wyzwalacze i powiązania usługi Azure Functions
• Używanie biblioteki OpenTelemetry z usługą Azure Functions
• Przykłady procesu roboczego Go dla Azure Functions
• Azure Functions — przewodnik dla deweloperów