Comment utiliser API Gateway comme proxy pour un autre service AWS ?

Date de la dernière mise à jour : 16/04/2020

Je souhaite utiliser Amazon API Gateway comme proxy pour un autre service AWS. Comment intégrer d'autres services à API Gateway ?

Courte 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.

Solution

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 :

  1. Installez l'interface de ligne de commande AWS (AWS CLI).
  2. 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.
  3. Créez un abonnement à la rubrique.
  4. 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 AWS Identity and Access Management (IAM) accorde à API Gateway des autorisations en tant qu'entité approuvée pour assumer le service et effectuer l'action d'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.
  5. Créez une API REST API Gateway avec une ressourcede test. Pour plus d'informations et d'exemples, consultez les didacticiels 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 pour la configuration de l'exemple Amazon SNS, afin que vous puissiez ignorer la plupart des étapes de configuration de la console API Gateway ultérieurement. Veillez à 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 souhaitez 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 .

Astuce : Consultez la Référence des commandes de l'interface de ligne de commande AWS pour trouver la commande de l'interface de ligne de commande AWS 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

  1. Dans la console API Gateway, dans le volet APIs, choisissez le nom de votre API
  2. Dans le volet Resources choisissez une ressource. Pour l'exemple de configuration Amazon SNS, choisissez la ressource de test que vous avez créée.
  3. Choisissez Actions, puis Create Method (Créer une méthode).
  4. 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.
  5. 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, si l'API de service que vous intégrez est une action prise en charge, choisissez Use action name. (Consultez la Référence d'API du service pour obtenir la liste des actions prises en charge. Pour Amazon SNS, consultez Actions dans la Référence d'API.) Pour Action, entrez le nom de l'API de service. Pour l'exemple de configuration Amazon SNS, entrez Publish.
    Ou, pour Action Type, si l'API de service AWS attend un chemin de ressource dans votre demande, choisissez Use path override. Par exemple, pour l'API Amazon Polly ListLexicons entrez /v1/lexicons pour Path override (optional).
    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.
  6. Sélectionnez Save (Enregistrer).

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

Déterminez les paramètres de demande obligatoires 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.

  1. Dans la console API Gateway, dans le volet Method Execution de la méthode de votre API API Gateway, choisissez Method Request.
  2. (Facultatif) Dans le volet Method Request pour Request Validator, choisissez un valideur de demande si vous souhaitez valider les paramètres de chaîne de requête (ainsi qu'un corps et des en-têtes de demande).
  3. Développez URL Query String Parameters.
  4. Choisissez Add query string (Ajouter une chaîne de requête).
  5. Pour Name (Nom), entrez le nom d'un paramètre de demande pour l'API de service que vous intégrez.
  6. Choisissez l'icône de coche (Create a new query string).
  7. Si le paramètre est obligatoire, cochez la case sous Required.
  8. 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. Si elles sont requises pour l'API de service que vous intégrez, créez-les dans le volet Integration Request sous HTTP Request Headers and Request Body.

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

    {}

Autre exemple, si vous intégrez l'API SendMessage Amazon Simple Queue Service (Amazon SQS), vous pouvez mapper le corps de la demande à l'aide de 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.

  1. Dans la console API Gateway, revenez au volet Method Execution correspondant à la méthode de votre API API Gateway, puis choisissez Integration Request.
  2. Dans le volet Integration Request développez URL Query String Parameters.
  3. Choisissez Add query string (Ajouter une chaîne de requête).
  4. 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.
  5. Pour Mapped from, entrez method.request.querystring.param_name, en remplaçant 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.
  6. Choisissez l'icône de coche (Create) (Créer).
  7. 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 ressemble à vos attentes, vous pouvez exécuter la commande get-integration de l'interface de ligne de commande AWS pour vérifier la configuration. Par exemple :

$ 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": []
}

Testez votre configuration

  1. Dans la console API Gateway, revenez au volet Method Execution correspondant à la méthode de votre API API Gateway, puis choisissez TEST.
  2. Dans le volet Method Test procédez comme suit :
    Pour Query Strings, (Chaînes de requête), entrez une chaîne de requête qui inclut les paramètres et les valeurs de la demande. Pour l'exemple de configuration Amazon SNS, entrez TopicArn= arn:aws:sns:us-east-1:123456789012:test&Message="Hello", en remplaçant arn:aws:sns:us-east-1:123456789012:test avec l'ARN de votre rubrique Amazon SNS.
    Pour Headers et Request Body, si vous les avez créés pour votre configuration, entrez 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.
  3. Déployez votre API REST.
  4. Testez votre API à l'aide de l'outil de votre choix.