referencia para desarrolladores de Azure Functions Go

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 trabajo de Go permite escribir Azure Functions de forma nativa en Go, con una integración profunda 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 trabajo de Go utiliza 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 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"),
)

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 trabajador Go proporciona métodos de registro dedicados para los disparadores soportados.

Cargas útiles tipadas del desencadenador

La mayoría de los disparadores soportados reciben su carga útil en línea a través de gRPC. El host de Azure Functions serializa los datos de disparo en el mensaje gRPC, y el trabajador los deserializa en valores Go tipados. 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 admitidos:

Trigger	Firma del manejador	Método de registro
HTTP	`func(http.ResponseWriter, *http.Request)`	`app.HTTP()`
Timer	`TimerHandler`	`app.Timer()`
Almacenamiento de colas de Azure	`QueueHandler`	`app.Queue()`
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()`
Azure SQL	`func(context.Context, []bindings.SQLChange) error`	`app.SQL()`

Event Hubs y Service Bus también soportan manejadores de lotes fuertemente tipados a través de app.EventHubBatch(), app.ServiceBusQueueBatch(), y app.ServiceBusTopicBatch().

Enlaces de tipos de SDK

Las asociaciones de tipos del SDK proporcionan un cliente autenticado del SDK de Azure en lugar de datos de desencadenador serializados. Para Go, los disparadores Blob Storage admiten enlaces de tipo SDK. El host envía metadatos, como el nombre del contenedor y la ruta del blob, y el worker construye un cliente con alcance al recurso específico. Las vinculaciones de tipo SDK proporcionan:

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 el enlace de tipo del SDK de Blob Storage, añade una importación en blanco para el paquete del desencadenador Blob:

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
}

Activadores de host genéricos

Usa app.GenericTrigger() cuando una extensión de host compatible proporciona un disparador que no tiene un método de registro dedicado de Go. Los disparadores genéricos soportan texto en bruto, slices de bytes y tipos de Go compatibles 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}]`,
    },
})

Debe instalarse la extensión compatible del host. El registro genérico de desencadenadores no proporciona gestión HTTP, inyección de clientes SDK, reproducción de Durable Functions ni administración de mensajes específica del servicio. Para ejemplos completos, véase el ejemplo de desencadenantes genéricos.

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
}

Durable Functions

Go soporta orquestaciones y actividades de Durable Functions a través del middleware/durabletask paquete. Registra tus orquestadores y actividades con el middleware Durable antes de añadir el middleware a la app de funciones:

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

Durable Functions for Go requiere la extensión Durable Task versión 3.15.0 o posterior. Actualmente, las entidades no están soportadas. Para una aplicación completa, véase el ejemplo de Durable Functions.

Administración de dependencias

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

Inicialice un nuevo módulo:
```
go mod init myapp
```
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.
Dependencias ordenadas:
```
go mod tidy
```

Ejecutar localmente

Use Azure Functions Core Tools para ejecutar el proyecto localmente:

func start

Core Tools automáticamente:

Detecta FUNCTIONS_WORKER_RUNTIME = "native" de local.settings.json.
Resuelve el tiempo de ejecución de trabajo nativo en Go cuando hay un archivo go.mod presente.
Ejecuta go build -o bin/app . para compilar el proyecto para el sistema operativo local.
Inicia el host de Azure Functions, que se comunica con el binario compilado a través de gRPC.
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:

Cree un artefacto zip que se pueda implementar:
```
func pack
```

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 trabajo de Go de Azure Functions admite registro estructurado y 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 del trabajo de Go en la aplicación. Para obtener instrucciones de configuración, consulte Use OpenTelemetry con Azure Functions.

Limitaciones conocidas

func new no es compatible. Agregue funciones editando main.go directamente.
Las aplicaciones de funciones de Go solo funcionan en Linux con el plan Flex Consumption.
Solo se soportan los activadores dedicados listados en Triggers y los activadores genéricos compatibles del anfitrión.
Actualmente, no se soportan vinculaciones de entrada adicionales ni vinculaciones de salida no HTTP en este momento.
El empaquetado de go en Core Tools está destinado actualmente a aplicaciones x64 de Linux.

Pasos siguientes

Comentarios

¿Le ha resultado útil esta página?

Se actualizó por última vez el 2026-10-23