Introducción a las pruebas con sam local start-api

Utilice el AWS Serverless Application Model sam local start-api subcomando Command Line Interface (AWS SAMCLI) para ejecutar AWS Lambda las funciones de forma local y realizar pruebas a través de un servidor HTTP local. Este tipo de pruebas resulta útil para las funciones de Lambda que invocan un punto de conexión de Amazon API Gateway.

• Para obtener una introducción al AWS SAMCLI, consulte¿Qué es el? AWS SAMCLI.

• Para ver una lista de opciones de comandos sam local start-api, consulte sam local start-api.

• Para ver un ejemplo de uso de sam local start-api durante un flujo de trabajo de desarrollo típico, consulte Paso 7: (opcional) probar su aplicación localmente.

Requisitos previos

Para usar sam local start-api, complete lo siguiente para instalar la CLI de AWS SAM:

• AWS SAM requisitos previos.

• Instale la CLIAWS SAM.

Antes de usar sam local start-api, se recomienda tener conocimientos básicos de lo siguiente:

• Configuración de la AWS SAM de CLI.

• Crea tu aplicación en AWS SAM.

• Introducción a la construcción con AWS SAM.

• Introducción a la implementación con AWS SAM.

Uso de una API de inicio local

De forma predeterminada, cuando ejecuta sam local start-api, la CLI de AWS SAM asume que su directorio de trabajo actual es el directorio raíz del proyecto. Primero la CLI de AWS SAM buscará un archivo template.[yaml|yml] dentro de una subcarpeta .aws-sam. Si no lo encuentra, la CLI de AWS SAM buscará un archivo template.[yaml|yml] en su directorio de trabajo actual.

Para iniciar un servidor HTTP local

1. Desde el directorio raíz del proyecto, ejecute lo siguiente:

   $ sam local start-api <options>

2. La CLI de AWS SAM compila las funciones de Lambda en un contenedor local Docker. A continuación, genera la dirección local del punto de conexión del servidor HTTP. A continuación, se muestra un ejemplo:

   $ sam local start-api
   
   Initializing the lambda functions containers.
   Local image is up-to-date
   Using local image: public.ecr.aws/lambda/python:3.9-rapid-x86_64.
   
   Mounting /Users/.../sam-app/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated, inside runtime container
   Containers Initialization is done.
   Mounting HelloWorldFunction at http://127.0.0.1:3000/hello [GET]
   You can now browse to the above endpoints to invoke your functions. You do not need to restart/reload SAM CLI while working on your functions, changes will be reflected instantly/automatically. If you used sam build before running local commands, you will need to re-run sam build for the changes to be picked up. You only need to restart SAM CLI if you update your AWS SAM template
   2023-04-12 14:41:05 WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
    * Running on http://127.0.0.1:3000

3. Puede invocar la función de Lambda mediante el navegador o la línea de comandos. A continuación, se muestra un ejemplo:

   sam-app$ curl http://127.0.0.1:3000/hello
   {"message": "Hello world!"}%

4. Al realizar cambios en el código de la función de Lambda, tenga en cuenta lo siguiente para actualizar el servidor HTTP local:

   • Si la aplicación no tiene un directorio .aws-sam y la función utiliza un lenguaje interpretado, la CLI de AWS SAM actualizará automáticamente la función creando un nuevo contenedor y alojándolo.

   • Si la aplicación tiene un directorio .aws-sam, debe ejecutar sam build para actualizar la función. A continuación, ejecute nuevamente sam local start-api para alojar la función.

   • Si la función utiliza un lenguaje compilado o si el proyecto requiere un soporte de empaquetado complejo, ejecute su propia solución de compilación para actualizar la función. A continuación, ejecute nuevamente sam local start-api para alojar la función.

Funciones de Lambda que utilizan autorizadores de Lambda

nota

Esta característica es nueva en la versión 1.80.0 de la CLI de AWS SAM. Para actualizar, consulte Actualización de la CLI de AWS SAM.

En el caso de las funciones de Lambda configuradas para utilizar autorizadores de Lambda, la CLI de AWS SAM invocará automáticamente la función de Lambda antes de invocar el punto de conexión de la función de Lambda.

A continuación, se muestra un ejemplo de cómo iniciar un servidor HTTP local para una función que utiliza un autorizador Lambda:

$ sam local start-api
2023-04-17 15:02:13 Attaching import module proxy for analyzing dynamic imports

AWS SAM CLI does not guarantee 100% fidelity between authorizers locally
and authorizers deployed on AWS. Any application critical behavior should
be validated thoroughly before deploying to production.

Testing application behaviour against authorizers deployed on AWS can be done using the sam sync command.

Mounting HelloWorldFunction at http://127.0.0.1:3000/authorized-request [GET]
You can now browse to the above endpoints to invoke your functions. You do not need to restart/reload SAM CLI while working on your functions, changes will be reflected instantly/automatically. If you used sam build before running local commands, you will need to re-run sam build for the changes to be picked up. You only need to restart SAM CLI if you update your AWS SAM template
2023-04-17 15:02:13 WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on http://127.0.0.1:3000
2023-04-17 15:02:13 Press CTRL+C to quit

Al invocar el punto de conexión de la función de Lambda a través del servidor HTTP local, el primero invoca el autorizador Lambda de la CLI de AWS SAM. Si la autorización se realiza correctamente, la CLI de AWS SAM invocará el punto de conexión de la función de Lambda. A continuación, se muestra un ejemplo:

