Utilisation des intégrations de services AWS pour les API HTTP

Vous pouvez intégrer votre API HTTP avec des services AWS en utilisant des intégrations de première classe. Une intégration de première classe connecte une route API HTTP à une API de service AWS. Lorsqu'un client appelle une route soutenu par une intégration de première classe, API Gateway appelle une API de service AWS pour vous. Par exemple, vous pouvez utiliser des intégrations de première classe pour envoyer un message à une file d'attente Amazon Simple Queue Service, ou pour démarrer une machine d'état AWS Step Functions. Pour connaître les actions de service prises en charge, veuillez consulter Référence de sous-type d'intégration.

Mappage des paramètres de demande

Les intégrations de première classe ont des paramètres requis et des paramètres facultatifs. Vous devez configurer tous les paramètres requis pour créer une intégration. Vous pouvez utiliser des valeurs statiques ou des paramètres de mappage évalués de manière dynamique lors de l'exécution. Pour obtenir la liste complète des intégrations et des paramètres pris en charge, veuillez consulter Référence de sous-type d'intégration.

Mappage de paramètres
Type	Exemple	Remarques
Valeur d'en-tête	$request.header.nom	Les noms d'en-tête ne sont pas sensibles à la casse. API Gateway combine plusieurs valeurs d'en-tête avec des virgules, par exemple "header1": "value1,value2".
Valeur de chaîne de requête	$request.querystring.nom	Les noms de chaîne de requête sont sensibles à la casse. API Gateway combine plusieurs valeurs avec des virgules, par exemple "querystring1": "Value1,Value2".
Paramètre de chemin	$request.path.nom	Valeur d'un paramètre de chemin dans la demande. Par exemple, si la route est /pets/{petId}, vous pouvez mapper le paramètre petId de la demande avec $request.path.petid.
Transmission de corps de demande	$request.body	API Gateway transmet l'ensemble du corps de la demande.
Corps de la demande	$ request.body.nom	Expression de chemin JSON. La descente récursive ($request.body..name) et les expressions de filtre (?(expression)) ne sont pas prises en charge. Note Lorsque vous spécifiez un chemin JSON, API Gateway tronque le corps de la requête à 100 Ko, puis applique l'expression de sélection. Pour envoyer des charges utiles supérieures à 100 Ko, spécifiez $request.body.
Variable de contexte	$context.Nom_variable	Valeur d'une variable de contexte prise en charge.
Variable d'étape	$stageVariables.Nom_variable	Valeur d'une variable d'étape.
Valeur statique	string	Valeur constante.

Créer une intégration de première classe

Avant de créer une intégration de première classe, vous devez créer un rôle IAM qui accorde des autorisations API Gateway pour appeler l'action de service AWS avec laquelle vous êtes en train d'effectuer l'intégration. Pour en savoir plus, veuillez consulter Création d'un rôle pour un service AWS.

Pour créer une intégration de première classe, choisissez une action de service AWS prise en charge telle que SQS-SendMessage, configurez les paramètres de la demande et fournissez un rôle qui accorde à API Gateway les autorisations requises pour appeler l'API de service AWS intégrée. Selon le sous-type d'intégration, différents paramètres de demande sont requis. Pour en savoir plus, consultez la section Référence de sous-type d'intégration.

La commande AWS CLI suivante crée une intégration qui envoie un message Amazon SQS.

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-subtype SQS-SendMessage \
    --integration-type AWS_PROXY \
    --payload-format-version 1.0 \
    --credentials-arn arn:aws:iam::123456789012:role/apigateway-sqs \
    --request-parameters '{"QueueUrl": "$request.header.queueUrl", "MessageBody": "$request.body.message"}'

Création d’une intégration de première classe à l’aide d’AWS CloudFormation

L’exemple suivant montre un extrait AWS CloudFormation qui crée une route /{source}/{detailType} avec une intégration de première classe à Amazon EventBridge.

Le paramètre Source est mappé au paramètre de chemin {source}, le paramètre DetailType au paramètre de chemin {DetailType} et le paramètre Detail au corps de la demande.

L’extrait n’affiche pas le bus d’événements ni le rôle IAM qui accorde à API Gateway les autorisations nécessaires pour invoquer l’action PutEvents.

Route:
    Type: AWS::ApiGatewayV2::Route
    Properties:
      ApiId: !Ref HttpApi
      AuthorizationType: None
      RouteKey: 'POST /{source}/{detailType}'
      Target: !Join 
        - /
        - - integrations
          - !Ref Integration
  Integration:
    Type: AWS::ApiGatewayV2::Integration
    Properties:
      ApiId: !Ref HttpApi
      IntegrationType: AWS_PROXY
      IntegrationSubtype: EventBridge-PutEvents
      CredentialsArn: !GetAtt EventBridgeRole.Arn
      RequestParameters:
        Source: $request.path.source
        DetailType: $request.path.detailType
        Detail: $request.body
        EventBusName: !GetAtt EventBus.Arn
      PayloadFormatVersion: "1.0"