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à.
# Richiamo di funzione Lambda utilizzando un endpoint Gateway Amazon API
È possibile creare un'API web con un endpoint HTTP per la funzione Lambda utilizzando Amazon API Gateway. API Gateway fornisce strumenti per creare e documentare siti Web APIs che instradano le richieste HTTP verso le funzioni Lambda. È possibile proteggere l'accesso all'API con controlli di autenticazione e autorizzazione. APIs Puoi servire il traffico su Internet o essere accessibile solo all'interno del tuo VPC.
**Suggerimento**
Lambda offre due modi per richiamare una funzione tramite un endpoint HTTP: API Gateway e funzione Lambda. URLs In caso di dubbi su quale sia il metodo migliore per il tuo caso d'uso, consulta [Selezionare un metodo per richiamare la funzione Lambda tramite una richiesta HTTP](apig-http-invoke-decision.md).
Le risorse nell'API definiscono uno o più metodi, ad esempio GET o POST. I metodi hanno un'integrazione che instrada le richieste a una funzione Lambda o a un altro tipo di integrazione. È possibile definire ogni risorsa e metodo singolarmente oppure utilizzare tipi di risorse e metodi speciali per soddisfare tutte le richieste che si adattano a un modello. Una [risorsa proxy](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html) cattura tutti i percorsi sottostanti una risorsa. Il metodo `ANY` cattura tutti i metodi HTTP.
**Topics**
+ [Scelta di un tipo di API](#services-apigateway-apitypes)
+ [Aggiunta di un endpoint alla funzione Lambda](#apigateway-add)
+ [Integrazione proxy](#apigateway-proxy)
+ [Formato dell'evento](#apigateway-example-event)
+ [Formato della risposta](#apigateway-types-transforms)
+ [Permissions](#apigateway-permissions)
+ [Applicazione di esempio](#services-apigateway-samples)
+ [Il gestore di eventi di Powertools for Lambda AWS](#services-apigateway-powertools)
+ [Tutorial: uso di Lambda con Amazon API Gateway](services-apigateway-tutorial.md)
+ [Gestione degli errori con un'API di API Gateway](services-apigateway-errors.md)
+ [Selezionare un metodo per richiamare la funzione Lambda tramite una richiesta HTTP](apig-http-invoke-decision.md)
## Scelta di un tipo di API
API Gateway supporta tre tipi di funzioni APIs che richiamano funzioni Lambda:
+ [API HTTP: un'API](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html) leggera e a bassa RESTful latenza.
+ [API REST: un'API](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html) personalizzabile e ricca di funzionalità RESTful .
+ [WebSocket API](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api.html): un'API Web che mantiene connessioni persistenti con i client per comunicazioni full-duplex.
HTTP APIs e REST APIs elaborano entrambe RESTful APIs le richieste HTTP e restituiscono risposte. APIs Gli HTTP sono più recenti e sono creati con l'API API Gateway versione 2. Le seguenti funzionalità sono nuove per HTTP: APIs
**Funzionalità API HTTP**
+ **Distribuzioni automatiche**: quando si modificano routing o integrazioni, le modifiche vengono distribuite automaticamente alle fasi in cui è abilitata la distribuzione automatica.
+ **Fase predefinita**: è possibile creare una fase predefinita (`$default`) che invii le richieste nel percorso root dell'URL dell'API. Per le fasi denominate, è necessario includere il nome dello stage all'inizio del percorso.
+ **Configurazione CORS:** è possibile configurare l'API in modo da aggiungere intestazioni CORS alle risposte in uscita, invece di aggiungerle manualmente nel codice della funzione.
APIs I REST sono i classici RESTful APIs che API Gateway ha supportato sin dal lancio. APIs Attualmente REST offre più funzionalità di personalizzazione, integrazione e gestione.
**Funzionalità REST API**
+ **Tipi di integrazione**: REST APIs supporta integrazioni Lambda personalizzate. Con un'integrazione personalizzata, è possibile inviare solo il corpo della richiesta alla funzione, o applicare un modello di trasformazione al corpo della richiesta prima di inviarlo alla funzione.
+ **Controllo degli accessi**: REST APIs supporta più opzioni per l'autenticazione e l'autorizzazione.
+ **Monitoraggio e tracciamento**: REST APIs supporta il AWS X-Ray tracciamento e opzioni di registrazione aggiuntive.
Per un confronto dettagliato, consulta [Choose between HTTP APIs and REST APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html) nella *API Gateway Developer Guide*.
WebSocket APIs utilizza anche l'API API Gateway versione 2 e supporta un set di funzionalità simile. Utilizza un' WebSocket API per le applicazioni che traggono vantaggio da una connessione persistente tra il client e l'API. WebSocket APIs forniscono una comunicazione full-duplex, il che significa che sia il client che l'API possono inviare messaggi in modo continuo senza attendere una risposta.
HTTP APIs supporta un formato di eventi semplificato (versione 2.0). Per un esempio di evento da un'API HTTP, consulta [Creare integrazioni AWS Lambda proxy per HTTP APIs in API Gateway](https://docs.aws.amazon.com//apigateway/latest/developerguide/http-api-develop-integrations-lambda.html).
Per ulteriori informazioni, consulta [Creare integrazioni AWS Lambda proxy per HTTP APIs in API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html).
## Aggiunta di un endpoint alla funzione Lambda
**Per aggiungere un endpoint pubblico alla funzione Lambda**
1. Aprire la pagina [Funzioni](https://console.aws.amazon.com/lambda/home#/functions) della console Lambda.
1. Scegliere una funzione.
1. In **Function overview (Panoramica delle funzioni)**, scegliere **Add trigger (Aggiungi trigger)**.
1. Selezionare **API Gateway**.
1. Scegliere **Create an API** (Crea una nuova API) o **Use an existing API** (Usa un'API esistente).
1. **Nuova API:** per **API type** (Tipo di API), scegliere **HTTP API** (API HTTP). Per ulteriori informazioni, consulta [Scelta di un tipo di API](#services-apigateway-apitypes).
1. **API esistente:** seleziona l'API dal menu a discesa o inserisci l'ID API (ad esempio, r3pmxmplak).
1. Per **Security (Sicurezza)**, scegliere **Open (Apri)**.
1. Scegliere **Add (Aggiungi)**.
## Integrazione proxy
Gli API Gateway APIs sono composti da fasi, risorse, metodi e integrazioni. La fase e la risorsa determinano il percorso dell'endpoint:
**Formato del percorso API**
+ `/prod/`: la fase e la risorsa radice di `prod`.
+ `/prod/user`: la fase di `prod` e la risorsa di `user`.
+ `/dev/{proxy+}` – Qualunque routing della fase `dev`.
+ `/`— (HTTP APIs) La fase e la risorsa principale predefinite.
Un'integrazione Lambda mappa una combinazione di percorso e metodo HTTP a una funzione Lambda. È possibile configurare API Gateway in modo da passare il corpo della richiesta HTTP così com'è (integrazione personalizzata), o da incapsulare il corpo della richiesta in un documento che include tutte le informazioni sulla richiesta, incluse intestazioni, risorsa, percorso e metodo.
Per ulteriori informazioni, consulta [Integrazioni del proxy Lambda di API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html).
## Formato dell'evento
Amazon API Gateway richiama la funzione [in modo sincrono](invocation-sync.md) con un evento che contiene una rappresentazione JSON della richiesta HTTP. Per un'integrazione personalizzata, l'evento è il corpo della richiesta. Per un'integrazione proxy, l'evento ha una struttura definita. Per un esempio di evento proxy proveniente da una REST API di API Gateway, consulta [Formato di input di una funzione Lambda per l'integrazione del proxy](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format) nella *Guida per gli sviluppatori di API Gateway*.
## Formato della risposta
API Gateway attende una risposta dalla funzione e inoltra il risultato al chiamante. Per un'integrazione personalizzata, è possibile definire una risposta di integrazione e una risposta al metodo per convertire l'output dalla funzione a una risposta HTTP. Per un'integrazione proxy, la funzione deve rispondere con una rappresentazione della risposta in un formato specifico.
L'esempio seguente mostra un oggetto risposta da una funzione Node.js. L'oggetto risposta rappresenta una risposta HTTP riuscita che contiene un documento JSON.
**Example index.mjs: oggetto risposta di integrazione proxy (Node.js)**
```
var response = {
"statusCode": 200,
"headers": {
"Content-Type": "application/json"
},
"isBase64Encoded": false,
"multiValueHeaders": {
"X-Custom-Header": ["My value", "My other value"],
},
"body": "{\n \"TotalCodeSize\": 104330022,\n \"FunctionCount\": 26\n}"
}
```
Il runtime Lambda serializza l'oggetto di risposta in JSON e lo invia all'API. L'API analizza la risposta e la utilizza per creare una risposta HTTP, che quindi la invia al client che ha effettuato la richiesta originale.
**Example Risposta HTTP**
```
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 55
< Connection: keep-alive
< x-amzn-RequestId: 32998fea-xmpl-4268-8c72-16138d629356
< X-Custom-Header: My value
< X-Custom-Header: My other value
< X-Amzn-Trace-Id: Root=1-5e6aa925-ccecxmplbae116148e52f036
<
{
"TotalCodeSize": 104330022,
"FunctionCount": 26
}
```
## Permissions
Amazon API Gateway ottiene l'autorizzazione a richiamare la funzione dalla [policy basata su risorse](access-control-resource-based.md) della funzione. È possibile concedere l'autorizzazione a un'intera API o concedere un accesso limitato a una fase, una risorsa o un metodo.
Quando aggiungi un'API alla funzione utilizzando la console Lambda, la console API Gateway o in un modello AWS SAM , la policy basata su risorse della funzione viene aggiornata automaticamente. Di seguito è riportata una policy di funzioni di esempio.
**Example Policy di funzione**
****
```
{
"Version":"2012-10-17",
"Id": "default",
"Statement": [
{
"Sid": "nodejs-apig-functiongetEndpointPermissionProd-BWDBXMPLXE2F",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "lambda:InvokeFunction",
"Resource": "arn:aws:lambda:us-east-2:{{111122223333}}:function:nodejs-apig-function-1G3MXMPLXVXYI",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:execute-api:us-east-2:{{111122223333}}:ktyvxmpls1/*/GET/"
}
}
}
]
}
```
È possibile gestire manualmente le autorizzazioni delle policy di funzione con le seguenti operazioni API:
+ [AddPermission](https://docs.aws.amazon.com/lambda/latest/api/API_AddPermission.html)
+ [RemovePermission](https://docs.aws.amazon.com/lambda/latest/api/API_RemovePermission.html)
+ [GetPolicy](https://docs.aws.amazon.com/lambda/latest/api/API_GetPolicy.html)
Per concedere l'autorizzazione di chiamata a un'API esistente, utilizzare il comando `add-permission`. Esempio:
```
aws lambda add-permission \
--function-name my-function \
--statement-id apigateway-get --action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-east-2:123456789012:mnh1xmpli7/default/GET/"
```
Verrà visualizzato l’output seguente:
```
{
"Statement": "{\"Sid\":\"apigateway-test-2\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"apigateway.amazonaws.com\"},\"Action\":\"lambda:InvokeFunction\",\"Resource\":\"arn:aws:lambda:us-east-2:123456789012:function:my-function\",\"Condition\":{\"ArnLike\":{\"AWS:SourceArn\":\"arn:aws:execute-api:us-east-2:123456789012:mnh1xmpli7/default/GET\"}}}"
}
```
**Nota**
Se la funzione e l'API sono diverse Regioni AWS, l'identificatore di regione nell'ARN di origine deve corrispondere alla regione della funzione, non alla regione dell'API. Quando API Gateway richiama una funzione, utilizza un ARN di risorsa basato sull'ARN dell'API, ma modificato per corrispondere alla regione della funzione.
L'ARN di origine in questo esempio concede l'autorizzazione a un'integrazione nel metodo GET della risorsa root nella fase predefinita di un'API, con ID `mnh1xmpli7`. È possibile utilizzare un asterisco nell'ARN di origine per concedere autorizzazioni a più fasi, metodi o risorse.
**Modelli di risorse**
+ `mnh1xmpli7/*/GET/*`: metodo GET su tutte le risorse in tutte le fasi.
+ `mnh1xmpli7/prod/ANY/user`: metodo ANY sulla risorsa `user` nella fase `prod`.
+ `mnh1xmpli7/*/*/*`: qualsiasi metodo su tutte le risorse in tutte le fasi.
Per informazioni dettagliate sulla visualizzazione delle policy e sulla rimozione delle istruzioni, vedere [Visualizzazione delle policy IAM basate sulle risorse in Lambda](access-control-resource-based.md).
## Applicazione di esempio
L'app di esempio [API Gateway with Node.js](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/nodejs-apig) include una funzione con un AWS SAM modello che crea un'API REST con AWS X-Ray tracciamento abilitato. Include anche script per l'implementazione, il richiamo della funzione, il test dell'API e la pulizia.
## Il gestore di eventi di Powertools for Lambda AWS
Il gestore di eventi del toolkit Powertools for AWS Lambda fornisce routing, middleware, configurazione CORS, generazione di specifiche OpenAPI, convalida delle richieste, gestione degli errori e altre funzioni utili durante la scrittura di funzioni Lambda richiamate da un endpoint API Gateway (HTTP o REST). L'utilità Event Handler è disponibile per Python TypeScript e/. JavaScript Per ulteriori informazioni, vedete l'[API REST di Event Handler](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/api_gateway/) nella documentazione di *Powertools for AWS Lambda (Python)* [e l'API HTTP Event Handler](https://docs.aws.amazon.com/powertools/typescript/latest/features/event-handler/http/) nella documentazione di *Powertools* for Lambda (). AWS TypeScript
### Python
```
from aws_lambda_powertools import Logger
from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.logging import correlation_paths
from aws_lambda_powertools.utilities.typing.lambda_context import LambdaContext
app = APIGatewayRestResolver()
logger = Logger()
@app.get("/healthz")
def ping():
return {"message": "health status ok"}
@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
def lambda_handler(event: dict, context: LambdaContext) -> dict:
return app.resolve(event, context)
```
### Typescript
```
import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
import { Logger } from '@aws-lambda-powertools/logger';
import {
correlationPaths,
search,
} from '@aws-lambda-powertools/logger/correlationId';
import type { Context } from 'aws-lambda/handler';
const logger = new Logger({
correlationIdSearchFn: search,
});
const app = new Router({ logger });
app.get("/healthz", async () => {
return { message: "health status ok" };
});
export const handler = async (event: unknown, context: Context) => {
// You can continue using other utilities just as before
logger.addContext(context);
logger.setCorrelationId(event, correlationPaths.API_GATEWAY_REST);
return app.resolve(event, context);
};
```