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 une API passerelle REST APIs avec Step Functions
Découvrez comment utiliser Amazon API Gateway pour créer, publier, gérer et surveiller, HTTP et REST APIs avec Step Functions. Pour intégrer API Gateway, vous définissez un Task
état dans Step Functions qui appelle directement une API passerelle HTTP ou un point de REST terminaison de API passerelle, sans écrire de code ni dépendre d'une autre infrastructure. Une définition d'Task
état inclut toutes les informations nécessaires à l'APIappel. Vous pouvez également sélectionner différentes méthodes d'autorisation.
Step Functions peut contrôler certains AWS services directement depuis Amazon States Language (ASL). Pour en savoir plus, consultez Intégration d’autres services et Transmission de paramètres à un service API dans Step Functions.
En quoi l'intégration Optimized API Gateway est différente de l' AWS SDKintégration API Gateway
-
apigateway:invoke:
n'a pas d'équivalent dans l'intégration des AWS SDK services. Au lieu de cela, le service Optimized API Gateway appelle directement votre point de terminaison API Gateway.
APIPrise en charge des fonctionnalités de passerelle
L'intégration de Step Functions API Gateway prend en charge certaines fonctionnalités de 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 les HTTP API intégrations Step Functions API API Gateway REST API et Gateway :
-
Autorisateurs : IAM (utilisant la version 4 de Signature), No Auth, autorisateurs Lambda (basés sur les paramètres de la demande et basés sur des jetons avec en-tête personnalisé)
-
APItypes : Régional
-
APIgestion : noms de API domaine de API passerelle, API stage, chemin, paramètres de requête, corps de requête
-
-
Soutenu par l'HTTPAPIintégration de Step Functions API Gateway. L'RESTAPIintégration Step Functions API Gateway qui fournit l'option d'optimisation pour Edge n'est pas prise APIs en charge.
-
Non pris en charge par l'intégration de Step Functions API Gateway :
-
Autorisateurs : Amazon Cognito, Native Open ID OAuth Connect/ 2.0, en-tête d'autorisation pour les autorisateurs Lambda basés sur des jetons
-
APItypes : Privé
-
APIgestion : noms de domaine personnalisés
-
Pour plus d'informations sur API Gateway et ses « HTTP and » RESTAPIs, consultez ce qui suit.
-
La page des concepts API d'Amazon Gateway.
-
Choisir entre HTTP APIs et REST APIs dans le guide du développeur de API Gateway.
Format des demandes
Lorsque vous créez votre définition Task
d'état, Step Functions valide les paramètres, crée le nécessaire URL pour effectuer l'appel, puis appelle leAPI. La réponse inclut le code d'HTTPétat, 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 API passerelleURL. Le format est
.<API ID>
.execute-api.<region>
.amazonaws.comL'APIidentifiant ne peut contenir qu'une combinaison des caractères alphanumériques suivants :
0123456789abcdefghijklmnopqrstuvwxyz
-
-
Method
-
Type :
Enum
-
La HTTP méthode, qui doit être l'une des suivantes :
-
GET
-
POST
-
PUT
-
DELETE
-
PATCH
-
HEAD
-
OPTIONS
-
-
Paramètres de demande facultatifs
-
Headers
-
Type :
JSON
-
HTTPles en-têtes permettent d'obtenir une liste de valeurs associées à la même clé.
-
-
Stage
-
Type :
String
-
Nom de l'étape vers laquelle le API est déployé dans API Gateway. C'est facultatif pour tous ceux HTTP API qui utilisent la
$default
scène.
-
-
Path
-
Type :
String
-
Paramètres de chemin ajoutés après le point de API terminaison.
-
-
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
ouString
. -
Le corps HTTP de la demande. Son type peut être un
JSON
objet ouString
.RequestBody
n'est pris en charge que pour lesPUT
HTTP méthodesPATCH
POST
, 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 à votreAPI. Dans l'exemple suivant, le
category
champ ne sera pas inclus dans la demande, sauf s'AllowNullValues
il est défini comme teltrue
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 de saisie de la demande ne seront pas envoyés à votreAPI. Vous pouvez forcer l'envoi de valeurs nulles à votre adresse API en la définissant
true
dansAllowNullValues
la définition de votre machine à états.
-
-
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 HTTP d'en-tête suivantes ne sont actuellement pas autorisées :
-
Tout ce qui est préfixé par
X-Forwarded
,X-Amz
ouX-Amzn
. -
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", "Parameters": { "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 API directement la méthode sans autorisation.
-
IAMrôle : Avec cette méthode, Step Functions joue le rôle de machine à états, signe la demande avec Signature Version 4 (SigV4), puis appelle leAPI.
-
Politique en matière de ressources : Step Functions authentifie la demande, puis appelle leAPI. Vous devez y associer une politique de ressources API spécifiant les éléments suivants :
-
La machine à états qui invoquera API Gateway.
Important
Vous devez spécifier votre machine d'état pour en limiter l'accès. Si vous ne le faites pas, toute machine d'état qui authentifie sa demande de API passerelle en vous authentifiant par la politique de ressources API aura accès à votre compte.
-
That Step Functions est le service qui appelle API Gateway :
"Service": "states.amazonaws.com"
. -
La ressource à laquelle vous souhaitez accéder, notamment :
-
Le
region
. -
Le
account-id
dans la région spécifiée. -
Le
api-id
. -
Le
stage-name
. -
Le
HTTP-VERB
(méthode). -
Le
resource-path-specifier
.
-
Pour un exemple de politique en matière de ressources, consultez IAMles politiques relatives à Step Functions et API Gateway.
Pour plus d'informations sur le format de ressource, voir Format de ressource des autorisations d'exécution API dans API Gateway dans le Guide du développeur de API Gateway.
Note
Les politiques de ressources ne sont prises en charge que pour le RESTAPI.
-
Modèles d'intégration des services
L'intégration API Gateway prend en charge deux modèles d'intégration de services :
-
Réponse à la requête, 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 HTTP réponse.
-
Attendre un rappel avec le jeton de tâche(
.waitForTaskToken
), qui attend qu'un jeton de tâche soit renvoyé avec une charge utile. Pour utiliser le.waitForTaskToken
modèle, ajoutez-le. waitForTaskJeton à la fin du champ Ressource de votre définition de tâche, comme illustré dans l'exemple suivant :{ "Type": "Task", "Resource":"arn:aws:states:::apigateway:invoke.waitForTaskToken", "Parameters": { "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com", "Method": "POST", "Headers": { "TaskToken.$": "States.Array($$.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'APIappel. |
Headers |
JSON |
Les en-têtes de réponse. |
StatusCode |
Integer |
Code HTTP d'état 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'HTTPétat est disponible, l'erreur sera renvoyée dans le format
ApiGateway.
.<HTTP Status Code>
-
Si le code d'HTTPétat n'est pas disponible, l'erreur sera renvoyée dans le format
ApiGateway.
.<Exception>
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.
Pour plus d'informations, consultez :
-
Concepts API d'Amazon Gateway présentés dans le guide du développeur de API Gateway.
-
IAMpolitiques relatives aux appels Amazon API Gateway dans Step Functions
-
Un exemple de projet qui montre comment Interagissez avec et API gérez par API Gateway
Concepts API d'Amazon Gateway présentés dans le guide du développeur de API Gateway.