Aplicación de ejemplo de función en blanco para AWS Lambda

La aplicación de ejemplo de función en blanco es una aplicación de inicio que demuestra operaciones comunes en Lambda con una función que llama a la API de Lambda. Muestra el uso del registro, las variables de entorno, el seguimiento de AWS X-Ray, las capas, las pruebas de unidad y el SDK de AWS. Explore esta aplicación para aprender acerca de la creación de funciones de Lambda en su lenguaje de programación o úselo como punto de partida para sus propios proyectos.

Las variantes de esta aplicación de ejemplo están disponibles para los siguientes idiomas:

Variantes

• Node.js: blank-nodejs.

• Python: blank-python.

• Ruby: blank-ruby.

• Java: blank-java.

• Go: blank-go.

• C#: blank-csharp.

• PowerShell — Powershell en blanco.

Los ejemplos de este tema resaltan el código de la versión Node.js, pero los detalles son generalmente aplicables a todas las variantes.

Puede implementar el ejemplo en unos minutos con la AWS CLI y con AWS CloudFormation. Siga las instrucciones del archivo README para descargarla, configurarla e implementarla en su cuenta.

Arquitectura y código de controlador

La aplicación de ejemplo consta de un código de función, una plantilla de AWS CloudFormation y recursos auxiliares. Al implementar el ejemplo, utiliza los siguientes servicios de AWS:

• AWS Lambda— Ejecuta el código de la función, envía los CloudWatch registros a Logs y envía los datos de rastreo a X-Ray. La función también llama a la API de Lambda para obtener detalles sobre las cuotas y el uso de la cuenta en la región actual.

• AWS X-Ray: recopila datos de rastreo, indexa los rastros para las búsquedas y genera un mapa de servicio.

• Amazon CloudWatch: almacena registros y métricas.

• AWS Identity and Access Management (IAM): otorga el permiso.

• Amazon Simple Storage Service (Amazon S3): almacena el paquete de implementación de la función durante la implementación.

• AWS CloudFormation: crea los recursos de la aplicación e implementa el código de la función.

Se aplican cargos estándar por cada servicio. Para más información, consulte Precios de AWS.

El código de función muestra un flujo de trabajo básico para procesar un evento. El controlador toma un evento de Amazon Simple Queue Service (Amazon SQS) como entrada e itera a través de los registros que contiene, registrando el contenido de cada mensaje. Registra el contenido del evento, el objeto de contexto y las variables de entorno. Luego realiza una llamada con el SDK de AWS y devuelve la respuesta al tiempo de ejecución de Lambda.

ejemplo blank-nodejs/function/index.js: código de controlador

// 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.getAccountSettings().promise()
}

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

Los tipos de entrada/salida para el controlador y el soporte para la programación asíncrona varían según el tiempo de ejecución. En este ejemplo, el método del controlador es async, por lo que en Node.js esto implica que debe devolver una promesa al tiempo de ejecución. El tiempo de ejecución de Lambda espera a que se resuelva la promesa y devuelve la respuesta al invocador. Si el código de función o el SDK de AWS del cliente devuelven un error, el tiempo de ejecución formatea el error en un documento JSON y lo devuelve.

La aplicación de ejemplo no incluye una cola de Amazon SQS para enviar eventos, pero usa un evento de Amazon SQS (event.json) para ilustrar cómo se procesan los eventos. Para agregar una cola de Amazon SQS a la aplicación, consulte Uso de Lambda con Amazon SQS.

Automatización de implementación con AWS CloudFormation y la AWS CLI

Los recursos de la aplicación de ejemplo se definen en una plantilla de AWS CloudFormation y se implementan con la AWS CLI. El proyecto incluye scripts de shell simples que automatizan el proceso de configuración, implementación, invocación y desmantelamiento de la aplicación.

La plantilla de aplicación utiliza un tipo de recurso AWS Serverless Application Model (AWS SAM) para definir el modelo. AWS SAM simplifica la creación de plantillas para aplicaciones sin servidor automatizando la definición de roles de ejecución, API y otros recursos.

La plantilla define los recursos de la pila de aplicaciones. Esto incluye la función, su rol de ejecución y una capa de Lambda que proporciona las dependencias de biblioteca de la función. La pila no incluye el depósito que se AWS CLI utiliza durante la implementación ni el grupo de CloudWatch registros.

ejemplo blank-nodejs/template.yml: recursos sin 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: nodejs16.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:
        - nodejs16.x

