Invocation d’une fonction Lambda à l’aide d’un point de terminaison Amazon API Gateway

Vous pouvez créer une API web avec un point de terminaison HTTP pour votre fonction Lambda à l’aide d’Amazon API Gateway. API Gateway fournit des outils pour créer et documenter des API web qui acheminent des requêtes HTTP vers des fonctions Lambda. Vous pouvez sécuriser l’accès à votre API avec des contrôles d’authentification et d’autorisation. Vos API peuvent servir le trafic sur Internet ou peuvent être accessibles uniquement au sein de votre VPC.

Les ressources de votre API définissent une ou plusieurs méthodes, telles que GET ou POST. Les méthodes ont une intégration qui achemine les requêtes vers une fonction Lambda ou un autre type d’intégration. Vous pouvez définir chaque ressource et méthode individuellement, ou utiliser des types de ressource et de méthode spéciaux pour correspondre à toutes les demandes adaptées à un modèle. Une ressource proxy attrape tous les chemins sous une ressource. La méthode ANY attrape toutes les méthodes HTTP.

Choix d’un type d’API

API Gateway prend en charge trois types d’API qui appellent des fonctions Lambda :

Les API HTTP et les API REST sont toutes deux des API RESTful qui traitent les requêtes HTTP et les réponses renvoyées. Les API HTTP sont plus récentes et construites avec l’API API Gateway version 2. Les fonctionnalités suivantes sont nouvelles pour les API HTTP :

Les API REST sont les API RESTful classiques prises en charge par API Gateway depuis leur lancement. Les API REST disposent actuellement d’un plus grand nombre de fonctionnalités de personnalisation, d’intégration et de gestion.

Pour une comparaison détaillée, consultez Choose between HTTP APIs and REST APIs dans le Guide du développeur API Gateway.

Les API WebSocket utilisent également l’API API Gateway version 2 et prennent en charge un ensemble de fonctions similaire. Utilisez une API WebSocket pour les applications qui bénéficient d’une connexion persistante entre le client et l’API. Les API WebSocket fournissent une communication duplex intégral, ce qui signifie que le client et l’API peuvent envoyer des messages en continu sans attendre de réponse.

Les API HTTP prennent en charge un format d’événement simplifié (version 2.0). Pour obtenir un exemple d’événement provenant d’une API HTTP, consultez la rubrique Create AWS Lambda proxy integrations for HTTP APIs in API Gateway.

Pour plus d’informations, consultez la rubrique Create AWS Lambda proxy integrations for HTTP APIs in API Gateway.

Ajout d’un point de terminaison public à votre fonction Lambda

Intégration de proxy

Les API Gateway comprennent des étapes, des ressources, des méthodes et des intégrations. L’étape et la ressource déterminent le chemin du point de terminaison :

Une intégration Lambda mappe une combinaison de chemin d’accès et de méthode HTTP à une fonction Lambda. Vous pouvez configurer API Gateway pour transmettre le corps de la demande HTTP tel quel (intégration personnalisée) ou pour encapsuler le corps de requête dans un document qui inclut toutes les informations de la demande, y compris les en-têtes, la ressource, le chemin et la méthode.

Pour plus d’informations, consultez Lambda proxy integrations in API Gateway.

Format des événements

Amazon API Gateway appelle votre fonction de manière synchrone avec un événement contenant une représentation JSON de la requête HTTP. Pour une intégration personnalisée, l’événement est le corps de la requête. Pour une intégration par proxy, l’événement a une structure définie. Pour obtenir un exemple d’événement de proxy à partir d’une API REST API Gateway, consultez la rubrique Input format of a Lambda function for proxy integration du guide du développeur API Gateway.

Format de la réponse

API Gateway attend une réponse de votre fonction et relaie le résultat à l’appelant. Pour une intégration personnalisée, vous définissez une réponse d’intégration et une réponse de méthode pour convertir la sortie de la fonction en réponse HTTP. Pour une intégration par proxy, la fonction doit répondre avec une représentation de la réponse dans un format spécifique.

L’exemple suivant montre un objet de réponse d’une fonction Node.js. L’objet de réponse représente une réponse HTTP réussie qui contient un document JSON.

var response = {
      "statusCode": 200,
      "headers": {
        "Content-Type": "application/json"
      },
      "isBase64Encoded": false,
      "multiValueHeaders": { 
        "X-Custom-Header": ["My value", "My other value"],
      },
      "body": "{\n  \"TotalCodeSize\": 104330022,\n  \"FunctionCount\": 26\n}"
    }

