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éation d'une API Step Functions à l'aide d'API Gateway
<a name="tutorial-api-gateway"></a>

Vous pouvez utiliser Amazon API Gateway pour AWS Step Functions APIs associer vos méthodes à une API API Gateway. Lorsqu'une requête HTTPS est envoyée à une méthode d'API, API Gateway appelle vos actions d'API Step Functions.

Ce didacticiel vous montre comment créer une API qui utilise une ressource et la méthode `POST` pour communiquer avec l'action d'API `[StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)`. Vous allez utiliser la console Gestion des identités et des accès AWS (IAM) pour créer un rôle pour API Gateway. Vous allez ensuite utiliser la console API Gateway pour créer une API API Gateway, créer une ressource et une méthode, et associer la méthode à l'action de l'`StartExecution`API. En dernier lieu, vous déploierez et testerez votre API.

**Note**  
Bien qu'Amazon API Gateway puisse démarrer une exécution de Step Functions en appelant`StartExecution`, vous devez appeler `[DescribeExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeExecution.html)` pour obtenir le résultat.

## Étape 1 : créer un rôle IAM pour API Gateway
<a name="api-gateway-step-1"></a>

Avant de créer votre API API Gateway, vous devez autoriser API Gateway à appeler les actions de l'API Step Functions.<a name="api-gateway-procedure-create-iam-role"></a>

**Pour configurer les autorisations pour API Gateway**

