Configuration de transformations de données dans API Gateway - Amazon API Gateway

Configuration de transformations de données dans API Gateway

Cette section explique comment configurer des modèles de mappage pour transformer les demandes et réponses d’intégration à l’aide de la console et de l’interface de ligne de commande AWS.

Configuration d’une transformation de données à l’aide de la console API Gateway

Dans ce didacticiel, vous allez créer une API incomplète et une table DynamoDB à l’aide du fichier .zip data-transformation-tutorial-console.zip suivant. Cette API incomplète possède une ressource /pets avec les méthodes GET et POST.

  • La méthode GET obtiendra des données à partir du point de terminaison HTTP http://petstore-demo-endpoint.execute-api.com/petstore/pets. Les données de sortie seront transformées conformément au modèle de mappage figurant dans Modèle de mappage PetStore.

  • La méthode POST permettra à l’utilisateur de publier (POST) les informations sur les animaux dans une table Amazon DynamoDB à l’aide d’un modèle de mappage.

Téléchargez et décompressez le modèle de création d’application pour AWS CloudFormation. Vous allez utiliser ce modèle pour créer une table DynamoDB afin de publier les informations sur les animaux et une API incomplète. Vous terminerez les étapes restantes dans la console API Gateway.

Pour créer une pile AWS CloudFormation
  1. Ouvrez la console AWS CloudFormation, à l’adresse https://console.aws.amazon.com/cloudformation.

  2. Choisissez Créer une pile, puis choisissez Avec de nouvelles ressources (standard).

  3. Dans Spécifier le modèle, choisissez Charger un modèle de fichier.

  4. Sélectionnez le modèle que vous avez téléchargé.

  5. Choisissez Suivant.

  6. Pour Nom de la pile, saisissez data-transformation-tutorial-console, puis choisissez Suivant.

  7. Pour Configurer les options de pile, choisissez Suivant.

  8. Pour Capacités, sachez que AWS CloudFormation peut créer des ressources IAM dans votre compte.

  9. Sélectionnez Envoyer.

AWS CloudFormation fournit les ressources spécifiées dans le modèle. La fin du provisionnement de vos ressources peut prendre quelques minutes. Lorsque le statut de votre pile AWS CloudFormation est CREATE_COMPLETE, vous êtes prêt à passer à l’étape suivante.

Pour tester la réponse d’intégration GET
  1. Dans l’onglet Ressources de la pile AWS CloudFormation pour data-transformation-tutorial-console, sélectionnez l’ID physique de votre API.

  2. Dans le volet de navigation principal, choisissez Ressources, puis sélectionnez la méthode GET.

  3. Choisissez l’onglet Test. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.

    La sortie du test affichera les informations suivantes :

    [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ]

    Vous allez transformer cette sortie conformément au modèle de mappage figurant dans Modèle de mappage PetStore.

Pour transformer la réponse d’intégration GET
  1. Choisissez l’onglet Réponse d’intégration.

    Aucun modèle de mappage n’est actuellement défini, de sorte que la réponse d’intégration ne sera pas transformée.

  2. Pour Par défaut - Réponse, choisissez Modifier.

  3. Choisissez Modèles de mappage, puis procédez comme suit :

    1. Sélectionnez Add mapping template.

    2. Pour Type de contenu, entrez application/json.

    3. Pour Corps du modèle, saisissez ce qui suit :

      #set($inputRoot = $input.path('$')) [ #foreach($elem in $inputRoot) { "description" : "Item $elem.id is a $elem.type.", "askingPrice" : $elem.price }#if($foreach.hasNext),#end #end ]

    Choisissez Enregistrer.

Pour tester la réponse d’intégration GET
  • Choisissez l’onglet Tester, puis choisissez Tester.

    La sortie du test affichera la réponse transformée.

    [ { "description" : "Item 1 is a dog.", "askingPrice" : 249.99 }, { "description" : "Item 2 is a cat.", "askingPrice" : 124.99 }, { "description" : "Item 3 is a fish.", "askingPrice" : 0.99 } ]
