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

Lecture de 12 minute(s)

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

Brève description

Les API de service AWS sont essentiellement des API REST auxquelles vous pouvez envoyer une demande HTTPS. Vous pouvez intégrer de nombreux services AWS à API Gateway, mais la configuration et le mappage varient en fonction de chaque API de service.

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

Cet article décrit un exemple de configuration permettant d’intégrer l’API Publish d’Amazon Simple Notiﬁcation Service (Amazon SNS) à API Gateway. Appuyez-vous sur cet exemple pour intégrer d’autres services.

Résolution

Remarque : si des erreurs surviennent lors de l’exécution des commandes de l’Interface de la ligne de commande AWS (AWS CLI), vérifiez que vous utilisez la version la plus récente d’AWS CLI.

Configurer les outils et les ressources obligatoires

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

Installez AWS CLI.
Créez une rubrique Amazon SNS. Notez l’Amazon Resource Name (ARN) de la rubrique. Cette information vous servira à l’étape suivante et ultérieurement dans cette configuration.
Créez un abonnement à la rubrique.
Ouvrez la console de gestion des identités et des accès AWS (IAM), puis créez un rôle d’exécution de proxy de service AWS. Notez l’ARN du rôle, car vous en aurez besoin dans la suite de la configuration. Ce rôle IAM autorise API Gateway à assumer le service et à exécuter l’action d’API que vous intégrez en tant qu’entité de confiance. Pour l’exemple de configuration d’Amazon SNS, autorisez l’action sns:Publish. Pour en savoir plus, consultez la page Modèle d’autorisations API Gateway pour appeler une API.
Créez une API REST API Gateway avec une ressource test. Pour en savoir plus et obtenir davantage d’exemples, consultez les didacticiels et ateliers 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édéfinit les paramètres pour l’exemple de configuration d’Amazon SNS. Veillez à remplacer arn:aws:iam::account-id:role/apigateway-sns-role par l’ARN de votre rôle IAM. Remplacez la 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 requête dans API Gateway. Pour obtenir un exemple de demande HTTPS, effectuez l’une des opérations suivantes :

Vous trouverez des exemples dans la documentation de l’API. Pour l’API Publish d’Amazon SNS, vous pouvez consulter la référence de l’API de service afin d’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

- ou -

Générez-le à partir d’un appel d’API. Utilisez AWS CLI pour appeler l’API de service, puis analysez le résultat. Déterminez la commande AWS CLI correspondante pour l’API de service que vous intégrez, puis exécutez une demande test avec l’option --debug.

Conseil : consultez la référence des commandes AWS CLI pour trouver la commande AWS CLI correspondante.

Pour l’exemple de configuration d’Amazon SNS, exécutez cette commande :

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 commande contient la requête HTTPS et les en-têtes 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 requête est envoyée sous la forme d’une méthode HTTP POST.

Créer une méthode pour votre API API Gateway

Depuis la console API Gateway, dans le volet API choisissez le nom de votre API.
Dans le volet Ressources, sélectionnez une ressource. Pour l’exemple de configuration d’Amazon SNS, choisissez la ressource test que vous avez créée.
Choisissez Actions, puis choisissez 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 requête HTTPS. (Pour l’exemple de configuration d’Amazon SNS, choisissez POST.) Cliquez ensuite sur l’icône en forme de coche.
Dans le volet Configuration, procédez comme suit :
Pour le type d’intégration, choisissez AWS Service.
Pour le champ Région AWS, choisissez la région AWS de la ressource associée à l’API de service que vous intégrez. Pour l’exemple de configuration d’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 le champ Sous-domaine AWS, saisissez 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 d’Amazon SNS, laissez ce champ vide.
Pour la méthode HTTP, choisissez la méthode qui correspond à l’API du service AWS que vous intégrez. Pour l’exemple de configuration d’Amazon SNS, choisissez POST.
Pour le champ Type d’action, si l’API de service que vous intégrez est une action prise en charge, choisissez Utiliser un nom d’action. Consultez la référence d’API du service pour obtenir la liste des actions prises en charge. Pour Amazon SNS, consultez la section Actions.
Pour le champ Action, saisissez le nom de l’API de service. Pour l’exemple de configuration d’Amazon SNS, saisissez Publish.
-ou-
Pour le champ Type d’action, si l’API de service AWS attend un chemin de ressource dans votre requête, choisissez Utiliser un remplacement du chemin. Par exemple, pour l’API Amazon Polly ListLexicons, saisissez /v1/lexicons pour le champ Remplacement du chemin (facultatif).
Pour le champ Rôle d’exécution, saisissez l’ARN du rôle IAM que vous avez créé.
(Facultatif) Pour les champs Gestion de contenu et Utiliser le délai d’attente par défaut, apportez les modifications nécessaires en fonction de votre cas d’utilisation. Pour l’exemple de configuration d’Amazon SNS, ne modifiez pas ces paramètres.
Choisissez Enregistrer.

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