Al implementar la aplicación, AWS CloudFormation aplica la transformación AWS SAM a la plantilla para generar una plantilla de AWS CloudFormation con tipos estándar como AWS::Lambda::Function y AWS::IAM::Role.

ejemplo plantilla procesada

{
  "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"
          }
        ],

En este ejemplo, la propiedad Code especifica un objeto en un bucket de Amazon S3. Esto corresponde a la ruta local de la propiedad CodeUri en la plantilla de proyecto:

      CodeUri: function/.

Para cargar los archivos de proyecto en Amazon S3, el script de implementación utiliza los comandos de la AWS CLI. El comando cloudformation package preprocesa la plantilla, carga artefactos y reemplaza rutas locales por ubicaciones de objetos de Amazon S3. El comando cloudformation deploy implementa la plantilla procesada con un conjunto de cambios de AWS CloudFormation.

ejemplo blank-nodejs/3-deploy.sh: paquete e implementación

#!/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

La primera vez que ejecuta este script, crea una pila de AWS CloudFormation denominada blank-nodejs. Si realiza cambios en el código de función o en la plantilla, puede ejecutarlo de nuevo para actualizar la pila.

El script de limpieza (blank-nodejs/5-cleanup.sh) elimina la pila y, opcionalmente, elimina el bucket de implementación y los registros de funciones.

Instrumentación con el AWS X-Ray

La función de ejemplo está configurada para el seguimiento con AWS X-Ray. Con el modo de seguimiento establecido en activo, Lambda registra la información de tiempo de un subconjunto de invocaciones y la envía a X-Ray. X-Ray procesa los datos para generar un mapa de servicios que muestra un nodo de cliente y dos nodos de servicio.

El primer nodo de servicio (AWS::Lambda) representa el servicio de Lambda, que valida la solicitud de invocación y la envía a la función. El segundo nodo, AWS::Lambda::Function, representa la función en sí.

Para registrar detalles adicionales, la función de ejemplo utiliza el SDK de X-Ray. Con cambios mínimos en el código de función, el SDK de X-Ray registra detalles sobre las llamadas realizadas con el SDK de AWS a los servicios de AWS.

ejemplo blank-nodejs/function/index.js: instrumentación.

const AWSXRay = require('aws-xray-sdk-core')
const AWS = AWSXRay.captureAWS(require('aws-sdk'))

// Create client outside of handler to reuse
const lambda = new AWS.Lambda()

La instrumentación del cliente de SDK de AWS agrega un nodo adicional al mapa de servicio y más detalles en los registros de seguimiento. En este ejemplo, el mapa de servicio muestra la función de ejemplo que llama a la API de Lambda para obtener detalles sobre el almacenamiento y el uso de simultaneidad en la región actual.

El registro de seguimiento muestra detalles de tiempo para la invocación, con subsegmentos para la inicialización de funciones, la invocación y la sobrecarga. El subsegmento de invocación tiene un subsegmento para la llamada del SDK de AWS a la operación de la API GetAccountSettings.

Puede incluir el SDK de X-Ray y otras bibliotecas en el paquete de implementación de su función o implementarlas por separado en una capa de Lambda. Para Node.js, Ruby y Python, el tiempo de ejecución de Lambda incluye el SDK de AWS en el entorno de ejecución.

Administración de dependencias con capas

Puede instalar bibliotecas localmente e incluirlas en el paquete de implementación que cargue en Lambda, pero esto tiene sus inconvenientes. Los tamaños de archivo mayores provocan un aumento de los tiempos de implementación y pueden impedir que pruebe los cambios en el código de función en la consola de Lambda. Para mantener el paquete de implementación pequeño y evitar la carga de dependencias que no han cambiado, la aplicación de ejemplo crea una capa de Lambda y la asocia con la función.

ejemplo blank-nodejs/template.yml: capa de dependencia

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs16.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:
        - nodejs16.x

El script 2-build-layer.sh instala las dependencias de la función con npm y las coloca en una carpeta con la estructura requerida por el tiempo de ejecución de Lambda.

ejemplo 2-build-layer.sh: preparación de la capa

#!/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/

La primera vez que implemente la aplicación de ejemplo, la AWS CLI empaqueta por separado la capa del código de función e implementa ambos. En las siguientes implementaciones, el archivo de capas solo se carga si ha cambiado el contenido de la carpeta lib.