Utilisation de sam local start-api Options Bonnes pratiques En savoir plus

Présentation des tests avec sam local start-api

Utilisez l'interface AWS Serverless Application Model de ligne de commande (AWS SAM CLI) sam local start-api pour exécuter vos AWS Lambda fonctions localement et les tester via un HTTP serveur hôte local. Ce type de test est utile pour les fonctions Lambda invoquées par un point de terminaison Amazon API Gateway.

Pour une introduction au AWS SAM CLI, voir Qu'est-ce que le AWS SAM CLI?
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.

Pour l'utilisersam local start-api, installez AWS SAM CLI en complétant ce qui suit :

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

Utilisation de sam local start-api

Lorsque vous courezsam local start-api, AWS SAM CLI suppose que votre répertoire de travail actuel est le répertoire racine de votre projet. Le AWS SAM CLI recherchera d'abord un template.[yaml|yml] fichier dans un .aws-sam sous-dossier. S'il n'est pas trouvé, le AWS SAM CLI recherchera un template.[yaml|yml] fichier dans votre répertoire de travail actuel.

Pour démarrer un HTTP serveur local

À partir du répertoire racine de votre projet, effectuez les actions suivantes :
```
$ sam local start-api <options>
```

Le AWS SAM CLI construit vos fonctions Lambda dans un environnement local Docker contenant. Il affiche ensuite l'adresse locale du point de terminaison de votre HTTP serveur. 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

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!"}%
```
Lorsque vous modifiez le code de votre fonction Lambda, tenez compte des points suivants pour actualiser votre serveur local HTTP :
- Si votre application ne possède pas de .aws-sam répertoire et que votre fonction utilise un langage interprété, AWS SAM CLI mettra 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 AWS SAM CLI version 1.80.0. Pour effectuer une mise à niveau, consultez Mise à niveau de la CLI AWS SAM en cours.

Pour les fonctions Lambda qui utilisent des autorisateurs Lambda, AWS SAM CLI invoquera automatiquement votre autorisateur Lambda avant d'appeler le point de terminaison de votre fonction Lambda.

Voici un exemple de démarrage d'un HTTP serveur local pour une fonction qui utilise un autorisateur 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 appelez le point de terminaison de votre fonction Lambda via le HTTP serveur local, AWS SAM CLI appelle d'abord votre autorisateur Lambda. Si l'autorisation est acceptée, le AWS SAM CLI 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, le AWS SAM CLI crée un nouveau conteneur chaque fois que votre fonction est invoquée via le HTTP serveur local. Utilisez l'option --warm-containers pour réutiliser automatiquement votre conteneur pour les appels de fonctions. Cela permet d'accélérer le temps nécessaire pour AWS SAM CLI pour préparer votre fonction Lambda pour un appel local. 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'un changement de code est détecté, le AWS SAM CLI arrête automatiquement le conteneur de fonctions Lambda.
Lorsque vous invoquez à nouveau la fonction, AWS SAM CLI crée automatiquement un nouveau conteneur.

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

Par défaut, le AWS SAM CLI utilise des images de base Lambda provenant d'Amazon Elastic Container Registry ECR (Amazon) pour appeler 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 pour AWS SAM CLI pour faire référence, utilisez l'--templateoption. Le AWS SAM CLI chargera 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 sam local start-api sous-commande crée un HTTP serveur en utilisant localhost l'adresse 127.0.0.1 IP. 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.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Présentation de sam local invoke

Présentation de sam local start-lambda