Definição dos manipuladores de função do Lambda em Go

O manipulador da função do Lambda é o método no código da função que processa eventos. Quando sua função é invocada, o Lambda executa o método do manipulador. A função é executada até que o manipulador retorne uma resposta, seja encerrado ou atinja o tempo limite.

Esta página descreve como trabalhar com manipuladores de função do Lambda em Go, incluindo a configuração de projeto, as convenções de nomenclatura e as práticas recomendadas. Além disso, esta página apresenta um exemplo de uma função do Lambda em Go que aceita informações sobre um pedido, produz um recibo em formato de texto e armazena esse arquivo em um bucket do Amazon Simple Storage Service (S3). Para obter mais informações sobre como implantar a função após gravá-la, consulte Implantar funções do Lambda em Go com arquivos .zip ou Implantar funções do Lambda em Go com imagens de contêiner.

Configuração do projeto de manipulador em Go

Uma função do Lambda escrita em Go é criada como um executável do Go. É possível inicializar um projeto de função do Lambda em Go da mesma forma que inicializa qualquer outro projeto em Go, usando o seguinte comando go mod init:

go mod init example-go

Neste caso, example-go é o nome do módulo. Você pode substituí-lo por qualquer nome que desejar. Este comando inicializa seu projeto e gera o arquivo go.mod, que lista as dependências do projeto.

Use o comando go get para adicionar quaisquer dependências externas ao seu projeto. Por exemplo, para todas as funções do Lambda em Go, é necessário incluir o pacote github.com/aws/aws-lambda-go/lambda, que implementa o modelo de programação do Lambda para Go. Para incluir este pacote, use o seguinte comando go get:

go get github.com/aws/aws-lambda-go

O código da sua função deve estar em um arquivo em Go. No exemplo apresentado a seguir, chamamos esse arquivo de main.go. Neste arquivo, você implementa a lógica principal da função em um método manipulador, bem como uma função main() que chama esse manipulador.

Exemplo de código de função do Lambda em Go

O exemplo de código apresentado a seguir para uma função do Lambda em Go aceita informações sobre um pedido, produz um recibo em formato de texto e armazena esse arquivo em um bucket do Amazon S3.

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"os"
	"strings"

	"github.com/aws/aws-lambda-go/lambda"
	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/aws/aws-sdk-go-v2/service/s3"
)

type Order struct {
	OrderID string  `json:"order_id"`
	Amount  float64 `json:"amount"`
	Item    string  `json:"item"`
}

var (
	s3Client *s3.Client
)

func init() {
	// Initialize the S3 client outside of the handler, during the init phase
	cfg, err := config.LoadDefaultConfig(context.TODO())
	if err != nil {
		log.Fatalf("unable to load SDK config, %v", err)
	}

	s3Client = s3.NewFromConfig(cfg)
}

func uploadReceiptToS3(ctx context.Context, bucketName, key, receiptContent string) error {
	_, err := s3Client.PutObject(ctx, &s3.PutObjectInput{
		Bucket: &bucketName,
		Key:    &key,
		Body:   strings.NewReader(receiptContent),
	})
	if err != nil {
		log.Printf("Failed to upload receipt to S3: %v", err)
		return err
	}
	return nil
}

func handleRequest(ctx context.Context, event json.RawMessage) error {
	// Parse the input event
	var order Order
	if err := json.Unmarshal(event, &order); err != nil {
		log.Printf("Failed to unmarshal event: %v", err)
		return err
	}

	// Access environment variables
	bucketName := os.Getenv("RECEIPT_BUCKET")
	if bucketName == "" {
		log.Printf("RECEIPT_BUCKET environment variable is not set")
		return fmt.Errorf("missing required environment variable RECEIPT_BUCKET")
	}

	// Create the receipt content and key destination
	receiptContent := fmt.Sprintf("OrderID: %s\nAmount: $%.2f\nItem: %s",
		order.OrderID, order.Amount, order.Item)
	key := "receipts/" + order.OrderID + ".txt"

	// Upload the receipt to S3 using the helper method
	if err := uploadReceiptToS3(ctx, bucketName, key, receiptContent); err != nil {
		return err
	}

	log.Printf("Successfully processed order %s and stored receipt in S3 bucket %s", order.OrderID, bucketName)
	return nil
}

