Didacticiel : création d’une API REST avec une intégration Lambda sans proxy

Dans cette présentation, nous utilisons la console API Gateway pour créer une API qui permet à un client d’appeler des fonctions Lambda via l’intégration Lambda autre que de proxy (également désignée sous le nom d’intégration personnalisée). Pour en savoir plus sur AWS Lambda et les fonctions Lambda, consultez le Guide du développeur AWS Lambda.

Pour faciliter l’apprentissage, nous avons choisi une fonction Lambda simple avec une configuration d’API minimale pour vous guider à travers les étapes de création d’une API Amazon API Gateway avec l’intégration personnalisée Lambda. Lorsque nécessaire, nous décrivons un aspect de la logique. Pour un exemple plus détaillé de l’intégration personnalisée Lambda, consultez Didacticiel : création d’une API REST de calculatrice avec deux intégrations de service AWS et une intégration Lambda sans proxy.

Avant de créer l’API, configurez le backend Lambda en créant une fonction Lambda dans AWS Lambda, comme décrit ci-après.

Création d’une fonction Lambda pour l’intégration Lambda autre que de proxy

Au cours de cette étape, vous allez créer une fonction Lambda de type « Hello, World ! » pour l’intégration Lambda personnalisée. Tout au long de cette procédure, la fonction est appelée GetStartedLambdaIntegration.

La mise en œuvre de cette fonction Lambda GetStartedLambdaIntegration est la suivante :

Node.js

'use strict';
var days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];            
var times = ['morning', 'afternoon', 'evening', 'night', 'day'];

console.log('Loading function');

export const handler = function(event, context, callback) {
  // Parse the input for the name, city, time and day property values
  let name = event.name === undefined ? 'you' : event.name;
  let city = event.city === undefined ? 'World' : event.city;
  let time = times.indexOf(event.time)<0 ? 'day' : event.time;
  let day = days.indexOf(event.day)<0 ? null : event.day;

  // Generate a greeting
  let greeting = 'Good ' + time + ', ' + name + ' of ' + city + '. ';
  if (day) greeting += 'Happy ' + day + '!';
  
  // Log the greeting to CloudWatch
  console.log('Hello: ', greeting);
  
  // Return a greeting to the caller
  callback(null, {
      "greeting": greeting
  }); 
};

Python

import json

days = {
    'Sunday',
    'Monday',
    'Tuesday',
    'Wednesday',
    'Thursday',
    'Friday',
    'Saturday'}
times = {'morning', 'afternoon', 'evening', 'night', 'day'}


def lambda_handler(event, context):
    print(event)
    # parse the input for the name, city, time, and day property values
    try:
        if event['name']:
            name = event['name']
    except KeyError:
        name = 'you'
    try:
        if event['city']:
            city = event['city']
    except KeyError:
        city = 'World'
    try:
        if event['time'] in times:
            time = event['time']
        else:
            time = 'day'
    except KeyError:
        time = 'day'
    try:
        if event['day'] in days:
            day = event['day']
        else:
            day = ''
    except KeyError:
        day = ''
    # Generate a greeting
    greeting = 'Good ' + time + ', ' + name + ' of ' + \
        city + '.' + ['', ' Happy ' + day + '!'][day != '']
    # Log the greeting to CloudWatch
    print(greeting)

    # Return a greeting to the caller
    return {"greeting": greeting}

Pour l’intégration personnalisée Lambda, API Gateway transmet les entrées à la fonction Lambda depuis le client en tant que corps de la demande d’intégration. L’objet event du gestionnaire de la fonction Lambda correspond à l’entrée.

Notre fonction Lambda est simple. Elle analyse l’objet event en entrée par rapport aux propriétés name, city, time et day. Elle renvoie ensuite un message d’accueil, en tant qu’objet JSON {"message":greeting}, à l’appelant. Le message suit le modèle "Good [morning|afternoon|day], [name|you] in [city|World]. Happy day!". Il est supposé que l’entrée de la fonction Lambda est l’objet JSON suivant :

