Introduzione ai test con sam local start-api

Utilizzate il AWS Serverless Application Model sam local start-api sottocomando Command Line Interface (AWS SAMCLI) per eseguire le AWS Lambda funzioni localmente e testarle tramite un host di server HTTP locale. Questo tipo di test è utile per le funzioni Lambda richiamate da un endpoint Amazon API Gateway.

• Per un'introduzione a, consulta. AWS SAMCLI Che cos'è il? AWS SAMCLI

• Per un elenco delle opzioni di sam local start-api comando, vederesam local start-api.

• Per un esempio di utilizzo sam local start-api durante un tipico flusso di lavoro di sviluppo, vediPassaggio 7: (Facoltativo) Testa l'applicazione localmente.

Prerequisiti

Per utilizzarlosam local start-api, AWS SAMCLI installate il completando quanto segue:

• AWS SAM prerequisiti.

• Installa il AWS SAMCLI.

Prima dell'usosam local start-api, si consiglia una conoscenza di base di quanto segue:

• Configurazione del AWS SAMCLI.

• Crea la tua applicazione con il sam init comando.

• Introduzione alla costruzione con il sam build comando.

• Introduzione alla distribuzione con il comando sam deploy.

Usare sam local start-api

Quando si eseguesam local start-api, si AWS SAMCLI presuppone che la directory di lavoro corrente sia la directory principale del progetto. AWS SAMCLICercheranno innanzitutto un template.[yaml|yml] file all'interno di una .aws-sam sottocartella. Se non viene trovato, AWS SAMCLI cercherà un template.[yaml|yml] file all'interno della directory di lavoro corrente.

Per avviare un server HTTP locale

1. Dalla directory principale del progetto, esegui quanto segue:

   $ sam local start-api <options>

2. AWS SAMCLICrea le tue funzioni Lambda in un Docker contenitore locale. Quindi restituisce l'indirizzo locale dell'endpoint del server HTTP. Di seguito è riportato un esempio:

   $ 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. È possibile richiamare la funzione Lambda tramite il browser o il prompt dei comandi. Di seguito è riportato un esempio:

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

4. Quando apporti modifiche al codice della funzione Lambda, considera quanto segue per aggiornare il server HTTP locale:

   • Se l'applicazione non dispone di una .aws-sam directory e la funzione utilizza un linguaggio interpretato, AWS SAMCLI aggiornerà automaticamente la funzione creando un nuovo contenitore e ospitandolo.

   • Se l'applicazione dispone di una .aws-sam directory, è necessario eseguirla sam build per aggiornare la funzione. Quindi esegui sam local start-api nuovamente per ospitare la funzione.

   • Se la tua funzione utilizza un linguaggio compilato o se il tuo progetto richiede un supporto complesso per la creazione di pacchetti, esegui la tua soluzione di compilazione per aggiornare la funzione. Quindi esegui sam local start-api nuovamente per ospitare la funzione.

Funzioni Lambda che utilizzano gli autorizzatori Lambda

Nota

Questa funzionalità è nuova nella AWS SAMCLI versione 1.80.0. Per eseguire l'aggiornamento, consulta Aggiornamento del AWS SAMCLI.

Per le funzioni Lambda che utilizzano gli autorizzatori Lambda, richiameranno AWS SAMCLI automaticamente l'autorizzatore Lambda prima di richiamare l'endpoint della funzione Lambda.

Di seguito è riportato un esempio di avvio di un server HTTP locale per una funzione che utilizza un autorizzatore 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 richiami l'endpoint della funzione Lambda tramite il server HTTP locale, il primo richiama AWS SAMCLI l'autorizzazione Lambda. Se l'autorizzazione ha esito positivo, AWS SAMCLI invocherà l'endpoint della funzione Lambda. Di seguito è riportato un esempio:

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

Opzioni

Riutilizza continuamente i contenitori per velocizzare le chiamate alle funzioni locali

Per impostazione predefinita, AWS SAMCLI crea un nuovo contenitore ogni volta che la funzione viene richiamata tramite il server HTTP locale. Utilizzate l'--warm-containersopzione per riutilizzare automaticamente il contenitore per le chiamate di funzioni. Ciò velocizza il tempo necessario per AWS SAMCLI preparare la funzione Lambda per la chiamata locale. È possibile personalizzare ulteriormente questa opzione fornendo l'eagerargomento or. lazy

• eager— I contenitori per tutte le funzioni vengono caricati all'avvio e persistono tra una chiamata e l'altra.

• lazy— I contenitori vengono caricati solo quando ogni funzione viene richiamata per la prima volta. Quindi persistono per ulteriori invocazioni.

Di seguito è riportato un esempio:

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

Quando usi --warm-containers e modifichi il codice della funzione Lambda:

• Se l'applicazione ha una .aws-sam directory, eseguila sam build per aggiornare il codice della funzione negli artefatti di build dell'applicazione.

• Quando viene rilevata una modifica al codice, spegne AWS SAMCLI automaticamente il contenitore delle funzioni Lambda.

• Quando richiami nuovamente la funzione, crea AWS SAMCLI automaticamente un nuovo contenitore.

Specificate un'immagine del contenitore da usare per le funzioni Lambda

Per impostazione predefinita, AWS SAMCLI utilizza immagini di base Lambda da Amazon Elastic Container Registry (Amazon ECR) per richiamare le funzioni localmente. Usa l'--invoke-imageopzione per fare riferimento a un'immagine del contenitore personalizzata. Di seguito è riportato un esempio:

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

È possibile specificare la funzione da utilizzare con l'immagine del contenitore personalizzata. Di seguito è riportato un esempio:

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

Specificate un modello da testare localmente

Per specificare un modello AWS SAMCLI a cui fare riferimento, utilizzate l'--templateopzione. AWS SAMCLICaricherà solo quel AWS SAM modello e le risorse a cui punta. Di seguito è riportato un esempio:

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

Specificate l'ambiente di sviluppo host della vostra funzione Lambda

Per impostazione predefinita, il sam local start-api sottocomando crea un server HTTP utilizzando localhost un indirizzo IP. 127.0.0.1 È possibile personalizzare questi valori se l'ambiente di sviluppo locale è isolato dal computer locale.

Utilizzate l'--container-hostopzione per specificare un host. Di seguito è riportato un esempio:

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

Utilizzate l'--container-host-interfaceopzione per specificare l'indirizzo IP della rete host a cui devono collegarsi le porte del contenitore. Di seguito è riportato un esempio:

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

Best practice

Se l'applicazione ha una .aws-sam directory in esecuzionesam build, assicuratevi di eseguirla sam build ogni volta che aggiornate il codice della funzione. Quindi, sam local start-api esegui per testare localmente il codice funzionale aggiornato.

I test locali sono un'ottima soluzione per lo sviluppo e il test rapidi prima della distribuzione nel cloud. Tuttavia, i test locali non convalidano tutto, come le autorizzazioni tra le risorse nel cloud. Per quanto possibile, testa le tue applicazioni nel cloud. Ti consigliamo di sam syncutilizzarlo per velocizzare i flussi di lavoro di test sul cloud.

Ulteriori informazioni

Per un elenco di tutte le sam local start-api opzioni, consultasam local start-api.