Informazioni di riferimento per sviluppatori Funzioni di Azure Go

Importante

Il supporto di Go per Funzioni di Azure è attualmente disponibile in anteprima pubblica. Durante l'anteprima, le app per le funzioni Go sono supportate solo nel piano Flex Consumption.

Funzioni di Azure è un servizio di calcolo serverless che è possibile usare per eseguire codice basato su eventi senza effettuare il provisioning o la gestione dell'infrastruttura. Il worker Go consente di scrivere Funzioni di Azure in Go in modo nativo, con un'integrazione approfondita con l'ecosistema dei trigger di Funzioni di Azure.

Questa guida consente di:

• Informazioni sul modello di programmazione Go
• Creare e strutturare il codice del progetto
• Uso dei trigger
• Distribuire ed eseguire l'app in locale e in Azure

Per altre informazioni sullo sviluppo Funzioni di Azure in generale, vedere le informazioni di riferimento Funzioni di Azure developer.

Come iniziare

Scegliere l'ambiente adatto al flusso di lavoro e iniziare a usare Funzioni di Azure per Go:

• Guida introduttiva alla riga di comando

Prerequisiti

• Passare alla versione 1.24 o successiva
• Funzioni di Azure Core Tools versione 4.12 o versione successiva. Eseguire func --version per verificare la versione installata.
• interfaccia della riga di comando di Azure versione 2.87.0 o versioni successive, quando si creano risorse Azure o si distribuiscono pacchetti in Azure. Eseguire az version per verificare la versione installata.

Modello di programmazione

Il worker Go adotta un modello di programmazione basato sul codice. È possibile definire funzioni serverless e i relativi trigger usando gestori Go idiomatici.

Punto di ingresso

Ogni progetto di codice Go inizia con una funzione main() che crea un FunctionApp, registra le funzioni e avvia il 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)
}

Registrazione delle funzioni

Registrare le funzioni usando l'API Fluent Builder con il modello di opzioni funzionali. Ogni tipo di trigger ha un metodo di registrazione nell'oggetto App :

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

Struttura del progetto

Un progetto di codice Go per Funzioni di Azure è un modulo Go standard. Quando si esegue func init --worker-runtime go, vengono generati i file seguenti:

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

Il host.json file contiene opzioni di configurazione a livello di host. Per altre informazioni, vedi il riferimento host.json.

local.settings.json

Il file archivia local.settings.json le impostazioni dell'app e le stringhe di connessione usate durante lo sviluppo locale. Questo file non viene pubblicato in Azure. Per maggiori informazioni, vedere File di impostazioni locali.

Trigger

Il worker Go organizza i trigger in due livelli in base ai requisiti di dipendenza:

Attivatori principali

I trigger di base ricevono il payload inline tramite gRPC. L'host di Funzioni di Azure serializza i dati del trigger nel messaggio gRPC e il worker li deserializza in strutture Go tipizzate. Questi attivatori hanno:

• Signature tipizzate del gestore con sicurezza in fase di compilazione
• Nessuna dipendenza esterna da Azure SDK: è necessario solo encoding/json
• Payload con dimensioni limitate: i documenti del feed delle modifiche, i messaggi e gli eventi sono oggetti distinti con dimensioni limitate

Trigger di base supportati:

Trigger	Firma del gestore	Metodo di registrazione
HTTP	func(http.ResponseWriter, *http.Request)	app.HTTP()
Timer	TimerHandler	app.Timer()
Azure Cosmos DB, un servizio di database distribuito globale di Microsoft	func(context.Context, []bindings.CosmosDocument) error	app.CosmosDB()
bus di servizio di Azure (coda)	ServiceBusHandler	app.ServiceBusQueue()
bus di servizio di Azure (argomento)	ServiceBusHandler	app.ServiceBusTopic()
Event Hubs	EventHubHandler	app.EventHub()
Event Grid	EventGridHandler	app.EventGrid()

Trigger dell'estensione

I trigger di estensione forniscono un client Azure SDK autenticato anziché dati non elaborati. L'host invia solo i metadati (come il nome del contenitore e il percorso del BLOB) e il worker crea un client con ambito limitato alla risorsa specifica. Questi trigger hanno:

• Inserimento del client SDK: il gestore riceve un client pronto per l'uso
• Dipendenze isolate: i pacchetti Azure SDK vivono in triggers/<name>/
• Supporto per lo streaming: consente la lettura di payload di grandi dimensioni senza buffering tramite gRPC

Per usare un trigger di estensione, aggiungere un'importazione vuota per il pacchetto di estensione:

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

Trigger	Il gestore riceve	Metodo di registrazione
gestione rete virtuale di Azure	*blob.Client	app.Blob()

Esempio di trigger del 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
}

Trigger HTTP

I gestori di trigger HTTP usano i tipi Go net/http standard, rendendoli immediatamente familiari per gli sviluppatori 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)
}