{
  "city": "...",
  "time": "...",
  "day": "...",
  "name" : "..."
}

Pour plus d’informations, consultez le Manuel du développeur AWS Lambda.

En outre, la fonction enregistre son exécution sur Amazon CloudWatch en appelant console.log(...). Cet aspect est précieux pour suivre les appels lors du débogage de la fonction. Pour permettre à la fonction GetStartedLambdaIntegration d’enregistrer l’appel, définissez un rôle IAM avec les politiques appropriées pour que la fonction Lambda puisse créer les flux CloudWatch et ajouter des entrées de journal aux flux. La console Lambda vous guide tout au long de la création des rôles et politiques IAM requis.

Si vous configurez l’API sans utiliser la console API Gateway, par exemple en important une API depuis un fichier OpenAPI, vous devez créer explicitement, si nécessaire, et configurer une politique et un rôle d’appel pour qu’API Gateway puisse appeler les fonctions Lambda. Pour plus d’informations sur la configuration des rôles d’appel et d’exécution Lambda pour une API Amazon API Gateway, consultez Contrôle de l’accès à une API REST avec des autorisations IAM.

Par rapport à GetStartedLambdaProxyIntegration, la fonction Lambda pour l’intégration de proxy Lambda, la fonction GetStartedLambdaIntegration Lambda pour l’intégration personnalisée Lambda prend uniquement les entrées du corps de la requête d’intégration d’API Amazon API Gateway. La fonction peut renvoyer une sortie sous forme d’un objet JSON, d’une chaîne, d’un nombre, d’une valeur booléenne ou même d’un blob binaire. La fonction Lambda de l’intégration de proxy Lambda, en revanche, peut accepter les entrées de toutes données de la demande, mais doit renvoyer en sortie un objet JSON particulier. La fonction GetStartedLambdaIntegration pour l’intégration personnalisée Lambda peut avoir comme entrées les paramètres de la demande d’API, à condition qu’API Gateway mappe les paramètres de la demande d’API au corps de demande d’intégration avant de transférer la demande du client au backend. Pour que cela se produise, le développeur de l’API doit créer un modèle de mappage et le configurer sur la méthode de l’API lors de la création de l’API.

Maintenant, créez la fonction Lambda GetStartedLambdaIntegration.

À titre d’exercice, vous pouvez utiliser la console IAM pour afficher le rôle IAM (GetStartedLambdaIntegrationRole) créé dans le cadre de la création de la fonction Lambda. Deux politiques en ligne sont attachées à ce rôle IAM. L’une stipule les autorisations les plus élémentaires pour l’exécution Lambda. Cela permet d’appeler CloudWatch CreateLogGroup pour toutes les ressources CloudWatch de votre compte dans la région où la fonction Lambda est créée. Cette politique permet également la création de flux CloudWatch et la journalisation des événements de la fonction Lambda GetStartedLambdaIntegration.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "logs:CreateLogGroup",
            "Resource": "arn:aws:logs:region:account-id:*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogStream",
                "logs:PutLogEvents"
            ],
            "Resource": [
                "arn:aws:logs:region:account-id:log-group:/aws/lambda/GetStartedLambdaIntegration:*"
            ]
        }
    ]
}

L’autre document de politique s’applique à l’appel d’un autre service AWS qui n’est pas utilisé dans cet exemple. Vous pouvez l’ignorer pour l’instant.

Associée au rôle IAM se trouve une entité de confiance, qui est lambda.amazonaws.com. Voici la relation d’approbation :

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "lambda.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

La combinaison de cette relation d’approbation et de la politique en ligne permet à la fonction Lambda d’appeler une fonction console.log() pour enregistrer les événements sur CloudWatch Logs.

Création d’une API avec l’intégration Lambda autre que de proxy

