Présentation des tests avec sam local start-api

Utilisez la AWS Serverless Application Model sam local start-api sous-commande Command Line Interface (AWS SAMCLI) pour exécuter vos AWS Lambda fonctions localement et les tester via un hôte de serveur HTTP local. Ce type de test est utile pour les fonctions Lambda qui sont appelées par un point de terminaison Amazon API Gateway.

• Pour une introduction à la AWS SAMCLI, voirQu'est-ce que c'est AWS SAMCLI ?.

• Pour obtenir la liste des options de commande sam local start-api, consultez sam local start-api.

• Pour un exemple d'utilisation de sam local start-api dans le cadre d'un flux de travail de développement classique, consultez Étape 7 : (Facultatif) testez votre application localement.

Prérequis

Pour utiliser sam local start-api, installez la CLI AWS SAM en procédant comme suit :

• AWS SAM prérequis.

• Installer la CLI  AWS SAM.

Avant d'utiliser sam local start-api, nous vous recommandons d'avoir des connaissances de base sur les points suivants :

• Configuration de la CLI  AWS SAM.

• Créez votre application à l'aide de la sam init commande.

• Présentation de la construction avec la sam build commande.

• Présentation du déploiement à l'aide de la sam deploy commande.

Utilisation de sam local start-api

Lorsque vous utilisez sam local start-api, la CLI AWS SAM suppose que le répertoire de travail actuel est le répertoire racine du projet. La CLI AWS SAM recherche d'abord un fichier template.[yaml|yml] dans un sous-dossier .aws-sam. Si elle ne le trouve pas, la CLI AWS SAM recherche un fichier template.[yaml|yml] dans votre répertoire de travail actuel.

Pour démarrer un serveur HTTP local

1. À partir du répertoire racine de votre projet, effectuez les actions suivantes :

   $ sam local start-api <options>

2. La CLI AWS SAM crée vos fonctions Lambda dans un conteneur Docker local. Elle affiche ensuite l'adresse locale du point de terminaison de votre serveur HTTP. Voici un exemple :

   $ 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. Vous pouvez appeler votre fonction Lambda via le navigateur ou l'invite de commande. Voici un exemple :

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

4. Lorsque vous modifiez le code de votre fonction Lambda, tenez compte des points suivants pour actualiser votre serveur HTTP local :

   • Si votre application ne possède pas de répertoire .aws-sam et que votre fonction utilise un langage interprété, la CLI  AWS SAM met automatiquement à jour votre fonction en créant un nouveau conteneur et en l'hébergeant.

   • Si votre application possède un répertoire .aws-sam, vous devez exécuter sam build pour mettre à jour votre fonction. Exécutez ensuite à nouveau sam local start-api pour héberger la fonction.

   • Si votre fonction utilise un langage compilé ou si votre projet nécessite une prise en charge complexe d'empaquetage, exécutez votre propre solution de création pour mettre à jour votre fonction. Exécutez ensuite à nouveau sam local start-api pour héberger la fonction.

Fonctions Lambda qui utilisent des mécanismes d'autorisation Lambda

Note

Cette fonctionnalité est nouvelle dans la version 1.80.0 de la CLI  AWS SAM. Pour effectuer une mise à niveau, consultez Mise à niveau de la CLI  AWS SAM en cours.

Pour les fonctions Lambda qui utilisent des mécanismes d'autorisation Lambda, la CLI  AWS SAM invoquera automatiquement votre mécanisme d'autorisation Lambda avant d'appeler le point de terminaison de votre fonction Lambda.

Voici un exemple de démarrage d'un serveur HTTP local pour une fonction qui utilise un mécanisme d'autorisation 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

Lorsque vous invoquez le point de terminaison de votre fonction Lambda via le serveur HTTP local, la CLI  AWS SAM invoque d'abord votre mécanisme d'autorisation Lambda. Si l'autorisation est réussie, la CLI  AWS SAM invoquera le point de terminaison de votre fonction Lambda. Voici un exemple :

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

Options

Réutiliser en permanence les conteneurs pour accélérer les appels de fonctions locales

Par défaut, la CLI  AWS SAM crée un nouveau conteneur chaque fois que votre fonction est invoquée via le serveur HTTP local. Utilisez l'option --warm-containers pour réutiliser automatiquement votre conteneur pour les appels de fonctions. Cela accélère le temps nécessaire à la CLI  AWS SAM pour préparer votre fonction Lambda pour l'invocation locale. Vous pouvez personnaliser davantage cette option en fournissant l'argument eager ou lazy.

• eager : les conteneurs pour toutes les fonctions sont chargés au démarrage et persistent entre les appels.

• lazy : les conteneurs ne sont chargés que lorsque chaque fonction est appelée pour la première fois. Ils persistent ensuite pour des appels supplémentaires.

Voici un exemple :

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

Lorsque vous utilisez --warm-containers et modifiez le code de votre fonction Lambda :

• Si votre application dispose d'un répertoire .aws-sam, exécutez sam build pour mettre à jour le code de votre code de fonction dans les artefacts de création de votre application.

• Lorsqu'une modification de code est détectée, la CLI  AWS SAM arrête automatiquement le conteneur de fonctions Lambda.

• Lorsque vous invoquez à nouveau la fonction, la CLI  AWS SAM crée automatiquement un nouveau conteneur.

Spécifier une image de conteneur à utiliser pour vos fonctions Lambda

Par défaut, la CLI  AWS SAM utilise les images de base Lambda provenant d'Amazon Elastic Container Registry (Amazon ECR) pour invoquer vos fonctions localement. Utilisez l'option --invoke-image pour référencer une image de conteneur personnalisée. Voici un exemple :

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

Vous pouvez spécifier la fonction à utiliser avec l'image de conteneur personnalisée. Voici un exemple :

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

Spécifier un modèle à tester localement

Pour spécifier un modèle à référencer par la CLI AWS SAM, utilisez l'option --template. Ils AWS SAMCLI chargeront uniquement ce AWS SAM modèle et les ressources vers lesquelles il pointe. Voici un exemple :

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

Spécifier l'environnement de développement hôte de votre fonction Lambda

Par défaut, la sous-commande sam local start-api crée un serveur HTTP utilisant localhost avec l'adresse IP 127.0.0.1. Vous pouvez personnaliser ces valeurs si votre environnement de développement local est isolé de votre ordinateur local.

Utilisez l'option --container-host pour spécifier un hôte. Voici un exemple :

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

Utilisez l'option --container-host-interface pour spécifier l'adresse IP du réseau hôte à laquelle les ports de conteneur doivent se relier. Voici un exemple :

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

Bonnes pratiques

Si votre application possède un répertoire .aws-sam qui exécute sam build, assurez-vous d'exécuter sam build chaque fois que vous mettez à jour le code de votre fonction. Exécutez ensuite sam local start-api pour tester localement votre code de fonction mis à jour.

Les tests locaux constituent une excellente solution pour un développement et des tests rapides avant le déploiement dans le cloud. Toutefois, les tests locaux ne valident pas tout, notamment les autorisations entre vos ressources dans le cloud. Dans la mesure du possible, testez vos applications dans le cloud. Nous vous recommandons d'utiliser sam sync pour accélérer vos flux de travail de test dans le cloud.

En savoir plus

Pour obtenir la liste de toutes les options sam local start-api, consultez sam local start-api.