Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Intégrations Lambda pour REST APIs dans API Gateway
Vous pouvez intégrer une méthode API avec une fonction Lambda en utilisant l’intégration de proxy Lambda ou l’intégration autre que proxy (personnalisée) Lambda.
Avec l’intégration de proxy Lambda, la configuration requise est simple. Définissez la méthode HTTP de l’intégration sur POST, l’URI du point de terminaison de l’intégration sur l’ARN de l’action d’appel de la fonction Lambda d’une fonction Lambda spécifique, et autorisez API Gateway à appeler la fonction Lambda en votre nom.
Avec l’intégration autre que de proxy Lambda, outre la configuration de l’intégration de proxy, vous pouvez spécifier la façon dont les données des demandes entrantes sont mappées à la demande d’intégration et la façon dont les données de réponse d’intégration résultantes sont mappées à la réponse de méthode.
**Topics**
+ [Intégrations de proxy Lambda dans API Gateway](set-up-lambda-proxy-integrations.md)
+ [Configuration d’intégrations personnalisées Lambda dans API Gateway](set-up-lambda-custom-integrations.md)
+ [Configuration d’un appel asynchrone de la fonction Lambda du backend](set-up-lambda-integration-async.md)
+ [Gestion des erreurs Lambda dans API Gateway](handle-errors-in-lambda-integration.md)
# Intégrations de proxy Lambda dans API Gateway
La section suivante explique comment utiliser une intégration de proxy Lambda.
**Topics**
+ [Présentation de l’intégration de proxy Lambda API Gateway](#api-gateway-create-api-as-simple-proxy)
+ [Prise en charge des en-têtes à valeurs multiples et des paramètres de chaîne de requête](#apigateway-multivalue-headers-and-parameters)
+ [Format d’entrée d’une fonction Lambda pour l’intégration de proxy](#api-gateway-simple-proxy-for-lambda-input-format)
+ [Format de sortie d’une fonction Lambda pour l’intégration de proxy](#api-gateway-simple-proxy-for-lambda-output-format)
+ [Configurez l'intégration du proxy Lambda pour API Gateway à l'aide du AWS CLI](set-up-lambda-proxy-integration-using-cli.md)
+ [Configuration d’une ressource proxy avec une intégration de proxy Lambda à l’aide d’une définition OpenAPI](api-gateway-set-up-lambda-proxy-integration-on-proxy-resource.md)
## Présentation de l’intégration de proxy Lambda API Gateway
L’intégration de proxy Lambda Amazon API Gateway est un mécanisme simple, puissant et agile pour créer une API avec la configuration d’une seule méthode d’API. L’intégration de proxy Lambda permet au client d’appeler une seule fonction Lambda du backend. La fonction accède à de nombreuses ressources ou fonctionnalités d'autres AWS services, notamment en appelant d'autres fonctions Lambda.
Dans l’intégration de proxy Lambda, quand un client envoie une demande d’API, API Gateway transmet à la fonction Lambda intégrée un [objet d’événement](#api-gateway-simple-proxy-for-lambda-input-format), si ce n’est que l’ordre des paramètres de la demande n’est pas préservé. Les [données de la demande](#api-gateway-simple-proxy-for-lambda-input-format) incluent les en-têtes de demande, les paramètres de chaîne de requête, les variables du chemin de l’URL, la charge utile et les données de configuration de l’API. Les données de configuration peuvent inclure le nom de la phase de déploiement en cours, les variables de la phase, l’identité de l’utilisateur ou le contexte d’autorisation (le cas échéant). La fonction Lambda du backend analyse les données de la demande entrante pour déterminer la réponse qu’elle renvoie. Pour qu’API Gateway transmette la sortie Lambda comme réponse de l’API au client, la fonction Lambda doit renvoyer le résultat dans [ce format](#api-gateway-simple-proxy-for-lambda-output-format).
Dans la mesure où API Gateway n’intervient pas beaucoup entre le client et la fonction Lambda du backend pour l’intégration de proxy Lambda, le client et la fonction Lambda intégrée peuvent s’adapter aux modifications de l’autre sans interrompre la configuration de l’intégration existante de l’API. Pour ce faire, le client doit suivre les protocoles d’application édictés par la fonction Lambda du backend.
Vous pouvez configurer une intégration de proxy Lambda pour n’importe quelle méthode d’API. Mais une intégration de proxy Lambda est plus puissante quand elle est configurée pour une méthode d’API impliquant une ressource proxy générique. La ressource proxy générique peut être symbolisée par la variable spéciale de chemin modélisé `{proxy+}`, l’espace réservé de la méthode fourre-tout `ANY`, ou les deux. Le client peut transmettre les entrées de la fonction Lambda du backend dans la demande entrante comme paramètres de la demande ou comme charge utile applicable. Les paramètres de la demande comprennent les en-têtes, les variables du chemin de l’URL, les paramètres de la chaîne de requête et la charge utile applicable. La fonction Lambda intégrée vérifie l’ensemble des sources d’entrée avant de traiter la demande et de répondre au client avec des messages d’erreur significatifs si l’une des entrées requises est manquante.
Lors de l’appel d’une méthode d’API intégrée avec la méthode HTTP générique `ANY` et la ressource générique `{proxy+}`, le client soumet une demande avec une méthode HTTP particulière à la place de `ANY`. Le client spécifie également un chemin d’URL particulier au lieu de `{proxy+}` et inclut tous les en-têtes requis, les paramètres de chaîne de requête ou une charge utile applicable.
La liste suivante résume les comportements d’exécution de différentes méthodes d’API avec l’intégration de proxy Lambda :
+ `ANY /{proxy+}` : le client doit choisir une méthode HTTP particulière, doit définir une hiérarchie de chemins de ressources spécifiques et peut définir des en-têtes, des paramètres de chaîne de requête et une charge utile applicable pour transmettre les données en tant qu’entrées de la fonction Lambda intégrée.
+ `ANY /res` : le client doit choisir une méthode HTTP particulière et peut définir des en-têtes, des paramètres de chaîne de requête et une charge utile applicable pour transmettre les données en tant qu’entrées de la fonction Lambda intégrée.
+ `GET|POST|PUT|... /{proxy+}` : le client peut définir une hiérarchie de chemins de ressources spécifiques, des en-têtes, des paramètres de chaîne de requête et une charge utile applicable pour transmettre les données en tant qu’entrées de la fonction Lambda intégrée.
+ `GET|POST|PUT|... /res/{path}/...` : le client doit choisir un segment de chemin particulier (pour la variable `{path}`) et peut définir des en-têtes de demande, des paramètres de chaîne de requête et une charge utile applicable pour transmettre les données en entrée à la fonction Lambda intégrée.
+ `GET|POST|PUT|... /res` : le client peut choisir des en-têtes de demande, des paramètres de chaîne de requête et une charge utile applicable pour transmettre les données en entrée à la fonction Lambda intégrée.
Dans les deux cas, la ressource proxy `{proxy+}` et la ressource personnalisée `{custom}` sont exprimées comme des variables de chemin modélisé. Cependant, `{proxy+}` peut faire référence à n’importe quelle ressource de la hiérarchie des chemins, tandis que `{custom}` ne fait référence qu’à un segment de chemin particulier. Par exemple, une épicerie peut organiser son stock de produits en ligne par noms de département, catégories de produit et types de produits. Le site web de l’épicerie peut alors représenter les produits disponibles par les variables de chemin modélisé suivantes des ressources personnalisées : `/{department}/{produce-category}/{product-type}`. Par exemple, les pommes sont représentées par `/produce/fruit/apple` et les carottes par `/produce/vegetables/carrot`. Le site peut également utiliser `/{proxy+}` pour représenter n’importe quel département, catégorie de produit ou type de produit qu’un client peut rechercher lors de ses achats dans la boutique en ligne. Par exemple, `/{proxy+}` peut faire référence à l’un des articles suivants :
+ `/produce`
+ `/produce/fruit`
+ `/produce/vegetables/carrot`
Pour permettre aux clients de rechercher n’importe quel produit disponible, sa catégorie et le département du magasin associé, vous pouvez exposer une seule méthode `GET /{proxy+}` avec les autorisations en lecture seule. De même, pour permettre à un superviseur de mettre à jour l'inventaire du `produce` département, vous pouvez configurer une autre méthode unique `PUT /produce/{proxy+}` d' read/write autorisation. Pour permettre à un caissier de mettre à jour le total cumulé d'un légume, vous pouvez configurer une `POST /produce/vegetables/{proxy+}` méthode avec des read/write autorisations. Pour permettre à un responsable de boutique d'effectuer toute action possible sur n'importe quel produit disponible, le développeur de la boutique en ligne peut exposer la `ANY /{proxy+}` méthode avec read/write des autorisations. Dans tous les cas, au moment de l’exécution, le client ou l’employé doit sélectionner un produit spécifique d’un type donné dans un département choisi, une catégorie de produits spécifique d’un département donné ou un département spécifique.
Pour plus d’informations sur la configuration des intégrations de proxy API Gateway, consultez [Configuration de l’intégration de proxy avec une ressource proxy](api-gateway-set-up-simple-proxy.md).
L’intégration de proxy nécessite que le client ait une connaissance plus approfondie des exigences du backend. Par conséquent, pour garantir des performances d’application et une expérience de l’utilisateur optimales, le développeur du backend doit communiquer clairement au développeur du client les exigences du backend et fournir un mécanisme de retour d’erreur robuste lorsque les exigences ne sont pas satisfaites.
## Prise en charge des en-têtes à valeurs multiples et des paramètres de chaîne de requête
API Gateway prend désormais en charge les en-têtes multiples et les paramètres de chaîne de requête portant le même nom. Les en-têtes à valeurs multiples et les en-têtes et paramètres à valeur unique peuvent être combinés dans les mêmes demandes et réponses. Pour plus d’informations, consultez [Format d’entrée d’une fonction Lambda pour l’intégration de proxy](#api-gateway-simple-proxy-for-lambda-input-format) et [Format de sortie d’une fonction Lambda pour l’intégration de proxy](#api-gateway-simple-proxy-for-lambda-output-format).
## Format d’entrée d’une fonction Lambda pour l’intégration de proxy
Avec l’intégration de proxy Lambda, API Gateway mappe l’intégralité de la demande du client avec le paramètre `event` en entrée de la fonction Lambda du backend. L’exemple suivant montre la structure d’un événement qu’API Gateway envoie à une intégration de proxy Lambda.
Dans cet exemple, nous supposons que l’invocation d’API Gateway était la suivante :
```
curl 'https://a1b2c3.execute-api.us-east-1.amazonaws.com/my/path?parameter1=value1¶meter2=value1¶meter2=value2¶meter3=value1,value2' -H 'header1: value1' -H 'header2: value1' -H 'header2: value2' -H 'header3: value1,value2'
```
Le résultat se présente comme suit :
```
{
"resource": "/my/path",
"path": "/my/path",
"httpMethod": "GET",
"headers": {
"header1": "value1",
"header2": "value2",
"header3": "value1,value2"
},
"multiValueHeaders": {
"header1": ["value1"],
"header2": ["value1","value2"],
"header3": ["value1,value2"]
},
"queryStringParameters": {
"parameter1": "value1",
"parameter2": "value2",
"parameter3": "value1,value2"
},
"multiValueQueryStringParameters": {
"parameter1": ["value1"],
"parameter2": ["value1","value2"],
"parameter3": ["value1,value2"]
},
"requestContext": {
"accountId": "123456789012",
"apiId": "id",
"authorizer": {
"claims": null,
"scopes": null
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"extendedRequestId": "request-id",
"httpMethod": "GET",
"identity": {
"accessKey": null,
"accountId": null,
"caller": null,
"cognitoAuthenticationProvider": null,
"cognitoAuthenticationType": null,
"cognitoIdentityId": null,
"cognitoIdentityPoolId": null,
"principalOrgId": null,
"sourceIp": "IP",
"user": null,
"userAgent": "user-agent",
"userArn": null,
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"path": "/my/path",
"protocol": "HTTP/1.1",
"requestId": "id=",
"requestTime": "04/Mar/2020:19:15:17 +0000",
"requestTimeEpoch": 1583349317135,
"resourceId": null,
"resourcePath": "/my/path",
"stage": "$default"
},
"pathParameters": null,
"stageVariables": null,
"body": "Hello from Lambda!",
"isBase64Encoded": false
}
```
**Note**
Dans l’entrée :
La clé `headers` ne peut contenir que des en-têtes à valeur unique.
La clé `multiValueHeaders` peut contenir des en-têtes à valeurs multiples, ainsi que des en-têtes à valeur unique.
Si vous spécifiez des valeurs pour `headers` et `multiValueHeaders`, API Gateway les fusionne en une seule liste. Si la même paire clé-valeur est spécifiée dans les deux, seules les valeurs de `multiValueHeaders` s’afficheront dans la liste fusionnée.
Dans l’entrée de la fonction Lambda du backend, l’objet `requestContext` est une association de paires clé/valeur. Dans chaque paire, la clé est le nom d’une propriété de la variable [\$1context](api-gateway-mapping-template-reference.md#context-variable-reference) et la valeur est la valeur de cette propriété. API Gateway peut ajouter de nouvelles clés au mappage.
D’après les fonctions activées, le mappage `requestContext` peut varier d’une API à l’autre. Ainsi, dans l’exemple précédent, puisqu’aucun type d’autorisation n’est spécifié, il n’y a aucune propriété `$context.authorizer.*` ou `$context.identity.*` présente. Lorsqu’un type d’autorisation est spécifié, API Gateway transmet les informations sur l’utilisateur autorisé au point de terminaison d’intégration dans un objet `requestContext.identity`, comme suit :
+ Lorsque le type d’autorisation est `AWS_IAM`, les informations sur l’utilisateur autorisé comprennent des propriétés `$context.identity.*`.
+ Lorsque le type d’autorisation est `COGNITO_USER_POOLS` (mécanisme d’autorisation Amazon Cognito), les informations sur l’utilisateur autorisé comprennent les propriétés `$context.identity.cognito*` et `$context.authorizer.claims.*`.
+ Lorsque le type d’autorisation est `CUSTOM` (mécanisme d’autorisation Lambda), les informations sur l’utilisateur autorisé comprennent les propriétés `$context.authorizer.principalId`, ainsi que d’autres propriétés `$context.authorizer.*` applicables.
## Format de sortie d’une fonction Lambda pour l’intégration de proxy
Avec l’intégration de proxy Lambda, API Gateway demande à la fonction Lambda du backend de renvoyer la sortie selon le format JSON suivant :
```
{
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headerName": "headerValue", ... },
"multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
"body": "..."
}
```
Dans la sortie :
+ Les clés `headers` et`multiValueHeaders` peuvent être non précisées si aucun en-tête de réponse supplémentaire ne doit être renvoyé.
+ La clé `headers` ne peut contenir que des en-têtes à valeur unique.
+ La clé `multiValueHeaders` peut contenir des en-têtes à valeurs multiples, ainsi que des en-têtes à valeur unique. Vous pouvez utiliser la clé `multiValueHeaders` pour spécifier l’ensemble de vos en-têtes supplémentaires, y compris n’importe quel en-tête à valeur unique.
+ Si vous spécifiez des valeurs pour `headers` et `multiValueHeaders`, API Gateway les fusionne en une seule liste. Si la même paire clé-valeur est spécifiée dans les deux, seules les valeurs de `multiValueHeaders` s’afficheront dans la liste fusionnée.
Pour activer CORS pour l’intégration de proxy Lambda, vous devez ajouter `Access-Control-Allow-Origin:domain-name` à la sortie `headers`. `domain-name` peut être `*` pour n’importe quel nom de domaine. La sortie `body` est regroupée côté frontal en tant que charge utile de réponse de méthode. Si `body` est un blob binaire, vous pouvez l’encoder en tant que chaîne codée en Base64 en définissant `isBase64Encoded` sur `true` et en configurant `*/*` comme un **type de support binaire**. Sinon, vous pouvez le définir sur `false` ou le laisser non spécifié.
**Note**
Pour plus d’informations sur l’activation de la prise en charge des fichiers binaires, consultez [Activation de la prise en charge binaire à l’aide de la console API Gateway](api-gateway-payload-encodings-configure-with-console.md). Pour obtenir un exemple de fonction Lambda, consultez [Renvoi d’un support binaire d’une intégration de proxy Lambda dans API Gateway](lambda-proxy-binary-media.md).
Si le format de la sortie de la fonction est différent, API Gateway renvoie une réponse d’erreur `502 Bad Gateway`.
Pour renvoyer une réponse dans une fonction Lambda dans Node.js, vous pouvez utiliser des commandes telles que les suivantes :
+ Pour renvoyer un résultat positif, appelez `callback(null, {"statusCode": 200, "body": "results"})`.
+ Pour générer une exception, appelez `callback(new Error('internal server error'))`.
+ Pour une erreur côté client (par exemple, si un paramètre obligatoire est manquant), vous pouvez appeler `callback(null, {"statusCode": 400, "body": "Missing parameters of ..."})` pour renvoyer l’erreur sans générer d’exception.
Dans une fonction `async` Lambda dans Node.js, la syntaxe équivalente serait la suivante :
+ Pour renvoyer un résultat positif, appelez `return {"statusCode": 200, "body": "results"}`.
+ Pour générer une exception, appelez `throw new Error("internal server error")`.
+ Pour une erreur côté client (par exemple, si un paramètre obligatoire est manquant), vous pouvez appeler `return {"statusCode": 400, "body": "Missing parameters of ..."}` pour renvoyer l’erreur sans générer d’exception.
# Configurez l'intégration du proxy Lambda pour API Gateway à l'aide du AWS CLI
Dans cette section, nous vous expliquons comment configurer une API avec l’intégration de proxy Lambda à l’aide de l’ AWS CLI. Pour obtenir des instructions détaillées sur l’utilisation de la console API Gateway afin de configurer une ressource proxy avec l’intégration de proxy Lambda, consultez [Didacticiel : création d’une API REST avec une intégration de proxy Lambda](api-gateway-create-api-as-simple-proxy-for-lambda.md).
À titre d’exemple, nous utilisons l’exemple suivant de fonction Lambda comme backend de l’API :
```
export const handler = async(event, context) => {
console.log('Received event:', JSON.stringify(event, null, 2));
var res ={
"statusCode": 200,
"headers": {
"Content-Type": "*/*"
}
};
var greeter = 'World';
if (event.greeter && event.greeter!=="") {
greeter = event.greeter;
} else if (event.body && event.body !== "") {
var body = JSON.parse(event.body);
if (body.greeter && body.greeter !== "") {
greeter = body.greeter;
}
} else if (event.queryStringParameters && event.queryStringParameters.greeter && event.queryStringParameters.greeter !== "") {
greeter = event.queryStringParameters.greeter;
} else if (event.multiValueHeaders && event.multiValueHeaders.greeter && event.multiValueHeaders.greeter != "") {
greeter = event.multiValueHeaders.greeter.join(" and ");
} else if (event.headers && event.headers.greeter && event.headers.greeter != "") {
greeter = event.headers.greeter;
}
res.body = "Hello, " + greeter + "!";
return res
};
```
Si l’on compare ce code à la configuration de l’intégration personnalisée Lambda dans [Configuration d’intégrations personnalisées Lambda dans API Gateway](set-up-lambda-custom-integrations.md), l’entrée de cette fonction Lambda peut être exprimée dans les paramètres et le corps de la demande. Vous avez plus de latitude pour permettre au client de transmettre les mêmes données d’entrée. Ici, le client peut transmettre le nom de l’hôte sous la forme d’une propriété de paramètre de chaîne de demande, d’en-tête ou de corps. La fonction peut également prendre en charge l’intégration personnalisée Lambda. La configuration de l’API est plus simple. Vous ne configurez pas du tout la réponse de la méthode ou la réponse de l’intégration.
**Pour configurer une intégration de proxy Lambda à l'aide du AWS CLI**
1. Utilisez la [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)commande suivante pour créer une API :
```
aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)'
```
Le résultat se présente comme suit :
```
{
"name": "HelloWorldProxy (AWS CLI)",
"id": "te6si5ach7",
"rootResourceId" : "krznpq9xpg",
"createdDate": 1508461860
}
```
Vous allez utiliser l’API `id` (`te6si5ach7`) et `rootResourceId` (`krznpq9xpg`) tout au long de cet exemple.
1. Utilisez la commande [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) suivante pour créer une [ressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) API Gateway de `/greeting` :
```
aws apigateway create-resource \
--rest-api-id te6si5ach7 \
--parent-id krznpq9xpg \
--path-part {proxy+}
```
Le résultat se présente comme suit :
```
{
"path": "/{proxy+}",
"pathPart": "{proxy+}",
"id": "2jf6xt",
"parentId": "krznpq9xpg"
}
```
Vous allez utiliser la valeur `id` (`2jf6xt`) de la ressource `{proxy+}` pour créer une méthode sur la ressource `/{proxy+}` à l’étape suivante.
1. Utilisez la commande [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) suivante pour créer une demande de méthode `ANY` `ANY /{proxy+}` :
```
aws apigateway put-method --rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method ANY \
--authorization-type "NONE"
```
Le résultat se présente comme suit :
```
{
"apiKeyRequired": false,
"httpMethod": "ANY",
"authorizationType": "NONE"
}
```
Cette méthode d’API permet au client de recevoir ou d’envoyer des salutations de la fonction Lambda au backend.
1. Utilisez la commande [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) suivante pour configurer l’intégration de la méthode `ANY /{proxy+}` avec une fonction Lambda nommée `HelloWorld`. Cette fonction répond à la demande par un message `"Hello, {name}!"` si le paramètre `greeter` est précisé, ou `"Hello, World!"` si le paramètre de chaîne de demande n’est pas défini.
```
aws apigateway put-integration \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method ANY \
--type AWS_PROXY \
--integration-http-method POST \
--uri arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:HelloWorld/invocations \
--credentials arn:aws:iam::123456789012:role/apigAwsProxyRole
```
**Important**
Pour les intégrations Lambda, vous devez utiliser la méthode HTTP `POST` pour la demande d’intégration, conformément à la [spécification de l’action de service Lambda pour les appels de fonction](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html). Le rôle IAM `apigAwsProxyRole` doit avoir des politiques permettant au service `apigateway` d’appeler des fonctions Lambda. Pour plus d’informations sur les autorisations IAM, consultez [Modèle d’autorisation API Gateway pour l’appel d’une API](permissions.md#api-gateway-control-access-iam-permissions-model-for-calling-api).
Le résultat se présente comme suit :
```
{
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:1234567890:function:HelloWorld/invocations",
"httpMethod": "POST",
"cacheNamespace": "vvom7n",
"credentials": "arn:aws:iam::1234567890:role/apigAwsProxyRole",
"type": "AWS_PROXY"
}
```
Plutôt que de fournir un rôle IAM pour `credentials`, vous pouvez utiliser la commande [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) pour ajouter des autorisations basées sur les ressources. C’est ce que fait la console API Gateway.
1. Utilisez la commande [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) suivante pour déployer l’API sur une étape `test` :
```
aws apigateway create-deployment \
--rest-api-id te6si5ach7 \
--stage-name test
```
1. Testez l’API à l’aide des commandes cURL suivantes dans un terminal.
Appel de l’API avec le paramètre de chaîne de demande `?greeter=jane` :
```
curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=jane'
```
Appel de l’API avec un paramètre d’en-tête `greeter:jane` :
```
curl -X GET https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \
-H 'content-type: application/json' \
-H 'greeter: jane'
```
Appel de l’API avec un corps `{"greeter":"jane"}` :
```
curl -X POST https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \
-H 'content-type: application/json' \
-d '{ "greeter": "jane" }'
```
Dans tous les cas, la sortie est une réponse 200 avec le corps de réponse suivant :
```
Hello, jane!
```
# Configuration d’une ressource proxy avec une intégration de proxy Lambda à l’aide d’une définition OpenAPI
Pour configurer une ressource proxy avec le type d’intégration de proxy Lambda, créez une ressource d’API avec un paramètre de chemin gourmand (par exemple, `/parent/{proxy+}`) et intégrez cette ressource avec un backend de fonction Lambda (par exemple, `arn:aws:lambda:us-west-2:123456789012:function:SimpleLambda4ProxyResource`) sur la méthode `ANY`. Le paramètre de chemin gourmand doit se trouver à la fin du chemin de ressource d’API. Comme avec une ressource autre que de proxy, vous pouvez configurer la ressource proxy à l’aide de la console API Gateway, en important un fichier de définitions OpenAPI ou en appelant l’API REST API Gateway directement.
Le fichier de définitions d’API OpenAPI suivant présente un exemple d’API avec une ressource proxy intégrée à une fonction Lambda nommée `SimpleLambda4ProxyResource`.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-09-12T17:50:37Z",
"title": "ProxyIntegrationWithLambda"
},
"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations",
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"cacheNamespace": "roq9wj",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "aws_proxy"
}
}
}
},
"servers": [
{
"url": "https://gy415nuibc.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/testStage"
}
}
}
]
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-09-12T17:50:37Z",
"title": "ProxyIntegrationWithLambda"
},
"host": "gy415nuibc.execute-api.us-east-1.amazonaws.com",
"basePath": "/testStage",
"schemes": [
"https"
],
"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations",
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"cacheNamespace": "roq9wj",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "aws_proxy"
}
}
}
}
}
```
------
Avec l’intégration de proxy Lambda, au moment de l’exécution, API Gateway mappe une demande entrante dans le paramètre d’entrée `event` de la fonction Lambda. L’entrée inclut la méthode de demande, le chemin, les en-têtes, les paramètres de chaîne de demande, la charge utile, le contexte associé et les variables d’étape définies. Le format d’entrée est expliqué dans [Format d’entrée d’une fonction Lambda pour l’intégration de proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format). Pour qu’API Gateway mappe correctement la sortie Lambda aux réponses HTTP, la fonction Lambda doit sortir le résultat au format décrit dans [Format de sortie d’une fonction Lambda pour l’intégration de proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format).
Avec l’intégration de proxy Lambda d’une ressource proxy via la méthode `ANY`, la fonction Lambda du backend unique sert de gestionnaire d’événements pour toutes les demandes via la ressource proxy. Par exemple, pour consigner les modèles de trafic, vous pouvez demander à un appareil mobile d’envoyer ses informations de localisation, notamment l’état, la ville, la rue et le bâtiment en soumettant une demande avec `/state/city/street/house` dans le chemin d’URL de la ressource proxy. La fonction Lambda du backend peut ensuite analyser le chemin d’URL et insérer les tuples d’emplacement dans une table DynamoDB.
# Configuration d’intégrations personnalisées Lambda dans API Gateway
Pour vous montrer comment configurer l’intégration personnalisée Lambda, ou intégration sans proxy, nous allons créer une API d’API Gateway pour exposer la méthode `GET /greeting?greeter={name}` afin d’invoquer une fonction Lambda. Utilisez l’un des exemples de fonctions Lambda suivants pour votre API.
Utilisez l’un des exemples de fonctions Lambda suivants :
------
#### [ Node.js ]
```
'use strict';
var days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
var times = ['morning', 'afternoon', 'evening', 'night', 'day'];
export const handler = async(event) => {
console.log(event);
// Parse the input for the name, city, time and day property values
let name = event.name === null || event.name === undefined || event.name === "" ? '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
return greeting;
};
```
------
#### [ Python ]
```
import json
def lambda_handler(event, context):
print(event)
res = {
"statusCode": 200,
"headers": {
"Content-Type": "*/*"
}
}
if event['greeter'] == "":
res['body'] = "Hello, World"
elif (event['greeter']):
res['body'] = "Hello, " + event['greeter'] + "!"
else:
raise Exception('Missing the required greeter parameter.')
return res
```
------
La fonction répond avec un message `"Hello, {name}!"` si la valeur du paramètre `greeter` est une chaîne non vide. Elle renvoie un message `"Hello, World!"` si la valeur `greeter` est une chaîne vide. La fonction renvoie un message d’erreur `"Missing the required greeter parameter."` si le paramètre d’hôte n’est pas défini dans la demande entrante. Nous nommons la fonction `HelloWorld`.
Vous pouvez la créer dans la console Lambda ou à l’aide de la AWS CLI. Dans cette section, nous faisons référence à cette fonction avec l’ARN suivant :
```
arn:aws:lambda:us-east-1:123456789012:function:HelloWorld
```
Avec la fonction Lambda définie dans le backend, commencez à configurer l’API.
**Pour configurer l'intégration personnalisée Lambda à l'aide du AWS CLI**
1. Utilisez la [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)commande suivante pour créer une API :
```
aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)'
```
Le résultat se présente comme suit :
```
{
"name": "HelloWorld (AWS CLI)",
"id": "te6si5ach7",
"rootResourceId" : "krznpq9xpg",
"createdDate": 1508461860
}
```
Vous allez utiliser l’API `id` (`te6si5ach7`) et `rootResourceId` (`krznpq9xpg`) tout au long de cet exemple.
1. Utilisez la commande [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) suivante pour créer une [ressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) API Gateway de `/greeting` :
```
aws apigateway create-resource \
--rest-api-id te6si5ach7 \
--parent-id krznpq9xpg \
--path-part greeting
```
Le résultat se présente comme suit :
```
{
"path": "/greeting",
"pathPart": "greeting",
"id": "2jf6xt",
"parentId": "krznpq9xpg"
}
```
Vous allez utiliser la valeur `id` (`2jf6xt`) de la ressource `greeting` pour créer une méthode sur la ressource `/greeting` à l’étape suivante.
1. Utilisez la commande [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) suivante pour créer une demande de méthode d’API `GET /greeting?greeter={name}` :
```
aws apigateway put-method --rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--authorization-type "NONE" \
--request-parameters method.request.querystring.greeter=false
```
Le résultat se présente comme suit :
```
{
"apiKeyRequired": false,
"httpMethod": "GET",
"authorizationType": "NONE",
"requestParameters": {
"method.request.querystring.greeter": false
}
}
```
Cette méthode d’API permet au client de recevoir des salutations de la fonction Lambda au backend. Le paramètre `greeter` est facultatif, car le backend doit gérer soit un appelant anonyme, soit un appelant auto-identifié.
1. Utilisez la [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html)commande suivante pour configurer la `200 OK` réponse à la demande de méthode de `GET /greeting?greeter={name}` :
```
aws apigateway put-method-response \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--status-code 200
```
1. Utilisez la commande [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) suivante pour configurer l’intégration de la méthode `GET /greeting?greeter={name}` avec une fonction Lambda nommée `HelloWorld`. La fonction répond à la demande par un message `"Hello, {name}!"` si le paramètre `greeter` est précisé, ou `"Hello, World!"` si le paramètre de chaîne de demande n’est pas défini.
```
aws apigateway put-integration \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--type AWS \
--integration-http-method POST \
--uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations \
--request-templates '{"application/json":"{\"greeter\":\"$input.params('greeter')\"}"}' \
--credentials arn:aws:iam::123456789012:role/apigAwsProxyRole
```
Le modèle de mappage fourni ici convertit le paramètre de chaîne de demande `greeter` en propriété `greeter` de la charge utile JSON. Ceci est nécessaire parce que l’entrée d’une fonction Lambda doit être exprimée dans le corps.
**Important**
Pour les intégrations Lambda, vous devez utiliser la méthode HTTP `POST` pour la demande d’intégration, conformément à la [spécification de l’action de service Lambda pour les appels de fonction](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html). Le paramètre `uri` est l’ARN de l’action d’appel de fonction.
Le résultat se présente comme suit :
```
{
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\"greeter\":\"$input.params('greeter')\"}"
},
"cacheNamespace": "krznpq9xpg",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"type": "AWS"
}
```
Le rôle IAM `apigAwsProxyRole` doit avoir des politiques qui permettent au service `apigateway` d’appeler des fonctions Lambda. Plutôt que de préciser un rôle IAM pour `credentials`, vous pouvez appeler la commande [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) pour ajouter des autorisations basées sur les ressources. C’est ainsi que la console API Gateway ajoute ces autorisations.
1. Utilisez la [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html)commande suivante pour configurer la réponse d'intégration afin de transmettre la sortie de la fonction Lambda au client en tant que réponse de `200 OK` méthode :
```
aws apigateway put-integration-response \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--status-code 200 \
--selection-pattern ""
```
En définissant le modèle de sélection sur une chaîne vide, la réponse `200 OK` est la valeur par défaut.
Le résultat se présente comme suit :
```
{
"selectionPattern": "",
"statusCode": "200"
}
```
1. Utilisez la commande [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) suivante pour déployer l’API sur une étape `test` :
```
aws apigateway create-deployment \
--rest-api-id te6si5ach7 \
--stage-name test
```
1. Testez l’API à l’aide de la commande cURL suivante dans un terminal :
```
curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=me' \
-H 'authorization: AWS4-HMAC-SHA256 Credential={access_key}/20171020/us-west-2/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=f327...5751'
```
# Configuration d’un appel asynchrone de la fonction Lambda du backend
Dans l’intégration autre que de proxy (personnalisée) Lambda, la fonction Lambda du backend est, par défaut, invoquée de façon synchrone. Il s’agit du comportement souhaité pour la plupart des opérations d’API REST. Dans certaines applications, toutefois, les appels doivent avoir lieu de façon asynchrone (sous la forme d’une opération par lots ou d’une opération à latence longue), généralement par un autre composant du backend. Dans ce cas, la fonction Lambda du backend est invoquée de façon asynchrone et la méthode d’API REST frontale ne renvoie aucun résultat.
Vous pouvez également configurer la fonction Lambda pour une intégration Lambda autre que de proxy de sorte qu’elle soit invoquée de façon asynchrone en spécifiant `'Event'` en tant que [type d’appel](https://docs.aws.amazon.com/lambda/latest/dg/lambda-invocation.html). La procédure à suivre est expliquée ci-après :
## Configuration de l’appel asynchrone Lambda dans la console API Gateway
Pour que tous les appels soient asynchrones :
+ Dans **Requête d’intégration**, ajoutez un en-tête `X-Amz-Invocation-Type` avec une valeur statique de `'Event'`.
Pour que les clients décident si les appels sont asynchrones ou synchrones :
1. Dans **Requête de méthode**, ajoutez un en-tête `InvocationType`.
1. Dans **Requête d’intégration**, ajoutez un en-tête `X-Amz-Invocation-Type` avec une expression de mappage de `method.request.header.InvocationType`.
1. Les clients peuvent inclure l’en-tête `InvocationType: Event` dans les requêtes API pour les appels asynchrones, ou `InvocationType: RequestResponse` pour les appels synchrones.
## Configuration de l’appel asynchrone de Lambda à l’aide d’OpenAPI
Pour que tous les appels soient asynchrones :
+ Ajoutez l'`X-Amz-Invocation-Type`en-tête à la **x-amazon-apigateway-integration**section.
```
"x-amazon-apigateway-integration" : {
"type" : "aws",
"httpMethod" : "POST",
"uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.X-Amz-Invocation-Type" : "'Event'"
},
"passthroughBehavior" : "when_no_match",
"contentHandling" : "CONVERT_TO_TEXT"
}
```
Pour que les clients décident si les appels sont asynchrones ou synchrones :
1. Ajoutez l’en-tête suivant sur tout [objet d’élément de chemin OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject).
```
"parameters" : [ {
"name" : "InvocationType",
"in" : "header",
"schema" : {
"type" : "string"
}
} ]
```
1. Ajoutez l'`X-Amz-Invocation-Type`en-tête à la **x-amazon-apigateway-integration**section.
```
"x-amazon-apigateway-integration" : {
"type" : "aws",
"httpMethod" : "POST",
"uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.X-Amz-Invocation-Type" : "method.request.header.InvocationType"
},
"passthroughBehavior" : "when_no_match",
"contentHandling" : "CONVERT_TO_TEXT"
}
```
1. Les clients peuvent inclure l’en-tête `InvocationType: Event` dans les requêtes API pour les appels asynchrones, ou `InvocationType: RequestResponse` pour les appels synchrones.
## Configurer l'appel asynchrone Lambda à l'aide de CloudFormation
Les CloudFormation modèles suivants montrent comment configurer les `AWS::ApiGateway::Method` appels asynchrones.
Pour que tous les appels soient asynchrones :
```
AsyncMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref AsyncResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: AWS
RequestParameters:
integration.request.header.X-Amz-Invocation-Type: "'Event'"
IntegrationResponses:
- StatusCode: '200'
IntegrationHttpMethod: POST
Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations
MethodResponses:
- StatusCode: '200'
```
Pour que les clients décident si les appels sont asynchrones ou synchrones :
```
AsyncMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref AsyncResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
RequestParameters:
method.request.header.InvocationType: false
Integration:
Type: AWS
RequestParameters:
integration.request.header.X-Amz-Invocation-Type: method.request.header.InvocationType
IntegrationResponses:
- StatusCode: '200'
IntegrationHttpMethod: POST
Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations
MethodResponses:
- StatusCode: '200'
```
Les clients peuvent inclure l’en-tête `InvocationType: Event` dans les requêtes API pour les appels asynchrones, ou `InvocationType: RequestResponse` pour les appels synchrones.
# Gestion des erreurs Lambda dans API Gateway
Pour les intégrations personnalisées Lambda, vous devez mapper les erreurs renvoyées par Lambda dans la réponse d'intégration à des réponses d'erreurs HTTP standard pour vos clients. Sinon, les erreurs Lambda sont renvoyées en tant que réponses `200 OK` par défaut et le résultat n'est pas intuitif pour les utilisateurs de l'API.
Lambda peut renvoyer deux types d'erreurs : des erreurs standard et des erreurs personnalisées. Dans votre API, vous devez les gérer différemment.
Avec l'intégration de proxy Lambda, Lambda doit renvoyer une sortie au format suivant :
```
{
"isBase64Encoded" : "boolean",
"statusCode": "number",
"headers": { ... },
"body": "JSON string"
}
```
Dans cette sortie, `statusCode` est généralement `4XX` pour une erreur de client et `5XX` pour une erreur de serveur. API Gateway traite ces erreurs en mappant l'erreur Lambda à une réponse d'erreur HTTP, en fonction du code `statusCode` spécifié. Pour qu'API Gateway transmette le type d'erreur, (par exemple `InvalidParameterException`), dans le cadre de la réponse au client, la fonction Lambda doit inclure un en-tête (par exemple, `"X-Amzn-ErrorType":"InvalidParameterException"`) dans la propriété `headers`.
**Topics**
+ [Gestion des erreurs Lambda standard dans API Gateway](#handle-standard-errors-in-lambda-integration)
+ [Gestion des erreurs Lambda personnalisées dans API Gateway](#handle-custom-errors-in-lambda-integration)
## Gestion des erreurs Lambda standard dans API Gateway
Le format AWS Lambda d'une erreur standard est le suivant :
```
{
"errorMessage": "string",
"errorType": "string",
"stackTrace": [
"string",
...
]
}
```
Ici, `errorMessage` est une expression de chaîne de l'erreur. `errorType` est un type d'erreur ou d'exception dépendant du langage. `stackTrace` est une liste d'expressions de chaîne montrant la trace de la pile conduisant à l'apparition de l'erreur.
Par exemple, considérez la fonction Lambda JavaScript (Node.js) suivante.
```
export const handler = function(event, context, callback) {
callback(new Error("Malformed input ..."));
};
```
Cette fonction renvoie l'erreur Lambda standard suivante, contenant `Malformed input ...` comme message d'erreur :
```
{
"errorMessage": "Malformed input ...",
"errorType": "Error",
"stackTrace": [
"export const handler (/var/task/index.js:3:14)"
]
}
```
De même, examinez la fonction Lambda Python suivante qui génère une `Exception` avec le même message d'erreur `Malformed input ...`.
```
def lambda_handler(event, context):
raise Exception('Malformed input ...')
```
Cette fonction renvoie l'erreur Lambda standard suivante :
```
{
"stackTrace": [
[
"/var/task/lambda_function.py",
3,
"lambda_handler",
"raise Exception('Malformed input ...')"
]
],
"errorType": "Exception",
"errorMessage": "Malformed input ..."
}
```
Notez que les valeurs de propriété `errorType` et `stackTrace` sont dépendantes du langage. L'erreur standard s'applique également à n'importe quel objet d'erreur qui est une extension de l'objet `Error` ou une sous-classe de la classe `Exception`.
Pour mapper l'erreur Lambda standard à une réponse de méthode, vous devez d'abord décider d'un code de statut HTTP pour une erreur Lambda donnée. Vous définissez ensuite un modèle d'expression régulière sur la `[selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern)` propriété du code d'état HTTP [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)associé au code d'état HTTP donné. Dans la console API Gateway, ce `selectionPattern` est désigné comme **Expressions régulières de l’erreur Lambda** dans la section **Réponse d’intégration** sous chaque réponse d’intégration.
**Note**
API Gateway utilise des expressions régulières de type modèle Java pour le mappage de réponse. Pour plus d’informations, consultez la section [Modèles](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) dans la documentation Oracle.
Par exemple, utilisez ce qui suit [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html)pour configurer une nouvelle `selectionPattern` expression :
```
aws apigateway put-integration-response --rest-api-id z0vprf0mdh --resource-id x3o5ih --http-method GET --status-code 400 --selection-pattern "Malformed.*" --region us-west-2
```
Veillez également à configurer le code d'erreur correspondant (`400`) dans la [réponse de méthode](api-gateway-method-settings-method-response.md#setup-method-response-status-code). Sinon, API Gateway renvoie une réponse d'erreur de configuration non valide lors de l'exécution.
**Note**
Lors de l'exécution, API Gateway met en correspondance le message `errorMessage` de l'erreur Lambda avec le modèle de l'expression régulière sur la propriété `selectionPattern`. S'il existe une correspondance, API Gateway renvoie l'erreur Lambda en tant que réponse HTTP du code de statut HTTP correspondant. S'il n'existe pas de correspondance, API Gateway renvoie l'erreur sous la forme d'une réponse par défaut ou émet une exception de configuration non valide si aucune réponse par défaut n'est configurée.
La définition de la valeur `selectionPattern` sur `.*` pour une réponse donnée revient à réinitialiser cette réponse comme la réponse par défaut. En effet, un tel modèle de sélection correspond à tous les messages d'erreur, y compris null, c'est-à-dire, tout message d'erreur non spécifié. Le mappage résultant remplace le mappage par défaut. Si vous utilisez `.+` comme modèle de sélection pour filtrer les réponses, il se peut qu’il ne corresponde pas à une réponse contenant un caractère de nouvelle ligne (`\n`).
Pour mettre à jour une `selectionPattern` valeur existante à l'aide de AWS CLI, appelez l'[update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html)opération pour remplacer la valeur du `/selectionPattern` chemin par l'expression regex spécifiée du `Malformed*` modèle.
Pour définir l’expression `selectionPattern` à l’aide de la console API Gateway, saisissez l’expression dans la zone de texte **Expressions régulières de l’erreur Lambda** lors de la configuration ou de la mise à jour d’une réponse d’intégration d’un code de statut HTTP spécifié.
## Gestion des erreurs Lambda personnalisées dans API Gateway
Au lieu de l'erreur standard décrite dans la section précédente, vous AWS Lambda permet de renvoyer un objet d'erreur personnalisé sous forme de chaîne JSON. L'erreur peut être n'importe quel objet JSON valide. Par exemple, la fonction Lambda JavaScript (Node.js) suivante renvoie une erreur personnalisée :
```
export const handler = (event, context, callback) => {
...
// Error caught here:
var myErrorObj = {
errorType : "InternalServerError",
httpStatus : 500,
requestId : context.awsRequestId,
trace : {
"function": "abc()",
"line": 123,
"file": "abc.js"
}
}
callback(JSON.stringify(myErrorObj));
};
```
Vous devez transformer l'objet `myErrorObj` en chaîne JSON avant d'appeler `callback` pour quitter la fonction. Sinon, `myErrorObj` est renvoyé sous la forme d'une chaîne `"[object Object]"`. Lorsqu'une méthode de votre API est intégrée à la fonction Lambda précédente, API Gateway reçoit une réponse d'intégration avec la charge utile suivante :
```
{
"errorMessage": "{\"errorType\":\"InternalServerError\",\"httpStatus\":500,\"requestId\":\"e5849002-39a0-11e7-a419-5bb5807c9fb2\",\"trace\":{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}}"
}
```
Comme avec toute réponse d'intégration, vous pouvez transmettre cette réponse d'erreur telle quelle à la réponse de méthode. Vous pouvez aussi avoir un modèle de mappage pour transformer la charge utile en un autre format. Prenons l'exemple du modèle de mappage de corps suivant pour une réponse de méthode d'un code du statut `500` :
```
{
errorMessage: $input.path('$.errorMessage');
}
```
Ce modèle convertit le corps de réponse d'intégration qui contient la chaîne JSON d'erreur personnalisée en le corps de réponse de méthode suivant. Ce corps de réponse de méthode contient l'objet JSON d'erreur personnalisée :
```
{
"errorMessage" : {
errorType : "InternalServerError",
httpStatus : 500,
requestId : context.awsRequestId,
trace : {
"function": "abc()",
"line": 123,
"file": "abc.js"
}
}
};
```
En fonction des exigences de votre API, il se peut que vous ayez besoin de transmettre tout ou partie des propriétés d'erreur personnalisée comme paramètres d'en-tête de réponse de méthode. Vous pouvez le faire en appliquant les mappages d'erreur personnalisée du corps de réponse d'intégration aux en-têtes de réponse de méthode.
Par exemple, l'extension OpenAPI suivante définit un mappage à partir des propriétés `errorMessage.errorType`, `errorMessage.httpStatus`, `errorMessage.trace.function` et `errorMessage.trace` aux en-têtes `error_type`, `error_status`, `error_trace_function` et `error_trace`, respectivement.
```
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.error_trace_function": "integration.response.body.errorMessage.trace.function",
"method.response.header.error_status": "integration.response.body.errorMessage.httpStatus",
"method.response.header.error_type": "integration.response.body.errorMessage.errorType",
"method.response.header.error_trace": "integration.response.body.errorMessage.trace"
},
...
}
}
}
```
Lors de l'exécution, API Gateway désérialise le paramètre `integration.response.body` lorsqu'il effectue les mappages d'en-tête. Toutefois, cette désérialisation s'applique uniquement aux body-to-header mappages pour les réponses d'erreur personnalisées Lambda et ne s'applique pas aux mappages utilisant. body-to-body `$input.body` Avec ces mappages custom-error-body-to -header, le client reçoit les en-têtes suivants dans le cadre de la réponse de méthode, à condition que les `error_type` en-têtes`error_status`, `error_trace``error_trace_function`, et soient déclarés dans la demande de méthode.
```
"error_status":"500",
"error_trace":"{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}",
"error_trace_function":"abc()",
"error_type":"InternalServerError"
```
La propriété `errorMessage.trace` du corps de réponse d'intégration est une propriété complexe. Elle est mappée à l'en-tête `error_trace` sous la forme d'une chaîne JSON.