Comment puis-je utiliser API Gateway en tant que proxy pour un autre service AWS ?

Lecture de 12 minute(s)

Je veux utiliser Amazon API Gateway en tant que proxy pour un autre service AWS. Comment puis-je intégrer d'autres services à API Gateway ?

Brève description

Les API de service AWS sont essentiellement des API REST que vous pouvez adresser à une requête HTTPS. Vous pouvez intégrer de nombreux services AWS à API Gateway, mais la configuration et le mappage varient en fonction de l'API de service spécifique.

Pour intégrer un autre service à API Gateway, créez une demande HTTPS depuis API Gateway vers l'API de service afin que tous les paramètres de demande soient correctement mappés.

Cet article décrit un exemple de configuration pour intégrer l'API Publish d'Amazon Simple Notification Service (Amazon SNS) à API Gateway. Vous pouvez utiliser cet exemple comme aperçu pour intégrer d'autres services.

Résolution

Remarque : si vous recevez des erreurs lors de l'exécution de commandes de l'interface de la ligne de commande AWS (AWS CLI), assurez-vous d'utiliser la version la plus récente de l'AWS CLI.

Configuration des outils et ressources requis

Configurez votre environnement et créez toutes les ressources AWS requises pour votre cas d'utilisation. Pour l'exemple de configuration Amazon SNS, procédez comme suit :

Installez l'interface de ligne de commande AWS.
Créez une rubrique Amazon SNS. Notez l' Amazon Resource Name (ARN)de la rubrique. Vous aurez besoin de ces informations à l'étape suivante, ainsi qu'ultérieurement dans la configuration.
Créez un abonnement à la rubrique.
Ouvrez la console de gestion des identités et des accès AWS (AWS IAM), puis créez un rôle d'exécution de proxy de service AWS. Notez l'ARN du rôle pour plus tard dans la configuration. Ce rôle IAM donne à API Gateway des autorisations en tant qu'entité de confiance pour assumer le service et exécuter l'action API que vous intégrez. Pour l'exemple de configuration Amazon SNS, autorisez l'action sns:Publish. Pour plus d'informations, consultez Modèle d'autorisations API Gateway pour appeler une API.
Créez une API REST API Gateway avec une ressource de test. Pour plus d'informations et d'exemples, consultez les didacticiels et les ateliers d'Amazon API Gateway.
Remarque : vous pouvez éventuellement importer l'API REST à l'aide de l'exemple de définition OpenAPI 2.0 (Swagger) suivant. Cette option préconfigure les paramètres de l'exemple de configuration Amazon SNS. Vous pouvez ignorer la plupart des étapes de configuration de la console API Gateway ultérieurement. Assurez-vous de remplacer arn:aws:iam::account-id:role/apigateway-sns-role par l'ARN de votre rôle IAM. Remplacez région par la région AWS dans laquelle vous voulez créer votre API REST.

{
  "swagger": "2.0",
  "info": {
    "version": "2019-10-09T14:10:24Z",
    "title": "aws-service-integration"
  },
  "basePath": "/dev",
  "schemes": [
    "https"
  ],
  "paths": {
    "/test": {
      "post": {
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "Message",
            "in": "query",
            "required": true,
            "type": "string"
          },
          {
            "name": "topicArn",
            "in": "query",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "schema": {
              "$ref": "#/definitions/Empty"
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "credentials": "arn:aws:iam::account-id:role/apigateway-sns-role",
          "uri": "arn:aws:apigateway:region:sns:action/Publish",
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "requestParameters": {
            "integration.request.querystring.TopicArn": "method.request.querystring.topicArn",
            "integration.request.querystring.Message": "method.request.querystring.Message"
          },
          "passthroughBehavior": "when_no_match",
          "httpMethod": "POST",
          "type": "aws"
        }
      }
    }
  },
  "definitions": {
    "Empty": {
      "type": "object",
      "title": "Empty Schema"
    }
  }
}

Obtenir un exemple de demande HTTPS

Un exemple de demande HTTPS provenant de l'API de service que vous intégrez peut vous aider à mapper correctement les paramètres de demande dans API Gateway. Pour obtenir un exemple de demande HTTPS, effectuez l'une des actions suivantes :

Retrouvez-le dans la documentation AWS

Consultez des exemples dans la documentation de l'API. Pour l'API Publish d'Amazon SNS, vous pouvez consulter la référence d'API du service pour obtenir un exemple de demande :