Avec la fonction Lambda (GetStartedLambdaIntegration) créée et testée, vous êtes prêt à exposer la fonction via une API Amazon API Gateway. À des fins d’illustration, nous exposons la fonction Lambda avec une méthode HTTP générique. Nous utilisons le corps de la demande, une variable de chemin d’URL, une chaîne de requête et un en-tête pour recevoir les données d’entrée requises du client. Nous activons le validateur de demande API Gateway pour l’API afin de garantir que toutes les données requises sont correctement définies et spécifiées. Nous configurons un modèle de mappage pour qu’API Gateway transforme les données de la demande fournie par le client au format valide comme requis par la fonction Lambda du backend.

Après avoir créé votre API, vous créez une ressource /{city}. Ceci est un exemple de ressource avec une variable de chemin qui accepte une entrée du client. Par la suite, vous mapperez cette variable de chemin avec l’entrée de la fonction Lambda à l’aide d’un modèle de mappage.

Après avoir créé votre ressource /{city}, vous créez une méthode ANY. Le verbe HTTP ANY est un espace réservé pour une méthode HTTP valide qu’un client soumet au moment de l’exécution. Cet exemple montre que la méthode ANY peut être utilisée pour l’intégration personnalisée Lambda aussi bien que pour l’intégration de proxy Lambda.

Après avoir activé un validateur de requête, vous configurez la requête d’intégration pour la méthode ANY en ajoutant un modèle de mappage corporel pour transformer la requête entrante en une charge utile JSON, comme l’exige la fonction Lambda du backend.

Test de l’appel de la méthode d’API

La console API Gateway fournit une installation de test qui vous permet de tester l’appel de l’API avant qu’elle ne soit déployée. Vous utilisez la fonctionnalité Test de la console pour tester l’API en soumettant la demande suivante :

POST /Seattle?time=morning
day:Wednesday

{
    "callerName": "John"
}

Dans cette demande de test, vous allez définir ANY sur POST et {city} sur Seattle, attribuer Wednesday comme valeur de l’en-tête day et attribuer "John" comme valeur de callerName.

Vérifiez que la charge utile de la réponse retournée se présente comme suit :

{
  "greeting": "Good morning, John of Seattle. Happy Wednesday!"
}

Vous pouvez également consulter les journaux pour examiner comment API Gateway traite la demande et la réponse.