$ curl http://127.0.0.1:3000/authorized-request --header "header:my_token"
{"message": "from authorizer"}%

Invoking app.authorizer_handler (python3.8)
Local image is up-to-date
Using local image: public.ecr.aws/lambda/python:3.8-rapid-x86_64.

Mounting /Users/.../sam-app/... as /var/task:ro,delegated, inside runtime container
START RequestId: 38d3b472-a2c8-4ea6-9a77-9b386989bef0 Version: $LATEST
END RequestId: 38d3b472-a2c8-4ea6-9a77-9b386989bef0
REPORT RequestId: 38d3b472-a2c8-4ea6-9a77-9b386989bef0    Init Duration: 1.08 ms    Duration: 628.26 msBilled Duration: 629 ms    Memory Size: 128 MB    Max Memory Used: 128 MB
Invoking app.request_handler (python3.8)
Using local image: public.ecr.aws/lambda/python:3.8-rapid-x86_64.

Mounting /Users/.../sam-app/... as /var/task:ro,delegated, inside runtime container
START RequestId: fdc12255-79a3-4365-97e9-9459d06446ff Version: $LATEST
END RequestId: fdc12255-79a3-4365-97e9-9459d06446ff
REPORT RequestId: fdc12255-79a3-4365-97e9-9459d06446ff    Init Duration: 0.95 ms    Duration: 659.13 msBilled Duration: 660 ms    Memory Size: 128 MB    Max Memory Used: 128 MB
No Content-Type given. Defaulting to 'application/json'.
2023-04-17 15:03:03 127.0.0.1 - - [17/Apr/2023 15:03:03] "GET /authorized-request HTTP/1.1" 200 -

Opciones

Reutilice los contenedores de forma continua para acelerar las invocaciones de funciones locales

De forma predeterminada, la CLI de AWS SAM crea un contenedor nuevo cada vez que se invoca la función a través del servidor HTTP local. Utilice la opción --warm-containers de reutilizar automáticamente el contenedor para las invocaciones de funciones. Esto acelera el tiempo que tarda la CLI de AWS SAM en preparar la función de Lambda para la invocación local. Puede personalizar aún más esta opción proporcionando el argumento eager o lazy.

• eager: los contenedores de todas las funciones se cargan al inicio y se conservan entre las invocaciones.

• lazy: los contenedores solo se cargan cuando se invoca cada función por primera vez. A continuación, se conservan para realizar más invocaciones.

A continuación, se muestra un ejemplo:

$ sam local start-api --warm-containers eager

Al utilizar --warm-containers y modificar el código de la función de Lambda:

• Si la aplicación tiene un directorio .aws-sam, ejecute sam build para actualizar el código de función en los artefactos de compilación de la aplicación.

• Cuando se detecta un cambio en el código, la CLI de AWS SAM cierra automáticamente el contenedor de funciones de Lambda.

• Cuando vuelva a invocar la función, la CLI de AWS SAM crea automáticamente un nuevo contenedor.

Especifique una imagen de contenedor para utilizarla en las funciones de Lambda

De forma predeterminada, la CLI de AWS SAM utiliza imágenes base de Lambda de Amazon Elastic Container Registry (Amazon ECR) para invocar sus funciones de forma local. Utilice la opción --invoke-image para hacer referencia a una imagen de contenedor personalizada. A continuación, se muestra un ejemplo:

$ sam local start-api --invoke-image public.ecr.aws/sam/emu-python3.8

Puede especificar la función que se va a utilizar con la imagen de contenedor personalizada. A continuación, se muestra un ejemplo:

$ sam local start-api --invoke-image Function1=amazon/aws/sam-cli-emulation-image-python3.8

Especifique una plantilla para probarla localmente

Para especificar una plantilla a la que CLI de AWS SAM haga referencia, utilice la opción --template. AWS SAMCLICargará solo esa AWS SAM plantilla y los recursos a los que apunta. A continuación, se muestra un ejemplo:

$ sam local start-api --template myTemplate.yaml

Especifique el entorno de desarrollo del host de su función de Lambda

De forma predeterminada, el subcomando sam local start-api crea un servidor HTTP localhost con una dirección IP 127.0.0.1. Puede personalizar estos valores si su entorno de desarrollo local está aislado de su máquina local.

Utilice la opción --container-host para especificar un host. A continuación, se muestra un ejemplo:

$ sam local start-api --container-host host.docker.internal

Utilice la opción --container-host-interface para especificar un la dirección IP del host de la red a la que deben enlazarse los puertos del contenedor. A continuación, se muestra un ejemplo:

$ sam local start-api --container-host-interface 0.0.0.0

Prácticas recomendadas

Si la aplicación tiene un directorio .aws-sam desde el que se ejecuta sam build, asegúrese de ejecutar sam build cada vez que actualice el código de la función. A continuación, ejecute sam local start-api para probar localmente el código de función actualizado.

Las pruebas locales son una excelente solución para desarrollar y probar rápidamente antes de implementarlas en la nube. Sin embargo, las pruebas locales no lo validan todo, como los permisos entre los recursos de la nube. En la medida de lo posible, pruebe sus aplicaciones en la nube. Le recomendamos que utilice sam sync para acelerar los flujos de trabajo de pruebas en la nube.

Más información

Para obtener una lista de todas las opciones sam local start-api, consulte sam local start-api.