Introducción a las pruebas con sam local start-api - AWS Serverless Application Model
Uso de una API de inicio localOpcionesPrácticas recomendadasMás información

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

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

Utiliza el comando sam local start-api de la interfaz de la línea de comandos AWS Serverless Application Model (CLI de AWS SAM) para ejecutar las funciones AWS Lambda localmente y realizar pruebas a través de un host 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 usar sam local start-api, completa lo siguiente para instalar la CLI de AWS SAM:

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

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, ejecuta 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. Puedes 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, ejecuta 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, ejecuta su propia solución de compilación para actualizar la función. A continuación, ejecuta 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, consulta Actualización de AWS SAM CLI.

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

Reutiliza 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. Utiliza 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, ejecuta 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.

Especifica 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. Utiliza 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

Puedes 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

Especifica una plantilla para probarla localmente

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

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

Especifica 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.

Utiliza 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

Utiliza 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, ejecuta sam local start-api para probar localmente el código de función actualizado.

El testeo local son una excelente solución para desarrollar y probar rápidamente antes de implementarlas en la nube. Sin embargo, las testeo local 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. Te recomendamos que utiliza 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, consulta sam local start-api.