APIPrise en charge des fonctionnalités de passerelle Format des demandes Authentification et autorisation Modèles d'intégration des services Format de sortie Gestion des erreurs

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.com.
  
  L'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 ou String.
- Le corps HTTP de la demande. Son type peut être un JSON objet ouString. RequestBodyn'est pris en charge que pour les PUT HTTP méthodes PATCHPOST, 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'AllowNullValuesil 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 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 dans AllowNullValues la définition de votre machine à états.
AuthType
- Type : JSON
- La méthode d'authentification. La méthode par défaut estNO_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é parX-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 :
1. 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.
2. That Step Functions est le service qui appelle API Gateway :"Service": "states.amazonaws.com".
3. 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 formatApiGateway.<HTTP Status Code>.
Si le code d'HTTPétat n'est pas disponible, l'erreur sera renvoyée dans le formatApiGateway.<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.

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

Intégrations optimisées

Amazon Athena

Créez une API passerelle REST APIs avec Step Functions

En quoi l'intégration Optimized API Gateway est différente de l' AWS SDKintégration API Gateway

APIPrise en charge des fonctionnalités de passerelle

Format des demandes

Paramètres de demande requis

Paramètres de demande facultatifs

Note

Note

Authentification et autorisation

Important

Note

Modèles d'intégration des services

Format de sortie

Gestion des erreurs

Note