Tâches de base d’une demande d’intégration d’API

Une demande d’intégration est une demande HTTP qu’API Gateway soumet au backend en la transmettant avec les données de demande soumises par le client et en les transformant, le cas échéant. La méthode HTTP (ou verbe) et l’URI de la demande d’intégration sont dictées par le backend (à savoir, le point de terminaison d’intégration). Elles peuvent être identiques ou différentes de la méthode HTTP et de l’URI de la demande de méthode, respectivement.

Par exemple, lorsqu’une fonction Lambda renvoie un fichier récupéré dans Amazon S3, vous pouvez exposer cette opération intuitivement en tant que demande de méthode GET au client même si la demande d’intégration correspondante nécessite l’utilisation d’une demande POST pour appeler la fonction Lambda. Pour un point de terminaison HTTP, il est probable que la demande de méthode et la demande d’intégration correspondante utilisent toutes deux le même verbe HTTP. Toutefois, cela n’est pas obligatoire. Vous pouvez intégrer la demande de méthode suivante :

GET /{var}?query=value
Host: api.domain.net

Avec la demande d’intégration suivante :

POST /
Host: service.domain.com
Content-Type: application/json
Content-Length: ...

{
   path: "{var}'s value",
   type: "value"
}

En tant que développeur d’API, vous pouvez utiliser n’importe quel verbe HTTP et URI pour qu’une demande de méthode corresponde à vos besoins. Cependant, vous devez suivre les conditions du point de terminaison de l’intégration. Lorsque les données de la demande de méthode sont différentes des données de la demande d’intégration, vous pouvez rapprocher la différence en fournissant des mappages à partir des données de demande de la méthode aux données de la demande d’intégration.

Dans les exemples précédents, le mappage traduit les valeurs de variable de chemin d’accès ({var}) et de paramètre de demande (query) de la demande de méthode GET aux valeurs des propriétés path et type de charge utile de la demande d’intégration. Les autres données de demandes mappables comprennent les en-têtes et le corps des demandes. Celles-ci sont décrites dans Mappage de paramètres pour les API REST dans API Gateway.

Lors de la configuration de la demande d’intégration HTTP ou de proxy HTTP, vous attribuez l’URL du point de terminaison HTTP backend en tant que valeur d’URI de la demande d’intégration. Par exemple, dans l’API PetStore, la demande de méthode pour obtenir une page d’animaux domestiques possède l’URI de demande d’intégration suivante :

http://petstore-demo-endpoint.execute-api.com/petstore/pets

Lors de la configuration de l’intégration Lambda ou de proxy Lambda, vous attribuez l’Amazon Resource Name (ARN) pour appeler la fonction Lambda en tant que valeur d’URI de la demande d’intégration. Cet ARN présente le format suivant :

arn:aws:apigateway:api-region:lambda:path//2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations

La partie après arn:aws:apigateway:api-region:lambda:path/, à savoir /2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations, est le chemin d’URI de l’API REST de l’action Invoke Lambda. Si vous utilisez la console API Gateway pour configurer l’intégration Lambda, API Gateway crée l’ARN et l’attribue à l’URI d’intégration après vous avoir invité à choisir le lambda-function-name à partir d’une région.

Lors de la configuration de la demande d’intégration avec une autre action de service AWS, l’URI de demande d’intégration est également un ARN, similaire à l’intégration avec l’action Lambda Invoke. Par exemple, pour l’intégration avec l’action GetBucket d’Amazon S3, l’URI de la demande d’intégration est un ARN au format suivant :

arn:aws:apigateway:api-region:s3:path/{bucket}

L’URI de la demande d’intégration correspond à la convention de chemin pour spécifier l’action, où {bucket} est l’espace réservé d’un nom de compartiment. Une action de service AWS peut également être référencée par son nom. Grâce au nom de l’action, l’URI de demande d’intégration pour l’action GetBucket d’Amazon S3 devient la suivante :

arn:aws:apigateway:api-region:s3:action/GetBucket

Grâce à l’URI de la demande d’intégration basée sur l’action, le nom du compartiment ({bucket}) doit être spécifié dans le corps de la demande d’intégration ({ Bucket: "{bucket}" }), en respectant le format d’entrée de l’action GetBucket.

Pour les intégrations AWS, vous devez également configurer les informations d’identification pour permettre à API Gateway d’appeler les actions intégrées. Vous pouvez créer un rôle IAM ou choisir un rôle IAM existant pour qu’API Gateway appelle l’action, puis spécifier le rôle à l’aide de son ARN. Voici un exemple de cet ARN :

arn:aws:iam::account-id:role/iam-role-name

Ce rôle IAM doit contenir une politique permettant l’exécution de l’action. Il doit également avoir déclaré API Gateway (dans la relation d’approbation du rôle) en tant qu’entité de confiance pour assumer le rôle. Ces autorisations peuvent être accordées sur l’action même. Ce sont les autorisations basées sur les ressources. Pour l’intégration Lambda, vous pouvez appeler l’action addPermission de Lambda pour définir les autorisations basées sur les ressources, puis définissez credentials sur null dans la demande d’intégration API Gateway.

Nous avons vu la configuration de l’intégration de base. Les paramètres avancés comprennent les données de demande de méthode de mappage aux données de demande d’intégration. Pour plus d’informations, consultez Transformations de données pour les API REST dans API Gateway.