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:

• Início rápido da linha de comandos

Pré-requisitos

• Vai para a versão 1.24 ou posterior
• Funções do Azure Core Tools versão 4.12 ou posterior. Corre func --version para verificar a versão instalada.
• CLI do Azure versão 2.87.0 ou posterior, quando crias Azure recursos ou implementas pacotes para Azure. Corre az version para verificar a versão instalada.

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 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 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 trabalhador Go organiza os gatilhos em dois níveis com base nos requisitos de dependência:

Acionadores principais

Os disparadores principais recebem a sua carga útil diretamente via gRPC. O host do Funções do Azure serializa os dados do trigger na mensagem gRPC, e o trabalhador desserializa-os em estruturas Go tipadas. 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 principais suportados:

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 nome do contentor e caminho do blob), e o trabalhador constrói um cliente com âmbito para o recurso específico. Estes gatilhos têm:

• 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 um acionador de extensão, adicione uma importação vazia para o pacote de extensão:

import _ "github.com/azure/azure-functions-golang-worker/triggers/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 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
}

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 (pré-visualização)

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

• func new não é suportado. Adiciona funções editando main.go diretamente.
• Durable Functions não é compatível com Go durante a fase de pré-visualização pública.
• As aplicações funcionais do Go correm apenas no Linux no Azure.
• Apenas os gatilhos listados em Triggers são suportados durante a pré-visualização.
• Atualmente, o empacotamento em Go no Core Tools destina-se a aplicações para Linux x64.

Passos seguintes

• Crie a sua primeira função de Go
• Gatilhos e vinculações do Funções do Azure
• Utilizar o OpenTelemetry com as Funções do Azure
• Funções do Azure Go amostras de trabalhadores
• Funções do Azure guia para desenvolvedores