referencia para desarrolladores de Azure Functions Go

Importante

La compatibilidad con Go para Azure Functions está actualmente en versión preliminar pública. Durante la versión preliminar, las aplicaciones de funciones de Go solo se admiten en el plan de consumo flexible.

Azure Functions es un servicio de proceso sin servidor que puede usar para ejecutar código controlado por eventos sin aprovisionar ni administrar la infraestructura. El proceso de trabajo de Go permite escribir Azure Functions de forma nativa en Go, con una integración estrecha con el ecosistema de desencadenadores de Azure Functions.

Esta guía le ayuda a:

• Descripción del modelo de programación de Go
• Crear y estructurar el código del proyecto
• Trabajar con desencadenadores
• Implementar y ejecutar la aplicación localmente y en Azure

Para obtener más información sobre el desarrollo de Azure Functions en general, consulte la referencia del desarrollador de Azure Functions.

Cómo empezar

Elija el entorno que se adapte al flujo de trabajo y empiece a trabajar con Azure Functions para Go:

• Inicio rápido de la línea de comandos

Prerequisites

• Go 1.24 o una versión posterior
• Azure Functions Core Tools versión 4.12 o posterior. Ejecute func --version para comprobar la versión instalada.
• CLI de Azure versión 2.87.0 o posterior, al crear recursos Azure o implementar paquetes en Azure. Ejecute az version para comprobar la versión instalada.

Modelo de programación

El worker de Go usa un modelo de programación centrado en el código. Las funciones sin servidor y sus desencadenadores se definen mediante controladores de Go idiomáticos.

Punto de entrada

Cada proyecto de código de Go comienza con una main() función que crea una FunctionAppfunción , registra las funciones e inicia el trabajo:

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

Registro de funciones

Registre funciones mediante la API fluent builder con el patrón de opciones funcionales. Cada tipo de desencadenador tiene un método de registro en el App objeto :

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

Estructura del proyecto

Un proyecto de código de Go para Azure Functions es un módulo de Go estándar. Al ejecutar func init --worker-runtime go, se generan los siguientes archivos:

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

El host.json archivo contiene opciones de configuración de nivel de host. Para obtener más información, consulte la referencia dehost.json.

local.settings.json

El local.settings.json archivo almacena la configuración de la aplicación y las cadenas de conexión que se usan durante el desarrollo local. Este archivo no se publica en Azure. Para más información, consulte Archivo de configuración local.

Desencadenadores

El trabajo de Go organiza los desencadenadores en dos niveles en función de sus requisitos de dependencia:

Desencadenadores principales

Los desencadenadores principales reciben su carga en línea a través de gRPC. El host de Azure Functions serializa los datos del activador en el mensaje gRPC, y el proceso de trabajo los deserializa en estructuras tipadas de Go. Estos desencadenadores tienen:

• Firmas de controlador tipadas con seguridad en tiempo de compilación
• No se necesitan dependencias externas del SDK de Azure: solo se necesita encoding/json
• Cargas limitadas: los documentos, los mensajes y los eventos de fuente de cambios son objetos discretos y limitados por tamaño

Desencadenadores principales admitidos:

Trigger	Firma del manejador	Método de registro
HTTP	func(http.ResponseWriter, *http.Request)	app.HTTP()
Timer	TimerHandler	app.Timer()
Azure Cosmos DB (la base de datos de Azure Cosmos)	func(context.Context, []bindings.CosmosDocument) error	app.CosmosDB()
Azure Service Bus (cola)	ServiceBusHandler	app.ServiceBusQueue()
Azure Service Bus (tema)	ServiceBusHandler	app.ServiceBusTopic()
Event Hubs	EventHubHandler	app.EventHub()
Event Grid	EventGridHandler	app.EventGrid()

Desencadenadores de extensión

Los desencadenadores de extensión proporcionan un cliente de SDK de Azure autenticado en lugar de datos sin procesar. El host solo envía metadatos (como el nombre del contenedor y la ruta del blob), y el proceso de trabajo crea un cliente limitado al recurso específico. Estos desencadenadores tienen:

• Inserción de cliente del SDK: el controlador recibe un cliente listo para usar
• Dependencias aisladas: los paquetes del SDK de Azure se encuentran en triggers/<name>/
• Compatibilidad con streaming: permite leer cargas grandes sin almacenar en búfer a través de gRPC.

Para usar un desencadenador de extensión, agregue una importación en blanco para el paquete de extensión:

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

Trigger	El controlador recibe	Método de registro
Blob Storage	*blob.Client	app.Blob()

Ejemplo de desencadenador de blobs

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
}

Desencadenadores HTTP

Los controladores de activadores HTTP usan tipos estándar de Go net/http, lo que hace que resulten inmediatamente familiares para los desarrolladores de 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)
}

