Funções do Azure Go referência para desenvolvedores

Funções do Azure é um serviço de computação serverless que pode usar para executar código orientado a eventos sem necessidade de fornecer ou gerir infraestrutura. O worker Go permite-lhe desenvolver Funções do Azure nativamente em Go, com uma integração estreita no ecossistema de accionadores das Funções do Azure.

Este guia ajuda-o a:

  • Compreenda o modelo de programação do Go
  • Crie e estrutura o seu código de projeto
  • Trabalhar com acionadores
  • Implemente e execute a sua aplicação localmente e no Azure

Para saber mais sobre o desenvolvimento do Funções do Azure em geral, consulte a referência para programadores do Funções do Azure.

Como Começar

Escolha o ambiente que se adapte ao seu fluxo de trabalho e comece com o Funções do Azure for Go:

Pré-requisitos

Modelo de programação

O trabalhador Go utiliza um modelo de programação baseado no código. Pode definir funções sem servidor e os respetivos acionadores utilizando processadores idiomáticos em Go.

Ponto de entrada

Cada projeto de código Go começa com uma main() função que cria um FunctionApp, regista funções e inicia o trabalhador:

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

Registo de funções

Regista funções usando a API fluent builder com o padrão de opções funcionais. Cada tipo de gatilho tem um método de registo 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 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"),
)

Estrutura do projeto

Um projeto de código Go para Funções do Azure é um módulo padrão de Go. Quando executa func init --worker-runtime go, são gerados os seguintes ficheiros:

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 ficheiro contém opções de configuração ao nível do anfitrião. Para mais informações, consulte a host.json referência.

local.settings.json

O local.settings.json ficheiro armazena as definições da aplicação e as strings de ligação usadas durante o desenvolvimento local. Este ficheiro não está publicado no Azure. Para obter mais informações, consulte Arquivo de configurações locais.

Acionadores

O worker Go fornece métodos dedicados de registo para acionadores suportados.

Payloads de acionadores tipados

A maioria dos gatilhos suportados recebe a sua carga útil inline através do gRPC. O host do Funções do Azure serializa os dados de disparo na mensagem gRPC, e o worker desserializa-os em valores Go tipados. Estes gatilhos têm:

  • Assinaturas tipadas de manipuladores com segurança em tempo de compilação
  • Sem dependências de SDK do Azure externas: apenas é necessário encoding/json
  • Cargas úteis limitadas: documentos, mensagens e eventos com fluxo de alterações são objetos discretos e limitados pelo tamanho

Acionadores suportados:

Trigger Assinatura do manipulador Método de registo
HTTP func(http.ResponseWriter, *http.Request) app.HTTP()
Timer TimerHandler app.Timer()
Armazenamento de Filas do Azure QueueHandler app.Queue()
Azure Cosmos DB func(context.Context, []bindings.CosmosDocument) error app.CosmosDB()
Azure Service Bus (Queue) ServiceBusHandler app.ServiceBusQueue()
Azure Service Bus (Tópico) ServiceBusHandler app.ServiceBusTopic()
Hubs de Eventos EventHubHandler app.EventHub()
Event Grid EventGridHandler app.EventGrid()
SQL do Azure func(context.Context, []bindings.SQLChange) error app.SQL()

O Event Hubs e o Service Bus também suportam manipuladores de lotes fortemente tipados através de app.EventHubBatch(), app.ServiceBusQueueBatch(), e app.ServiceBusTopicBatch().

Ligações de tipo SDK

As ligações de tipo SDK fornecem um cliente SDK do Azure autenticado em vez de dados de trigger serializados. Para Go, os gatilhos Armazenamento de Blobs suportam associações de tipo SDK. O host envia metadados, como o nome do contentor e o caminho do blob, e o worker constrói um cliente com âmbito para o recurso específico. As associações de tipos do SDK fornecem:

  • Injeção de cliente SDK: o handler recebe um cliente pronto a usar
  • Dependências isoladas: os pacotes do SDK do Azure estão em triggers/<name>/
  • Suporte a streaming: permite ler grandes cargas úteis sem buffering através do gRPC

Para usar a vinculação do tipo Armazenamento de Blobs SDK, adicione uma importação em branco para o pacote Blob trigger:

import _ "github.com/azure/azure-functions-golang-worker/triggers/blob"
Trigger Handler recebe Método de registo
Armazenamento de Blobs *blob.Client app.Blob()

Exemplo de accionador 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 genéricos do host

