Azure Functions Go fejlesztői referencia

Important

A Azure Functions támogatása jelenleg nyilvános előzetes verzióban érhető el. Az előzetes verzióban a Go függvényalkalmazások csak a Rugalmas használat csomagban támogatottak.

Azure Functions egy kiszolgáló nélküli számítási szolgáltatás, amellyel eseményvezérelt kódot futtathat infrastruktúra kiépítése és kezelése nélkül. A Go worker lehetővé teszi, hogy natívan, Go nyelven írjon Azure Functions-függvényeket, szorosan integrálva az Azure Functions trigger-ökoszisztémájába.

Ez az útmutató a következőkben nyújt segítséget:

• A Go programozási modell ismertetése
• Projektkód létrehozása és felépítése
• Triggerek használata
• Az alkalmazás üzembe helyezése és futtatása helyileg és a Azure

Az Azure Functions fejlesztéséről általában további információért lásd a Azure Functions fejlesztői referenciát.

Kezdő lépések

Válassza ki a munkafolyamatához legjobban illő környezetet, és kezdje el használni az Azure Functions for Go szolgáltatást:

• Parancssori gyors üzembe helyezés

Prerequisites

• Go 1.24 vagy újabb
• Azure Functions Core Tools verzió 4.12 vagy újabb. Futtassa func --version a telepített verzió ellenőrzéséhez.
• Azure CLI2.87.0 vagy újabb verziója, amikor Azure-erőforrásokat hoz létre, vagy csomagokat telepít az Azure-ba. Futtassa az version a telepített verzió ellenőrzéséhez.

Programozási modell

A Go-feldolgozó egy kódelső programozási modellt használ. A kiszolgáló nélküli függvényeket és azok eseményindítóit idiomatikus Go-kezelőkkel definiálhatja.

Belépési pont

Minden Go-kódprojekt egy main() függvényt hoz létre FunctionApp, regisztrálja a függvényeket, és elindítja a feldolgozót:

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

Függvényregisztráció

Függvények regisztrálása a fluent builder API-val a funkcionális beállítások mintájával. Minden eseményindító-típushoz tartozik egy regisztrációs metódus a(z) App objektumon:

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

A projekt szerkezete

Az Azure Functions Go-kódprojektje egy szabványos Go-modul. Futtatáskor func init --worker-runtime goa következő fájlok jönnek létre:

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

A host.json fájl gazdagépszintű konfigurációs beállításokat tartalmaz. További információ: host.json referencia.

local.settings.json

A local.settings.json fájl tárolja a helyi fejlesztés során használt alkalmazásbeállításokat és kapcsolati sztringeket. Ez a fájl nincs közzé téve az Azure-ba. További információt a Helyi beállítások fájlban talál.

Kiváltók

A Go-feldolgozó a függőségi követelmények alapján két szintre szervezi az eseményindítókat:

Alapvető eseményindítók

Az alapvető eseményindítók közvetlenül, gRPC-n keresztül kapják meg az adatterhet. Az Azure Functions host a trigger adatait a gRPC-üzenetbe szerializálja, a worker pedig típusos Go-struktúrákká deszerializálja azokat. Ezek az eseményindítók a következők:

• Típusos kezelőfüggvény-szignatúrák fordításkori biztonsággal
• Nem szükséges külső Azure SDK függőség: csak encoding/json van szükség
• Korlátozott méretű hasznos adatok: a változási hírcsatorna dokumentumai, az üzenetek és az események különálló, méretükben korlátozott objektumok

Támogatott alapvető eseményindítók:

Trigger	Kezelői aláírás	Regisztrációs módszer
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 (üzenetsor)	ServiceBusHandler	app.ServiceBusQueue()
Azure Service Bus (témakör)	ServiceBusHandler	app.ServiceBusTopic()
Event Hubs	EventHubHandler	app.EventHub()
Event Grid	EventGridHandler	app.EventGrid()

Bővítmény-eseményindítók

A bővítmény-eseményindítók a nyers adatok helyett hitelesített Azure SDK ügyfelet biztosítanak. A gazdagép csak metaadatokat küld (például a tároló nevét és a blob elérési útját), a feldolgozó pedig létrehoz egy, az adott erőforrásra korlátozott ügyfélprogramot. Ezek az eseményindítók a következők:

• SDK-ügyfélinjektálás: a kezelő használatra kész ügyfelet kap
• Elkülönített függőségek: az Azure SDK-csomagok itt találhatók: triggers/<name>/
• Streaming támogatása: lehetővé teszi a nagyméretű adatok olvasását pufferelés nélkül, gRPC-n keresztül

A bővítménytrigger használatához adjon hozzá egy üres importutasítást a bővítménycsomaghoz:

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

Trigger	A kezelő fogadja a	Regisztrációs módszer
Blob Storage	*blob.Client	app.Blob()

Példa Blob-eseményindítóra

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-eseményindítók

A HTTP-triggerkezelők szabványos Go-típusokat net/http használnak, így azonnal ismerősek lesznek a Go-fejlesztők számára:

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-függvények regisztrálása metódusokkal és engedélyezési szinttel:

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

HTTP-streamelés

A Go-feldolgozó támogatja a HTTP-streamelést olyan helyzetekben, mint a kiszolgáló által küldött események vagy a nagy válaszadatok küldése:

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