https://sns.us-west-2.amazonaws.com/?Action=Publish
&TargetArn=arn%3Aaws%3Asns%3Aus-west-2%3A803981987763%3Aendpoint%2FAPNS_SANDBOX%2Fpushapp%2F98e9ced9-f136-3893-9d60-776547eafebb
&Message=%7B%22default%22%3A%22This+is+the+default+Message%22%2C%22APNS_SANDBOX%22%3A%22%7B+%5C%22aps%5C%22+%3A+%7B+%5C%22alert%5C%22+%3A+%5C%22You+have+got+email.%5C%22%2C+%5C%22badge%5C%22+%3A+9%2C%5C%22sound%5C%22+%3A%5C%22default%5C%22%7D%7D%22%7D
&Version=2010-03-31
&AUTHPARAMS

Générez-le à partir d'un appel d'API

Utilisez l'interface de ligne de commande AWS pour appeler l'API de service, puis analysez la sortie. Déterminez la commande de l'interface de ligne de commande AWS correspondante pour l'API de service que vous intégrez, puis exécutez une demande de test avec l'option --debug.

Conseil : consultez la Référence des commandes de l'AWS CLI pour trouver la commande de l'AWS CLI correspondante.

Pour l'exemple de configuration Amazon SNS, exécutez la commande suivante :

Remarque : Remplacez arn:aws:sns:us-east-1:123456789012:test par l'ARN de votre rubrique Amazon SNS.

$ aws sns publish --topic-arn arn:aws:sns:us-east-1:123456789012:test --message "hi" --debug

La sortie de la commande contient la demande HTTPS et les en-têtes qui sont transmis. Voici un exemple de ce qu'il faut rechercher :

2018-11-22 11:56:39,647 - MainThread - botocore.client - DEBUG - Registering retry handlers for service: sns
2018-11-22 11:56:39,648 - MainThread - botocore.hooks - DEBUG - Event before-parameter-build.sns.Publish: calling handler <function generate_idempotent_uuid at 0x11093d320>
2018-11-22 11:56:39,649 - MainThread - botocore.endpoint - DEBUG - Making request for OperationModel(name=Publish) (verify_ssl=True) with params: {'body': {'Action': u'Publish', u'Message': u'hello', 'Version': u'2010-03-31', u'TopicArn': u'arn:aws:sns:us-east-1:123456789012:test'}, 'url': u'https://sns.us-east-1.amazonaws.com/', 'headers': {'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8', 'User-Agent': 'aws-cli/1.15.74 Python/2.7.14 Darwin/16.7.0 botocore/1.9.23'}, 'context': {'auth_type': None, 'client_region': 'us-east-1', 'has_streaming_input': False, 'client_config': <botocore.config.Config object at 0x1118437d0>}, 'query_string': '', 'url_path': '/', 'method': u'POST'}
2018-11-22 11:56:39,650 - MainThread - botocore.hooks - DEBUG - Event request-created.sns.Publish: calling handler <bound method RequestSigner.handler of <botocore.signers.RequestSigner object at 0x111843750>>
2018-11-22 11:56:39,650 - MainThread - botocore.hooks - DEBUG - Event choose-signer.sns.Publish: calling handler <function set_operation_specific_signer at 0x11093d230>
2018-11-22 11:56:39,650 - MainThread - botocore.auth - DEBUG - Calculating signature using v4 auth.
2018-11-22 11:56:39,651 - MainThread - botocore.auth - DEBUG - CanonicalRequest:
POST
/

content-type:application/x-www-form-urlencoded; charset=utf-8
host:sns.us-east-1.amazonaws.com
x-amz-date:20181122T062639Z

content-type;host;x-amz-date

Dans cet exemple, la demande est envoyée en tant que méthode HTTP POST.

Création d'une méthode pour votre API API Gateway

