Utilisation des intégrations de AWS Lambda proxy pour les API HTTP - Amazon API Gateway
Version du format de charge utileFormat de réponse de fonction Lambda

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.

Utilisation des intégrations de AWS Lambda proxy pour les API HTTP

Une intégration de proxy Lambda vous permet d'intégrer un itinéraire API à une fonction Lambda. Lorsqu'un client appelle votre API, API Gateway envoie la demande à la fonction Lambda et renvoie la réponse de la fonction au client. Pour obtenir des exemples de création d'une API HTTP, veuillez consulter Création d'une API HTTP.

Version du format de charge utile

La version du format de charge utile spécifie le format de l'événement qu'API Gateway envoie à une intégration Lambda, ainsi que la manière dont API Gateway interprète la réponse de Lambda. Si vous ne spécifiez pas de version de format de charge utile, la dernière version est AWS Management Console utilisée par défaut. Si vous créez une intégration Lambda à l'aide du AWS CLI AWS CloudFormation, ou d'un SDK, vous devez spécifier un. payloadFormatVersion Les valeurs prises en charge sont 1.0 et 2.0.

Pour plus d'informations sur la façon de définir lepayloadFormatVersion, consultez la section create-integration. Pour plus d'informations sur la façon de déterminer la valeur payloadFormatVersion d'une intégration existante, consultez get-integration

Différences de format de charge utile

La liste suivante indique les différences entre les versions du format 1.0 et du format 2.0 de charge utile :

  • Le format 2.0 n'a pas de champs multiValueHeaders ou multiValueQueryStringParameters. Les en-têtes dupliqués sont combinés avec des virgules et inclus dans le champ headers. Les chaînes de requête en double sont combinées avec des virgules et incluses dans le champ queryStringParameters.

  • Le format 2.0 rawPath a. Si vous utilisez un mappage d'API pour connecter votre stage à un nom de domaine personnalisé, vous rawPath ne fournirez pas la valeur de mappage d'API. Utilisez le format 1.0 et accédez path au mappage d'API pour votre nom de domaine personnalisé.

  • Le format 2.0 inclut un nouveau champ cookies. Tous les en-têtes de cookie dans la demande sont combinés avec des virgules et ajoutés au champ cookies. Dans la réponse au client, chaque cookie devient un en-tête set-cookie.

Structure du format de charge utile

Les exemples suivants montrent la structure de chaque version de format de charge utile. Tous les noms d'en-tête sont en minuscules.

2.0
{
  "version": "2.0",
  "routeKey": "$default",
  "rawPath": "/my/path",
  "rawQueryString": "parameter1=value1&parameter1=value2&parameter2=value",
  "cookies": [
    "cookie1",
    "cookie2"
  ],
  "headers": {
    "header1": "value1",
    "header2": "value1,value2"
  },
  "queryStringParameters": {
    "parameter1": "value1,value2",
    "parameter2": "value"
  },
  "requestContext": {
    "accountId": "123456789012",
    "apiId": "api-id",
    "authentication": {
      "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"
        }
      }
    },
    "authorizer": {
      "jwt": {
        "claims": {
          "claim1": "value1",
          "claim2": "value2"
        },
        "scopes": [
          "scope1",
          "scope2"
        ]
      }
    },
    "domainName": "id.execute-api.us-east-1.amazonaws.com",
    "domainPrefix": "id",
    "http": {
      "method": "POST",
      "path": "/my/path",
      "protocol": "HTTP/1.1",
      "sourceIp": "192.0.2.1",
      "userAgent": "agent"
    },
    "requestId": "id",
    "routeKey": "$default",
    "stage": "$default",
    "time": "12/Mar/2020:19:03:58 +0000",
    "timeEpoch": 1583348638390
  },
  "body": "Hello from Lambda",
  "pathParameters": {
    "parameter1": "value1"
  },
  "isBase64Encoded": false,
  "stageVariables": {
    "stageVariable1": "value1",
    "stageVariable2": "value2"
  }
}
1.0
{
  "version": "1.0",
  "resource": "/my/path",
  "path": "/my/path",
  "httpMethod": "GET",
  "headers": {
    "header1": "value1",
    "header2": "value2"
  },
  "multiValueHeaders": {
    "header1": [
      "value1"
    ],
    "header2": [
      "value1",
      "value2"
    ]
  },
  "queryStringParameters": {
    "parameter1": "value1",
    "parameter2": "value"
  },
  "multiValueQueryStringParameters": {
    "parameter1": [
      "value1",
      "value2"
    ],
    "parameter2": [
      "value"
    ]
  },
  "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": "192.0.2.1",
      "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
}

Format de réponse de fonction Lambda

La version du format de charge utile détermine la structure de la réponse que votre fonction Lambda doit renvoyer.

Réponse de la fonction Lambda pour le format 1.0

Avec la version 1.0 au format, les intégrations Lambda doivent renvoyer une réponse au format JSON suivant :

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headername": "headervalue", ... },
    "multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... },
    "body": "..."
}

Réponse de la fonction Lambda pour le format 2.0

Avec la version de format 2.0, API Gateway peut déduire le format de réponse pour vous. API Gateway fait les hypothèses suivantes si votre fonction Lambda renvoie JSON valide et ne renvoie pas un statusCode:

  • isBase64Encoded est false.

  • statusCode est 200.

  • content-type est application/json.

  • body est la réponse de la fonction.

Les exemples suivants montrent la sortie d'une fonction Lambda et l'interprétation d'API Gateway.

Sortie de la fonction Lambda Interprétation d'API Gateway 
"Hello from Lambda!"
 
{
  "isBase64Encoded": false,
  "statusCode": 200,
  "body": "Hello from Lambda!",
  "headers": {
    "content-type": "application/json"
  }
}
 
{ "message": "Hello from Lambda!" }
 
{
  "isBase64Encoded": false,
  "statusCode": 200,
  "body": "{ \"message\": \"Hello from Lambda!\" }",
  "headers": {
    "content-type": "application/json"
  }
}

Pour personnaliser la réponse, votre fonction Lambda doit renvoyer une réponse au format suivant.

{
    "cookies" : ["cookie1", "cookie2"],
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headername": "headervalue", ... },
    "body": "Hello from Lambda!"
}