Identifiez les paramètres de demande obligatoires et facultatifs pour l’API de service que vous intégrez. Pour connaître ces paramètres, consultez l’exemple de demande HTTPS que vous avez reçu précédemment ou la référence d’API pour l’API de service. Pour obtenir un exemple, consultez la section Publish.

Depuis la console API Gateway, dans le volet Exécution de la méthode correspondant à la méthode de votre API API Gateway, sélectionnez Demande de méthode.
(Facultatif) Dans le volet Demande de méthode, pour le champ Validateur de demande, choisissez un validateur de demande, un corps et des en-têtes si vous souhaitez valider les paramètres de la chaîne de demande.
Développez la section Paramètres de chaîne de requête d’URL.
Choisissez Ajouter une chaîne de requête.
Dans le champ Nom, saisissez le nom d’un paramètre de demande pour l’API de service que vous intégrez.
Cliquez sur l’icône en forme de coche (Créer une nouvelle chaîne de requête).
Si le paramètre est obligatoire, cochez la case sous Obligatoire.
Répétez les étapes 4 à 7 pour tous les paramètres de demande que vous souhaitez inclure. Pour l’exemple de configuration d’Amazon SNS, créez un paramètre nommé T****opicArn et un autre nommé Message.

Pour en savoir plus, consultez la page Configurer une méthode à l’aide de la console API Gateway.

Remarque : pour certaines API de service, vous devez envoyer les en-têtes et le corps obligatoires dans la demande d’intégration en plus des paramètres obligatoires. Vous pouvez créer les en-têtes et le corps dans le volet Demande d’intégration sous En-têtes de demande HTTP et Corps de la demande.

Par exemple, si vous intégrez l’API ListCollections d’Amazon Rekognition, 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 SendMessage d’Amazon Simple Queue Service (Amazon SQS), mappez le corps de la requête à 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 requête.) Dans cet exemple, une demande ressemble à ce qui suit :

{'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 Exécution de la méthode correspondant à la méthode de votre API API Gateway, puis sélectionnez Demande d’intégration.
Dans le volet Demande d’intégration, développez le champ Paramètres de chaîne de requête d’URL.
Choisissez Ajouter une chaîne de requête.
Dans le champ Nom, saisissez 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 le champ Mappage à 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.
Cliquez sur l’icône en forme de coche (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 et un corps obligatoires pour la demande de méthode, mappez-les également à la demande d’intégration. Créez-les dans le volet Demande d’intégration sous En-têtes HTTP et Modèles de mappage.

Pour en savoir plus, consultez la page Configurer une demande d’intégration d’API à l’aide de la console API Gateway.

(Facultatif) Vérifier votre configuration d’intégration

Pour vérifier que votre configuration d’intégration correspond à vos attentes, vous pouvez exécuter la commande AWS CLI get-integration et procéder comme suit :

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

Pour l’exemple de configuration d’Amazon SNS, le résultat ressemble à ce qui suit :

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

Dans la console API Gateway, revenez au volet Exécution de la méthode correspondant à la méthode de votre API API Gateway, puis sélectionnez TEST.

Dans le volet Test de méthode, procédez comme suit :
Pour le champ Chaînes de requête, saisissez une chaîne de requête qui inclut les paramètres de requête et leurs valeurs. Pour l’exemple de configuration d’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 les champs En-têtes et Corps de la requête, si vous les avez créés pour votre configuration, saisissez les noms d’en-têtes et le corps de la requête au format JSON.
Choisissez Test. Une réponse s’affiche dans le volet Test de méthode. En cas de succès, ce message s’affiche : Status: 200. Pour l’exemple de configuration d’Amazon SNS, en cas de succès, un MessageID apparaît dans le corps de la réponse.
Pour en savoir plus, consultez la page Utiliser la console API Gateway pour tester une méthode API REST.
Déployez votre API REST.
Testez votre API à l’aide de l’outil de votre choix.