Dans la console API Gateway, dans le panneau API, choisissez le nom de votre API.
Dans le volet Resources choisissez une ressource. Pour l'exemple de configuration Amazon SNS, choisissez la ressource de test que vous avez créée.
Choisissez Actions, puis Create Method (Créer une méthode).
Dans la liste déroulante, choisissez la méthode utilisée par votre API de service dans l'exemple de demande HTTPS. (Pour l'exemple de configuration Amazon SNS, choisissez POST.) Ensuite, choisissez l'icône de coche.
Dans le volet Setup procédez comme suit :
Pour Integration type (Type d'intégration), choisissez AWS Service.
Pour AWS Region, choisissez la région AWS de la ressource associée à l'API de service que vous intégrez. Pour l'exemple de configuration Amazon SNS, choisissez la région de votre rubrique SNS.
Pour AWS Service, choisissez le service que vous intégrez à API Gateway. Par exemple, Simple Notification Service (SNS).
(Facultatif) Pour AWS Subdomain, entrez le sous-domaine utilisé par le service AWS. Consultez la documentation du service pour confirmer la disponibilité d'un sous-domaine. Pour l'exemple de configuration Amazon SNS, laissez le champ vide.
Pour HTTP method, (Méthode HTTP), choisissez la méthode qui correspond à l'API de service AWS que vous intégrez. Pour l'exemple de configuration Amazon SNS, choisissez POST.
Pour Action Type (Type d'action), si l'API de service que vous intégrez est une action prise en charge, choisissez Use action name (Utiliser le nom de l'action). (Consultez la Référence de l'API de service pour obtenir la liste des actions prises en charge. Pour Amazon SNS, consultez Actions (Actions) dans.) Pour Action, saisissez le nom de l'API de service. Pour l'exemple de configuration Amazon SNS, saisissez Publish (Publier).
-ou-
Pour Action Type (Type d'action), si l'API de service AWS attend un chemin d'accès aux ressources dans votre demande, choisissez Use path override (Utiliser le remplacement du chemin). Par exemple, pour l'API Amazon Polly ListLexicons saisissez /v1/lexicons pour Path override (optional) (Remplacement du chemin (facultatif)).
Pour Execution role (Rôle d'exécution), entrez l'ARN du rôle IAM que vous avez créé.
(Facultatif) Pour Content Handling et Use Default Timeout, apportez les modifications nécessaires à votre cas d'utilisation. Pour l'exemple de configuration Amazon SNS, ne modifiez pas ces paramètres.
Choisissez Save (Enregistrer).

Créer des paramètres pour la demande de méthode

Déterminez les paramètres de demande requis et facultatifs pour l'API de service que vous intégrez. Pour identifier ces paramètres, reportez-vous à l'exemple de demande HTTPS que vous avez obtenu précédemment ou reportez-vous à la Référence d'API pour l'API de service. Par exemple, consultez Publier.

Dans la console API Gateway, dans le panneau Method Execution (Exécution de méthode) de la méthode de votre API API Gateway, choisissez Method Request (demande de méthode).
(Facultatif) Dans le panneau Method Request (demande de méthode), pour Request Validator (Validateur de demande), choisissez un validateur de demande, le corps et les en-têtes si vous voulez valider les paramètres de la chaîne de requête.
Développez URL Query String Parameters (Paramètres de la chaîne de requête de l'URL).
Choisissez Add query string (Ajouter une chaîne de requête).
Pour Name (Nom), entrez le nom d'un paramètre de demande pour l'API de service que vous intégrez.
Choisissez l'icône de coche (Create a new query string).
Si le paramètre est obligatoire, cochez la case sous Required.
Répétez les étapes 4 à 7 pour tous les paramètres de demande que vous souhaitez inclure. Pour l'exemple de configuration Amazon SNS, créez un paramètre nommé TopicArn et un autre nommé Message.

Pour plus d'informations, consultez Configuration d'une méthode à l'aide de la console API Gateway.

Remarque : pour certaines API de service, vous devez envoyer les en-têtes requis et un corps dans la demande d'intégration en plus des paramètres requis. Vous pouvez créer les en-têtes et le corps dans le panneau Integration Request (Demande d'intégration) sous HTTP Request Headers (En-têtes de la demande HTTP) and Request Body (Corps de la demande).

Par exemple, si vous intégrez l'API Amazon Rekognition ListCollections, créez l'en-tête X-Amz-Target : RekognitionService.ListCollections. La demande ressemble à ceci :

POST https://rekognition.us-west-2.amazonaws.com/ HTTP/1.1
    Host: rekognition.us-west-2.amazonaws.com
    Accept-Encoding: identity
    Content-Length: 2
    X-Amz-Target: RekognitionService.ListCollections
    X-Amz-Date: 20170105T155800Z
    User-Agent: aws-cli/1.11.25 Python/2.7.9 Windows/8 botocore/1.4.82
    Content-Type: application/x-amz-json-1.1
    Authorization: AWS4-HMAC-SHA256 Credential=XXXXXXXX/20170105/us-west-2/rekognition/aws4_request,
      SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=XXXXXXXX

    {}

Si vous intégrez l'API Amazon Simple Queue Service (Amazon SQS) SendMessage, vous pouvez mapper le corps de la demande à l'aide l'expression de mappage method.request.body.JSONPath_EXPRESSION. (Remplacez JSONPath_EXPRESSION par une expression JSONPath pour un champ JSON du corps de la demande.) Dans cet exemple, une demande ressemble à ceci :

{'url_path': '/', 'query_string': '', 'method': 'POST',
'headers': {'Content-Type': 'application/x-www-form-urlencoded; 
charset=utf-8', 'User-Agent': 'aws-cli/1.16.81 Python/3.6.5 Darwin/18.7.0 botocore/1.12.183'}, 
'body': {'Action': 'SendMessage', 'Version': '2012-11-05', 'QueueUrl': 'https://sqs.ap-southeast-2.amazonaws.com/123456789012/test01', 'MessageBody': 'Hello'}, 
'url': 'https://ap-southeast-2.queue.amazonaws.com/', 'context': {'client_region': 'ap-southeast-2', 'client_config': <botocore.config.Config object at 0x106862da0>, 'has_streaming_input': False, 'auth_type': None}}

Créer des paramètres pour la demande d'intégration

Mappez les paramètres que vous avez créés pour la demande de méthode aux paramètres de la demande d'intégration.

Dans la console API Gateway, revenez au volet Method Execution correspondant à la méthode de votre API API Gateway, puis choisissez Integration Request.
Dans le volet Integration Request développez URL Query String Parameters.
Choisissez Add query string (Ajouter une chaîne de requête).
Pour Name (Nom), entrez le nom d'un paramètre de demande pour l'API de service que vous intégrez.
Remarque : le nom est sensible à la casse et doit apparaître exactement comme prévu par l'API de service.
Pour Mapped from (Mappé à partir de), saisissez method.request.querystring.param_name. Remplacez param_name par le nom du paramètre correspondant que vous avez créé pour la demande de méthode. Par exemple, method.request.querystring.TopicArn.
Choisissez l'icône de coche (Create) (Créer).
Répétez les étapes 3 à 6 pour créer des paramètres pour la demande d'intégration qui correspondent à chacun des paramètres que vous avez créés pour la demande de méthode.

Remarque : Si vous avez créé des en-têtes obligatoires et un corps pour la demande de méthode, mappez-les également à la demande d'intégration. Créez-les dans le volet Integration Request sous HTTP Headers and Mapping Templates.

Pour plus d'informations, consultez Configuration d'une demande d'intégration d'API à l'aide de la console API Gateway.

(Facultatif) Vérification de votre configuration d'intégration

Pour confirmer que votre configuration d'intégration est conforme à vos attentes, vous pouvez exécuter la commande get-integration de l'AWS CLI pour vérifier la configuration de manière similaire à ce qui suit :

$ aws apigateway get-integration --rest-api-id 1234123412 --resource-id y9h6rt --http-method POST

Pour l'exemple de configuration Amazon SNS, la sortie ressemble à ceci :

{
    "integrationResponses": {
        "200": {
            "responseTemplates": {
                "application/json": null
            },
            "statusCode": "200"
        }
    },
    "passthroughBehavior": "WHEN_NO_MATCH",
    "timeoutInMillis": 29000,
    "uri": "arn:aws:apigateway:us-east-2:sns:action/Publish",
    "httpMethod": "POST",
    "cacheNamespace": "y9h6rt",
    "credentials": "arn:aws:iam::1234567890:role/apigateway-sns-role",
    "type": "AWS",
    "requestParameters": {
        "integration.request.querystring.TopicArn": "method.request.querystring.topicArn",
        "integration.request.querystring.Message": "method.request.querystring.Message"
    },
    "cacheKeyParameters": []
}

Tester votre configuration

Dans la console API Gateway, revenez au panneau Method Execution (Exécution de méthode) correspondant à la méthode de votre API API Gateway, puis choisissez TEST (TESTER).
Dans le volet Method Test procédez comme suit :
Pour Query Strings, (Chaînes de requête), saisissez une chaîne de requête qui inclut les paramètres et les valeurs de la demande. Pour l'exemple de configuration Amazon SNS, saisissez TopicArn= arn:aws:sns:us-east-1:123456789012:test&Message="Hello". Remplacez arn:aws:sns:us-east-1:123456789012:test par l'ARN de votre rubrique Amazon SNS.
Pour Headers (En-têtes) et Request Body (Corps de la demande), si vous les avez créés pour votre configuration, saisissez les noms d'en-tête et le corps de la demande JSON.
Choisissez Test. Une réponse s'affiche dans le volet Method Test. Si la réponse aboutit, vous voyez Status: 200. Pour la configuration de l'exemple Amazon SNS, une réponse positive inclut un MessageId dans le corps de la réponse.
Pour plus d'informations, consultez Utilisation de la console API Gateway pour tester une méthode d'API REST.
Déployez votre API REST.
Testez votre API à l'aide de l'outil de votre choix.