Registrare le funzioni HTTP con metodi e livello di autorizzazione:

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

streaming tramite HTTP

Il worker Go supporta lo streaming HTTP per scenari come gli eventi inviati dal server o l'invio di grandi quantità di dati di risposta:

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

Attivazione del timer

I trigger timer vengono eseguiti in base a una pianificazione definita da un'espressione 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
}

Gestione delle dipendenze

I progetti di codice Go usano moduli Go standard per la gestione delle dipendenze.

1. Inizializzare un nuovo modulo:

   go mod init myapp
   

2. Aggiungere Funzioni di Azure Go Worker SDK:

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

   Per il supporto del trigger BLOB, la dipendenza viene inclusa automaticamente tramite l'importazione vuota di triggers/blob.

3. Dipendenze ordinate:

   go mod tidy
   

Esegui localmente

Usare Funzioni di Azure Core Tools per eseguire il progetto in locale:

func start

Core Tools in automatico:

1. Rileva FUNCTIONS_WORKER_RUNTIME = "native" da local.settings.json.
2. Imposta il runtime del worker nativo su Go quando è presente un file go.mod.
3. Esegue go build -o bin/app . per compilare il progetto per il sistema operativo locale.
4. Avvia l'host Funzioni di Azure, che comunica con il file binario compilato su gRPC.
5. Visualizza gli endpoint della funzione , ad esempio http://localhost:7071/api/hello.

Usare local.settings.json per configurare le variabili di ambiente per lo sviluppo locale:

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

Il valore generato AzureWebJobsStorage è vuoto per i progetti Go. Impostarlo su una stringa di connessione di un account di archiviazione o UseDevelopmentStorage=true quando si usano trigger che richiedono l'archiviazione dell'host durante lo sviluppo locale.

Distribuzione

Compilazione e pacchettizzazione

Funzioni di Azure Core Tools versione 4.12 o versioni successive gestisce le build Go per i flussi di distribuzione locali e Azure comuni:

• func start compila il progetto come bin/app per il sistema operativo locale prima di avviare l'host di Funzioni locale.
• func azure functionapp publish compila, crea il pacchetto e distribuisce il progetto in una Function App esistente in Azure.
• func pack compila il progetto come bin/app per Linux x64 e crea un pacchetto .zip distribuibile.

Quando si crea un pacchetto per Azure, il file di .zip generato contiene i file necessari per l'host di Funzioni Linux. Il file binario compilato viene archiviato come bin/app nel progetto locale, ma Core Tools lo inserisce nella radice del pacchetto di distribuzione come app.

Se si usa func pack --no-build, è necessario compilare il file binario Linux x64 prima della creazione del pacchetto:

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

Distribuire con Core Tools

Usa func azure functionapp publish per distribuire il tuo progetto Go in un'app per funzioni esistente di Azure:

func azure functionapp publish <APP_NAME>

Sostituire <APP_NAME> con il nome dell'app per le funzioni.

Distribuire un pacchetto ZIP

Usare func pack quando è necessario creare un pacchetto di distribuzione separatamente dalla pubblicazione:

1. Creare un artefatto ZIP distribuibile:

   func pack
   

2. Distribuire il pacchetto usando il interfaccia della riga di comando di Azure:

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

Il pacchetto prodotto da func pack è pronto per l'esecuzione in Azure, quindi non richiedere una compilazione remota quando viene distribuita.

Supporto di Docker

È possibile eseguire progetti di codice Go nei contenitori. Inizializzare un progetto con il supporto di Docker:

func init --worker-runtime go --docker

Il comando genera un Dockerfile insieme ai file di progetto standard.

Telemetria e osservabilità

Il worker Go di Funzioni di Azure supporta il logging strutturato e l'osservabilità basata su OpenTelemetry. Usare metodi con riconoscimento del contesto del pacchetto standard log/slog , ad esempio slog.InfoContext, per correlare i log con la chiamata alla funzione corrente. Per abilitare OpenTelemetry, configura l'host di Functions e registra il middleware OpenTelemetry del worker Go nell'applicazione. Per istruzioni sull'installazione, vedere Use OpenTelemetry with Funzioni di Azure.

Limitazioni note (anteprima)

Durante l'anteprima pubblica si applicano le limitazioni seguenti:

• func new non è supportata. Aggiungere funzioni modificando main.go direttamente.
• Durable Functions non è supportato per Go durante l'anteprima pubblica.
• Le app per le funzioni Go vengono eseguite in Linux solo in Azure.
• Durante l'anteprima sono supportati solo i trigger elencati in Trigger .
• La creazione di pacchetti Go in Core Tools è attualmente destinata alle app Linux x64.

Passaggi successivi

• Creare la prima funzione Go
• Trigger e associazioni di Funzioni di Azure
• Utilizza OpenTelemetry con Funzioni di Azure
• esempi di lavoro Funzioni di Azure Go
• Guida per sviluppatori di Funzioni di Azure