Pour transformer les données d’entrée issues de la méthode POST
  1. Choisissez la méthode POST.

  2. Choisissez l’onglet Requête d’intégration, puis dans la section Paramètres de requête d’intégration, choisissez Modifier.

    Le modèle AWS CloudFormation a renseigné certains champs de demande d’intégration.

    • Le type d’intégration est Service AWS.

    • Le Service AWS est DynamoDB.

    • La méthode HTTP est POST.

    • L’action est PutItem.

    • Le rôle d’exécution permettant à API Gateway de placer un élément dans la table DynamoDB est data-transformation-tutorial-console-APIGatewayRole. AWS CloudFormation a créé ce rôle pour permettre à API Gateway de disposer des autorisations minimales nécessaires pour interagir avec DynamoDB.

    Le nom de la table DynamoDB n’a pas été spécifié. Vous allez spécifier ce nom dans les étapes suivantes.

  3. Pour Transmission du corps de requête, sélectionnez Jamais.

    Cela signifie que l’API rejettera les données avec des types de contenu qui ne disposent pas d’un modèle de mappage.

  4. Choisissez Modèles de mappage.

  5. Type de contenu est défini sur application/json. Cela signifie que tous les types de contenu autres qu’application/json seront rejetés par l’API. Pour plus d’informations sur les comportements de transmission d’intégration, consultez Comportements de transfert direct.

  6. Saisissez le code suivant dans l’éditeur de texte.

    { "TableName":"data-transformation-tutorial-console-ddb", "Item": { "id": { "N": $input.json("$.id") }, "type": { "S": $input.json("$.type") }, "price": { "N": $input.json("$.price") } } }

    Ce modèle spécifie la table en tant que data-transformation-tutorial-console-ddb et définit les éléments en tant que idtype et price. Ces éléments proviennent du corps de la méthode POST. Vous pouvez également utiliser un modèle de données pour favoriser la création d’un modèle de mappage. Pour en savoir plus, consultez Validation des demandes pour les API REST dans API Gateway.

  7. Choisissez Enregistrer pour enregistrer votre modèle de mappage.

Pour ajouter une réponse de méthode et d’intégration à partir de la méthode POST

AWS CloudFormation a créé une réponse de méthode et d’intégration vide. Vous allez modifier cette réponse pour fournir plus d’informations. Pour plus d’informations sur la façon de modifier des réponses, consultez Guide de référence du mappage des données de demande d’API et de réponse Amazon API Gateway.

  1. Dans l’onglet Réponse d’intégration, pour Par défaut - Réponse, choisissez Modifier.

  2. Choisissez Modèles de mappage, puis choisissez Ajouter un modèle de mappage.

  3. Pour Type de contenu, saisissez application/json.

  4. Dans l’éditeur de code, entrez le modèle de mappage de sortie suivant pour envoyer un message de sortie :

    { "message" : "Your response was recorded at $context.requestTime" }

    Pour plus d’informations sur les variables de contexte, consultez Variables $context pour les modèles de données, les mécanismes d’autorisation, les modèles de mappage et la journalisation des accès de CloudWatch..

  5. Choisissez Enregistrer pour enregistrer votre modèle de mappage.

Test de la méthode POST

Choisissez l’onglet Test. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.

  1. Dans le corps de la demande, entrez l’exemple suivant.

    { "id": "4", "type" : "dog", "price": "321" }
  2. Sélectionnez Test (Tester).

    La sortie doit afficher votre message de réussite.

    Vous pouvez ouvrir la console DynamoDB à l’adresse https://console.aws.amazon.com/dynamodb/ pour vérifier que l’exemple d’élément figure dans votre table.

Pour supprimer une pile AWS CloudFormation
  1. Ouvrez la console AWS CloudFormation, à l’adresse https://console.aws.amazon.com/cloudformation.

  2. Sélectionnez votre pile AWS CloudFormation.

  3. Choisissez Supprimer, puis confirmez votre choix.

Configuration de la transformation des données à l’aide de l’interface de ligne de commande AWS

Dans ce didacticiel, vous allez créer une API incomplète et une table DynamoDB à l’aide du fichier .zip data-transformation-tutorial-cli.zip suivant. Cette API incomplète possède une ressource /pets avec une méthode GET intégrée au point de terminaison HTTP http://petstore-demo-endpoint.execute-api.com/petstore/pets. Vous allez créer une méthode POST pour vous connecter à une table DynamoDB et utiliser des modèles de mappage pour entrer des données dans une table DynamoDB.

  • Vous allez transformer les données de sortie conformément au modèle de mappage figurant dans Modèle de mappage PetStore.

  • Vous allez créer une méthode POST pour permettre à l’utilisateur de publier (POST) les informations sur les animaux dans une table Amazon DynamoDB à l’aide d’un modèle de mappage.