Execution log for request test-request
Thu Aug 31 01:07:25 UTC 2017 : Starting execution for request: test-invoke-request
Thu Aug 31 01:07:25 UTC 2017 : HTTP Method: POST, Resource Path: /Seattle
Thu Aug 31 01:07:25 UTC 2017 : Method request path: {city=Seattle}
Thu Aug 31 01:07:25 UTC 2017 : Method request query string: {time=morning}
Thu Aug 31 01:07:25 UTC 2017 : Method request headers: {day=Wednesday}
Thu Aug 31 01:07:25 UTC 2017 : Method request body before transformations: { "callerName": "John" }
Thu Aug 31 01:07:25 UTC 2017 : Request validation succeeded for content type application/json
Thu Aug 31 01:07:25 UTC 2017 : Endpoint request URI: https://lambda.us-west-2.amazonaws.com/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:GetStartedLambdaIntegration/invocations
Thu Aug 31 01:07:25 UTC 2017 : Endpoint request headers: {x-amzn-lambda-integration-tag=test-request, Authorization=****************************************************************************************************************************************************************************************************************************************************************************************************************************************338c72, X-Amz-Date=20170831T010725Z, x-amzn-apigateway-api-id=beags1mnid, X-Amz-Source-Arn=arn:aws:execute-api:us-west-2:123456789012:beags1mnid/null/POST/{city}, Accept=application/json, User-Agent=AmazonAPIGateway_beags1mnid, X-Amz-Security-Token=FQoDYXdzELL//////////wEaDMHGzEdEOT/VvGhabiK3AzgKrJw+3zLqJZG4PhOq12K6W21+QotY2rrZyOzqhLoiuRg3CAYNQ2eqgL5D54+63ey9bIdtwHGoyBdq8ecWxJK/YUnT2Rau0L9HCG5p7FC05h3IvwlFfvcidQNXeYvsKJTLXI05/yEnY3ttIAnpNYLOezD9Es8rBfyruHfJfOqextKlsC8DymCcqlGkig8qLKcZ0hWJWVwiPJiFgL7laabXs++ZhCa4hdZo4iqlG729DE4gaV1mJVdoAagIUwLMo+y4NxFDu0r7I0/EO5nYcCrppGVVBYiGk7H4T6sXuhTkbNNqVmXtV3ch5bOlh7 [TRUNCATED]
Thu Aug 31 01:07:25 UTC 2017 : Endpoint request body after transformations: {
  "city": "Seattle",
  "time": "morning",
  "day": "Wednesday",
  "name" : "John"
}
Thu Aug 31 01:07:25 UTC 2017 : Sending request to https://lambda.us-west-2.amazonaws.com/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:GetStartedLambdaIntegration/invocations
Thu Aug 31 01:07:25 UTC 2017 : Received response. Integration latency: 328 ms
Thu Aug 31 01:07:25 UTC 2017 : Endpoint response body before transformations: {"greeting":"Good morning, John of Seattle. Happy Wednesday!"}
Thu Aug 31 01:07:25 UTC 2017 : Endpoint response headers: {x-amzn-Remapped-Content-Length=0, x-amzn-RequestId=c0475a28-8de8-11e7-8d3f-4183da788f0f, Connection=keep-alive, Content-Length=62, Date=Thu, 31 Aug 2017 01:07:25 GMT, X-Amzn-Trace-Id=root=1-59a7614d-373151b01b0713127e646635;sampled=0, Content-Type=application/json}
Thu Aug 31 01:07:25 UTC 2017 : Method response body after transformations: {"greeting":"Good morning, John of Seattle. Happy Wednesday!"}
Thu Aug 31 01:07:25 UTC 2017 : Method response headers: {X-Amzn-Trace-Id=sampled=0;root=1-59a7614d-373151b01b0713127e646635, Content-Type=application/json}
Thu Aug 31 01:07:25 UTC 2017 : Successfully completed execution
Thu Aug 31 01:07:25 UTC 2017 : Method completed with status: 200

Les journaux présentent la demande entrante avant le mappage et la demande d’intégration après le mappage. Lorsqu’un test échoue, les journaux sont utiles pour évaluer si l’entrée d’origine est correcte ou si le modèle de mappage fonctionne correctement.

Déploiement de l’API

L’appel du test est une simulation et possède ses limites. Par exemple, il contourne tout mécanisme d’autorisation activé sur l’API. Pour tester l’exécution de l’API en temps réel, vous devez d’abord déployer l’API. Pour déployer une API, vous créez une phase afin de créer un instantané de l’API à ce moment-là. Le nom de la phase définit également le chemin de base après le nom d’hôte par défaut de l’API. La ressource racine de l’API est ajoutée après le nom de la phase. Lorsque vous modifiez l’API, vous devez la redéployer vers une phase nouvelle ou existante pour que les modifications prennent effet.

Sous Détails de l’étape, choisissez l’icône de copie pour copier l’URL d’invocation de votre API. Le modèle général de l’URL de base de l’API est https://api-id.region.amazonaws.com/stageName. Par exemple, l’URL de base de l’API (beags1mnid) créée dans la région us-west-2 et déployée sur la phase test est https://beags1mnid.execute-api.us-west-2.amazonaws.com/test.

Test de l’API dans une phase de déploiement

Il existe plusieurs façons de tester une API déployée. Pour les requêtes GET n’utilisant que les variables de chemin d’URL ou les paramètres de chaîne de requête, vous pouvez saisir l’URL de la ressource d’API dans un navigateur. Pour les autres méthodes, vous devez utiliser les utilitaires de test plus avancés de l’API REST, tels que POSTMAN ou cURL.

Nettoyage

Si vous n’avez plus besoin des fonctions Lambda que vous avez créées pour cette procédure, vous pouvez maintenant les supprimer. Vous pouvez également supprimer les ressources IAM associées.