Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Integrazioni Lambda per REST APIs in API Gateway
Puoi integrare un metodo API con una funzione Lambda tramite l'integrazione proxy Lambda o l'integrazione non proxy (personalizzata) Lambda.
Nell'integrazione proxy Lambda la configurazione richiesta è semplice. Impostare il metodo HTTP dell'integrazione su POST, l'URI dell'endpoint di integrazione sull'ARN dell'operazione di chiamata di una specifica funzione Lambda e la credenziale su un ruolo IAM con autorizzazioni per permettere ad API Gateway di chiamare la funzione Lambda per conto tuo.
Nell'integrazione non proxy Lambda, oltre alla procedura di configurazione dell'integrazione proxy, devi specificare anche il modo in cui i dati della richiesta in entrata vengono mappati alla richiesta di integrazione e il modo in cui i dati della risposta di integrazione risultante vengono mappati alla risposta del metodo.
**Topics**
+ [Integrazioni proxy Lambda in Gateway API](set-up-lambda-proxy-integrations.md)
+ [Configurazione di integrazioni personalizzate Lambda in API Gateway](set-up-lambda-custom-integrations.md)
+ [Configurazione della chiamata asincrona della funzione Lambda back-end](set-up-lambda-integration-async.md)
+ [Gestione degli errori Lambda in API Gateway](handle-errors-in-lambda-integration.md)
# Integrazioni proxy Lambda in Gateway API
La sezione seguente illustra come utilizzare un'integrazione proxy Lambda.
**Topics**
+ [Informazioni sull'integrazione proxy Lambda di API Gateway](#api-gateway-create-api-as-simple-proxy)
+ [Supporto per le intestazioni multi-valore e i parametri di stringa di query](#apigateway-multivalue-headers-and-parameters)
+ [Formato di input di una funzione Lambda per l'integrazione proxy](#api-gateway-simple-proxy-for-lambda-input-format)
+ [Formato di output di una funzione Lambda per l'integrazione proxy](#api-gateway-simple-proxy-for-lambda-output-format)
+ [Configura l'integrazione del proxy Lambda per API Gateway utilizzando il AWS CLI](set-up-lambda-proxy-integration-using-cli.md)
+ [Configurazione di una risorsa proxy con l'integrazione proxy Lambda con una definizione OpenAPI](api-gateway-set-up-lambda-proxy-integration-on-proxy-resource.md)
## Informazioni sull'integrazione proxy Lambda di API Gateway
L'integrazione proxy Lambda di Amazon API Gateway è un sistema semplice, potente e agile per creare un'API con una configurazione di un singolo metodo API. Permette al client di chiamare una singola funzione Lambda nel back-end. La funzione accede a molte risorse o funzionalità di altri AWS servizi, inclusa la chiamata ad altre funzioni Lambda.
Nell'integrazione proxy Lambda, quando un client invia una richiesta API, API Gateway passa alla funzione Lambda integrata un [oggetto evento](#api-gateway-simple-proxy-for-lambda-input-format), ad eccezione del fatto che non viene mantenuto l'ordine dei parametri della richiesta. Questi [dati di richiesta](#api-gateway-simple-proxy-for-lambda-input-format) includono intestazioni di richiesta, parametri delle stringhe di query, variabili di percorso URL, payload e dati di configurazione API. I dati di configurazione possono includere il nome della fase di distribuzione corrente, variabili di fasi, identità utente o contesto di autorizzazione (se presente). La funzione Lambda back-end analizza i dati delle richieste in entrata per stabilire la risposta da restituire. Perché API Gateway possa passare l'output Lambda come risposta API al client, la funzione Lambda deve restituire il risultato in [questo formato](#api-gateway-simple-proxy-for-lambda-output-format).
Poiché API Gateway non interviene in modo significativo tra il client e la funzione Lambda back-end per l'integrazione proxy Lambda, il client e la funzione Lambda integrata possono adattarsi alle modifiche reciproche senza alterare la configurazione di integrazione esistente dell'API. Per consentirlo, il client deve seguire i protocolli di applicazione attuati dalla funzione Lambda back-end.
Puoi configurare un'integrazione proxy Lambda per qualsiasi metodo API. Tuttavia un'integrazione proxy Lambda è più potente quando viene configurata per un metodo API che coinvolge una risorsa proxy generica. La risorsa proxy generica può essere indicata dalla speciale variabile di percorso preconfigurata `{proxy+}`, dal segnaposto del metodo catch-all `ANY` o da entrambi. Il client può passare l'input alla funzione Lambda back-end nella richiesta in entrata come parametri di richiesta o payload applicabile. I parametri di richiesta includono intestazioni, variabili di percorso URL, parametri delle stringhe di query e il payload applicabile. La funzione Lambda integrata verifica tutte le sorgenti di input prima di elaborare la richiesta e rispondere al client con messaggi di errore significativi, se manca qualcuno degli input richiesti.
Quando si chiama un metodo API integrato con il metodo HTTP generico `ANY` e la risorsa generica `{proxy+}`, il client invia una richiesta con un metodo HTTP specifico al posto di `ANY`. Il client inoltre specifica un particolare percorso URL al posto di `{proxy+}` e include eventuali intestazioni, parametri delle stringhe di query o payload applicabile necessari.
L'elenco di seguito riepiloga i comportamenti di runtime di diversi metodi API con l'integrazione proxy Lambda:
+ `ANY /{proxy+}`: per passare i dati come input alla funzione Lambda integrata, il client deve scegliere un metodo HTTP specifico, deve impostare una determinata gerarchia di percorso di risorsa e può impostare qualsiasi intestazione, parametro di stringa di query e payload applicabile.
+ `ANY /res`: per passare i dati come input alla funzione Lambda integrata, il client deve scegliere un metodo HTTP specifico e può impostare qualsiasi intestazione, parametro di stringa di query e payload applicabile.
+ `GET|POST|PUT|... /{proxy+}`: per passare i dati come input alla funzione Lambda integrata, il client può impostare una specifica gerarchia di percorso di risorsa, qualsiasi intestazione, parametro di stringa di query e payload applicabile.
+ `GET|POST|PUT|... /res/{path}/...`: per passare i dati di input alla funzione Lambda integrata, il client deve scegliere un segmento di percorso specifico (per la variabile `{path}`) e può impostare qualsiasi intestazione di richiesta, parametro di stringa di query e payload applicabile.
+ `GET|POST|PUT|... /res`: per passare i dati di input alla funzione Lambda integrata, il client può scegliere qualsiasi intestazione di richiesta, parametro di stringa di query e payload applicabile.
La risorsa proxy `{proxy+}` e quella personalizzata `{custom}` sono entrambe espresse come variabili di percorso preconfigurate. Tuttavia `{proxy+}` può fare riferimento a qualsiasi risorsa in una gerarchia di percorso, mentre `{custom}` fa riferimento solo a un segmento di percorso specifico. Ad esempio, un negozio di generi alimentari potrebbe organizzare il proprio inventario di prodotti online in base ai nomi dei reparti, alle categorie di produzione e ai tipi di prodotto. Il sito Web del negozio potrebbe quindi rappresentare i prodotti disponibili in base alle seguenti variabili di percorso preconfigurate di risorse personalizzate: `/{department}/{produce-category}/{product-type}`. Ad esempio le mele sono rappresentate da `/produce/fruit/apple` e le carote da `/produce/vegetables/carrot`. Può anche usare `/{proxy+}` per rappresentare qualsiasi reparto, categoria di produzione o tipo di prodotto che un cliente può cercare quando fa acquisti nel negozio online. Ad esempio, `/{proxy+}` può fare riferimento a uno qualsiasi degli articoli seguenti:
+ `/produce`
+ `/produce/fruit`
+ `/produce/vegetables/carrot`
Per permettere ai clienti di cercare i prodotti disponibili, la categoria di produzione e il reparto del negozio associato, puoi esporre un singolo metodo `GET /{proxy+}` con autorizzazioni di sola lettura. Allo stesso modo, per consentire a un supervisore di aggiornare l'inventario del `produce` reparto, puoi impostare un altro metodo unico di utilizzo delle `PUT /produce/{proxy+}` autorizzazioni. read/write Per consentire a un cassiere di aggiornare il totale corrente di un ortaggio, puoi impostare un `POST /produce/vegetables/{proxy+}` metodo con autorizzazioni. read/write Per consentire al gestore del negozio di eseguire qualsiasi azione possibile su qualsiasi prodotto disponibile, lo sviluppatore del negozio online può esporre il metodo con le `ANY /{proxy+}` autorizzazioni. read/write In ogni caso, al runtime il cliente o il dipendente deve selezionare un prodotto specifico di un determinato tipo in un reparto scelto, una particolare categoria di produzione in un reparto scelto o un reparto specifico.
Per ulteriori informazioni sull'impostazione delle integrazioni proxy di API Gateway, consulta [Configurazione di un'integrazione proxy mediante una risorsa proxy](api-gateway-set-up-simple-proxy.md).
Per l'integrazione proxy è necessario che il client abbia una conoscenza più dettagliata dei requisiti del back-end. Pertanto, per garantire prestazioni dell'app e un'esperienza utente ottimali, lo sviluppatore di back-end deve comunicare chiaramente allo sviluppatore del client i requisiti del back-end e fornire un sistema solido di notifica degli errori quando i requisiti non vengono soddisfatti.
## Supporto per le intestazioni multi-valore e i parametri di stringa di query
API Gateway ora supporta più intestazioni e parametri di stringa di query con lo stesso nome. Le intestazioni multi-valore, quelle con valore singolo e le intestazioni di valore e parametri possono essere combinati nelle stesse richieste e risposte. Per ulteriori informazioni, consultare [Formato di input di una funzione Lambda per l'integrazione proxy](#api-gateway-simple-proxy-for-lambda-input-format) e [Formato di output di una funzione Lambda per l'integrazione proxy](#api-gateway-simple-proxy-for-lambda-output-format).
## Formato di input di una funzione Lambda per l'integrazione proxy
Con l'integrazione proxy Lambda, API Gateway mappa l'intera richiesta client al parametro di input `event` della funzione Lambda di back-end. Nell'esempio seguente viene illustrata la struttura di un evento che API Gateway invia a un'integrazione proxy Lambda.
In questo esempio si presuppone che l’invocazione a Gateway API sia la seguente:
```
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'
```
L'output sarà simile al seguente:
```
{
"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
}
```
**Nota**
Nell'input:
La chiave `headers` può contenere solo una decina di intestazioni di valore.
La chiave `multiValueHeaders` può contenere intestazioni multi-valore e il valore di una decina di intestazioni.
Se si specificano valori sia per `headers` che per `multiValueHeaders`, API Gateway li unisce in un unico elenco. Se la stessa coppia chiave-valore viene specificata in entrambi, solo i valori di `multiValueHeaders` verranno visualizzati nell'elenco risultante.
Nell'input per la funzione Lambda back-end l'oggetto `requestContext` è una mappa di coppie chiave/valore. In ogni coppia la chiave è il nome di una proprietà della variabile [\$1context](api-gateway-mapping-template-reference.md#context-variable-reference) e il valore è il valore della proprietà. Gateway API potrebbe aggiungere nuove chiavi alla mappa.
A seconda delle funzionalità abilitate, la mappa `requestContext` può variare in base all'API. Ad esempio, nell'esempio precedente non è specificato alcun tipo di autorizzazione e di conseguenza non è presente alcuna proprietà `$context.authorizer.*` o `$context.identity.*`. Quando è specificato un tipo di autorizzazione, API Gateway passa informazioni sugli utenti autorizzati all'endpoint di integrazione in un oggetto `requestContext.identity` nel modo seguente:
+ Quando il tipo di autorizzazione è `AWS_IAM`, le informazioni sugli utenti autorizzati includono proprietà `$context.identity.*`.
+ Quando il tipo di autorizzazione è `COGNITO_USER_POOLS` (autorizzazione di Amazon Cognito), le informazioni sugli utenti autorizzati includono le proprietà `$context.identity.cognito*` e `$context.authorizer.claims.*`.
+ Quando il tipo di autorizzazione è `CUSTOM` (autorizzazione Lambda), le informazioni sugli utenti autorizzati includono `$context.authorizer.principalId` e altre proprietà `$context.authorizer.*` applicabili.
## Formato di output di una funzione Lambda per l'integrazione proxy
Nell'integrazione proxy Lambda, API Gateway richiede la funzione Lambda back-end per restituire l'output in base al seguente formato JSON:
```
{
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headerName": "headerValue", ... },
"multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
"body": "..."
}
```
Nell'output:
+ Le chiavi `headers` e `multiValueHeaders` possono non essere specificate se non devono essere restituite intestazioni di risposta aggiuntive.
+ La chiave `headers` può contenere solo una decina di intestazioni di valore.
+ La chiave `multiValueHeaders` può contenere intestazioni multi-valore e il valore di una decina di intestazioni. È possibile utilizzare la chiave `multiValueHeaders` per specificare tutte le intestazioni aggiuntive, incluse quelle con valore singolo.
+ Se si specificano valori sia per `headers` che per `multiValueHeaders`, API Gateway li unisce in un unico elenco. Se la stessa coppia chiave-valore viene specificata in entrambi, solo i valori di `multiValueHeaders` verranno visualizzati nell'elenco risultante.
Per abilitare CORS per l'integrazione proxy Lambda, devi aggiungere `Access-Control-Allow-Origin:domain-name` all'output `headers`. `domain-name` può essere `*` per qualsiasi nome di dominio. Viene eseguito il marshalling del parametro `body` di output al front-end come payload di risposta del metodo. Se `body` è un BLOB binario, puoi codificarlo come stringa con codifica Base64 impostando `isBase64Encoded` su `true` e configurando `*/*` come **Binary Media Type (Tipo multimediale binario)**. In caso contrario, puoi impostarlo su `false` o lasciarlo non specificato.
**Nota**
Per ulteriori informazioni sull'abilitazione del supporto binario, consulta [Abilitazione del supporto binario tramite la console API Gateway](api-gateway-payload-encodings-configure-with-console.md). Per un esempio di funzione Lambda, consulta [Restituzione di supporti binari da un'integrazione proxy Lambda in Gateway API](lambda-proxy-binary-media.md).
Se l'output della funzione ha un formato diverso, API Gateway restituisce una risposta di errore `502 Bad Gateway`.
Per restituire una risposta in una funzione Lambda in Node.js, è possibile utilizzare comandi come i seguenti:
+ Per ottenere un buon risultato, effettuare la chiamata a `callback(null, {"statusCode": 200, "body": "results"})`.
+ Per generare un'eccezione, chiama `callback(new Error('internal server error'))`.
+ Per un errore lato client (se, ad esempio, un parametro obbligatorio è mancante), puoi chiamare `callback(null, {"statusCode": 400, "body": "Missing parameters of ..."})` per restituire l'errore senza generare un'eccezione.
In una funzione Lambda `async` in Node.js, la sintassi equivalente è la seguente:
+ Per ottenere un buon risultato, effettuare la chiamata a `return {"statusCode": 200, "body": "results"}`.
+ Per generare un'eccezione, chiama `throw new Error("internal server error")`.
+ Per un errore lato client (se, ad esempio, un parametro obbligatorio è mancante), puoi chiamare `return {"statusCode": 400, "body": "Missing parameters of ..."}` per restituire l'errore senza generare un'eccezione.
# Configura l'integrazione del proxy Lambda per API Gateway utilizzando il AWS CLI
In questa sezione viene illustrato come usare AWS CLI per configurare un'API con l'integrazione proxy Lambda. Per istruzioni dettagliate sull'uso della console API Gateway per configurare una risorsa proxy con l'integrazione proxy Lambda, consulta [Tutorial: creazione di una REST API con un'integrazione proxy Lambda](api-gateway-create-api-as-simple-proxy-for-lambda.md).
Per questo scenario useremo la funzione Lambda di esempio seguente come back-end dell'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
};
```
Rispetto alla configurazione dell'integrazione personalizzata Lambda riportata in [Configurazione di integrazioni personalizzate Lambda in API Gateway](set-up-lambda-custom-integrations.md), l'input per questa funzione Lambda può essere espresso nei parametri e nel corpo della richiesta. Avrai maggiore libertà per permettere al client di passare gli stessi dati di input. Qui il client può passare il nome del mittente della formula di saluto come parametro della stringa di query, intestazione o proprietà del corpo. La funzione può anche supportare l'integrazione personalizzata Lambda. La configurazione dell'API è più semplice. Non devi configurare la risposta del metodo o la risposta di integrazione.
**Per configurare un'integrazione con proxy Lambda utilizzando il AWS CLI**
1. Usa il seguente [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)comando per creare un'API:
```
aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)'
```
L'output sarà simile al seguente:
```
{
"name": "HelloWorldProxy (AWS CLI)",
"id": "te6si5ach7",
"rootResourceId" : "krznpq9xpg",
"createdDate": 1508461860
}
```
In questo esempio si utilizza `id` dell’API (`te6si5ach7`) e `rootResourceId` (`krznpq9xpg`).
1. Utilizza il seguente comando [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) per creare una [risorsa](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) `/greeting` di Gateway API:
```
aws apigateway create-resource \
--rest-api-id te6si5ach7 \
--parent-id krznpq9xpg \
--path-part {proxy+}
```
L'output sarà simile al seguente:
```
{
"path": "/{proxy+}",
"pathPart": "{proxy+}",
"id": "2jf6xt",
"parentId": "krznpq9xpg"
}
```
Nel passaggio successivo si utilizza il valore `id` (`2jf6xt`) della risorsa `{proxy+}` per creare un metodo sulla risorsa `/{proxy+}`.
1. Utilizza il seguente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) per creare una richiesta di metodo `ANY` come `ANY /{proxy+}`:
```
aws apigateway put-method --rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method ANY \
--authorization-type "NONE"
```
L'output sarà simile al seguente:
```
{
"apiKeyRequired": false,
"httpMethod": "ANY",
"authorizationType": "NONE"
}
```
Questo metodo API permette al client di ricevere o inviare formule di saluto dalla funzione Lambda nel back-end.
1. Utilizza il seguente comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) per configurare l’integrazione del metodo `ANY /{proxy+}` con una funzione Lambda denominata `HelloWorld`. Questa funzione risponde alla richiesta con un messaggio `"Hello, {name}!"` se è specificato il parametro `greeter`, altrimenti con un messaggio `"Hello, World!"` se il parametro della stringa di query non è impostato.
```
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
```
**Importante**
Per le integrazioni Lambda, devi usare il metodo HTTP `POST` per la richiesta di integrazione, secondo la [specifica dell'operazione del servizio Lambda per le chiamate della funzione](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html). Il ruolo IAM `apigAwsProxyRole` deve includere policy che permettono al servizio `apigateway` di richiamare funzioni Lambda. Per ulteriori informazioni sulle autorizzazioni IAM, consultare [Modello di autorizzazione API Gateway per invocare un'API](permissions.md#api-gateway-control-access-iam-permissions-model-for-calling-api).
L'output sarà simile al seguente:
```
{
"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"
}
```
Invece di specificare un ruolo IAM per `credentials`, è possibile utilizzare il comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) per aggiungere autorizzazioni basate su risorse. Questo è ciò che fa la console API Gateway.
1. Utilizza il seguente comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) per distribuire l’API in una fase `test`.
```
aws apigateway create-deployment \
--rest-api-id te6si5ach7 \
--stage-name test
```
1. Testa l'API usando i comandi cURL seguenti in un terminale.
Chiamata dell'API con il parametro della stringa di query `?greeter=jane`:
```
curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=jane'
```
Chiamata dell'API con un parametro di intestazione `greeter:jane`:
```
curl -X GET https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \
-H 'content-type: application/json' \
-H 'greeter: jane'
```
Chiamata dell'API con un corpo `{"greeter":"jane"}`:
```
curl -X POST https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \
-H 'content-type: application/json' \
-d '{ "greeter": "jane" }'
```
In tutti i casi, l'output è una risposta 200 con il corpo seguente:
```
Hello, jane!
```
# Configurazione di una risorsa proxy con l'integrazione proxy Lambda con una definizione OpenAPI
Per configurare una risorsa proxy con il tipo di integrazione proxy Lambda, crea una risorsa API con un parametro di percorso greedy, ad esempio `/parent/{proxy+}`, e integra la risorsa con il back-end di una funzione Lambda , ad esempio `arn:aws:lambda:us-west-2:123456789012:function:SimpleLambda4ProxyResource`, nel metodo `ANY`. Il parametro di percorso greedy deve trovarsi alla fine del percorso della risorsa API. Come per una risorsa non proxy, puoi configurare la risorsa proxy usando la console API Gateway, importando un file di definizione OpenAPI o chiamando direttamente l'API REST di API Gateway.
Il file di definizione API OpenAPI mostra un esempio di API con una risorsa proxy integrata con una funzione Lambda denominata `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"
}
}
}
}
}
```
------
Nell'integrazione proxy Lambda, in fase di esecuzione, API Gateway mappa una richiesta in entrata nel parametro di input `event` della funzione Lambda. L'input include il metodo della richiesta, il percorso, le intestazioni, qualsiasi parametro della stringa di query, qualsiasi payload, il contesto associato e qualsiasi variabile di fase definita. Il formato di input viene descritto in [Formato di input di una funzione Lambda per l'integrazione proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format). Perché API Gateway possa mappare correttamente l'output di Lambda a risposte HTTP, la funzione Lambda deve restituire il risultato nel formato descritto in [Formato di output di una funzione Lambda per l'integrazione proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format).
Con l'integrazione proxy Lambda di una risorsa proxy tramite il metodo `ANY`, la singola funzione Lambda back-end funge da gestore eventi per tutte le richieste attraverso la risorsa proxy. Ad esempio, per registrare i modelli di traffico, puoi fare in modo che un dispositivo mobile invii le informazioni di posizione relative a stato, città, indirizzo ed edificio inviando una richiesta con `/state/city/street/house` nel percorso URL della risorsa proxy. La funzione Lambda back-end può quindi analizzare il percorso URL e inserire le tuple di posizione in una tabella DynamoDB.
# Configurazione di integrazioni personalizzate Lambda in API Gateway
Per mostrare come si configura l’integrazione personalizzata, o non proxy, Lambda, si crea un’API di Gateway API per esporre il metodo `GET /greeting?greeter={name}` in modo da invocare una funzione Lambda. Usa uno dei seguenti esempi di funzioni Lambda per l'API.
Usa uno dei seguenti esempi di funzioni Lambda:
------
#### [ 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
```
------
Questa funzione risponde con un messaggio `"Hello, {name}!"` se il valore del parametro `greeter` è una stringa non vuota. La funzione restituisce un messaggio `"Hello, World!"` se il valore di `greeter` è una stringa vuota. La funzione restituisce un messaggio di errore `"Missing the required greeter parameter."` se il parametro greeter non è impostato nella richiesta in ingresso. Denominiamo la funzione `HelloWorld`.
Puoi crearla nella console Lambda o tramite la AWS CLI. In questa sezione faremo riferimento alla funzione usando l'ARN seguente:
```
arn:aws:lambda:us-east-1:123456789012:function:HelloWorld
```
Con la funzione Lambda impostata nel back-end, procedi a configurare l'API.
**Per configurare l'integrazione personalizzata Lambda utilizzando il AWS CLI**
1. Usa il seguente [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)comando per creare un'API:
```
aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)'
```
L'output sarà simile al seguente:
```
{
"name": "HelloWorld (AWS CLI)",
"id": "te6si5ach7",
"rootResourceId" : "krznpq9xpg",
"createdDate": 1508461860
}
```
In questo esempio si utilizza `id` dell’API (`te6si5ach7`) e `rootResourceId` (`krznpq9xpg`).
1. Utilizza il seguente comando [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) per creare una [risorsa](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) `/greeting` di Gateway API:
```
aws apigateway create-resource \
--rest-api-id te6si5ach7 \
--parent-id krznpq9xpg \
--path-part greeting
```
L'output sarà simile al seguente:
```
{
"path": "/greeting",
"pathPart": "greeting",
"id": "2jf6xt",
"parentId": "krznpq9xpg"
}
```
Nel passaggio successivo si utilizza il valore `id` (`2jf6xt`) della risorsa `greeting` per creare un metodo sulla risorsa `/greeting`.
1. Utilizza il seguente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) per creare una richiesta di metodo 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
```
L'output sarà simile al seguente:
```
{
"apiKeyRequired": false,
"httpMethod": "GET",
"authorizationType": "NONE",
"requestParameters": {
"method.request.querystring.greeter": false
}
}
```
Questo metodo API permette al client di ricevere una formula di saluto dalla funzione Lambda nel back-end. Il parametro `greeter` è facoltativo perché il back-end deve gestire un chiamante anonimo o un chiamante autoidentificato.
1. Utilizzate il seguente [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html)comando per impostare la `200 OK` risposta alla richiesta del metodo di`GET /greeting?greeter={name}`:
```
aws apigateway put-method-response \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--status-code 200
```
1. Utilizza il seguente comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) per configurare l’integrazione del metodo `GET /greeting?greeter={name}` con una funzione Lambda denominata `HelloWorld`. La funzione risponde alla richiesta con un messaggio `"Hello, {name}!"` se è specificato il parametro `greeter`, altrimenti con `"Hello, World!"` se il parametro della stringa di query non è impostato.
```
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
```
Il modello di mappatura fornito qui traduce il parametro della stringa di query `greeter` nella proprietà `greeter` del payload JSON. Questo è necessario perché l'input di una funzione Lambda deve essere espresso nel corpo.
**Importante**
Per le integrazioni Lambda, devi usare il metodo HTTP `POST` per la richiesta di integrazione, secondo la [specifica dell'operazione del servizio Lambda per le chiamate della funzione](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html). Il parametro `uri` è l'ARN dell'operazione di chiamata della funzione.
L'output sarà simile al seguente:
```
{
"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"
}
```
Il ruolo IAM `apigAwsProxyRole` deve includere policy che permettono al servizio `apigateway` di richiamare funzioni Lambda. Invece di specificare un ruolo IAM per `credentials`, puoi chiamare il comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) per aggiungere autorizzazioni basate su risorse. Questo è il modo in cui la console API Gateway aggiunge queste autorizzazioni.
1. Utilizzate il [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html)comando seguente per impostare la risposta di integrazione per passare l'output della funzione Lambda al client come risposta del `200 OK` metodo:
```
aws apigateway put-integration-response \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--status-code 200 \
--selection-pattern ""
```
Impostando il modello di selezione su una stringa vuota, la risposta predefinita è `200 OK`.
L'output sarà simile al seguente:
```
{
"selectionPattern": "",
"statusCode": "200"
}
```
1. Utilizza il seguente comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) per distribuire l’API in una fase `test`.
```
aws apigateway create-deployment \
--rest-api-id te6si5ach7 \
--stage-name test
```
1. Testa l'API usando il comando cURL seguente in un terminale:
```
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'
```
# Configurazione della chiamata asincrona della funzione Lambda back-end
Nell'integrazione non proxy (personalizzata) Lambda la funzione Lambda back-end viene richiamata in modo sincrono per impostazione predefinita. Questo è il comportamento desiderato per la maggior parte delle operazioni API REST. Alcune applicazioni, tuttavia, richiedono che la chiamata venga effettuata in modo asincrono, ad esempio un'operazione batch o una con latenza elevata, in genere da un componente di back-end separato. In questo caso, la funzione Lambda back-end viene richiamata in modo asincrono e il metodo API REST front-end non restituisce il risultato.
Puoi configurare la funzione Lambda affinché un'integrazione non proxy Lambda venga richiamata in modo asincrono specificando `'Event'` come [tipo di chiamata Lambda](https://docs.aws.amazon.com/lambda/latest/dg/lambda-invocation.html). Questo avviene così:
## Configurazione della chiamata asincrona Lambda nella console API Gateway
Affinché tutte le invocazioni siano asincrone:
+ In **Richiesta di integrazione** aggiungi un'intestazione `X-Amz-Invocation-Type` con un valore statico `'Event'`.
Affinché i client decidano se le invocazioni sono asincrone o sincrone:
1. In **Richiesta metodo** aggiungi un'intestazione `InvocationType`.
1. In **Richiesta di integrazione** aggiungi un'intestazione `X-Amz-Invocation-Type` con un'espressione di mappatura `method.request.header.InvocationType`.
1. I client possono includere l'intestazione `InvocationType: Event` nelle richieste API per le invocazioni asincrone o `InvocationType: RequestResponse` per le invocazioni sincrone.
## Configurazione della chiamata asincrona Lambda utilizzando OpenAPI
Affinché tutte le invocazioni siano asincrone:
+ Aggiungi l'`X-Amz-Invocation-Type`intestazione alla **x-amazon-apigateway-integration**sezione.
```
"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"
}
```
Affinché i client decidano se le invocazioni sono asincrone o sincrone:
1. Aggiungi la seguente intestazione su qualsiasi [oggetto OpenAPI Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject).
```
"parameters" : [ {
"name" : "InvocationType",
"in" : "header",
"schema" : {
"type" : "string"
}
} ]
```
1. Aggiungi l'`X-Amz-Invocation-Type`intestazione alla sezione. **x-amazon-apigateway-integration**
```
"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. I client possono includere l'intestazione `InvocationType: Event` nelle richieste API per le invocazioni asincrone o `InvocationType: RequestResponse` per le invocazioni sincrone.
## Configurare la chiamata asincrona Lambda utilizzando CloudFormation
I seguenti CloudFormation modelli mostrano come configurare le chiamate asincrone. `AWS::ApiGateway::Method`
Affinché tutte le invocazioni siano asincrone:
```
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'
```
Affinché i client decidano se le invocazioni sono asincrone o sincrone:
```
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'
```
I client possono includere l'intestazione `InvocationType: Event` nelle richieste API per le invocazioni asincrone o `InvocationType: RequestResponse` per le invocazioni sincrone.
# Gestione degli errori Lambda in API Gateway
Per le integrazioni personalizzate Lambda, devi mappare gli errori restituiti da Lambda nella risposta di integrazione alle risposte di errore HTTP standard per i client. Altrimenti, gli errori Lambda vengono restituiti come risposte `200 OK` per impostazione predefinita e il risultato non è intuitivo per gli utenti dell'API.
Esistono due tipi di errore che Lambda può restituire: errori standard ed errori personalizzati. Nella tua API, devi gestirli in modo diverso.
Con l'integrazione proxy Lambda, Lambda deve restituire un output nel formato seguente:
```
{
"isBase64Encoded" : "boolean",
"statusCode": "number",
"headers": { ... },
"body": "JSON string"
}
```
In questo output, `statusCode` è in genere `4XX` per un errore del client e `5XX` per un errore del server. API Gateway gestisce questi errori mappando l'errore Lambda a una risposta di errore HTTP, in base al `statusCode` specificato. Affinché API Gateway passi il tipo di errore (ad esempio, `InvalidParameterException`), come parte della risposta al client, la funzione Lambda deve includere un'intestazione (ad esempio, `"X-Amzn-ErrorType":"InvalidParameterException"`) nella proprietà `headers`.
**Topics**
+ [Gestione degli errori Lambda standard in API Gateway](#handle-standard-errors-in-lambda-integration)
+ [Gestione degli errori Lambda personalizzati in API Gateway](#handle-custom-errors-in-lambda-integration)
## Gestione degli errori Lambda standard in API Gateway
Un AWS Lambda errore standard ha il seguente formato:
```
{
"errorMessage": "string",
"errorType": "string",
"stackTrace": [
"string",
...
]
}
```
Qui, `errorMessage` è un'espressione della stringa dell'errore. `errorType` è un tipo di eccezione o di errore dipendente dal linguaggio. `stackTrace` è un elenco di espressioni delle stringhe che mostrano la traccia dello stack che porta al verificarsi dell'errore.
Ad esempio, si consideri la seguente JavaScript funzione Lambda (Node.js).
```
export const handler = function(event, context, callback) {
callback(new Error("Malformed input ..."));
};
```
Questa funzione restituisce il seguente errore Lambda standard, contenente `Malformed input ...` come messaggio di errore:
```
{
"errorMessage": "Malformed input ...",
"errorType": "Error",
"stackTrace": [
"export const handler (/var/task/index.js:3:14)"
]
}
```
Allo stesso modo, considera la seguente funzione Python Lambda che genera un'eccezione `Exception` con lo stesso messaggio di errore `Malformed input ...`.
```
def lambda_handler(event, context):
raise Exception('Malformed input ...')
```
La funzione restituisce il seguente errore Lambda standard:
```
{
"stackTrace": [
[
"/var/task/lambda_function.py",
3,
"lambda_handler",
"raise Exception('Malformed input ...')"
]
],
"errorType": "Exception",
"errorMessage": "Malformed input ..."
}
```
Da notare che i valori delle proprietà `errorType` e `stackTrace` dipendono dal linguaggio. L'errore standard si applica anche a qualsiasi oggetto di errore che è un'estensione dell'oggetto `Error` o una sottoclasse della classe `Exception`.
Per mappare l'errore Lambda standard a una risposta del metodo, devi prima stabilire il codice di stato HTTP per un dato errore Lambda. Quindi impostate un modello di espressione regolare sulla `[selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern)` proprietà del codice di stato HTTP [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)associato al dato codice di stato HTTP. Nella console Gateway API, questo `selectionPattern` è indicato come **Espressione regolare errore Lambda** sotto ogni risposta di integrazione nella sezione **Risposta di integrazione**.
**Nota**
API Gateway usa le espressioni regolari basate sullo stile del modello Java per la mappatura della risposta. Per ulteriori informazioni, consulta [Pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) nella documentazione Oracle.
Ad esempio, utilizzate quanto segue [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html)per impostare una nuova `selectionPattern` espressione:
```
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
```
Accertati di configurare anche il codice di errore corrispondente (`400`) sulla [risposta del metodo](api-gateway-method-settings-method-response.md#setup-method-response-status-code). Altrimenti, API Gateway restituisce una risposta di errore di configurazione non valida al runtime.
**Nota**
Al runtime, API Gateway abbina l'elemento `errorMessage` dell'errore Lambda al modello dell'espressione regolare per la proprietà `selectionPattern`. Se c'è una corrispondenza, API Gateway restituisce l'errore Lambda come risposta HTTP del codice di stato HTTP corrispondente. Se non c'è corrispondenza, API Gateway restituisce l'errore come risposta predefinita oppure genera un'eccezione di configurazione non valida se non è stata configurata una risposta predefinita.
Impostare il valore `selectionPattern` su `.*` per una data risposta significa reimpostare questa risposta come risposta predefinita. Questo succede perché tale modello di selezione corrisponderà a tutti i messaggi di errore, incluso null, come, ad esempio, messaggi di errore non specificati. La mappatura che ne deriva sovrascrive la mappatura predefinita. Se si usa `.+` come modello di selezione per filtrare le risposte, potrebbe non corrispondere a una risposta contenente un carattere di nuova riga (’`\n`).
Per aggiornare un `selectionPattern` valore esistente utilizzando AWS CLI, chiamate l'[update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html)operazione per sostituire il valore del `/selectionPattern` percorso con l'espressione regex specificata del `Malformed*` pattern.
Per impostare l'espressione `selectionPattern` tramite la console Gateway API, immetti l'espressione nella casella di testo **Espressione regolare errore Lambda** quando configuri o aggiorni una risposta di integrazione di un codice di stato HTTP specifico.
## Gestione degli errori Lambda personalizzati in API Gateway
Invece dell'errore standard descritto nella sezione precedente, AWS Lambda consente di restituire un oggetto di errore personalizzato come stringa JSON. L'errore può essere qualsiasi oggetto JSON valido. Ad esempio, la seguente funzione Lambda JavaScript (Node.js) restituisce un errore personalizzato:
```
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));
};
```
Devi trasformare l'oggetto `myErrorObj` in una stringa JSON prima di chiamare `callback` per uscire dalla funzione. In caso contrario, viene restituito `myErrorObj` come stringa di `"[object Object]"`. Quando un metodo dell'API è integrato con la precedente funzione Lambda, API Gateway riceve una risposta di integrazione con il seguente payload:
```
{
"errorMessage": "{\"errorType\":\"InternalServerError\",\"httpStatus\":500,\"requestId\":\"e5849002-39a0-11e7-a419-5bb5807c9fb2\",\"trace\":{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}}"
}
```
Come nel caso delle risposte di integrazione, puoi passare questa risposta di errore invariata alla risposta di metodo. Oppure puoi avere un modello di mappatura per trasformare il payload in un formato diverso. Ad esempio, considera il seguente modello di mappatura del corpo per la risposta di un metodo del codice di stato `500`:
```
{
errorMessage: $input.path('$.errorMessage');
}
```
Questo modello traduce il corpo della risposta di integrazione che contiene la stringa JSON di errore personalizzato nel corpo di risposta del metodo seguente. Questo corpo di risposta del metodo contiene un oggetto JSON di errore personalizzato:
```
{
"errorMessage" : {
errorType : "InternalServerError",
httpStatus : 500,
requestId : context.awsRequestId,
trace : {
"function": "abc()",
"line": 123,
"file": "abc.js"
}
}
};
```
In base ai tuoi requisiti API, potresti aver bisogno di passare alcune o tutte le proprietà degli errori personalizzati come parametri dell'intestazione della risposta di metodo. Puoi farlo applicando le mappature degli errori personalizzati dal corpo della risposta di integrazione alle intestazioni della risposta di metodo.
Ad esempio, la seguente estensione OpenAPI definisce una mappatura dalle proprietà `errorMessage.errorType`, `errorMessage.httpStatus`, `errorMessage.trace.function` ed `errorMessage.trace` alle intestazioni `error_type`, `error_status`, `error_trace_function` ed `error_trace`, rispettivamente.
```
"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"
},
...
}
}
}
```
Al runtime, API Gateway deserializza il parametro `integration.response.body` nel corso delle mappature delle intestazioni. Tuttavia, questa deserializzazione si applica solo alle body-to-header mappature per le risposte di errore personalizzate Lambda e non si applica alle mappature che utilizzano. body-to-body `$input.body` Con queste mappature custom-error-body-to -header, il client riceve le seguenti intestazioni come parte della risposta del metodo, a condizione che,, e le intestazioni siano dichiarate nella richiesta del `error_status` metodo. `error_trace` `error_trace_function` `error_type`
```
"error_status":"500",
"error_trace":"{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}",
"error_trace_function":"abc()",
"error_type":"InternalServerError"
```
La proprietà `errorMessage.trace` del corpo della risposta di integrazione è una proprietà complessa. Viene mappata all'intestazione `error_trace` come una stringa JSON.