Pour créer une pile AWS CloudFormation

Téléchargez et décompressez le modèle de création d’application pour AWS CloudFormation.

Pour effectuer le didacticiel suivant, vous avez besoin de l’AWS Command Line Interface (AWS CLI) version 2.

Pour les commandes longues, un caractère d’échappement (\) est utilisé pour les fractionner en plusieurs lignes.

Note

Dans Windows, certaines commandes CLI Bash que vous utilisez couramment (par exemple zip) ne sont pas prises en charge par les terminaux intégrés du système d’exploitation. Installez le sous-système Windows pour Linux afin d’obtenir une version intégrée à Windows d’Ubuntu et Bash. Les exemples de commandes CLI de ce guide utilisent le formatage Linux. Les commandes qui incluent des documents JSON en ligne doivent être reformatées si vous utilisez la CLI Windows.

  1. Utilisez la commande suivante pour créer la pile AWS CloudFormation.

    aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
  2. AWS CloudFormation fournit les ressources spécifiées dans le modèle. La fin du provisionnement de vos ressources peut prendre quelques minutes. Utilisez la commande suivante pour voir le statut de votre pile AWS CloudFormation.

    aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli
  3. Lorsque le statut de votre pile AWS CloudFormation est StackStatus: "CREATE_COMPLETE", utilisez la commande suivante pour récupérer les valeurs de sortie pertinentes pour les étapes à venir.

    aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"

    Les valeurs de sortie sont les suivantes :

    • ApiRole, qui est le nom du rôle qui permet à API Gateway de placer des éléments dans la table DynamoDB. Pour ce didacticiel, le nom du rôle est data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG.

    • DDBTableName, qui est le nom de la table DynamoDB. Pour ce didacticiel, le nom de la table est data-transformation-tutorial-cli-ddb.

    • ResourceId, qui est l’ID de la ressource des animaux de compagnie où les méthodes GET et POST sont exposées. Pour ce didacticiel, l’ID de ressource est efg456.

    • ApiId, qui est l’ID de l’API. Pour ce didacticiel, l’ID d’API est abc123.

Pour tester la méthode GET avant la transformation des données
  • Utilisez la commande suivante pour tester la méthode GET.

    aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET

    La sortie du test affichera les informations suivantes.

    [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ]

    Vous allez transformer cette sortie conformément au modèle de mappage figurant dans Modèle de mappage PetStore.

Pour transformer la réponse d’intégration GET
  • Utilisez la commande suivante pour mettre à jour la réponse d’intégration de la méthode GET. Remplacez rest-api-id et resource-id par vos valeurs.

    Utilisez la commande suivante pour créer la réponse d’intégration.

    aws apigateway put-integration-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ --status-code 200 \ --selection-pattern "" \ --response-templates '{"application/json": "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"}'
Pour tester la méthode GET
  • Utilisez la commande suivante pour tester la méthode GET.

    aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \

    La sortie du test affichera la réponse transformée.

    [ { "description" : "Item 1 is a dog.", "askingPrice" : 249.99 }, { "description" : "Item 2 is a cat.", "askingPrice" : 124.99 }, { "description" : "Item 3 is a fish.", "askingPrice" : 0.99 } ]
Pour créer une méthode POST
  1. Utilisez la commande suivante pour créer une nouvelle méthode sur la ressource /pets.

    aws apigateway put-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --authorization-type "NONE" \

    Cette méthode vous permet d’envoyer des informations sur les animaux de compagnie à la table DynamoDB que vous avez créée dans la pile AWS CloudFormation.

  2. Utilisez la commande suivante pour créer une intégration de Service AWS sur la méthode POST.

    aws apigateway put-integration --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --type AWS \ --integration-http-method POST \ --uri "arn:aws:apigateway:us-east-2:dynamodb:action/PutItem" \ --credentials arn:aws:iam::111122223333:role/data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG \ --request-templates '{"application/json":"{\"TableName\":\"data-transformation-tutorial-cli-ddb\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"}'
  3. Utilisez la commande suivante pour créer une réponse de méthode pour un appel réussi de la méthode POST.

    aws apigateway put-method-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --status-code 200
  4. Utilisez la commande suivante pour créer une réponse d’intégration pour l’appel réussi de la méthode POST.

    aws apigateway put-integration-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --status-code 200 \ --selection-pattern "" \ --response-templates '{"application/json": "{\"message\": \"Your response was recorded at $context.requestTime\"}"}'