L’environnement d’exécution Lambda sérialise l’objet réponse dans JSON et l’envoie à l’API. L’API analyse la réponse et l’utilise pour créer une réponse HTTP, qu’elle envoie ensuite au client qui a fait la demande d’origine.

< HTTP/1.1 200 OK
  < Content-Type: application/json
  < Content-Length: 55
  < Connection: keep-alive
  < x-amzn-RequestId: 32998fea-xmpl-4268-8c72-16138d629356
  < X-Custom-Header: My value
  < X-Custom-Header: My other value
  < X-Amzn-Trace-Id: Root=1-5e6aa925-ccecxmplbae116148e52f036
  <
  {
    "TotalCodeSize": 104330022,
    "FunctionCount": 26
  }

Autorisations

Amazon API Gateway obtient l’autorisation d’appeler votre fonction à partir de la politique basée sur une ressource de la fonction. Vous pouvez accorder l’autorisation d’appel à toute une API ou accorder un accès limité à une étape, à une ressource ou à une méthode.

Lorsque vous ajoutez une API à votre fonction à l’aide de la console Lambda, de la console API Gateway ou d’un modèle AWS SAM, la politique basée sur une ressource de la fonction est mise à jour automatiquement. Voici un exemple de politique de fonction.

Vous pouvez gérer manuellement les autorisations de politique de fonction à l’aide des opérations d’API suivantes :

Pour accorder l’autorisation d’invocation à une API existante, utilisez la commande add-permission. Exemple :

aws lambda add-permission \
  --function-name my-function \
  --statement-id apigateway-get --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:us-east-2:123456789012:mnh1xmpli7/default/GET/"

Vous devriez voir la sortie suivante :

{
    "Statement": "{\"Sid\":\"apigateway-test-2\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"apigateway.amazonaws.com\"},\"Action\":\"lambda:InvokeFunction\",\"Resource\":\"arn:aws:lambda:us-east-2:123456789012:function:my-function\",\"Condition\":{\"ArnLike\":{\"AWS:SourceArn\":\"arn:aws:execute-api:us-east-2:123456789012:mnh1xmpli7/default/GET\"}}}"
}

L’ARN source dans cet exemple accorde l’autorisation à une intégration sur la méthode GET de la ressource racine au cours de l’étape par défaut d’une API, avec l’ID mnh1xmpli7. Vous pouvez utiliser un astérisque dans l’ARN source pour accorder des autorisations à plusieurs étapes, méthodes ou ressources.

Pour de plus amples informations sur l’affichage de la politique et la suppression des instructions, veuillez consulter Voir les politiques IAM basées sur les ressources dans Lambda.

Exemple d’application

L’exemple d’application API Gateway avec Node.js inclut une fonction avec un modèle AWS SAM qui crée une API REST dont le suivi AWS X-Ray est activé. Il inclut également des scripts pour le déploiement, l’invocation de la fonction, le test de l’API et le nettoyage.

Le gestionnaire d’événements de Powertools pour AWS Lambda

Le gestionnaire d’événements de la boîte à outils Powertools pour AWS Lambda fournit le routage, l’intergiciel, la configuration CORS, la génération de spécifications OpenAPI, la validation des demandes, la gestion des erreurs et d’autres fonctionnalités utiles lors de l’écriture de fonctions Lambda invoquées par un point de terminaison API Gateway (HTTP ou REST). L’utilitaire de gestion d’événements est disponible pour Python et TypeScript/JavaScript. Pour plus d’informations, consultez l’API REST du gestionnaire d’événements dans la documentation de Powertools pour AWS Lambda (Python) et l’API REST du gestionnaire d’événements dans la documentation de Powertools pour AWS Lambda (TypeScript).

Python

from aws_lambda_powertools import Logger
from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.logging import correlation_paths
from aws_lambda_powertools.utilities.typing.lambda_context import LambdaContext

app = APIGatewayRestResolver()
logger = Logger()

@app.get("/healthz")
def ping():
    return {"message": "health status ok"}

@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)  
def lambda_handler(event: dict, context: LambdaContext) -> dict:
    return app.resolve(event, context)

TypeScript

import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
import { Logger } from '@aws-lambda-powertools/logger';
import {
  correlationPaths,
  search,
} from '@aws-lambda-powertools/logger/correlationId';
import type { Context } from 'aws-lambda/handler';

const logger = new Logger({
  correlationIdSearchFn: search,
});

const app = new Router({ logger });

app.get("/healthz", async () => {
  return { message: "health status ok" };
});

export const handler = async (event: unknown, context: Context) => {
  // You can continue using other utilities just as before
  logger.addContext(context);
  logger.setCorrelationId(event, correlationPaths.API_GATEWAY_REST);
  return app.resolve(event, context);
};