1. Connectez-vous à la [console IAM](https://console.aws.amazon.com/iam/home) et choisissez **Rôles**, **Créer un rôle**.

1. Sur la page **Select trusted entity** (Sélectionner une entité de confiance), procédez comme suit :

   1. Pour le **type d'entité fiable**, conservez la sélection par défaut de **Service AWS**.

   1. **Dans le cas d'utilisation**, choisissez **API Gateway** dans la liste déroulante.

1. Sélectionnez **API Gateway**, puis **Next**.

1. Sur la page **Ajouter des autorisations**, sélectionnez **Suivant**.

1. (Facultatif) Sur la page **Nom, révision et création**, entrez des informations, telles que le nom du rôle. Par exemple, saisissez **APIGatewayToStepFunctions**.

1. Choisissez **Créer un rôle**.

   Le rôle IAM apparaît dans la liste des rôles.

1. Choisissez le nom de votre rôle et notez l' **ARN de rôle**, comme illustré dans l'exemple suivant.

   ```
   arn:aws:iam::123456789012:role/APIGatewayToStepFunctions
   ```<a name="api-gateway-attach-policy-to-role"></a>

**Pour associer une politique au rôle IAM**

1. Sur la page **Rôles**, recherchez votre rôle (`APIGatewayToStepFunctions`), puis choisissez le rôle.

1. Dans l'onglet **Autorisations**, choisissez **Ajouter des autorisations**, puis choisissez **Joindre des politiques**.

1. Sur la page **Joindre une politique**, recherchez`AWSStepFunctionsFullAccess`, choisissez la politique, puis choisissez **Ajouter des autorisations**.

## Étape 2 : Création de votre API API Gateway
<a name="api-gateway-step-2"></a>

Après avoir créé votre rôle IAM, vous pouvez créer votre API API Gateway personnalisée.

**Pour créer l’API**

1. Ouvrez la [console Amazon API Gateway](https://console.aws.amazon.com/apigateway/), puis choisissez **Create API**.

1. Sur la page **Choisissez un type d'API**, dans le volet **API REST**, choisissez **Build**.

1. Sur la page **Créer une API REST**, sélectionnez **Nouvelle API**, puis entrez le **nom ***StartExecutionAPI*** de l'API**.

1. Conservez le **type de point de terminaison d'API** **régional**, puis choisissez **Create API**.<a name="api-gateway-create-resource"></a>

**Pour créer une ressource**

1. Sur la page **Ressources** de***StartExecutionAPI***, choisissez **Créer une ressource**.

1. Sur la page **Créer une ressource**, entrez le **nom **execution** de la ressource**, puis choisissez **Créer une ressource**.<a name="api-gateway-create-method"></a>

**Pour créer une méthode POST**

1. Choisissez la ressource **/execution**, puis choisissez **Create method**.

1. Dans **Type de méthode**, sélectionnez`POST`.

1. Pour **Type d’intégration**, choisissez **Service AWS**.

1. Pour **Région AWS**, choisissez une région dans la liste.

1. Pour **Service AWS**, choisissez **Step Functions** dans la liste.

1. Laissez **Sous-domaine AWS** vide.

1. Pour la **méthode HTTP**, choisissez **POST** dans la liste.
**Note**  
Toutes les actions de l'API Step Functions utilisent la `POST` méthode HTTP.

1. Pour **Type d’action**, sélectionnez **Utiliser un nom d’action**.

1. Pour **Nom de l’action**, saisissez **StartExecution**.

1. Pour le **rôle d'exécution**, entrez [l'ARN du rôle IAM que vous avez créé précédemment](#api-gateway-procedure-create-iam-role), comme indiqué dans l'exemple suivant.

   ```
   arn:aws:iam::123456789012:role/APIGatewayToStepFunctions
   ```

1. **Conservez les options par défaut pour le **cache des informations d'identification** et le **délai d'expiration par défaut**, puis choisissez Enregistrer.**

Le mappage visuel entre API Gateway et Step Functions est affiché sur la page **d'exécution de la méthode /execution - POST**.

## Étape 3 : tester et déployer l'API API Gateway
<a name="api-gateway-step-3"></a>

Une fois que vous avez créé l'API, testez-la et déployez-la. <a name="api-gateway-test-api"></a>

**Pour tester la communication entre API Gateway et Step Functions**

1. Sur la page **/execution - POST - Method Execution**, choisissez l'onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.

1. **Dans l'onglet **/execution - POST - Method Test**, copiez les paramètres de demande suivants dans la section **Corps de la requête** en utilisant l'ARN d'une machine à états existante (ou [créez une nouvelle machine à états utilisant une fonction Lambda](tutorial-creating-lambda-state-machine.md)), puis choisissez Test.**

   ```
   {
      "input": "{}",
      "name": "MyExecution",
      "stateMachineArn": "arn:aws:states:region:123456789012:stateMachine:HelloWorld"
   }
   ```

   Pour plus d'informations, consultez la [syntaxe des `StartExecution` demandes](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html#API_StartExecution_RequestSyntax) dans la *référence de l'AWS Step FunctionsAPI*.
**Note**  
Si vous ne souhaitez pas inclure l'ARN de votre machine d'état dans le corps de votre appel API Gateway, vous pouvez configurer un modèle de mappage dans l'onglet **Demande d'intégration**, comme indiqué dans l'exemple suivant.  

   ```
   {
       "input": "$util.escapeJavaScript($input.json('$'))",
       "stateMachineArn": "$util.escapeJavaScript($stageVariables.arn)"
   }
   ```
Avec cette approche, vous pouvez spécifier ARNs des machines à états différents en fonction de votre stade de développement (par exemple`dev`,`test`, et`prod`). Pour plus d'informations sur la spécification des variables d'étape dans un modèle de mappage, consultez [https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html#stagevariables-template-reference](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html#stagevariables-template-reference)le *guide du développeur d'API Gateway*.

1. L'exécution démarre et l'ARN d'exécution ainsi que sa date d'époque sont affichés sous le **corps de la réponse.**

   ```
   {
      "executionArn": "arn:aws:states:region:123456789012:execution:HelloWorld:MyExecution",
      "startDate": 1486768956.878
   }
   ```
**Note**  
Vous pouvez consulter l'exécution en choisissant votre machine d'état sur la [console AWS Step Functions](https://console.aws.amazon.com/states/).

**Pour déployer votre API**

1. Sur la page **Ressources** de***StartExecutionAPI***, choisissez **Deploy API**.

1. Pour **Étape**, sélectionnez **Nouvelle étape**.

1. Sous **Stage name (Nom de l’étape)**, entrez **alpha**.

1. (Facultatif) Sous **Description**, entrez une description.

1. Choisissez **Déployer**.

**Pour tester votre déploiement**

1. Sur la page **Stages** de***StartExecutionAPI***, développez **alpha**,**/**, **/execution**, **POST**, puis choisissez la méthode **POST**.

1. Sous **Method overrides**, choisissez l'icône de copie pour copier l'URL d'appel de votre API. L'URL complète doit ressembler à l'exemple suivant.

   ```
   https://a1b2c3d4e5.execute-api.region.amazonaws.com/alpha/execution
   ```

1. À partir de la ligne de commande, exécutez la commande `curl` à l'aide de l'ARN de votre machine d'état, puis appelez l'URL de votre déploiement, comme illustré dans l'exemple suivant :

   ```
   curl -X POST -d '{"input": "{}","name": "MyExecution","stateMachineArn": "arn:aws:states:region:123456789012:stateMachine:HelloWorld"}' https://a1b2c3d4e5.execute-api.region.amazonaws.com/alpha/execution
   ```

   L'ARN d'exécution et sa date d'époque sont renvoyés, comme illustré dans l'exemple suivant.

   ```
   {"executionArn":"arn:aws:states:region:123456789012:execution:HelloWorld:MyExecution","startDate":1.486772644911E9}
   ```
**Note**  
Si le message d'erreur « jeton d'authentification manquant » s'affiche, assurez-vous que l'URL d'appel se termine par **/execution**.