Pour tester la méthode POST
  • Utilisez la commande suivante pour tester la méthode POST.

    aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}'

    La sortie affichera le message de réussite.

Pour supprimer une pile AWS CloudFormation
  • Utilisez la commande suivante pour supprimer vos ressources AWS CloudFormation.

    aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli

Modèle AWS CloudFormation de transformation de données terminé

L’exemple suivant est un modèle AWS CloudFormation terminé qui crée une API et une table DynamoDB avec une ressource /pets à l’aide des méthodes GET et POST.

  • La méthode GET obtiendra des données à partir du point de terminaison HTTP http://petstore-demo-endpoint.execute-api.com/petstore/pets. Les données de sortie seront transformées conformément au modèle de mappage figurant dans Modèle de mappage PetStore.

  • La méthode POST permettra à l’utilisateur de publier (POST) les informations sur les animaux de compagnie dans une table DynamoDB à l’aide d’un modèle de mappage.

AWSTemplateFormatVersion: 2010-09-09 Description: A completed Amazon API Gateway REST API that uses non-proxy integration to POST to an Amazon DynamoDB table and non-proxy integration to GET transformed pets data. Parameters: StageName: Type: String Default: v1 Description: Name of API stage. Resources: DynamoDBTable: Type: 'AWS::DynamoDB::Table' Properties: TableName: !Sub data-transformation-tutorial-complete AttributeDefinitions: - AttributeName: id AttributeType: N KeySchema: - AttributeName: id KeyType: HASH ProvisionedThroughput: ReadCapacityUnits: 5 WriteCapacityUnits: 5 APIGatewayRole: Type: 'AWS::IAM::Role' Properties: AssumeRolePolicyDocument: Version: 2012-10-17 Statement: - Action: - 'sts:AssumeRole' Effect: Allow Principal: Service: - apigateway.amazonaws.com Policies: - PolicyName: APIGatewayDynamoDBPolicy PolicyDocument: Version: 2012-10-17 Statement: - Effect: Allow Action: - 'dynamodb:PutItem' Resource: !GetAtt DynamoDBTable.Arn Api: Type: 'AWS::ApiGateway::RestApi' Properties: Name: data-transformation-complete-api ApiKeySourceType: HEADER PetsResource: Type: 'AWS::ApiGateway::Resource' Properties: RestApiId: !Ref Api ParentId: !GetAtt Api.RootResourceId PathPart: 'pets' PetsMethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref PetsResource HttpMethod: GET ApiKeyRequired: false AuthorizationType: NONE Integration: Type: HTTP Credentials: !GetAtt APIGatewayRole.Arn IntegrationHttpMethod: GET Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/ PassthroughBehavior: WHEN_NO_TEMPLATES IntegrationResponses: - StatusCode: '200' ResponseTemplates: application/json: "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]" MethodResponses: - StatusCode: '200' PetsMethodPost: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref PetsResource HttpMethod: POST ApiKeyRequired: false AuthorizationType: NONE Integration: Type: AWS Credentials: !GetAtt APIGatewayRole.Arn IntegrationHttpMethod: POST Uri: arn:aws:apigateway:us-west-1:dynamodb:action/PutItem PassthroughBehavior: NEVER RequestTemplates: application/json: "{\"TableName\":\"data-transformation-tutorial-complete\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}" IntegrationResponses: - StatusCode: 200 ResponseTemplates: application/json: "{\"message\": \"Your response was recorded at $context.requestTime\"}" MethodResponses: - StatusCode: '200' ApiDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: - PetsMethodGet Properties: RestApiId: !Ref Api StageName: !Sub '${StageName}' Outputs: ApiId: Description: API ID for CLI commands Value: !Ref Api ResourceId: Description: /pets resource ID for CLI commands Value: !Ref PetsResource ApiRole: Description: Role ID to allow API Gateway to put and scan items in DynamoDB table Value: !Ref APIGatewayRole DDBTableName: Description: DynamoDB table name Value: !Ref DynamoDBTable

Étapes suivantes

Pour explorer des modèles de mappage plus complexes, consultez les exemples suivants :