Introdução aos testes com sam local start-api

Use o AWS Serverless Application Model sam local start-api subcomando Command Line Interface (AWS SAMCLI) para executar suas AWS Lambda funções localmente e testar por meio de um host de servidor HTTP local. Esse tipo de teste é útil para funções do Lambda invocadas por um endpoint do Amazon API Gateway.

• Para obter uma introdução ao AWS SAMCLI, consulteO que é o AWS SAMCLI?.

• Para obter uma lista de opções de comando sam local start-api, consulte sam local start-api.

• Para obter um exemplo de uso do sam local start-api durante um fluxo de trabalho de desenvolvimento típico, consulte Etapa 7: (opcional) Teste seu aplicativo localmente.

Pré-requisitos

Para usar o sam local start-api, instale o AWS SAM CLI fazendo o seguinte:

• AWS SAM pré-requisitos.

• Instale o AWS SAM CLI.

Antes de usar sam local start-api, recomendamos uma compreensão básica do seguinte:

• Configurando o AWS SAM CLI.

• Crie seu aplicativo com o sam init comando.

• Introdução à construção com o sam build comando.

• Introdução à implantação com o comando sam deploy.

Usando SAM API de inicialização local

Quando você executa sam local start-api, AWS SAMCLI pressupõe que seu diretório de trabalho atual seja o diretório raiz do seu projeto. O AWS SAM CLI, primeiro procurará um arquivo template.[yaml|yml] dentro de uma subpasta .aws-sam. Se não for encontrado, o AWS SAMCLI procurará um arquivo template.[yaml|yml] em seu diretório de trabalho atual.

Para iniciar um servidor HTTP local

1. No diretório raiz do seu projeto, execute o seguinte:

   $ sam local start-api <options>

2. O AWS SAMCLI cria suas funções do Lambda em um contêiner local Docker. Em seguida, ele envia o endereço local para o endpoint do servidor HTTP. Veja um exemplo a seguir:

   $ 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. Você pode invocar sua função do Lambda por meio do navegador ou do prompt de comando. Veja um exemplo a seguir:

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

4. Ao fazer alterações no código da função do Lambda, considere o seguinte para atualizar seu servidor HTTP local:

   • Se seu aplicativo não tiver um diretório .aws-sam e sua função usar uma linguagem interpretada, os AWS SAMCLI atualizarão automaticamente sua função criando um novo contêiner e hospedando-o.

   • Se seu aplicativo tiver um diretório .aws-sam, você precisará executar sam build para atualizar sua função. Em seguida, execute sam local start-api novamente para hospedar a função.

   • Se sua função usa uma linguagem compilada ou se seu projeto requer suporte a pacotes complexos, execute sua própria solução de compilação para atualizar sua função. Em seguida, execute sam local start-api novamente para hospedar a função.

Funções Lambda que usam autorizadores Lambda

nota

Esse atributo é novo na versão 1.80.0 do AWS SAM CLI. Para atualizar, consulte Atualizar o AWS SAM CLI.

Para funções Lambda que usam autorizadores Lambda, os AWS SAMCLI invocarão automaticamente seu autorizador Lambda antes de invocar seu endpoint de função do Lambda.

Veja a seguir um exemplo de como iniciar um servidor HTTP local para uma função que usa um 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

Quando você invoca seu endpoint da função do Lambda por meio do servidor HTTP local, o AWS SAMCLI invoca primeiro seu autorizador Lambda. Se a autorização for bem-sucedida, AWS SAM e CLI invocarão seu endpoint da função do Lambda. Veja um exemplo a seguir:

$ 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 -

Opções

Reutilize continuamente os contêineres para acelerar as invocações de funções locais

Por padrão, o AWS SAMCLI cria um novo contêiner toda vez que sua função é invocada por meio do servidor HTTP local. Use a opção --warm-containers de reutilizar automaticamente seu contêiner para invocações de funções. Isso acelera o tempo necessário para AWS SAMCLI preparar sua função do Lambda para invocação local. Você pode personalizar ainda mais essa opção fornecendo o argumento eager ou lazy.

• eager – Os contêineres para todas as funções são carregados na inicialização e persistem entre as invocações.

• lazy – Os contêineres são carregados somente quando cada função é invocada pela primeira vez. Eles então persistem para invocações adicionais.

Veja um exemplo a seguir:

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

Ao usar --warm-containers e modificar o código da função do Lambda:

• Se seu aplicativo tiver um diretório .aws-sam, execute sam build para atualizar o código da função nos artefatos de construção do seu aplicativo.

• Quando uma alteração de código é detectada, o AWS SAMCLI desliga automaticamente o contêiner da função do Lambda.

• Quando você invoca a função novamente, o AWS SAMCLI cria automaticamente um novo contêiner.

Especifique uma imagem de contêiner para usar em suas funções do Lambda

Por padrão, o AWS SAMCLI usa imagens de base do Lambda do Amazon Elastic Container Registry (Amazon ECR) para invocar suas funções no local. Use a opção --invoke-image para referenciar uma imagem de contêiner personalizada. Veja um exemplo a seguir:

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

Você pode especificar a função a ser usada com a imagem personalizada do contêiner. Veja um exemplo a seguir:

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

Especifique um modelo para testar localmente

Para especificar um modelo para o AWS SAMCLI para referência, use a opção --template. Eles AWS SAMCLI carregarão apenas esse AWS SAM modelo e os recursos para os quais ele aponta. Veja um exemplo a seguir:

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

Especifique o ambiente de desenvolvimento do host da sua função do Lambda

Por padrão, o subcomando sam local start-api cria um servidor HTTP usando localhost com endereço IP 127.0.0.1. Você pode personalizar esses valores se o ambiente de desenvolvimento local estiver isolado da máquina local.

Use a opção --container-host para especificar um host. Veja um exemplo a seguir:

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

Use a opção --container-host-interface para especificar o endereço IP da rede host à qual as portas do contêiner devem se vincular. Veja um exemplo a seguir:

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

Práticas recomendadas

Se seu aplicativo tiver um diretório .aws-sam executando sam build, certifique-se de executar o sam build sempre que atualizar o código da função. Em seguida, execute o sam local start-api para testar localmente seu código de função atualizado.

O teste local é uma ótima solução para desenvolvimento e teste rápidos antes da implantação na nuvem. No entanto, os testes locais não validam tudo, como permissões entre seus recursos na nuvem. Tanto quanto possível, teste seus aplicativos na nuvem. Recomendamos usar o sam sync para acelerar seus fluxos de trabalho de testes na nuvem.

Saiba mais

Para obter uma lista de todas as opções sam local start-api, consulte sam local start-api.