Registrar funciones HTTP con métodos y nivel de autorización:

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

Transmisión por HTTP

El worker de Go es compatible con la transmisión HTTP en escenarios como eventos enviados por el servidor o el envío de grandes volúmenes de datos de respuesta:

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

Activador del temporizador

Los desencadenadores de temporizador se ejecutan según una programación definida por una expresión 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
}

Administración de dependencias

Los proyectos de código de Go usan módulos de Go estándar para la administración de dependencias.

1. Inicialice un nuevo módulo:

   go mod init myapp
   

2. Agregue el SDK de trabajo de Azure Functions Go:

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

   Para la compatibilidad con el desencadenador de blobs, la dependencia se incluye automáticamente a través de la importación en blanco de triggers/blob.

3. Dependencias ordenadas:

   go mod tidy
   

Ejecutar localmente

Use Azure Functions Core Tools para ejecutar el proyecto localmente:

func start

Core Tools automáticamente:

1. Detecta FUNCTIONS_WORKER_RUNTIME = "native" desde local.settings.json.
2. Resuelve el tiempo de ejecución de trabajo nativo en Go cuando hay un go.mod archivo presente.
3. Ejecuta go build -o bin/app . para compilar el proyecto para el sistema operativo local.
4. Inicia el host de Azure Functions, que se comunica con el binario compilado a través de gRPC.
5. Muestra los endpoints de tus funciones (por ejemplo, http://localhost:7071/api/hello).

Use local.settings.json para configurar variables de entorno para el desarrollo local:

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

El valor generado AzureWebJobsStorage está vacío para los proyectos de Go. Establézcalo como una cadena de conexión de una cuenta de almacenamiento o UseDevelopmentStorage=true cuando use desencadenadores que requieran almacenamiento del host durante el desarrollo local.

Deployment

Compilación y empaquetado

Azure Functions Core Tools versión 4.12 o posterior gestiona las compilaciones de Go para los flujos habituales de implementación local y en Azure:

• func start compila el proyecto como bin/app para el sistema operativo local antes de iniciar el host local de Functions.
• func azure functionapp publish compila, empaqueta e implementa el proyecto en una aplicación de funciones existente en Azure.
• func pack compila el proyecto como bin/app para Linux x64 y crea un paquete .zip implementable.

Al empaquetar para Azure, el archivo .zip generado contiene los archivos necesarios para el host de Functions de Linux. El binario compilado se almacena como bin/app en el proyecto local, pero Core Tools lo coloca en la raíz del paquete de implementación como aplicación.

Si usa func pack --no-build, debe compilar el binario x64 de Linux antes de empaquetar:

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

Implementación con Core Tools

Use func azure functionapp publish para implementar el proyecto de Go en una aplicación de funciones existente en Azure:

func azure functionapp publish <APP_NAME>

Reemplace <APP_NAME> por el nombre de la aplicación de función.

Implementación de un paquete ZIP

Use func pack cuando necesite crear un paquete de implementación independientemente de la publicación:

1. Cree un artefacto zip que se pueda implementar:

   func pack
   

2. Implemente el paquete mediante el CLI de Azure:

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

El paquete generado por func pack está listo para ejecutarse en Azure, por lo que no solicite una compilación remota al implementarlo.

Compatibilidad con Docker

Puede ejecutar proyectos de código de Go en contenedores. Inicialice un proyecto con compatibilidad con Docker:

func init --worker-runtime go --docker

El comando genera un Dockerfile junto con los archivos de proyecto estándar.

Telemetría y observabilidad

El proceso de trabajo de Go para Azure Functions admite el registro estructurado y la observabilidad basada en OpenTelemetry. Use métodos compatibles con el contexto del paquete estándar log/slog , como slog.InfoContext, para correlacionar los registros con la invocación de función actual. Para habilitar OpenTelemetry, configure el host de Functions y registre el middleware de OpenTelemetry para el trabajador de Go en su aplicación. Para obtener instrucciones de configuración, consulte Use OpenTelemetry con Azure Functions.

Limitaciones conocidas (versión preliminar)

Durante la versión preliminar pública, se aplican las siguientes limitaciones:

• func new no es compatible. Agregue funciones editando main.go directamente.
• Durable Functions no es compatible con Go durante la vista previa pública.
• Las aplicaciones de funciones de Go solo se ejecutan en Linux en Azure.
• Solo se admiten los desencadenadores enumerados en Desencadenadores durante la versión preliminar.
• El empaquetado de go en Core Tools está destinado actualmente a aplicaciones x64 de Linux.

Pasos siguientes

• Creación de la primera función go
• Enlaces y desencadenadores de Azure Functions
• Uso de OpenTelemetry con Azure Functions
• Ejemplos del proceso de trabajo de Go de Azure Functions
• Guía para desarrolladores de Azure Functions