func main() {
	lambda.Start(handleRequest)
}

Este arquivo main.go contém as seguintes seções de código:

Para que esta função funcione corretamente, seu perfil de execução deve permitir a ação s3:PutObject. Além disso, certifique-se de definir a variável de ambiente RECEIPT_BUCKET. Após uma invocação com êxito, o bucket do Amazon S3 deve conter um arquivo de recibo.

Convenções de nomenclatura para manipuladores

Para funções do Lambda em Go, você pode usar qualquer nome para o manipulador. Neste exemplo, o nome do método do manipulador é handleRequest. Para referenciar o valor do manipulador em seu código, você pode usar a variável de ambiente _HANDLER.

Para funções em Go implantadas usando um pacote de implantação .zip, o arquivo executável que contém o código da sua função deve ser nomeado bootstrap. Além disso, o arquivo bootstrap deve estar na raiz do arquivo .zip. Para funções em Go implantadas usando uma imagem de contêiner, é possível usar qualquer nome para o arquivo executável.

Definição e acesso ao objeto do evento de entrada

O formato de entrada JSON é o mais comum e padrão para funções do Lambda. Neste exemplo, a função espera uma entrada semelhante à seguinte:

{
    "order_id": "12345",
    "amount": 199.99,
    "item": "Wireless Headphones"
}

Ao trabalhar com funções do Lambda em Go, é possível definir o formato do evento de entrada esperado como uma estrutura em Go. Neste exemplo, definimos uma estrutura para representar um Order:

type Order struct {
    OrderID string  `json:"order_id"`
    Amount  float64 `json:"amount"`
    Item    string  `json:"item"`
}

Essa estrutura corresponde ao formato de entrada esperado. Após definir a estrutura, você pode gravar uma assinatura de manipulador que aceita um tipo JSON genérico compatível com a biblioteca padrão encoding/json. Em seguida, é possível realizar a desserialização em sua estrutura ao usar a função func Unmarshal. Isso é ilustrado nas primeiras linhas do manipulador:

