Referência do desenvolvedor do Azure Functions Go

Importante

O suporte do Go para Azure Functions está atualmente em versão prévia pública. Durante a versão prévia, os aplicativos de funções Go têm suporte apenas no plano de Consumo Flex.

Azure Functions é um serviço de computação sem servidor que você pode usar para executar código controlado por eventos sem provisionar ou gerenciar a infraestrutura. O worker do Go permite que você desenvolva Azure Functions nativamente em Go, com integração profunda ao ecossistema de gatilhos do Azure Functions.

Este guia ajuda você a:

Entender o modelo de programação go
Criar e estruturar o código do projeto
Trabalhar com gatilhos
Implantar e executar seu aplicativo localmente e em Azure

Para saber mais sobre o desenvolvimento do Azure Functions em geral, consulte a referência do desenvolvedor do Azure Functions.

Como começar

Escolha o ambiente que se ajusta ao fluxo de trabalho e comece a usar Azure Functions para Go:

Início rápido da linha de comando

Prerequisites

Go 1.24 ou posterior
Azure Functions Core Tools versão 4.12 ou posterior. Execute func --version para verificar sua versão instalada.
CLI do Azure versão 2.87.0 ou posterior, ao criar recursos Azure ou implantar pacotes para Azure. Execute az version para verificar sua versão instalada.

Modelo de programação

O Go worker utiliza um modelo de programação code-first. Você define funções sem servidor e seus gatilhos usando manipuladores go idiomáticos.

Ponto de entrada

Todo projeto de código Go começa com uma função main() que cria um(a) FunctionApp, registra funções e inicia o 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)
}

Registro de função

Registre funções por meio da API fluente de construção, com o padrão de opções funcionais. Cada tipo de gatilho tem um método de registro no 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"),
)

Estrutura do Projeto

Um projeto de código Go para Azure Functions é um módulo Go padrão. Quando você executa func init --worker-runtime go, os seguintes arquivos são gerados:

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

O host.json arquivo contém opções de configuração no nível do host. Para obter mais informações, consulte a referência do host.json.

local.settings.json

O local.settings.json arquivo armazena as configurações do aplicativo e as cadeias de conexão usadas durante o desenvolvimento local. Este arquivo não é publicado no Azure. Para obter mais informações, confira Arquivo de configurações local.

Gatilhos

O go worker organiza gatilhos em duas camadas com base em seus requisitos de dependência:

Gatilhos principais

Os gatilhos centrais recebem sua carga útil diretamente via gRPC. O host do Azure Functions serializa os dados do gatilho em uma mensagem gRPC, e o worker os desserializa em structs Go tipadas. Esses gatilhos têm:

Assinaturas de manipulador tipadas com segurança em tempo de compilação
Não dependências de SDK do Azure externas: somente encoding/json é necessário
Cargas limitadas: documentos, mensagens e eventos do feed de alterações são objetos discretos e limitados por tamanho

Gatilhos centrais compatíveis:

Trigger	Assinatura do manipulador	Método de registro
HTTP	`func(http.ResponseWriter, *http.Request)`	`app.HTTP()`
Timer	`TimerHandler`	`app.Timer()`
Azure Cosmos DB	`func(context.Context, []bindings.CosmosDocument) error`	`app.CosmosDB()`
Barramento de Serviço do Azure (Fila)	`ServiceBusHandler`	`app.ServiceBusQueue()`
Barramento de Serviço do Azure (Tópico)	`ServiceBusHandler`	`app.ServiceBusTopic()`
Hubs de Eventos	`EventHubHandler`	`app.EventHub()`
Grade de Eventos	`EventGridHandler`	`app.EventGrid()`

Acionadores de extensão

Os gatilhos de extensão fornecem um cliente SDK do Azure autenticado em vez de dados brutos. O host envia apenas metadados (como o nome do contêiner e o caminho do blob), e o processo de trabalho constrói um cliente restrito ao recurso específico. Esses gatilhos têm:

Injeção de cliente do SDK: o manipulador recebe um cliente pronto para uso
Dependências isoladas: os pacotes do SDK do Azure ficam em triggers/<name>/
Suporte de streaming: habilita a leitura de cargas grandes sem buffer por meio de gRPC

Para usar um gatilho de extensão, adicione uma importação em branco para o pacote de extensão:

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

Trigger	O manipulador recebe	Método de registro
Armazenamento de Blobs	`*blob.Client`	`app.Blob()`

Exemplo de gatilho de 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
}

Gatilhos HTTP

Os manipuladores de gatilho HTTP usam tipos go net/http padrão, tornando-os imediatamente familiares aos desenvolvedores do 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 funções HTTP com métodos e nível de autorização:

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

