Informazioni di riferimento per sviluppatori Funzioni di Azure Go

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

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 fornisce metodi di registrazione dedicati per i trigger supportati.

Payload di trigger tipizzati

La maggior parte dei trigger supportati riceve il proprio payload in linea tramite gRPC. L'host di Funzioni di Azure serializza i dati di trigger nel messaggio gRPC, e il worker li deserializza in valori Go tipizzati. 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 supportati:

Trigger	Firma del gestore	Metodo di registrazione
HTTP	`func(http.ResponseWriter, *http.Request)`	`app.HTTP()`
Timer	`TimerHandler`	`app.Timer()`
Archiviazione in coda di Azure	`QueueHandler`	`app.Queue()`
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()`
Azure SQL	`func(context.Context, []bindings.SQLChange) error`	`app.SQL()`

Event Hubs e bus di servizio supportano anche gestori batch fortemente tipizzati tramite app.EventHubBatch(), app.ServiceBusQueueBatch(), e app.ServiceBusTopicBatch().

Associazioni dei tipi di SDK

I bindings di tipo SDK forniscono un client Azure SDK autenticato invece dei dati di trigger serializzati. Per il linguaggio Go, i trigger di gestione rete virtuale di Azure supportano i binding di tipo SDK. L'host invia metadati, come il nome del container e il percorso del blob, e il worker costruisce un client con ambito sulla risorsa specifica. I bindings di tipo SDK forniscono:

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 utilizzare il tipo di binding gestione rete virtuale di Azure SDK, aggiungi un'importazione vuota per il pacchetto trigger Blob:

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 di host generici

Usare app.GenericTrigger() quando un'estensione host compatibile fornisce un trigger che non ha un metodo dedicato di registrazione Go. I trigger generici supportano testo grezzo, slice di byte e tipi di Go compatibili con JSON:

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

Deve essere installata l'estensione host compatibile. La registrazione generica dei trigger non fornisce gestione HTTP, iniezione client SDK, riproduzione Durable Functions o regolazione dei messaggi specifica del servizio. Per esempi completi, vedi il sample di trigger generici.

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
}

Durable Functions

Go supporta le orchestrazioni e le attività di Durable Functions tramite il pacchetto middleware/durabletask. Registra i tuoi orchestratori e attività con il middleware Durable prima di aggiungere il middleware all'app funzionale:

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

Durable Functions for Go richiede l'estensione Durable Task versione 3.15.0 o successiva. Attualmente le entità non sono supportate. Per un'applicazione completa, vedi l'esempio di Durable Functions.

Gestione delle dipendenze

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

Inizializzare un nuovo modulo:
```
go mod init myapp
```
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.
Dipendenze ordinate:
```
go mod tidy
```

Esecuzione locale

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

func start

Core Tools in automatico:

Rileva FUNCTIONS_WORKER_RUNTIME = "native" da local.settings.json.
Risolve il runtime del worker nativo su Go quando è presente un file go.mod.
Esegue go build -o bin/app . per compilare il progetto per il sistema operativo locale.
Avvia l'host Funzioni di Azure, che comunica con il file binario compilato su gRPC.
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:

Creare un artefatto ZIP distribuibile:
```
func pack
```

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, configurare l'host Functions e registrare il middleware OpenTelemetry del worker Go nell'app. Per istruzioni sull'installazione, vedere Use OpenTelemetry with Funzioni di Azure.

Limitazioni note

func new non è supportata. Aggiungere funzioni modificando main.go direttamente.
Le app per le funzioni Go girano solo su Linux nel piano Flex Consumption.
Sono supportati solo i trigger dedicati elencati in Triggers e i trigger host generici compatibili.
Attualmente non sono supportati binding aggiuntivi di input e output non HTTP.
La creazione di pacchetti Go in Core Tools è attualmente destinata alle app Linux x64.

Passaggi successivi

Commenti e suggerimenti

Questa pagina è stata utile?

Ultimo aggiornamento: 2026-10-23