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.
# Créez des API REST API Gateway avec Step Functions
Découvrez comment utiliser Amazon API Gateway pour créer, publier, gérer et surveiller les API HTTP et REST avec Step Functions. Pour intégrer API Gateway, vous définissez un `Task` état dans Step Functions qui appelle directement un point de terminaison HTTP ou REST API Gateway, sans écrire de code ni recourir à une autre infrastructure. Une définition d'`Task`état inclut toutes les informations nécessaires à l'appel d'API. Vous pouvez également sélectionner différentes méthodes d'autorisation.
Pour en savoir plus sur l'intégration aux AWS services dans Step Functions, consultez [Intégration des services ](integrate-services.md) et[Transmission de paramètres à une API de service dans Step Functions](connect-parameters.md).
**Principales fonctionnalités de l'intégration d'Optimized API Gateway**
`apigateway:invoke:`n'a aucun équivalent dans l'intégration des services du AWS SDK. Au lieu de cela, le service Optimized API Gateway appelle directement votre point de terminaison API Gateway.
## Support des fonctionnalités d'API Gateway
L'intégration de Step Functions API Gateway prend en charge certaines fonctionnalités d'API Gateway, mais pas toutes. Pour une liste plus détaillée des fonctionnalités prises en charge, consultez ce qui suit.
+ Pris en charge à la fois par l'API REST Step Functions API Gateway et par les intégrations de l'API HTTP API Gateway :
+ **Autorisateurs** : IAM (utilisant [Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html)), No Auth, Autorisateurs Lambda (basés sur des paramètres de demande et basés sur des jetons avec en-tête personnalisé)
+ **Types d'API** : régionaux
+ **Gestion des API** : noms de domaine de l'API API Gateway, stage de l'API, chemin, paramètres de requête, corps de la requête
+ Pris en charge par l'intégration de l'API HTTP Step Functions API Gateway. L'intégration de l'API REST Step Functions API Gateway qui fournit l'option pour les Edge-optimized API n'est pas prise en charge.
+ Non pris en charge par l'intégration de l'API Gateway Step Functions :
+ **Autorisateurs** : Amazon Cognito, Native Open ID Connect/OAuth 2.0, en-tête d'autorisation pour les autorisateurs Lambda basés sur des jetons
+ **Types d'API** : privés
+ **Gestion des API** : noms de domaine personnalisés
Pour plus d'informations sur API Gateway et ses API HTTP et REST, consultez ce qui suit.
+ La page des [concepts d'Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-basic-concept.html).
+ [Choisir entre les API HTTP et les API REST](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html) dans le guide du développeur d'API Gateway.
## Format des demandes
Lorsque vous créez votre définition `Task` d'état, Step Functions valide les paramètres, crée l'URL nécessaire pour effectuer l'appel, puis appelle l'API. La réponse inclut le code d'état HTTP, les en-têtes et le corps de la réponse. Le format de demande comporte des paramètres obligatoires et facultatifs.
### Paramètres de demande requis
+ `ApiEndpoint`
+ Type : `String`
+ Le nom d'hôte d'une URL d'API Gateway. Le format est `{{}}.execute-api.{{region}}.amazonaws.com`.
L'ID d'API ne peut contenir qu'une combinaison des caractères alphanumériques suivants : `0123456789abcdefghijklmnopqrstuvwxyz`
+ `Method`
+ Type : `Enum`
+ La méthode HTTP, qui doit être l'une des suivantes :
+ `GET`
+ `POST`
+ `PUT`
+ `DELETE`
+ `PATCH`
+ `HEAD`
+ `OPTIONS`
### Paramètres de demande facultatifs
+ `Headers`
+ Type : `JSON`
+ Les en-têtes HTTP permettent d'obtenir une liste de valeurs associées à la même clé.
+ `Stage`
+ Type : `String`
+ Nom de l'étape sur laquelle l'API est déployée dans API Gateway. C'est facultatif pour toute API HTTP qui utilise le `$default` stage.
+ `Path`
+ Type : `String`
+ Paramètres de chemin ajoutés après le point de terminaison de l'API.
+ `QueryParameters`
+ Type : `JSON`
+ Les chaînes de requête n'autorisent qu'une liste de valeurs associées à la même clé.
+ `RequestBody`
+ Type : `JSON` ou `String`.
+ Le corps de la requête HTTP. Son type peut être un `JSON` objet ou`String`. `RequestBody`n'est pris en charge que pour `PATCH` `POST` les méthodes `PUT` HTTP, et.
+ `AllowNullValues`
+ Type : `BOOLEAN` — valeur par défaut : `false`
+ Avec le paramètre par défaut, aucune **valeur nulle** dans l'état d'entrée de la demande **ne** sera envoyée à votre API. Dans l'exemple suivant, le `category` champ **ne sera pas** inclus dans la demande, sauf s'`AllowNullValues`il est défini comme tel `true` dans la définition de votre machine à états.
```
{
"NewPet": {
"type": "turtle",
"price": 123,
"category": null
}
}
```
**Note**
Par défaut, les champs contenant des valeurs **nulles** dans l'état d'entrée de la demande **ne seront pas** envoyés à votre API. Vous pouvez forcer l'envoi de valeurs nulles à votre API en le définissant `true` dans `AllowNullValues` la définition de votre machine d'état.
+ `AuthType`
+ Type : `JSON`
+ La méthode d'authentification. La méthode par défaut est`NO_AUTH`. Les valeurs autorisées sont :
+ `NO_AUTH`
+ `IAM_ROLE`
+ `RESOURCE_POLICY`
Voir **Authentification et autorisation** pour plus d'informations.
**Note**
Pour des raisons de sécurité, les clés d'en-tête HTTP suivantes ne sont actuellement pas autorisées :
Tout ce qui est préfixé par `X-Forwarded``X-Amz`, ou `X-Amzn` (sans distinction majuscules/majuscules).
`Authorization`
`Connection`
`Content-md5`
`Expect`
`Host`
`Max-Forwards`
`Proxy-Authenticate`
`Server`
`TE`
`Transfer-Encoding`
`Trailer`
`Upgrade`
`Via`
`Www-Authenticate`
L'exemple de code suivant montre comment invoquer API Gateway à l'aide de Step Functions.
```
{
"Type": "Task",
"Resource":"arn:aws:states:::apigateway:invoke",
"Arguments": {
"ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
"Method": "GET",
"Headers": {
"key": ["value1", "value2"]
},
"Stage": "prod",
"Path": "bills",
"QueryParameters": {
"billId": ["123456"]
},
"RequestBody": {},
"AuthType": "NO_AUTH"
}
}
```
## Authentification et autorisation
Vous pouvez utiliser les méthodes d'authentification suivantes :
+ **Aucune autorisation** : appelez l'API directement sans méthode d'autorisation.
+ **Rôle IAM** : avec cette méthode, Step Functions joue le rôle de machine à états, signe la demande avec [Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html) (SigV4), puis appelle l'API.
+ **Politique en matière de ressources** : Step Functions authentifie la demande, puis appelle l'API. Vous devez associer une politique de ressources à l'API qui spécifie les éléments suivants :
1. La machine d'état qui invoquera API Gateway.
**Important**
Vous devez spécifier votre machine d'état pour en limiter l'accès. Si ce n'est pas le cas, toute machine d'état qui authentifie sa demande API Gateway avec une authentification par **politique de ressources** auprès de votre API sera autorisée à y accéder.
1. That Step Functions est le service qui appelle API Gateway :`"Service": "states.amazonaws.com"`.
1. La ressource à laquelle vous souhaitez accéder, notamment :
+ La valeur {{region}}.
+ Le {{account-id}} dans la région spécifiée.
+ La valeur {{api-id}}.
+ La valeur {{stage-name}}.
+ La {{HTTP-VERB}} (méthode).
+ La valeur {{resource-path-specifier}}.
Pour un exemple de politique de ressources, consultez les [politiques IAM pour Step Functions et API Gateway](#api-gateway-iam).
Pour plus d'informations sur le format de ressource, consultez la section [Format de ressource des autorisations d'exécution d'API dans API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-control-access-using-iam-policies-to-invoke-api.html#api-gateway-iam-policy-resource-format-for-executing-api) dans le guide du développeur d'API Gateway.
**Note**
Les politiques de ressources ne sont prises en charge que pour l'API REST.
## Modèles d'intégration des services
L'intégration d'API Gateway prend en charge deux modèles d'intégration de services :
+ [Réponse à la requête](connect-to-resource.md#connect-default), qui est le modèle d'intégration par défaut. Il permet à Step Functions de passer à l'étape suivante immédiatement après avoir reçu une réponse HTTP.
+ [Attendre un rappel avec un jeton de tâche](connect-to-resource.md#connect-wait-token)(`.waitForTaskToken`), qui attend qu'un jeton de tâche soit renvoyé avec une charge utile. Pour utiliser le `.waitForTaskToken` modèle, ajoutez .wait ForTaskToken à la fin du champ **Resource** de votre définition de tâche, comme indiqué dans l'exemple suivant :
```
{
"Type": "Task",
"Resource":"arn:aws:states:::apigateway:invoke.waitForTaskToken",
"Arguments": {
"ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
"Method": "POST",
"Headers": {
"TaskToken": "{% $states.context.Task.Token %}"
},
"Stage": "prod",
"Path": "bills/add",
"QueryParameters": {},
"RequestBody": {
"billId": "my-new-bill"
},
"AuthType": "IAM_ROLE"
}
}
```
## Format de sortie
Les paramètres de sortie suivants sont fournis :
| Nom | Type | Description |
| --- | --- | --- |
| ResponseBody | JSON ou String | Le corps de réponse de l'appel d'API. |
| Headers | JSON | Les en-têtes de réponse. |
| StatusCode | Integer | Code de statut HTTP de la réponse. |
| StatusText | String | Le texte d'état de la réponse. |
Exemple de réponse :
```
{
"ResponseBody": {
"myBills": []
},
"Headers": {
"key": ["value1", "value2"]
},
"StatusCode": 200,
"StatusText": "OK"
}
```
## Gestion des erreurs
Lorsqu'une erreur se produit, un `error` et `cause` est renvoyé comme suit :
+ Si le code d'état HTTP est disponible, l'erreur sera renvoyée au format`ApiGateway.{{}}`.
+ Si le code d'état HTTP n'est pas disponible, l'erreur sera renvoyée au format`ApiGateway.{{}}`.
Dans les deux cas, le `cause` est renvoyé sous forme de chaîne.
L'exemple suivant montre une réponse dans laquelle une erreur s'est produite :
```
{
"error": "ApiGateway.403",
"cause": "{\"message\":\"Missing Authentication Token\"}"
}
```
**Note**
Le code d'état `2XX` indique le succès et aucune erreur ne sera renvoyée. Tous les autres codes d'état ou exceptions déclenchées provoqueront une erreur.
## Politiques IAM pour les appels à Amazon API Gateway
Les exemples de modèles suivants montrent comment AWS Step Functions générer des politiques IAM en fonction des ressources contenues dans la définition de votre machine d'état. Pour plus d’informations, consultez [Comment Step Functions génère des politiques IAM pour les services intégrés](service-integration-iam-templates.md) et [Découvrez les modèles d'intégration des services dans Step Functions](connect-to-resource.md).
*Ressources:*
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:{{us-east-1}}:{{123456789012}}:ENDPOINT/STAGE/GET/pets",
"arn:aws:execute-api:{{us-east-1}}:{{123456789012}}:ENDPOINT/STAGE/POST/pets"
],
"Effect": "Allow"
}
]
}
```
L'exemple de code suivant montre une politique de ressources pour appeler API Gateway.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "states.amazonaws.com"
},
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:{{us-east-1}}:{{123456789012}}:myApi-id/{{stage-name}}/{{HTTP-VERB}}/{{resource-path-specifier}}",
"Condition": {
"StringEquals": {
"aws:SourceArn": [
"{{}}"
]
}
}
}
]
}
```