Streaming HTTP

O worker do Go oferece suporte a streaming HTTP para cenários como eventos enviados por servidor ou o envio de grandes volumes de dados de resposta:

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

Disparador de temporizador

Os gatilhos do temporizador são executados em um agendamento definido por uma expressão 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
}

Gerenciamento de dependência

Os projetos de código go usam módulos Go padrão para gerenciamento de dependências.

Inicializar um novo módulo:
```
go mod init myapp
```
Adicione o SDK de trabalho do Azure Functions Go:
```
go get github.com/azure/azure-functions-golang-worker
```
Para dar suporte ao gatilho de blob, a dependência é incluída automaticamente pela importação anônima de triggers/blob.
Dependências arrumadas:
```
go mod tidy
```

Executar localmente

Use o Azure Functions Core Tools para executar seu projeto localmente:

func start

Ferramentas principais automaticamente:

Detecta FUNCTIONS_WORKER_RUNTIME = "native" a partir de local.settings.json.
Resolve o runtime do worker nativo para Go quando um arquivo go.mod estiver presente.
Executa go build -o bin/app . para compilar seu projeto para o sistema operacional local.
Inicia o host Azure Functions, que se comunica com o binário compilado por gRPC.
Exibe os endpoints da função (por exemplo, http://localhost:7071/api/hello).

Use local.settings.json para configurar variáveis de ambiente para desenvolvimento local:

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

O valor gerado AzureWebJobsStorage está vazio para projetos Go. Defina isso como a cadeia de conexão de uma conta de armazenamento ou UseDevelopmentStorage=true quando você usar gatilhos que exigem armazenamento do host durante o desenvolvimento local.

Implantação

Compilação e empacotamento

A versão 4.12 ou posterior do Azure Functions Core Tools cuida das compilações do Go para os fluxos comuns de implantação local e no Azure:

func start cria seu projeto como bin/app para seu sistema operacional local antes de iniciar o host local do Functions.
func azure functionapp publish compila, empacota e implanta seu projeto em um aplicativo de funções existente no Azure.
func pack cria seu projeto como bin/app para Linux x64 e cria um pacote de .zip implantável.

Ao empacotar para Azure, o arquivo .zip gerado contém os arquivos necessários para o host do Linux Functions. O binário compilado é armazenado como bin/app no seu projeto local, mas o Core Tools o coloca na raiz do pacote de implantação como app.

Se você usar func pack --no-build, será necessário criar o binário linux x64 antes de empacotar:

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

Implantar com ferramentas principais

Use func azure functionapp publish para implantar seu projeto Go em um aplicativo de funções existente no Azure:

func azure functionapp publish <APP_NAME>

Substitua <APP_NAME> pelo nome do aplicativo de funções.

Implantar um pacote zip

Use func pack quando precisar criar um pacote de implantação separadamente da publicação:

Crie um artefato ZIP pronto para implantação:
```
func pack
```

Implante o pacote usando o CLI do Azure:

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

O pacote produzido por func pack está pronto para ser executado em Azure, portanto, não solicite um build remoto ao implantá-lo.

Suporte ao Docker

Você pode executar projetos de código Go em contêineres. Inicializar um projeto com suporte ao Docker:

func init --worker-runtime go --docker

O comando gera um Dockerfile junto com os arquivos de projeto padrão.

Telemetria e observabilidade

O trabalho do Azure Functions Go dá suporte ao registro em log estruturado e à observabilidade baseada em OpenTelemetry. Use métodos com reconhecimento de contexto do pacote padrão log/slog , como slog.InfoContext, para correlacionar logs com a invocação de função atual. Para habilitar o OpenTelemetry, configure o host do Functions e registre o middleware OpenTelemetry do trabalho Go em seu aplicativo. Para obter instruções de instalação, consulte Use OpenTelemetry com Azure Functions.

Limitações conhecidas (versão prévia)

Durante a visualização pública, as seguintes limitações se aplicam:

Não há suporte para func new. Adicione funções editando main.go diretamente.
O Durable Functions não é compatível com Go durante a versão prévia pública.
Os aplicativos de funções Go são executados no Linux apenas em Azure.
Somente os gatilhos listados em Gatilhos têm suporte durante a visualização.
Atualmente, o empacotamento do Go no Core Tools é voltado para aplicativos para Linux x64.

Próximas Etapas

Criar sua primeira função Go
Gatilhos e associações de Azure Functions
Utilize o OpenTelemetry com o Azure Functions
exemplos de trabalho do Azure Functions Go
Guia do desenvolvedor do Azure Functions

Comentários

Esta página foi útil?

Last updated on 2026-06-03