func handleRequest(ctx context.Context, event json.RawMessage) error {
    // Parse the input event
    var order Order
    if err := json.Unmarshal(event, &order); err != nil {
        log.Printf("Failed to unmarshal event: %v", err)
        return err
    ...
}

Após a desserialização, é possível acessar os campos da variável order. Por exemplo, order.OrderID recupera o valor de "order_id" da entrada original.

Acesso e uso do objeto de contexto do Lambda

O objeto de contexto do Lambda contém informações sobre a invocação, a função e o ambiente de execução. Neste exemplo, declaramos essa variável como ctx na assinatura do manipulador:

func handleRequest(ctx context.Context, event json.RawMessage) error {
    ...
}

A entrada ctx context.Context é um argumento opcional em seu manipulador de função. Para obter mais informações sobre as assinaturas de manipulador aceitas, consulte Assinaturas de manipulador válidas para manipuladores em Go.

Se você realizar chamadas a outros serviços usando o AWS SDK, o objeto de contexto será necessário em algumas áreas importantes. Por exemplo, para inicializar corretamente os clientes do SDK, é possível carregar a configuração adequada do AWS SDK usando o objeto de contexto da seguinte maneira:

// Load AWS SDK configuration using the default credential provider chain
    cfg, err := config.LoadDefaultConfig(ctx)

As próprias chamadas do SDK podem exigir o objeto de contexto como um parâmetro de entrada. Por exemplo, a chamada s3Client.PutObject aceita o objeto de contexto como seu primeiro argumento:

// Upload the receipt to S3
    _, err = s3Client.PutObject(ctx, &s3.PutObjectInput{
        ...
    })

Além das solicitações do AWS SDK, é possível usar o objeto de contexto para realizar o monitoramento da função. Para obter mais informações sobre o objeto de contexto, consulte Usar o objeto de contexto do Lambda para recuperar informações das funções em Go.

Assinaturas de manipulador válidas para manipuladores em Go

Há várias opções ao criar um manipulador de função do Lambda no Go, mas você deve observar as seguintes regras:

As assinaturas válidas de manipulador são listadas a seguir. TIn e TOut representam tipos compatíveis com a biblioteca encoding/json padrão. Para obter mais informações, consulte func Unmarshal para saber como esses tipos são desserializados.

Uso do AWS SDK for Go v2 em seu manipulador

Frequentemente, você usará as funções do Lambda para interagir com ou fazer atualizações em outros recursos da AWS. A maneira mais simples de interagir com esses recursos é usar o AWS SDK for Go v2.

Para adicionar as dependências do SDK à sua função, use o comando go get para os clientes específicos do SDK que você precisa. No código de exemplo anterior, usamos a biblioteca config e a biblioteca s3. Adicione essas dependências ao executar os seguintes comandos no diretório que contém seus arquivos go.mod e main.go :

go get github.com/aws/aws-sdk-go-v2/config
go get github.com/aws/aws-sdk-go-v2/service/s3

Em seguida, importe as dependências correspondentes no bloco “import” da sua função:

import (
    ...
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

Ao usar o SDK no seu manipulador, configure os clientes com as configurações adequadas. A maneira mais simples de fazer isso é usar a cadeia de provedores de credenciais padrão. Este exemplo ilustra uma forma de carregar essa configuração:

// Load AWS SDK configuration using the default credential provider chain
    cfg, err := config.LoadDefaultConfig(ctx)
    if err != nil {
        log.Printf("Failed to load AWS SDK config: %v", err)
        return err
    }

Após carregar essa configuração na variável cfg, você pode fornecê-la nas instâncias dos clientes. No exemplo, o código cria uma instância de cliente do Amazon S3 da seguinte maneira:

// Create an S3 client
    s3Client := s3.NewFromConfig(cfg)

Neste exemplo, inicializamos nosso cliente do Amazon S3 na função init() para evitar a necessidade de inicializá-lo a cada vez que nossa função é invocada. O problema é que, na função init(), o Lambda não tem acesso ao objeto de contexto. Como solução alternativa, você pode fornecer um espaço reservado, como context.TODO(), durante a fase de inicialização. Posteriormente, ao fazer uma chamada usando o cliente, forneça o objeto de contexto completo. Esta solução alternativa também é descrita em Uso do contexto nas inicializações e nas chamadas do cliente do AWS SDK.

Após configurar e inicializar o cliente do SDK, você pode usá-lo para interagir com outros serviços da AWS. O código de exemplo chama a API PutObject do Amazon S3 da seguinte forma:

_, err = s3Client.PutObject(ctx, &s3.PutObjectInput{
    Bucket: &bucketName,
    Key:    &key,
    Body:   strings.NewReader(receiptContent),
})

Acesso a variáveis de ambiente

No código do manipulador, você pode fazer referência a qualquer variável de ambiente ao usar o método os.Getenv(). Neste exemplo, referenciamos a variável de ambiente RECEIPT_BUCKET definida usando a seguinte linha de código:

// Access environment variables
    bucketName := os.Getenv("RECEIPT_BUCKET")
    if bucketName == "" {
        log.Printf("RECEIPT_BUCKET environment variable is not set")
        return fmt.Errorf("missing required environment variable RECEIPT_BUCKET")
    }

Usar o estado global

Para evitar a criação de novos recursos a cada vez que você invoca a função, é possível declarar e modificar variáveis globais externas ao código do manipulador da função do Lambda. Defina essas variáveis globais em um bloco ou em uma instrução em var. Além disso, o manipulador pode declarar uma função init() que é executada durante a fase de inicialização. No AWS Lambda, o método init se comporta de maneira idêntica aos programas em Go padrão.

Práticas recomendadas de código para as funções do Lambda em GO

Adote as diretrizes da lista a seguir para usar as práticas recomendadas de codificação ao compilar suas funções do Lambda: