Aplicativo de exemplo de função em branco para o AWS Lambda - AWS Lambda
Arquitetura e código do manipuladorAutomação de implantação com o AWS CloudFormation e a AWS CLIInstrumentação com o AWS X-RayGerenciamento de dependências com camadas

Aplicativo de exemplo de função em branco para o AWS Lambda

A aplicação de exemplo de função em branco é uma aplicação inicial que demonstra operações comuns no Lambda com uma função que chama a API do Lambda. Ele mostra o uso de registro em log, variáveis de ambiente, rastreamento do AWS X-Ray, camadas, testes de unidade e do AWS SDK. Explore essa aplicação para saber como criar funções do Lambda em sua linguagem de programação, ou usá-lo como ponto de partida para seus próprios projetos.

As variantes deste aplicativo de exemplo estão disponíveis nas seguintes linguagens:

Variantes

Os exemplos neste tópico destacam o código da versão Node.js, mas os detalhes são geralmente aplicáveis a todas as variantes.

Você pode implantar a amostra em alguns minutos com a AWS CLI e o AWS CloudFormation. Siga as instruções no README para fazer download, configurar e implantá-la na conta.

Arquitetura e código do manipulador

O aplicativo de exemplo consiste em um código de função, um modelo do AWS CloudFormation e recursos de suporte. Ao implantar o exemplo, você usa os seguintes serviços da AWS:

  • AWS Lambda: executa o código da função, envia logs para o CloudWatch Logs e envia dados de rastreamento para o X-Ray. A função também chama a API do Lambda para obter detalhes sobre as cotas e o uso da conta na região atual.

  • AWS X-Ray: coleta de dados de rastreamento, indexa rastreamentos para pesquisa e gera um mapa de serviço.

  • Amazon CloudWatch— armazena logs e métricas.

  • AWS Identity and Access Management(IAM)— concede permissão.

  • Amazon Simple Storage Service (Amazon S3)— armazena o pacote de implantação da função durante a implantação.

  • AWS CloudFormation: cria recursos da aplicação e implanta o código da função.

Aplicam-se taxas padrão para cada serviço. Para obter mais informações, consulte Preços do AWS.

O código da função mostra um fluxo de trabalho básico para processar um evento. O manipulador pega um evento do Amazon Simple Queue Service (Amazon SQS) como entrada e percorre pelos registros que ele contém, registrando em log o conteúdo de cada mensagem. Ele registra o conteúdo do evento, o objeto de contexto e as variáveis de ambiente. Depois, ele faz uma chamada com o AWS SDK e passa a resposta de volta para o tempo de execução do Lambda.

exemplo blank-nodejs/function/index.js: código do handler
// Handler
exports.handler = async function(event, context) {
    event.Records.forEach(record => {
        console.log(record.body);
    });

    console.log('## ENVIRONMENT VARIABLES: ' + serialize(process.env));
    console.log('## CONTEXT: ' + serialize(context));
    console.log('## EVENT: ' + serialize(event));

    return getAccountSettings();
};

// Use SDK client
var getAccountSettings = function() {
    return lambda.send(new GetAccountSettingsCommand());
};

var serialize = function(object) {
    return JSON.stringify(object, null, 2);
};

A amostra de aplicação não inclui uma fila do Amazon SQS para enviar eventos, mas usa um evento do Amazon SQS (event.json) para ilustrar como os eventos são processados. Para adicionar uma fila do Amazon SQS à aplicação, consulte Usar o Lambda com o Amazon SQS.

Automação de implantação com o AWS CloudFormation e a AWS CLI

Os recursos do aplicativo de exemplo são definidos em um modelo do AWS CloudFormation e implantados com a AWS CLI. O projeto inclui scripts de shell simples que automatizam o processo de configuração, implantação, invocação e destruição do aplicativo.

O modelo de aplicativo usa um tipo de recurso AWS Serverless Application Model (AWS SAM) para definir o modelo. O AWS SAM simplifica a criação de modelos para aplicativos sem servidor automatizando a definição de funções de execução, APIs e outros recursos.

O modelo define os recursos na pilha de aplicativos. Isso inclui a função, sua função de execução e uma camada do Lambda que fornece as dependências da biblioteca da função. A pilha não inclui o bucket que a AWS CLI usa durante a implantação nem o grupo de logs do CloudWatch Logs.

exemplo blank-nodejs/template.yml: recursos sem servidor
AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'
Description: An AWS Lambda application that calls the Lambda API.
Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs20.x
      CodeUri: function/.
      Description: Call the AWS Lambda API
      Timeout: 10
      # Function's execution role
      Policies:
        - AWSLambdaBasicExecutionRole
        - AWSLambda_ReadOnlyAccess
        - AWSXrayWriteOnlyAccess
      Tracing: Active
      Layers:
        - !Ref libs
  libs:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: blank-nodejs-lib
      Description: Dependencies for the blank sample app.
      ContentUri: lib/.
      CompatibleRuntimes:
        - nodejs20.x

Quando você implanta o aplicativo, o AWS CloudFormation aplica a transformação do AWS SAM ao modelo para gerar um modelo do AWS CloudFormation com tipos padrão, como AWS::Lambda::Function e AWS::IAM::Role.

