Création d'intégrations de AWS Lambda proxy pour HTTP APIs dans API Gateway - 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.

Création d'intégrations de AWS Lambda proxy pour HTTP APIs dans API Gateway

Une intégration de proxy Lambda vous permet d’intégrer une route API avec 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 des données utiles spécifie le format de l’événement qu’API Gateway envoie à une intégration Lambda, et comment 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 configuration de la valeur payloadFormatVersion, consultez create-integration. Pour plus d’informations sur la détermination de la valeur payloadFormatVersion d’une intégration existante, consultez get-integration.

Différences des formats de données utiles

La liste suivante indique les différences entre les versions de format de données utiles 1.0 et 2.0 :

  • 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 inclut le champ rawPath. Si vous utilisez un mappage d’API pour connecter votre étape à un nom de domaine personnalisé, rawPath ne fournira pas la valeur du mappage d’API. Utilisez les formats 1.0 et path pour accéder 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 des formats de données utiles

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 de format 1.0, 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!"
}