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.
# Utilisation de variables d’étape pour une API REST dans API Gateway
Les variables d’étape sont des paires clé-valeur que vous pouvez définir en tant qu’attributs de configuration associés à une étape de déploiement d’une API REST. Elles se comportent comme les variables d’environnement et peuvent être utilisées dans vos modèles de mappage et de configuration d’API. Grâce aux étapes de déploiement dans API Gateway, vous pouvez gérer plusieurs étapes de version pour chaque API et utiliser des variables d’étape pour configurer une étape de déploiement d’API afin qu’elle interagisse avec différents points de terminaison backend.
Les variables d’étape ne sont pas destinées à être utilisées pour des données sensibles, telles que les informations d’identification. Pour transmettre des données sensibles aux intégrations, utilisez un AWS Lambda autorisateur. Vous pouvez transmettre des données sensibles aux intégrations dans la sortie du mécanisme d’autorisation Lambda. Pour en savoir plus, consultez la section [Sortie d’un mécanisme d’autorisation Lambda API Gateway](api-gateway-lambda-authorizer-output.md).
## Cas d’utilisation des variables d’étape
Voici quelques cas d’utilisation pour vos variables d’étape.
**Spécification d’un autre point de terminaison backend**
Votre API peut transmettre une demande `GET` en tant que proxy HTTP à l’hôte web backend. Vous pouvez utiliser une variable d’étape afin qu’API Gateway appelle `example.com` lorsque les appelants d’API invoquent votre point de terminaison de production. Ensuite, lorsque les appelants d’API invoquent l’étape bêta, API Gateway appelle un autre hôte web, par exemple `beta.example.com`. De même, vous pouvez utiliser des variables d’étape pour spécifier un nom de fonction AWS Lambda différent pour chaque étape de votre API. Vous ne pouvez pas utiliser une variable d’étape pour définir un autre point de terminaison d’intégration, par exemple pour pointer la demande `GET` vers une intégration de proxy HTTP dans une étape et une intégration de proxy Lambda dans une autre étape.
Lorsque vous spécifiez un nom de fonction Lambda en tant que valeur de variable d’étape, vous devez configurer les autorisations sur cette fonction Lambda manuellement. Lorsque vous spécifiez une fonction Lambda dans la console API Gateway, une AWS CLI commande apparaît pour configurer les autorisations appropriées. Pour ce faire, vous pouvez également utiliser la AWS CLI commande suivante.
```
aws lambda add-permission --function-name "arn:aws:lambda:us-east-2:123456789012:function:my-function" --source-arn "arn:aws:execute-api:us-east-2:123456789012:api_id/*/HTTP_METHOD/resource" --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
**Transmission d’informations à l’aide de modèles de mappage**
Vous pouvez également accéder aux variables d’étape dans les modèles de mappage, ou transmettre les paramètres de configuration à votre backend AWS Lambda ou HTTP. Par exemple, vous pouvez souhaiter réutiliser la même fonction Lambda pour plusieurs étapes de votre API, mais cette fonction doit lire les données d’une table Amazon DynamoDB différente selon l’étape. Dans les modèles de mappage qui génèrent la demande de la fonction Lambda, vous pouvez utiliser des variables d’étape pour transmettre le nom de la table à Lambda.
Pour utiliser une variable d’étape, vous devez d’abord la configurer, puis lui attribuer une valeur. Par exemple, pour personnaliser le point de terminaison d’intégration HTTP, créez d’abord la variable d’étape `url`, puis saisissez sa valeur, **http://\$1\$1stageVariables.url\$1**, dans la demande d’intégration de votre API. Cette valeur dit à API Gateway de remplacer votre variable d’étape `${}` au moment de l’exécution, en fonction de l’étape où se trouve votre API. Pour de plus amples informations, veuillez consulter [Configuration des variables d'étape pour REST APIs dans API Gateway](how-to-set-stage-variables-aws-console.md).
# Configuration des variables d'étape pour REST APIs dans API Gateway
Cette section explique comment définir diverses variables d’étape pour deux étapes de déploiement d’un exemple d’API à l’aide de la console Amazon API Gateway. Pour comprendre comment utiliser les variables d’étape dans API Gateway, nous vous recommandons de suivre toutes les procédures décrites dans cette section.
## Conditions préalables
Avant de commencer, vérifiez que vous respectez les conditions requises suivantes :
+ Vous devez disposer d’une API disponible dans API Gateway. Suivez les instructions de la section [Développez REST APIs dans API Gateway](rest-api-develop.md).
+ Vous devez avoir déployé l’API au moins une fois. Suivez les instructions de la section [Déploiement d’une API REST dans API Gateway](how-to-deploy-api.md).
+ Vous devez avoir créé la première étape pour une API déployée. Suivez les instructions de la section [Création d’une étape](set-up-stages.md#how-to-create-stage-console).
## Invocation d’un point de terminaison HTTP via une API avec une variable d’étape
Cette procédure décrit comment créer une variable d’étape pour un point de terminaison HTTP et deux étapes pour votre API. En outre, vous devez créer les variables d’étape `url`, `stageName` et `function` qui sont utilisées dans les procédures suivantes de cette section.
**Pour invoquer un point de terminaison HTTP via une API avec une variable d’étape**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Créez une API, puis créez une méthode `GET` sur la ressource racine de l’API. Définissez le type d’intégration sur **HTTP** et définissez **URL du point de terminaison** sur **http://\$1\$1stageVariables.url\$1**.
1. Déployez l’API vers une nouvelle étape nommée **beta**.
1. Dans le volet de navigation principal, choisissez **Étapes**, puis sélectionnez l’étape **bêta**.
1. Dans l’onglet **Variables d’étape**, choisissez **Modifier**.
1. Choisissez **Ajouter une variable d’étape**.
1. Pour **Nom**, saisissez **url**. Pour **Valeur**, entrez **httpbin.org/get**.
1. Choisissez **Ajouter une variable d’étape**, puis procédez comme suit :
Pour **Nom**, saisissez **stageName**. Pour **Valeur**, entrez **beta**.
1. Choisissez **Ajouter une variable d’étape**, puis procédez comme suit :
Pour **Nom**, saisissez **function**. Pour **Valeur**, entrez **HelloWorld**.
1. Choisissez **Enregistrer**.
1. Créez maintenant une deuxième étape. Dans le volet de navigation **Étapes**, choisissez **Créer une étape**. Sous **Stage name (Nom de l’étape)**, entrez **prod**. Sélectionnez un déploiement récent dans **Déploiement**, puis choisissez **Créer une étape**.
1. Comme pour l’étape **bêta**, définissez les trois variables d’étape (**url**, **stageName** et **function**) sur des valeurs différentes (**petstore-demo-endpoint.execute-api.com/petstore/pets**, **prod** et **HelloEveryone**) respectivement.
1. Dans le volet de navigation **Stages**, sélectionnez **beta**. Sous **Détails de l’étape**, choisissez l’icône de copie pour copier l’URL d’invocation de votre API, puis saisissez l’URL d’invocation de votre API dans un navigateur web. Cela lance la demande `GET` de l’étape **beta** sur la ressource racine de l’API.
**Note**
Le lien **Invoke URL** pointe sur la ressource racine de l’API à l’étape **beta**. L’entrée de l’URL dans un navigateur web appelle la méthode `GET` à l’étape **bêta** sur la ressource racine. Si les méthodes sont définies sur les ressources enfants et non sur la ressource racine elle-même, l’entrée de l’URL dans un navigateur web renvoie une réponse d’erreur `{"message":"Missing Authentication Token"}`. Dans ce cas, vous devez ajouter le nom d’une ressource enfant spécifique au lien **Invoke URL**.
1. La réponse renvoyée par la demande `GET` à l’étape **beta** est présentée ci-dessous. Vous pouvez également vérifier le résultat en utilisant un navigateur pour accéder à l’adresse **http://httpbin.org/get**. Cette valeur a été affectée à la variable `url` à l’étape **beta**. Les deux réponses sont identiques.
1. Dans le volet de navigation **Stages**, sélectionnez l’étape **prod**. Sous **Détails de l’étape**, choisissez l’icône de copie pour copier l’URL d’invocation de votre API, puis saisissez l’URL d’invocation de votre API dans un navigateur web. Cela lance la demande `GET` de l’étape **prod** sur la ressource racine de l’API.
1. La réponse renvoyée par la demande `GET` à l’étape **prod** est présentée ci-dessous. Vous pouvez vérifier le résultat en utilisant un navigateur pour accéder à **http ://petstore-demo-endpoint.execute-api. com/petstore/pets**. Cette valeur a été affectée à la variable `url` à l’étape **prod**. Les deux réponses sont identiques.
## Transmission de métadonnées spécifiques à l’étape à un backend HTTP
Cette procédure explique comment utiliser une valeur de variable d’étape dans une expression de paramètre de requête pour transmettre les métadonnées spécifiques à l’étape à un backend HTTP. Nous allons utiliser la variable d’étape `stageName` déclarée dans la procédure précédente.
**Pour transmettre des métadonnées spécifiques à l’étape à un backend HTTP**
1. Dans le volet de navigation **Resource**, sélectionnez la méthode **GET**.
Pour ajouter un paramètre de chaîne de requête à l’URL de la méthode, sélectionnez l’onglet **Demande de méthode**, puis dans la section **Paramètres de la demande de méthode**, choisissez **Modifier**.
1. Choisissez **Paramètres de chaîne de requête d’URL** et procédez comme suit :
1. Sélectionnez **Add query string** (Ajouter une chaîne de requêtes).
1. Pour **Nom**, saisissez **stageName**.
1. Gardez **Obligatoire** et **Mise en cache** désactivés.
1. Choisissez **Enregistrer**.
1. Choisissez l’onglet **Demande d’intégration**, puis dans la section **Paramètres de la demande d’intégration**, sélectionnez **Modifier**.
1. Pour **URL du point de terminaison**, ajoutez **?stageName=\$1\$1stageVariables.stageName\$1** à la valeur d’URL définie précédemment, de sorte que l’**URL du point de terminaison** soit **http://\$1\$1stageVariables.url\$1?stageName=\$1\$1stageVariables.stageName\$1**.
1. Choisissez **Déployer l’API** et sélectionnez l’étape **bêta**.
1. Dans le volet de navigation principal, choisissez **Étapes**. Dans le volet de navigation **Stages**, sélectionnez **beta**. Sous **Détails de l’étape**, choisissez l’icône de copie pour copier l’URL d’invocation de votre API, puis saisissez l’URL d’invocation de votre API dans un navigateur web.
**Note**
Nous utilisons ici l’étape beta, car le point de terminaison HTTP spécifié par la variable `url`, « http://httpbin.org/get », accepte les expressions de paramètre de requête et les renvoie en tant qu’objet `args` dans sa réponse.
1. Vous recevez la réponse suivante. Notez que la valeur `beta`, affectée à la variable d’étape `stageName`, est transmise au backend en tant qu’argument `stageName`.
![\[Réponse de la méthode GET de l’API avec un point de terminaison HTTP utilisant la variable d’étape url.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/stageVariables-new-console-invoke-beta-stage-with-url-and-stageName-response.png)
## Invocation d’une fonction Lambda via une API avec une variable d’étape
Cette procédure explique comment utiliser une variable d’étape pour appeler une fonction Lambda en tant que backend de votre API. Vous allez utiliser la variable d’étape `function` déclarée dans la section [Invocation d’un point de terminaison HTTP via une API avec une variable d’étape](#how-to-set-stage-variables-aws-console-http-endpoint).
Lorsque vous définissez une fonction Lambda en tant que valeur d’une variable d’étape, utilisez le nom local de la fonction, en incluant éventuellement son alias ou sa spécification de version, comme dans **HelloWorld**, **HelloWorld:1** ou **HelloWorld:alpha**. N’utilisez pas l’ARN de la fonction (par exemple, **arn:aws:lambda:us-east-1:123456789012:function:HelloWorld**). La console API Gateway considère la valeur de la variable d’étape d’une fonction Lambda comme le nom de fonction non qualifié et développe la variable d’étape donnée en un ARN.
**Pour invoquer une fonction Lambda via une API avec une variable d’étape**
1. Créez une fonction Lambda nommée **HelloWorld** à l’aide de l’exécution Node.js par défaut. Le code doit contenir ce qui suit :
```
export const handler = function(event, context, callback) {
if (event.stageName)
callback(null, 'Hello, World! I\'m calling from the ' + event.stageName + ' stage.');
else
callback(null, 'Hello, World! I\'m not sure where I\'m calling from...');
};
```
Pour plus d’informations sur la création d’une Fonction Lambda, consultez [Bien démarrer avec la console d’API REST](getting-started-rest-new-console.md#getting-started-rest-new-console-create-function).
1. Dans le volet **Ressources**, sélectionnez **Créer une ressource**, puis procédez comme suit :
1. Pour **Chemin de ressources**, sélectionnez **/**.
1. Sous **Resource Name (Nom de la ressource)**, entrez **lambdav1**.
1. Choisissez **Créer une ressource**.
1. Sélectionnez la ressource **/lambdav1**, puis choisissez **Créer une méthode**.
Ensuite, procédez comme suit :
1. Pour **Type de méthode**, sélectionnez **GET**.
1. Pour **Type d’intégration**, sélectionnez **Fonction Lambda**.
1. Maintenez **Intégration proxy Lambda** désactivée.
1. Sous **Lambda function (Fonction Lambda)**, saisissez `${stageVariables.function}`.
![\[Création d’une méthode GET intégrée avec une fonction Lambda spécifiée par la variable d’étape function\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/stageVariables-new-console-create-lambda-get-method.png)
**Astuce**
Lorsque vous y êtes invité avec la commande **Ajouter une autorisation**, copiez la commande [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html). Exécutez la commande sur chaque Fonction Lambda qui sera affectée à la variable d’étape `function`. Par exemple, si la valeur `$stageVariables.function` est `HelloWorld`, exécutez la commande AWS CLI suivante :
```
aws lambda add-permission --function-name arn:aws:lambda:us-east-1:account-id:function:HelloWorld --source-arn arn:aws:execute-api:us-east-1:account-id:api-id/*/GET/lambdav1 --principal apigateway.amazonaws.com --statement-id statement-id-guid --action lambda:InvokeFunction
```
Si vous ne le faites pas, l’appel de la méthode renverra une réponse `500 Internal Server Error`. Remplacez `${stageVariables.function}` par le nom de la Fonction Lambda qui est affectée à la variable d’étape.
![\[AWS CLI commande pour ajouter l'autorisation à la fonction Lambda à invoquer par la méthode que vous avez créée.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/stageVariables-new-console-add-permission-to-lambda-function.png)
1. Choisissez **Créer une méthode**.
1. Déployez l’API dans les étapes **prod** et **beta**.
1. Dans le volet de navigation principal, choisissez **Étapes**. Dans le volet de navigation **Stages**, sélectionnez **beta**. Sous **Détails de l’étape**, choisissez l’icône de copie pour copier l’URL d’invocation de votre API, puis saisissez l’URL d’invocation de votre API dans un navigateur web. Ajoutez **/lambdav1** à l’URL avant d’appuyer sur Entrée.
Vous recevez la réponse suivante.
```
"Hello, World! I'm not sure where I'm calling from..."
```
## Transmission des métadonnées spécifiques à l’étape à une fonction Lambda via une variable d’étape
Cette procédure explique comment utiliser une variable d’étape pour transmettre les métadonnées de configuration spécifiques à l’étape à une fonction Lambda. Vous créez une méthode `POST` et un modèle de mappage d’entrée pour générer la charge utile à l’aide de la variable d’étape `stageName` déclarée précédemment.
**Pour transmettre des métadonnées spécifiques à l’étape à une fonction Lambda via une variable d’étape**
1. Sélectionnez la ressource **/lambdav1**, puis choisissez **Créer une méthode**.
Ensuite, procédez comme suit :
1. Pour **Type de méthode**, sélectionnez **POST**.
1. Pour **Type d’intégration**, sélectionnez **Fonction Lambda**.
1. Maintenez **Intégration proxy Lambda** désactivée.
1. Sous **Lambda function (Fonction Lambda)**, saisissez `${stageVariables.function}`.
1. Lorsque vous y êtes invité avec la commande **Ajouter une autorisation**, copiez la commande [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html). Exécutez la commande sur chaque Fonction Lambda qui sera affectée à la variable d’étape `function`.
1. Choisissez **Créer une méthode**.
1. Choisissez l’onglet **Demande d’intégration**, puis dans la section **Paramètres de la demande d’intégration**, sélectionnez **Modifier**.
1. Choisissez **Modèles de mappage**, puis choisissez **Ajouter un modèle de mappage**.
1. Pour **Type de contenu**, entrez **application/json**.
1. Pour **Corps du modèle**, entrez le modèle suivant :
```
#set($inputRoot = $input.path('$'))
{
"stageName" : "$stageVariables.stageName"
}
```
**Note**
Dans un modèle de mappage, une variable d’étape doit être référencée entre guillemets (comme dans `"$stageVariables.stageName"` ou `"${stageVariables.stageName}"`). Dans d’autres endroits, il doit être référencé sans guillemets (comme dans `${stageVariables.function}`).
1. Choisissez **Enregistrer**.
1. Déployez l’API dans les étapes **beta** et **prod**.
1. Pour utiliser un client d’API REST afin de transmettre des métadonnées spécifiques à l’étape, procédez comme suit :
1. Dans le volet de navigation **Stages**, sélectionnez **beta**. Sous **Détails de l’étape**, choisissez l’icône de copie pour copier l’URL d’invocation de votre API, puis entrez l’URL d’invocation de votre API dans le champ d’entrée d’un client d’API REST. Ajoutez **/lambdav1** avant de soumettre votre demande.
Vous recevez la réponse suivante.
```
"Hello, World! I'm calling from the beta stage."
```
1. Dans le volet de navigation **Étapes**, choisissez **prod**. Sous **Détails de l’étape**, choisissez l’icône de copie pour copier l’URL d’invocation de votre API, puis entrez l’URL d’invocation de votre API dans le champ d’entrée d’un client d’API REST. Ajoutez **/lambdav1** avant de soumettre votre demande.
Vous recevez la réponse suivante.
```
"Hello, World! I'm calling from the prod stage."
```
1. Pour utiliser la fonctionnalité **Test** afin de transmettre des métadonnées spécifiques à l’étape, procédez comme suit :
1. Dans le volet de navigation **Ressources**, choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
1. Pour **function**, entrez **HelloWorld**.
1. Pour **stageName**, entrez **beta**.
1. Sélectionnez **Tester)**. Vous n’avez pas besoin d’ajouter de corps à votre demande `POST`.
Vous recevez la réponse suivante.
```
"Hello, World! I'm calling from the beta stage."
```
1. Vous pouvez répéter les étapes précédentes pour tester l’étape **Prod**. Pour **stageName**, entrez **Prod**.
Vous recevez la réponse suivante.
```
"Hello, World! I'm calling from the prod stage."
```
# Référence des variables de stage API Gateway pour REST APIs dans API Gateway
Vous pouvez utiliser les variables d’étape API Gateway dans les cas suivants.
## Expressions de mappage de paramètres
Une variable d’étape peut être utilisée dans une expression de mappage de paramètres pour un paramètre d’en-tête de demande ou de réponse d’une méthode d’API, sans aucune substitution partielle. Dans l’exemple suivant, la variable d’étape est référencée sans le caractère `$` et sans être indiquée entre accolades `{...}`.
+ `stageVariables.`
## Modèles de mappage
Une variable d’étape peut être utilisée n’importe où dans un modèle de mappage, comme illustré dans les exemples suivants.
+ `{ "name" : "$stageVariables."}`
+ `{ "name" : "${stageVariables.}"}`
## Intégration HTTP URIs
Une variable d’étape peut être utilisée dans une URL d’intégration HTTP, comme illustré dans les exemples suivants :
+ URI complet sans protocole – `http://${stageVariables.}`
+ Domaine complet – `http://${stageVariables.}/resource/operation`
+ Sous-domaine – `http://${stageVariables.}.example.com/resource/operation`
+ Chemin – `http://example.com/${stageVariables.}/bar`
+ Chaîne de requête – `http://example.com/foo?q=${stageVariables.}`
## AWS intégration URIs
Une variable d'étape peut être utilisée dans le cadre d'une action d' AWS URI ou de composants de chemin, comme illustré dans l'exemple suivant.
+ `arn:aws:apigateway:::${stageVariables.}`
## AWS intégration URIs (fonctions Lambda)
Une variable d’étape peut être utilisée à la place d’un nom de fonction Lambda, ou de sa version/son alias, comme illustré dans les exemples suivants.
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations`
**Note**
Pour utiliser une variable d’étape pour une fonction Lambda, la fonction doit se trouver dans le même compte que l’API. Les variables d’étape ne prennent pas en charge les fonctions Lambda inter-comptes.
## Groupe d’utilisateurs Amazon Cognito
Une variable d’étape peut être utilisée à la place d’un groupe d’utilisateurs Amazon Cognito pour un mécanisme d’autorisation `COGNITO_USER_POOLS`.
+ `arn:aws:cognito-idp:::userpool/${stageVariables.}`
## AWS informations d'identification d'intégration
Une variable d'étape peut être utilisée dans le cadre de l'ARN des informations d'identification AWS utilisateur/rôle, comme indiqué dans l'exemple suivant.
+ `arn:aws:iam:::${stageVariables.}`