Időzítőindító

Az időzítő eseményindítói a cron kifejezés által meghatározott ütemezés szerint futnak:

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
}

Függőségkezelés

A Go-kódprojektek standard Go-modulokat használnak a függőségkezeléshez.

1. Új modul inicializálása:

   go mod init myapp
   

2. Adja hozzá a Azure Functions Go-feldolgozó SDK-t:

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

   Blobtrigger-támogatás esetén a függőség automatikusan bekerül a(z) triggers/blob üres importálásával.

3. Rendezett függőségek:

   go mod tidy
   

Helyi futtatás

A Azure Functions Core Tools használatával helyileg futtathatja a projektet:

func start

Alapvető eszközök automatikusan:

1. Észleli a(z) FUNCTIONS_WORKER_RUNTIME = "native" elemet a(z) local.settings.json forrásból.
2. A natív worker-futtatókörnyezetet Go-ként azonosítja, ha egy go.mod fájl található.
3. Lefuttatja a(z) go build -o bin/app . parancsot, hogy lefordítsa a projektet az Ön helyi operációs rendszerére.
4. Elindítja az Azure Functions gazdafolyamatot, amely gRPC-n keresztül kommunikál a lefordított binárissal.
5. Megjeleníti a függvényvégpontokat (például http://localhost:7071/api/hello).

Környezeti változók helyi fejlesztéshez való konfigurálásához használható local.settings.json :

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

A létrehozott AzureWebJobsStorage érték üres a Go-projektek esetében. Állítsa be tárfiókhoz tartozó kapcsolati sztringre vagy UseDevelopmentStorage=true értékre, ha a helyi fejlesztés során olyan eseményindítókat használ, amelyek a gazdagép tárolóját igénylik.

Deployment

Fordítás és csomagolás

Azure Functions Core Tools 4.12 vagy újabb verziója kezeli a Go-buildeket a gyakori helyi és Azure üzembehelyezési folyamatokhoz:

• func start a helyi operációs rendszerhez a projektet bin/app néven építi le, mielőtt elindítaná a helyi Functions-gazdagépet.
• func azure functionapp publish felépíti, becsomagolja, és üzembe helyezi a projektet egy meglévő függvényalkalmazásba az Azure-ban.
• func pack Linux x64 rendszerre a projektet bin/app néven állítja össze, és egy telepíthető .zip csomagot hoz létre.

A Azure csomagolásakor a létrehozott .zip fájl tartalmazza a Linux Functions-gazdagép által szükséges fájlokat. A lefordított bináris fájl a helyi projektben bin/app néven van tárolva, de a Core Tools az üzembehelyezési csomag gyökerébe app néven helyezi.

Ha a(z) func pack --no-build elemet használja, a csomagolás előtt el kell készítenie a Linux x64 binárist:

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

Üzembe helyezés a Core Tools használatával

A func azure functionapp publish használatával telepítheti Go-projektjét egy meglévő Azure-beli függvényalkalmazásba:

func azure functionapp publish <APP_NAME>

Cserélje le <APP_NAME> a függvényalkalmazás nevére.

Zip-csomag üzembe helyezése

Akkor használható func pack , ha a közzétételtől elkülönítve kell létrehoznia egy üzembehelyezési csomagot:

1. Üzembe helyezhető zip-összetevő létrehozása:

   func pack
   

2. A csomag üzembe helyezése a Azure CLI használatával:

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

A func pack által előállított csomag készen áll a Azure való futtatásra, ezért telepítéskor ne kérjen távoli buildet.

Docker-támogatás

Go-kódprojekteket futtathat tárolókban. Projekt inicializálása Docker-támogatással:

func init --worker-runtime go --docker

A parancs létrehoz egy Dockerfile elemet a szabványos projektfájlokkal együtt.

Telemetria és megfigyelhetőség

A Azure Functions Go-feldolgozó támogatja a strukturált naplózást és az OpenTelemetry-alapú megfigyelhetőséget. Használjon környezettudatos metódusokat a standard log/slog csomagból, például slog.InfoContexta naplók az aktuális függvényhívással való korrelálásához. Az OpenTelemetria engedélyezéséhez konfigurálja a Functions-gazdagépet, és regisztrálja a Go worker OpenTelemetry köztes szoftverét az alkalmazásban. A beállítási utasításokat lásd: Az OpenTelemetry használata az Azure Functionsszel.

Ismert korlátozások (előzetes verzió)

A nyilvános előzetes verzióban a következő korlátozások érvényesek:

• func new nem támogatott. Adjon hozzá funkciókat a(z) main.go közvetlen szerkesztésével.
• A Durable Functions nem támogatott a Go esetében a nyilvános előzetes verzióban.
• A Go-alapú függvényalkalmazások az Azure-ban csak Linuxon futnak.
• Az előzetes verzióban csak az eseményindítókban felsorolt eseményindítók támogatottak.
• A Go-csomagolás a Core Toolsban jelenleg a Linux x64-alkalmazásokhoz készül.

Következő lépések

• Az első Go függvény létrehozása
• Az Azure Functions eseményindítói és kötései
• OpenTelemetry használata az Azure Functions-szel
• Azure Functions Go-feldolgozó példák
• Azure Functions – fejlesztői útmutató