Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# 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, voir [Qu'est-ce que c'est AWS SAMCLI ?](what-is-sam-overview.md#what-is-sam-cli)
+ Pour obtenir la liste des options de commande `sam local start-api`, consultez [sam local start-api](sam-cli-command-reference-sam-local-start-api.md).
+ 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](serverless-getting-started-hello-world.md#serverless-getting-started-hello-world-test).
**Note**
`sam local start-api`prend en charge des fonctions durables avec des fonctionnalités de point de contrôle et de rediffusion automatiques. Les fonctions durables fonctionnent parfaitement avec le point de terminaison API Gateway local.
## Conditions préalables
Pour utiliser `sam local start-api`, installez la CLI AWS SAM en procédant comme suit :
+ [AWS SAM prérequis](prerequisites.md).
+ [Installer la CLI AWS SAM](install-sam-cli.md).
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](using-sam-cli-configure.md).
+ [Créez votre application dans AWS SAM](using-sam-cli-init.md).
+ [Initiation à la construction avec AWS SAM](using-sam-cli-build.md).
+ [Présentation du déploiement avec AWS SAM](using-sam-cli-deploy.md).
## 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
```
1. 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
```
1. 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!"}%
```
1. 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](manage-sam-cli-versions.md#manage-sam-cli-versions-upgrade).
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`](using-sam-cli-sync.md) 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](sam-cli-command-reference-sam-local-start-api.md).