Utilize app.GenericTrigger() quando uma extensão de anfitrião compatível fornece um acionador que não tem um método dedicado de registo Go. Gatilhos genéricos suportam texto bruto, fatias de bytes e tipos Go compatíveis com 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}]`,
    },
})

A extensão do host compatível deve ser instalada. O registo genérico de triggers não fornece tratamento HTTP, injeção de clientes SDK, repetição do Durable Functions ou liquidação de mensagens específicas do serviço. Para exemplos completos, veja a amostra de gatilhos genéricos.

Gatilhos HTTP

Os manipuladores de gatilhos HTTP usam tipos padrão de Go net/http , tornando-os imediatamente familiares para os programadores 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)
}

Registar funções HTTP com métodos e nível de autorização:

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

Transmissão HTTP

O worker do Go suporta streaming HTTP para cenários como eventos enviados pelo servidor ou envio de grandes 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()
    }
}

Acionador de Cronómetro

Os gatilhos temporizadores executam-se num cronograma 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
}

Durable Functions

O Go suporta orquestrações e atividades do Durable Functions através do pacote middleware/durabletask. Registe os seus orquestradores e atividades com o middleware Durable antes de adicionar o middleware à aplicação de funções:

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

Durable Functions for Go requer a extensão Durable Task versão 3.15.0 ou posterior. As entidades não são atualmente suportadas. Para uma aplicação completa, consulte o exemplo Durable Functions.

Gestão de dependências

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

  1. Inicializar um novo módulo:

    go mod init myapp
    
  2. Adicione o SDK do trabalhador do Go para o Funções do Azure:

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

    Para suportar o acionador de blobs, a dependência é incluída automaticamente por meio da importação em branco de triggers/blob.

  3. Dependências organizadas:

    go mod tidy
    

Executar localmente

Utilize as ferramentas Funções do Azure Core Tools para executar o seu projeto localmente:

func start

Ferramentas Essenciais automaticamente:

  1. Detete FUNCTIONS_WORKER_RUNTIME = "native" a partir de local.settings.json.
  2. Resolve o runtime nativo do worker para Go quando estiver presente um ficheiro go.mod.
  3. Executa go build -o bin/app . para compilar o seu projeto para o seu sistema operativo local.
  4. Inicia o host do Funções do Azure, que comunica com o binário compilado via gRPC.
  5. Mostra os endpoints das suas funções (por exemplo, http://localhost:7071/api/hello).

Utilizar 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-o como uma cadeia de ligação a uma conta de armazenamento ou UseDevelopmentStorage=true quando utiliza gatilhos que requerem armazenamento do host durante o desenvolvimento local.

Deployment

Compilação e embalagem

Funções do Azure Core Tools versão 4.12 ou posterior processa as compilações em Go para os fluxos comuns de implementação local e no Azure:

  • func start constrói o teu projeto como bin/app para o teu sistema operativo local antes de iniciar o host local de Functions.
  • func azure functionapp publish constrói, empacota e implementa o seu projeto numa aplicação de funções existente em Azure.
  • func pack constrói o teu projeto como bin/app para Linux x64 e cria um pacote de .zip deployável.

Ao empacotar para Azure, o ficheiro de .zip gerado contém os ficheiros necessários ao host Linux Functions. O binário compilado é armazenado como bin/app no teu projeto local, mas o Core Tools coloca-o na raiz do pacote de deployment como app.

Se usar func pack --no-build, deve construir o binário Linux x64 antes de embalar:

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

Implementar com o Core Tools

Use func azure functionapp publish para implementar o seu projeto Go numa aplicação de funções existente em Azure:

func azure functionapp publish <APP_NAME>

Substitua <APP_NAME> pelo nome do seu aplicativo de função.

Implementar um pacote zip

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

  1. Crie um artefacto ZIP para implementação:

    func pack
    
  2. Implemente o pacote usando a 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 correr em Azure, por isso não peça uma compilação remota quando o implementar.

Suporte ao Docker

Podes executar projetos de código Go em containers. Inicialize um projeto com suporte Docker:

func init --worker-runtime go --docker

O comando gera um Dockerfile juntamente com os ficheiros padrão do projeto.

Telemetria e observabilidade

O worker Funções do Azure Go suporta registo estruturado e observabilidade baseada em OpenTelemetry. Use métodos conscientes do contexto do pacote padrão log/slog , como slog.InfoContext, para correlacionar os registos com a invocação atual da função. Para ativar o OpenTelemetry, configura o host Functions e regista o middleware Worker do Go OpenTelemetry na tua aplicação. Para instruções de configuração, consulte Use OpenTelemetry com Funções do Azure.

Limitações conhecidas

  • func new não é suportado. Adiciona funções editando main.go diretamente.
  • As aplicações de função Go correm apenas no Linux no plano Flex Consumption.
  • Apenas os gatilhos dedicados listados em Triggers e os gatilhos genéricos compatíveis são suportados.
  • Atualmente, não são suportados bindings adicionais de entrada e de saída que não sejam HTTP.
  • Atualmente, o empacotamento em Go no Core Tools destina-se a aplicações para Linux x64.

Passos seguintes