exemplo modelo processado
{
  "AWSTemplateFormatVersion": "2010-09-09",
  "Description": "An AWS Lambda application that calls the Lambda API.",
  "Resources": {
    "function": {
      "Type": "AWS::Lambda::Function",
      "Properties": {
        "Layers": [
          {
            "Ref": "libs32xmpl61b2"
          }
        ],
        "TracingConfig": {
          "Mode": "Active"
        },
        "Code": {
          "S3Bucket": "lambda-artifacts-6b000xmpl1e9bf2a",
          "S3Key": "3d3axmpl473d249d039d2d7a37512db3"
        },
        "Description": "Call the AWS Lambda API",
        "Tags": [
          {
            "Value": "SAM",
            "Key": "lambda:createdBy"
          }
        ],

Neste exemplo, a propriedade Code especifica um objeto em um bucket do Amazon S3. Isso corresponde ao caminho local na propriedade CodeUri no modelo de projeto:

      CodeUri: function/.

Para fazer upload dos arquivos do projeto no Amazon S3, o script de implantação usa comandos na AWS CLI. O comando cloudformation package pré-processa o modelo, faz upload de artefatos e substitui caminhos locais por locais de objetos do Amazon S3. O comando cloudformation deploy implanta o modelo processado com um conjunto de alterações do AWS CloudFormation.

exemplo blank-nodejs/3-deploy.sh: empacotar e implantar
#!/bin/bash
set -eo pipefail
ARTIFACT_BUCKET=$(cat bucket-name.txt)
aws cloudformation package --template-file template.yml --s3-bucket $ARTIFACT_BUCKET --output-template-file out.yml
aws cloudformation deploy --template-file out.yml --stack-name blank-nodejs --capabilities CAPABILITY_NAMED_IAM

Da primeira vez que você executar esse script, ele criará uma pilha do AWS CloudFormation chamada blank-nodejs. Se fizer alterações no modelo ou no código da função, você poderá executá-la novamente para atualizar a pilha.

O script de limpeza (blank-nodejs/5-cleanup.sh) exclui a pilha e, opcionalmente, exclui o bucket de implantação e os logs de função.

Instrumentação com o AWS X-Ray

A função de exemplo é configurada para rastreamento com AWS X-Ray. Com o modo de rastreamento definido como ativo, o Lambda registra informações de temporização para um subconjunto de invocações e as envia para o X-Ray. O X-Ray processa os dados para gerar um Mapa de serviço que mostra um nó de cliente e dois nós de serviço.

O primeiro nó de serviço (AWS::Lambda) representa o serviço do Lambda, que valida a solicitação de invocação e o envia para a função. O segundo nó, AWS::Lambda::Function, representa a própria função.

Para registrar detalhes adicionais, a função de exemplo usa o X-Ray SDK. Com alterações mínimas no código de função, o X-Ray SDK registra detalhes sobre chamadas feitas com o AWS SDK para serviços da AWS.

exemplo blank-nodejs/function/index.js: instrumentação
const AWSXRay = require('aws-xray-sdk-core');
const { LambdaClient, GetAccountSettingsCommand } = require('@aws-sdk/client-lambda');

// Create client outside of handler to reuse
const lambda = AWSXRay.captureAWSv3Client(new LambdaClient());

Instrumentar o cliente AWS SDK adiciona um nó extra ao mapa de serviços e mais detalhes em rastreamentos. Neste exemplo, o mapa de serviço mostra a função de exemplo chamando a API do Lambda para obter detalhes sobre armazenamento e uso de simultaneidade na região atual.

O rastreamento mostra detalhes de temporização para a invocação, com subsegmentos para inicialização da função, invocação e sobrecarga. O subsegmento de invocação tem um subsegmento para a chamada do AWS SDK para a operação de API GetAccountSettings.

Você pode incluir o X-Ray SDK e outras bibliotecas no pacote de implantação da função ou implantá-las separadamente em uma camada do Lambda. Para Node.js, Ruby e Python, o tempo de execução do Lambda inclui o AWS SDK no ambiente de execução.

Gerenciamento de dependências com camadas

Você pode instalar bibliotecas localmente e incluí-las no pacote de implantação que carregar no Lambda, mas isso tem suas desvantagens. Tamanhos de arquivo maiores geram tempos de implantação maiores e podem impedir que você teste alterações em seu código de função no console do Lambda. Para manter o pacote de implantação pequeno e evitar o upload de dependências que não foram alteradas, à aplicação de exemplo cria uma camada do Lambda e a associa à função.

exemplo blank-nodejs/template.yml: camada de dependência
Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs20.x
      CodeUri: function/.
      Description: Call the AWS Lambda API
      Timeout: 10
      # Function's execution role
      Policies:
        - AWSLambdaBasicExecutionRole
        - AWSLambda_ReadOnlyAccess
        - AWSXrayWriteOnlyAccess
      Tracing: Active
      Layers:
        - !Ref libs
  libs:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: blank-nodejs-lib
      Description: Dependencies for the blank sample app.
      ContentUri: lib/.
      CompatibleRuntimes:
        - nodejs20.x

O script 2-build-layer.sh instala as dependências da função com o npm e as coloca em uma pasta com a estrutura exigida pelo tempo de execução do Lambda.

exemplo 2-build-layer.sh: preparar a camada
#!/bin/bash
set -eo pipefail
mkdir -p lib/nodejs
rm -rf node_modules lib/nodejs/node_modules
npm install --production
mv node_modules lib/nodejs/

Ao implantar o aplicativo de exemplo pela primeira vez, a AWS CLI empacota a camada separadamente do código de função e implanta ambos. Para implantações subsequentes, o arquivo de camada só será carregado se o conteúdo da pasta lib tiver sido alterado.