Creazione delle integrazioni proxy AWS Lambda per API HTTP in Gateway API - Amazon API Gateway
Tipo di formato payloadFormato di risposta della funzione Lambda

Creazione delle integrazioni proxy AWS Lambda per API HTTP in Gateway API

Un'integrazione proxy Lambda consente di integrare una route API con una funzione Lambda. Quando un client chiama l'API, API Gateway invia la richiesta alla funzione Lambda e restituisce la risposta della funzione al client. Per esempi di creazione di un'API HTTP, consultare Creazione di un'API HTTP.

Tipo di formato payload

La versione del formato del payload specifica il formato dell'evento che Gateway API invia a un'integrazione Lambda e il modo in cui Gateway API interpreta la risposta ricevuta da Lambda. Se non si specifica un tipo di formato payload, AWS Management Console utilizza la versione più recente per impostazione predefinita. Se si crea un'integrazione Lambda mediante la AWS CLI, AWS CloudFormation o SDK, è necessario specificare payloadFormatVersion. I valori supportati sono 1.0 e 2.0.

Per ulteriori informazioni su come impostare payloadFormatVersion, consulta create-integration. Per ulteriori informazioni su come determinare l'entità payloadFormatVersion di un'integrazione esistente, consulta get-integration.

Differenze di formato del payload

L'elenco seguente mostra le differenze tra le versioni del formato del payload 1.0 e 2.0:

  • Il formato 2.0 non contiene i campi multiValueHeaders o multiValueQueryStringParameters. Le intestazioni duplicate sono combinate con virgole e incluse nel campo headers. Le stringhe di query duplicate sono combinate con virgole e incluse nel campo queryStringParameters.

  • Il formato 2.0 include rawPath. Se si utilizza una mappatura API per collegare la fase a un nome di dominio personalizzato, rawPath non fornirà il valore di mappatura API. Utilizza il formato 1.0 e path per accedere alla mappatura API per il nome di dominio personalizzato.

  • Il formato 2.0 include un nuovo campo cookies. Tutte le intestazioni dei cookie nella richiesta vengono combinate con virgole e aggiunte al campo cookies. Nella risposta al client, ogni cookie diventa un'intestazione set-cookie.

Struttura del formato del payload

Gli esempi seguenti mostrano la struttura di ogni tipo di formato payload. Per tutti i nomi delle intestazioni si utilizzano le minuscole.

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
}

Formato di risposta della funzione Lambda

Il tipo di formato del payload determina la struttura della risposta che deve essere restituita dalla funzione Lambda.

Risposta della funzione Lambda per il formato 1.0

Con la versione di formato 1.0, le integrazioni Lambda devono restituire una risposta nel formato JSON seguente:

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

Risposta della funzione Lambda per il formato 2.0

Con il tipo di formato 2.0, API Gateway può dedurre autonomamente il formato della risposta. Se la funzione Lambda restituisce un JSON valido e non restituisce un , API Gateway fa le seguenti ipotes statusCode:

  • isBase64Encoded è false.

  • statusCode è 200.

  • content-type è application/json.

  • body è la risposta della funzione.

Gli esempi seguenti mostrano l'output di una funzione Lambda e l'interpretazione da parte di API Gateway.

Risultato della funzione Lambda Interpretazione di 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"
  }
}

Per personalizzare la risposta, la funzione Lambda deve restituire una risposta con il seguente formato.

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