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à.
# Creazione di funzioni Lambda con TypeScript
È possibile utilizzare il runtime Node.js per eseguire il TypeScript codice. AWS Lambda Poiché Node.js non esegue il TypeScript codice in modo nativo, è necessario prima traspilare il TypeScript codice in. JavaScript Quindi, usa i JavaScript file per distribuire il codice della funzione in Lambda. Il codice viene eseguito in un ambiente che include l' AWS SDK for JavaScript, con le credenziali di un ruolo AWS Identity and Access Management (IAM) che gestisci. Per ulteriori informazioni sulle versioni SDK incluse nei runtime di Node.js, consulta [Versioni SDK incluse nel runtime](lambda-nodejs.md#nodejs-sdk-included).
Lambda supporta i seguenti runtime di Node.js.
| Name | Identificatore | Sistema operativo | Data di ritiro | Blocco creazione funzioni | Blocco aggiornamento funzioni |
| --- | --- | --- | --- | --- | --- |
| Node.js 24 | `nodejs24.x` | Amazon Linux 2023 | 30 aprile 2028 | 1 giugno 2028 | 1 luglio 2028 |
| Node.js 22 | `nodejs22.x` | Amazon Linux 2023 | 30 aprile 2027 | 1 giugno 2027 | 1 luglio 2027 |
| Node.js 20 | `nodejs20.x` | Amazon Linux 2023 | 30 aprile 2026 | 31 agosto 2026 | 30 settembre 2026 |
**Topics**
+ [
## Configurazione di un TypeScript ambiente di sviluppo
](#typescript-dev)
+ [
## Definizioni dei tipi per Lambda
](#typescript-type-definitions)
+ [
# Definisci il gestore di funzioni Lambda in TypeScript
](typescript-handler.md)
+ [
# Implementa codice trascritto TypeScript in Lambda con archivi di file.zip
](typescript-package.md)
+ [
# Implementa codice trascritto TypeScript in Lambda con immagini di container
](typescript-image.md)
+ [
# Utilizzo dell'oggetto contestuale Lambda per recuperare informazioni TypeScript sulla funzione
](typescript-context.md)
+ [
# Registra e monitora le funzioni TypeScript Lambda
](typescript-logging.md)
+ [
# TypeScript Codice di tracciamento in AWS Lambda
](typescript-tracing.md)
## Configurazione di un TypeScript ambiente di sviluppo
Utilizzate un ambiente di sviluppo integrato locale (IDE) o un editor di testo per scrivere il codice TypeScript della funzione. Non puoi creare TypeScript codice sulla console Lambda.
Puoi usare [esbuild](https://esbuild.github.io/) o il TypeScript compiler (`tsc`) di Microsoft per trasporre il codice in. TypeScript JavaScript [AWS Serverless Application Model (AWS SAM)](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started.html) e [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html) usano entrambi esbuild.
Durante l'utilizzo di esbuild, considera quanto segue:
+ [Ci sono diverse avvertenze. TypeScript ](https://esbuild.github.io/content-types/#typescript-caveats)
+ È necessario configurare le impostazioni di TypeScript traspilazione in modo che corrispondano al runtime di Node.js che si intende utilizzare. Per ulteriori informazioni, consulta [Target](https://esbuild.github.io/api/#target) nella documentazione esbuild. [Per un esempio di file **tsconfig.json** che dimostra come indirizzare una versione specifica di Node.js supportata da Lambda, fai riferimento al repository. TypeScript GitHub ](https://github.com/tsconfig/bases/blob/main/bases/node14.json)
+ esbuild non esegue controlli di tipo. Per controllare i tipi, utilizza il compilatore `tsc`. Esegui `tsc -noEmit` oppure aggiungi un parametro `"noEmit"` al file **tsconfig.json** come mostrato nell'esempio seguente. Questo configura per non emettere file. `tsc` JavaScript Dopo aver controllato i tipi, usa esbuild per convertire i TypeScript file in. JavaScript
**Example tsconfig.json**
```
{
"compilerOptions": {
"target": "es2020",
"strict": true,
"preserveConstEnums": true,
"noEmit": true,
"sourceMap": false,
"module":"commonjs",
"moduleResolution":"node",
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"isolatedModules": true,
},
"exclude": ["node_modules", "**/*.test.ts"]
}
```
## Definizioni dei tipi per Lambda
Il pacchetto [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) fornisce definizioni dei tipi per le funzioni Lambda. Installa questo pacchetto quando la tua funzione utilizza uno dei seguenti elementi:
+ Fonti di AWS eventi comuni, come:
+ `APIGatewayProxyEvent`: per [integrazioni proxy Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html)
+ `SNSEvent`: per [notifiche Amazon Simple Notification Service](with-sns.md)
+ `SQSEvent`: per [messaggi Amazon Simple Queue Service](with-sqs.md)
+ `S3Event`: per [eventi di trigger S3](with-s3.md)
+ `DynamoDBStreamEvent`: per [flussi Amazon DynamoDB](with-ddb.md)
+ L’oggetto [contestuale](typescript-context.md) Lambda
+ Il modello di gestore di [callback](typescript-handler.md#typescript-handler-callback)
Per aggiungere le definizioni dei tipi Lambda alla tua funzione, installa `@types/aws-lambda` come dipendenza di sviluppo:
```
npm install -D @types/aws-lambda
```
Quindi, importa i tipi da `aws-lambda`:
```
import { Context, S3Event, APIGatewayProxyEvent } from 'aws-lambda';
export const handler = async (event: S3Event, context: Context) => {
// Function code
};
```
L'istruzione `import ... from 'aws-lambda'` importa le definizioni dei tipi. Non importa il pacchetto npm `aws-lambda`, che è uno strumento di terzi non correlato. Per ulteriori informazioni, consulta [aws-lambda nel repository](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda). DefinitelyTyped GitHub
**Nota**
Non è necessario [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) quando si utilizzano definizioni di tipo personalizzate. Per una funzione di esempio che definisce il proprio tipo per un oggetto evento, vedi [Esempio di codice della TypeScript funzione Lambda](typescript-handler.md#typescript-example-code).
# Definisci il gestore di funzioni Lambda in TypeScript
Il *gestore* di funzioni Lambda è il metodo nel codice della funzione che elabora gli eventi. Quando viene richiamata la funzione, Lambda esegue il metodo del gestore. La funzione viene eseguita fino a quando il gestore non restituisce una risposta, termina o scade.
Questa pagina descrive come utilizzare i gestori di funzioni Lambda in TypeScript, incluse le opzioni per la configurazione del progetto, le convenzioni di denominazione e le migliori pratiche. Questa pagina include anche un esempio di funzione TypeScript Lambda che raccoglie informazioni su un ordine, produce una ricevuta in un file di testo e inserisce questo file in un bucket Amazon Simple Storage Service (Amazon S3). Per informazioni su come distribuire una funzione dopo averla scritta, consulta o. [Implementa codice trascritto TypeScript in Lambda con archivi di file.zip](typescript-package.md) [Implementa codice trascritto TypeScript in Lambda con immagini di container](typescript-image.md)
**Topics**
+ [
## Configurazione del progetto TypeScript
](#typescript-handler-setup)
+ [
## Esempio di codice della TypeScript funzione Lambda
](#typescript-example-code)
+ [
## Moduli CommonJS ed ES
](#typescript-commonjs-es-modules)
+ [
## Inizializzazione di Node.js
](#typescript-initialization)
+ [
## Convenzioni di denominazione dei gestori
](#typescript-handler-naming)
+ [
## Definizione e accesso all'oggetto evento di input
](#typescript-example-input)
+ [
## Modelli di gestione validi per le funzioni TypeScript
](#typescript-handler-signatures)
+ [
## Utilizzo dell'SDK per la JavaScript versione 3 nel gestore
](#typescript-example-sdk-usage)
+ [
## Accesso alle variabili d'ambiente
](#typescript-example-envvars)
+ [
## Utilizzo dello stato globale
](#typescript-handler-state)
+ [
## Procedure consigliate di codice per le TypeScript funzioni Lambda
](#typescript-best-practices)
## Configurazione del progetto TypeScript
Utilizzate un ambiente di sviluppo integrato locale (IDE) o un editor di testo per scrivere il codice TypeScript della funzione. Non puoi creare TypeScript codice sulla console Lambda.
Esistono diversi modi per inizializzare un progetto TypeScript Lambda. [Ad esempio, puoi creare un progetto utilizzando`npm`, creare un'[AWS SAM applicazione](typescript-package.md#aws-sam-ts) o creare un'AWS CDK applicazione.](typescript-package.md#aws-cdk-ts) Per creare il progetto utilizzando`npm`:
```
npm init
```
Il codice della funzione risiede in un `.ts` file, che trascrivi in un JavaScript file in fase di compilazione. Puoi usare [esbuild](https://esbuild.github.io/) o il TypeScript compiler (`tsc`) di Microsoft in cui trasporre il codice. TypeScript JavaScript Per usare esbuild, aggiungilo come dipendenza di sviluppo:
```
npm install -D esbuild
```
Un tipico progetto di funzione TypeScript Lambda segue questa struttura generale:
```
/project-root
├── index.ts - Contains main handler
├── dist/ - Contains compiled JavaScript
├── package.json - Project metadata and dependencies
├── package-lock.json - Dependency lock file
├── tsconfig.json - TypeScript configuration
└── node_modules/ - Installed dependencies
```
## Esempio di codice della TypeScript funzione Lambda
Il seguente codice di funzione Lambda di esempio raccoglie le informazioni su un ordine, produce una ricevuta in un file di testo e inserisce questo file in un bucket Amazon S3. Questo esempio definisce un tipo di evento personalizzato (). `OrderEvent` Per informazioni su come importare le definizioni dei tipi per le sorgenti di AWS eventi, consulta [Definizioni dei tipi per Lambda](lambda-typescript.md#typescript-type-definitions).
**Nota**
Questo esempio utilizza un gestore di moduli ES. Lambda supporta sia il modulo ES che i gestori CommonJS. Per ulteriori informazioni, consulta [Moduli CommonJS ed ES](nodejs-handler.md#nodejs-commonjs-es-modules).
**Example funzione Lambda index.ts**
```
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
// Initialize the S3 client outside the handler for reuse
const s3Client = new S3Client();
// Define the shape of the input event
type OrderEvent = {
order_id: string;
amount: number;
item: string;
}
/**
* Lambda handler for processing orders and storing receipts in S3.
*/
export const handler = async (event: OrderEvent): Promise => {
try {
// Access environment variables
const bucketName = process.env.RECEIPT_BUCKET;
if (!bucketName) {
throw new Error('RECEIPT_BUCKET environment variable is not set');
}
// Create the receipt content and key destination
const receiptContent = `OrderID: ${event.order_id}\nAmount: $${event.amount.toFixed(2)}\nItem: ${event.item}`;
const key = `receipts/${event.order_id}.txt`;
// Upload the receipt to S3
await uploadReceiptToS3(bucketName, key, receiptContent);
console.log(`Successfully processed order ${event.order_id} and stored receipt in S3 bucket ${bucketName}`);
return 'Success';
} catch (error) {
console.error(`Failed to process order: ${error instanceof Error ? error.message : 'Unknown error'}`);
throw error;
}
};
/**
* Helper function to upload receipt to S3
*/
async function uploadReceiptToS3(bucketName: string, key: string, receiptContent: string): Promise {
try {
const command = new PutObjectCommand({
Bucket: bucketName,
Key: key,
Body: receiptContent
});
await s3Client.send(command);
} catch (error) {
throw new Error(`Failed to upload receipt to S3: ${error instanceof Error ? error.message : 'Unknown error'}`);
}
}
```
Questo file `index.ts` contiene le sezioni seguenti:
+ `import`block: usa questo blocco per includere le librerie richieste dalla tua funzione Lambda, come i client [AWS SDK](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/the-request-object.html).
+ `const s3Client`dichiarazione: inizializza un client [Amazon S3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/) al di fuori della funzione di gestione. Ciò fa sì che Lambda esegua questo codice durante la [fase di inizializzazione](lambda-runtime-environment.md#runtimes-lifecycle-ib) e il client viene preservato per il [riutilizzo](lambda-runtime-environment.md#execution-environment-reuse) su più chiamate.
+ `type OrderEvent`: definisce la struttura dell'evento di input previsto.
+ `export const handler`: Questa è la funzione di gestione principale richiamata da Lambda. [Quando distribuisci la funzione, specifica `index.handler` la proprietà Handler.](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html#lambda-CreateFunction-request-Handler) Il valore della `Handler` proprietà è il nome del file e il nome del metodo del gestore esportato, separati da un punto.
+ `uploadReceiptToS3`funzione: Questa è una funzione di supporto a cui fa riferimento la funzione di gestione principale.
Affinché questa funzione funzioni correttamente, il suo [ruolo di esecuzione](lambda-intro-execution-role.md) deve consentire l'azione. `s3:PutObject` Inoltre, assicuratevi di definire la variabile di `RECEIPT_BUCKET` ambiente. Dopo una chiamata riuscita, il bucket Amazon S3 dovrebbe contenere un file di ricevuta.
## Moduli CommonJS ed ES
Node.js supporta due sistemi di moduli: CommonJS e ECMAScript modules (moduli ES). [Lambda consiglia di utilizzare i moduli ES in quanto supportano l'attesa di primo livello, che consente il completamento di attività asincrone durante l'inizializzazione dell'ambiente di esecuzione.](#typescript-initialization)
Node.js tratta i file con estensione come moduli CommonJS, mentre un'`.cjs`estensione indica i moduli ES. `.mjs` Per impostazione predefinita, Node.js tratta i file con l'estensione del nome `.js` file come moduli CommonJS. È possibile configurare Node.js per trattare `.js` i file come moduli ES specificando l'`type`as `module` nel file della funzione. `package.json` Puoi configurare Node.js in Lambda per rilevare automaticamente se un `.js` file deve essere trattato come CommonJS o come modulo ES aggiungendo il `—experimental-detect-module` flag alla variabile di ambiente. `NODE_OPTIONS` Per ulteriori informazioni, consulta le funzionalità di [Experimental Node.js](lambda-nodejs.md#nodejs-experimental-features).
Gli esempi seguenti mostrano gestori di funzioni scritti utilizzando sia i moduli ES che i moduli CommonJS. Gli esempi rimanenti in questa pagina utilizzano tutti i moduli ES.
## Inizializzazione di Node.js
Node.js utilizza un I/O modello non bloccante che supporta operazioni asincrone efficienti utilizzando un ciclo di eventi. Ad esempio, se Node.js effettua una chiamata di rete, la funzione continua a elaborare altre operazioni senza bloccare una risposta di rete. Quando viene ricevuta, la risposta di rete viene inserita nella coda di callback. Le attività della coda vengono elaborate al termine dell'operazione corrente.
Lambda consiglia di utilizzare l'await di primo livello in modo che le attività asincrone avviate durante l'inizializzazione dell'ambiente di esecuzione vengano completate durante l'inizializzazione. Le attività asincrone che non vengono completate durante l'inizializzazione vengono in genere eseguite durante la prima chiamata della funzione. Ciò può causare comportamenti o errori imprevisti. Ad esempio, l'inizializzazione della funzione può effettuare una chiamata di rete per recuperare un AWS parametro da Parameter Store. Se questa attività non viene completata durante l'inizializzazione, il valore può essere nullo durante una chiamata. È inoltre possibile che si verifichi un ritardo tra l'inizializzazione e l'invoca, che può causare errori nelle operazioni che richiedono un fattore temporale. In particolare, le chiamate AWS di servizio possono basarsi su firme di richiesta sensibili al fattore tempo, con conseguenti errori nelle chiamate di servizio se la chiamata non viene completata durante la fase di inizializzazione. Il completamento delle attività durante l'inizializzazione in genere migliora le prestazioni di avvio a freddo e richiama innanzitutto le prestazioni quando si utilizza Provisioned Concurrency. Per ulteriori informazioni, consulta il nostro post sul blog [Using Node.js ES](https://aws.amazon.com/blogs/compute/using-node-js-es-modules-and-top-level-await-in-aws-lambda) modules and top-level await in. AWS Lambda
## Convenzioni di denominazione dei gestori
Quando si configura una funzione, il valore dell'impostazione [Handler](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html#lambda-CreateFunction-request-Handler) è il nome del file e il nome del metodo del gestore esportato, separati da un punto. L'impostazione predefinita per le funzioni create nella console e negli esempi in questa guida è `index.handler`. Questo indica il metodo `handler` che viene esportato dal file `index.js` o `index.mjs`.
Se si crea una funzione nella console utilizzando un nome di file o un nome del gestore di funzione diverso, è necessario modificare il nome del gestore predefinito.
**Modifica del nome del gestore funzioni (console)**
1. Apri la pagina [Funzioni](https://console.aws.amazon.com/lambda/home#/functions) della console Lambda e scegli la tua funzione.
1. Scegli la scheda **Codice**.
1. Scorri verso il basso fino al riquadro **Impostazioni di runtime** e scegli **Modifica**.
1. In **Gestore**, inserisci il nuovo nome per il tuo gestore di funzioni.
1. Scegli **Save** (Salva).
## Definizione e accesso all'oggetto evento di input
JSON è il formato di input più comune e standard per le funzioni Lambda. In questo esempio, la funzione prevede un input simile a quanto segue:
```
{
"order_id": "12345",
"amount": 199.99,
"item": "Wireless Headphones"
}
```
Quando si utilizzano le funzioni Lambda in TypeScript, è possibile definire la forma dell'evento di input utilizzando un tipo o un'interfaccia. In questo esempio, definiamo la struttura dell'evento utilizzando un tipo:
```
type OrderEvent = {
order_id: string;
amount: number;
item: string;
}
```
Dopo aver definito il tipo o l'interfaccia, usala nella firma del gestore per garantire la sicurezza del tipo:
```
export const handler = async (event: OrderEvent): Promise => {
```
Durante la compilazione, TypeScript verifica che l'oggetto evento contenga i campi obbligatori con i tipi corretti. Ad esempio, il TypeScript compilatore segnala un errore se si tenta di utilizzare `event.order_id` come numero o `event.amount` come stringa.
## Modelli di gestione validi per le funzioni TypeScript
[Si consiglia di utilizzare [async/await](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/using-async-await.html) per dichiarare il gestore della funzione invece di utilizzare i callback.](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/using-a-callback-function.html) Async/await è un modo conciso e leggibile per scrivere codice asincrono, senza la necessità di callback annidati o di concatenare promesse. Con async/await puoi scrivere codice che si legga come codice sincrono, pur rimanendo asincrono e privo di blocchi.
Gli esempi in questa sezione utilizzano il tipo. `S3Event` Tuttavia, puoi utilizzare qualsiasi altro tipo di AWS evento nel pacchetto [@types /aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) o definire il tuo tipo di evento. Per utilizzare i tipi di: @types/aws-lambda
1. Aggiungi il @types/aws-lambda pacchetto come dipendenza di sviluppo:
```
npm install -D @types/aws-lambda
```
1. Importa i tipi di cui hai bisogno, ad esempio `Context``S3Event`, o`Callback`.
### gestori di funzioni asincrone (consigliati)
La parola chiave `async` contrassegna una funzione come asincrona, mentre la parola chiave `await` mette in pausa l'esecuzione della funzione fino alla risoluzione di `Promise`. Il gestore accetta i seguenti argomenti:
+ `event`: contiene i dati di input passati alla funzione.
+ `context`: contiene informazioni sull'invocazione, sulla funzione e sull'ambiente di esecuzione. Per ulteriori informazioni, consulta [Utilizzo dell'oggetto contestuale Lambda per recuperare informazioni TypeScript sulla funzione](typescript-context.md).
Ecco le firme valide per il pattern: async/await
```
export const handler = async (event: S3Event): Promise => { };
```
```
export const handler = async (event: S3Event, context: Context): Promise => { };
```
**Nota**
Quando elabori matrici di elementi in modo asincrono, assicurati di utilizzare await with `Promise.all` per garantire il completamento di tutte le operazioni. Metodi come `forEach` don't wait che i callback asincroni vengano completati. Per ulteriori informazioni, consulta la sezione [Array.prototype.forEach()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) nella documentazione di Mozilla.
### Gestori di funzioni sincroni
Se la funzione non esegue attività asincrone, è possibile utilizzare un gestore di funzioni sincrono, utilizzando una delle seguenti firme di funzione:
```
export const handler = (event: S3Event): void => { };
```
```
export const handler = (event: S3Event, context: Context): void => { };
```
### Gestori di funzioni di streaming delle risposte
Lambda supporta lo streaming delle risposte con Node.js. I gestori delle funzioni di streaming delle risposte utilizzano il decoratore AWSLambda.streamifyResponse () e accettano 3 parametri: event, responseStream e context. La firma della funzione è:
```
export const handler = awslambda.streamifyResponse(async (event: APIGatewayProxyEvent, responseStream: NodeJS.WritableStream, context: Context) => { });
```
Per ulteriori informazioni, consulta Response streaming per le funzioni Lambda.
### Gestori di funzioni basati su callback
**Nota**
I gestori di funzioni basati su callback sono supportati solo fino a Node.js 22. A partire da Node.js 24, le attività asincrone devono essere implementate utilizzando gestori di funzioni asincrone.
I gestori di funzioni basati su callback possono utilizzare gli argomenti event, context e callback. L'argomento callback prevede una risposta e una, che deve essere serializzabile in `Error` formato JSON.
Ecco la firma valida per il pattern del gestore di callback:
```
export const handler = (event: S3Event, context: Context, callback: Callback): void => { };
```
La funzione continua a essere eseguita fino a quando il [ciclo di eventi](https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/) non è vuoto o la funzione scade. La risposta non viene inviata all'invoker finché tutte le attività del ciclo di eventi non giungono a termine. Se la funzione va in timeout, viene invece restituito un errore. È possibile configurare il runtime per inviare immediatamente la risposta impostando il [contesto. callbackWaitsForEmptyEventLoop](typescript-context.md)a false.
**Example TypeScript funzione con callback**
L'esempio seguente utilizza`APIGatewayProxyCallback`, che è un tipo di callback specializzato specifico per le integrazioni API Gateway. La maggior parte delle fonti di AWS eventi utilizza il `Callback` tipo generico mostrato nelle firme precedenti.
```
import { Context, APIGatewayProxyCallback, APIGatewayEvent } from 'aws-lambda';
export const lambdaHandler = (event: APIGatewayEvent, context: Context, callback: APIGatewayProxyCallback): void => {
console.log(`Event: ${JSON.stringify(event, null, 2)}`);
console.log(`Context: ${JSON.stringify(context, null, 2)}`);
callback(null, {
statusCode: 200,
body: JSON.stringify({
message: 'hello world',
}),
});
};
```
## Utilizzo dell'SDK per la JavaScript versione 3 nel gestore
Spesso, utilizzerai le funzioni Lambda per interagire o aggiornare altre AWS risorse. Il modo più semplice per interfacciarsi con queste risorse consiste nell'utilizzare il AWS SDK per JavaScript. Tutti i runtime Lambda Node.js supportati includono l'[SDK per la versione](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/introduction/) 3. JavaScript Tuttavia, consigliamo vivamente di includere i client AWS SDK necessari nel pacchetto di distribuzione. Ciò massimizza la [compatibilità con le versioni precedenti durante](runtimes-update.md#runtime-update-compatibility) i futuri aggiornamenti del runtime Lambda.
Per aggiungere dipendenze SDK alla tua funzione, usa il `npm install` comando per i client SDK specifici di cui hai bisogno. Nel codice di esempio, abbiamo usato il client [Amazon S3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/). Aggiungi questa dipendenza eseguendo il comando seguente nella directory che contiene il `package.json` file:
```
npm install @aws-sdk/client-s3
```
Nel codice della funzione, importate il client e i comandi necessari, come dimostra la funzione di esempio:
```
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
```
Quindi, inizializza un client [Amazon S3:](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/)
```
const s3Client = new S3Client();
```
In questo esempio, abbiamo inizializzato il nostro client Amazon S3 all’esterno della funzione del gestore principale per evitare di doverlo inizializzare ogni volta che invochiamo la nostra funzione. Dopo aver inizializzato il client SDK, puoi utilizzarlo per effettuare chiamate API per quel servizio. AWS Il codice di esempio richiama l'azione dell'[PutObject](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/command/PutObjectCommand/)API Amazon S3 nel modo seguente:
```
const command = new PutObjectCommand({
Bucket: bucketName,
Key: key,
Body: receiptContent
});
```
## Accesso alle variabili d'ambiente
Nel codice del gestore, puoi fare riferimento a qualsiasi [variabile di ambiente utilizzando](configuration-envvars.md). `process.env` In questo esempio, facciamo riferimento alla variabile di ambiente `RECEIPT_BUCKET` definita utilizzando le seguenti righe di codice:
```
// Access environment variables
const bucketName = process.env.RECEIPT_BUCKET;
if (!bucketName) {
throw new Error('RECEIPT_BUCKET environment variable is not set');
}
```
## Utilizzo dello stato globale
Lambda esegue il codice statico durante la [fase di inizializzazione](lambda-runtime-environment.md#runtimes-lifecycle-ib) prima di richiamare la funzione per la prima volta. Le risorse create durante l'inizializzazione restano in memoria tra le invocazioni, in modo da evitare di doverle creare ogni volta che si invoca la funzione.
Nel codice di esempio, il codice di inizializzazione del client S3 è esterno al gestore. Il runtime inizializza il client prima che la funzione gestisca il primo evento e il client rimane disponibile per il riutilizzo in tutte le chiamate.
## Procedure consigliate di codice per le TypeScript funzioni Lambda
Segui queste linee guida durante la creazione di funzioni Lambda:
+ **Separare il gestore Lambda dalla logica principale.** In questo modo è possibile creare una funzione di cui è più semplice eseguire l'unit test.
+ **Controllare le dipendenze nel pacchetto di distribuzione della funzione. ** L'ambiente di AWS Lambda esecuzione contiene diverse librerie. Per i runtime Node.js e Python, questi includono. AWS SDKs Per abilitare il set di caratteristiche e aggiornamenti della sicurezza più recenti, Lambda aggiorna periodicamente tali librerie. Tali aggiornamenti possono introdurre lievi modifiche al comportamento della funzione Lambda. Per mantenere il controllo completo delle dipendenze utilizzate dalla funzione, inserire tutte le dipendenze nel pacchetto di implementazione.
+ **Ridurre la complessità delle dipendenze.** Preferire framework più semplici che si caricano velocemente all'avvio del [contesto di esecuzione](lambda-runtime-environment.md).
+ **Ridurre al minimo le dimensioni del pacchetto di implementazione al fine di soddisfare le esigenze di runtime. ** In questo modo viene ridotta la quantità di tempo necessaria per il download del pacchetto e per la relativa decompressione prima dell'invocazione.
**Sfruttare il riutilizzo del contesto di esecuzione per migliorare le prestazioni della funzione.** Inizializzare i client SDK e le connessioni al database all'esterno del gestore di funzioni e memorizzare localmente nella cache gli asset statici nella directory `/tmp`. Le chiamate successive elaborate dalla stessa istanza della funzione possono riutilizzare queste risorse. Ciò consente di risparmiare sui costi riducendo i tempi di esecuzione delle funzioni.
Per evitare potenziali perdite di dati tra le chiamate, non utilizzare il contesto di esecuzione per archiviare dati utente, eventi o altre informazioni con implicazioni di sicurezza. Se la funzione si basa su uno stato mutabile che non può essere archiviato in memoria all'interno del gestore, considerare la possibilità di creare una funzione separata o versioni separate di una funzione per ogni utente.
**Utilizzare una direttiva keep-alive per mantenere le connessioni persistenti.** Lambda elimina le connessioni inattive nel tempo. Se si tenta di riutilizzare una connessione inattiva quando si richiama una funzione, si verificherà un errore di connessione. Per mantenere la connessione persistente, utilizzare la direttiva keep-alive associata al runtime. Per un esempio, vedere [Riutilizzo delle connessioni con Keep-Alive in Node.js](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/node-reusing-connections.html).
**Utilizzare [le variabili di ambiente](configuration-envvars.md) per passare i parametri operativi alla funzione.** Se ad esempio si scrive in un bucket Amazon S3 anziché impostare come hard-coded il nome del bucket in cui si esegue la scrittura, configurare tale nome come una variabile di ambiente.
**Evita di usare invocazioni ricorsive** nella tua funzione Lambda, in cui la funzione si richiama da sola o avvia un processo che potrebbe richiamare nuovamente la funzione. Ciò potrebbe provocare un volume non desiderato di invocazioni della funzione e un aumento dei costi. Se noti un volume indesiderato di invocazioni, imposta immediatamente la simultaneità riservata della funzione su `0` per interrompere tutte le invocazioni della funzione mentre si aggiorna il codice.
**Non utilizzare documenti non documentati e non pubblici APIs** nel codice della funzione Lambda. Per i runtime AWS Lambda gestiti, Lambda applica periodicamente aggiornamenti di sicurezza e funzionalità all'interno di Lambda. APIs Questi aggiornamenti delle API interne possono essere incompatibili con le versioni precedenti e portare a conseguenze indesiderate, come errori di chiamata se la funzione dipende da questi elementi non pubblici. APIs [Consulta il riferimento alle API per un elenco di quelle disponibili al pubblico.](https://docs.aws.amazon.com/lambda/latest/api/welcome.html) APIs
**Scrivi un codice idempotente.** La scrittura di un codice idempotente per le tue funzioni garantisce che gli eventi duplicati vengano gestiti allo stesso modo. Il tuo codice dovrebbe convalidare correttamente gli eventi e gestire con garbo gli eventi duplicati. Per ulteriori informazioni, consulta [Come posso rendere idempotente la mia funzione Lambda?](https://aws.amazon.com/premiumsupport/knowledge-center/lambda-function-idempotent/).
# Implementa codice trascritto TypeScript in Lambda con archivi di file.zip
Prima di poter distribuire il TypeScript codice in AWS Lambda, devi trasporlo in. JavaScript Questa pagina spiega tre modi per creare e distribuire TypeScript codice in Lambda con archivi di file.zip:
+ [Usare () AWS Serverless Application ModelAWS SAM](#aws-sam-ts)
+ [Usando il AWS Cloud Development Kit (AWS CDK)](#aws-cdk-ts)
+ [Usando AWS Command Line Interface (AWS CLI) ed esbuild](#aws-cli-ts)
AWS SAM e AWS CDK semplifica la creazione e l'implementazione delle funzioni. TypeScript La [specifica del AWS SAM modello](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification.html) fornisce una sintassi semplice e chiara per descrivere le funzioni APIs, le autorizzazioni, le configurazioni e gli eventi Lambda che costituiscono l'applicazione serverless. [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/home.html) consente di creare applicazioni affidabili, scalabili e convenienti nel cloud con la notevole potenza espressiva di un linguaggio di programmazione. AWS CDK È destinato a utenti con esperienza da moderata a elevata. AWS Sia gli che AWS CDK i AWS SAM usano esbuild per trascrivere il codice TypeScript in. JavaScript
## Utilizzo AWS SAM per distribuire TypeScript codice in Lambda
Segui i passaggi seguenti per scaricare, creare e distribuire un' TypeScript applicazione Hello World di esempio utilizzando. AWS SAM Questa applicazione implementa un backend API di base. Consiste in un endpoint Gateway Amazon API e in una funzione Lambda. Quando si invia una richiesta GET all'endpoint API Gateway, viene richiamata la funzione Lambda. La funzione restituisce un messaggio `hello world`.
**Nota**
AWS SAM usa esbuild per creare le funzioni Lambda di Node.js TypeScript dal codice. il supporto di esbuild è attualmente in anteprima pubblica. Durante l'anteprima pubblica, il supporto di esbuild potrebbe essere soggetto a modifiche incompatibili con il passato.
**Prerequisiti**
Per completare le fasi riportate in questa sezione, è necessario:
+ [AWS CLI versione 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS SAM CLI versione 1.75 o successiva](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html)
+ Node.js
**Implementa un'applicazione di esempio AWS SAM**
1. Inizializza l'applicazione utilizzando il modello Hello World. TypeScript
```
sam init --app-template hello-world-typescript --name sam-app --package-type Zip --runtime nodejs24.x
```
1. (Facoltativo) L'applicazione di esempio include configurazioni per strumenti di uso comune, come per il linting del codice e [Jest [ESLlint](https://eslint.org/)](https://jestjs.io/)per il test delle unità. Per eseguire i comandi lint e test:
```
cd sam-app/hello-world
npm install
npm run lint
npm run test
```
1. Costruisci l'app.
```
cd sam-app
sam build
```
1. Distribuire l'app.
```
sam deploy --guided
```
1. Seguire le istruzioni visualizzate sullo schermo. Per accettare le opzioni predefinite fornite nell'esperienza interattiva, rispondi con `Enter`.
1. L'output mostra l'endpoint per la REST API. Apri l'endpoint in un browser per testare la funzione. Dovresti vedere questa risposta:
```
{"message":"hello world"}
```
1. Questo è un endpoint API pubblico accessibile su Internet. È consigliabile eliminare l'endpoint dopo il test.
```
sam delete
```
## Utilizzo di AWS CDK per distribuire il TypeScript codice in Lambda
Segui i passaggi seguenti per creare e distribuire un' TypeScript applicazione di esempio utilizzando. AWS CDK Questa applicazione implementa un backend API di base. È costituito da un endpoint API Gateway e da una funzione Lambda. Quando si invia una richiesta GET all'endpoint API Gateway, viene richiamata la funzione Lambda. La funzione restituisce un messaggio `hello world`.
**Prerequisiti**
Per completare le fasi riportate in questa sezione, è necessario:
+ [AWS CLI versione 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS CDK versione 2](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites)
+ Node.js
+ [Docker](https://www.docker.com/get-started/) o [esbuild](https://esbuild.github.io/)
**Implementa un'applicazione di esempio AWS CDK**
1. Crea una directory di progetto per la nuova applicazione.
```
mkdir hello-world
cd hello-world
```
1. Inizializza l'app.
```
cdk init app --language typescript
```
1. Aggiungi il pacchetto [@types /aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) come dipendenza di sviluppo. Questo pacchetto contiene le definizioni dei tipi per Lambda.
```
npm install -D @types/aws-lambda
```
1. Apri la directory **lib**. Dovresti vedere un file chiamato **hello-world-stack.ts.** Crea due nuovi file in questa directory: **hello-world.function.ts** e **hello-world.ts**.
1. Apri **hello-world.function.ts** e aggiungi il seguente codice al file. Questo è il codice per la funzione Lambda.
**Nota**
L'istruzione `import` importa le definizioni dei tipi da [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda). Non importa il pacchetto NPM `aws-lambda`, che è uno strumento di terzi non correlato. Per ulteriori informazioni, consulta [aws-lambda](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda) nel repository. DefinitelyTyped GitHub
```
import { Context, APIGatewayProxyResult, APIGatewayEvent } from 'aws-lambda';
export const handler = async (event: APIGatewayEvent, context: Context): Promise => {
console.log(`Event: ${JSON.stringify(event, null, 2)}`);
console.log(`Context: ${JSON.stringify(context, null, 2)}`);
return {
statusCode: 200,
body: JSON.stringify({
message: 'hello world',
}),
};
};
```
1. Apri **hello-world.ts** e aggiungi il seguente codice al file. Contiene il [NodejsFunction costrutto](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html), che crea la funzione Lambda, e il costrutto, che crea [LambdaRestApi l'](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.LambdaRestApi.html)API REST.
```
import { Construct } from 'constructs';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
import { LambdaRestApi } from 'aws-cdk-lib/aws-apigateway';
export class HelloWorld extends Construct {
constructor(scope: Construct, id: string) {
super(scope, id);
const helloFunction = new NodejsFunction(this, 'function');
new LambdaRestApi(this, 'apigw', {
handler: helloFunction,
});
}
}
```
Il costrutto `NodejsFunction` presuppone quanto segue per impostazione predefinita:
+ Viene richiamato il gestore di funzioni `handler`.
+ Il file .ts che contiene il codice funzione (**hello-world.function.ts**) si trova nella stessa directory del file .ts che contiene il costrutto (**hello-world.ts**). Il costrutto utilizza l'ID del costrutto ("hello-world") e il nome del file del gestore Lambda ("funzione") per trovare il codice funzione. Ad esempio, se il codice funzione si trova in un file chiamato **hello-world.my-function.ts**, il file **hello-world.ts** deve fare riferimento al codice funzione in questo modo:
```
const helloFunction = new NodejsFunction(this, 'my-function');
```
È possibile modificare questo comportamento e configurare altri parametri esbuild. Per ulteriori informazioni, consulta [Configurazione di esbuild](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html#configuring-esbuild) nel riferimento all'API. AWS CDK
1. **Apri .tshello-world-stack.** Questo è il codice che definisce lo [stack AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/stacks.html). Sostituisci il codice con il seguente:
```
import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { HelloWorld } from './hello-world';
export class HelloWorldStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
new HelloWorld(this, 'hello-world');
}
}
```
1. dalla directory `hello-world` contenente il file `cdk.json`, implementa l'applicazione.
```
cdk deploy
```
1. AWS CDK Compila e impacchetta la funzione Lambda utilizzando esbuild, quindi distribuisce la funzione nel runtime Lambda. L'output mostra l'endpoint per la REST API. Apri l'endpoint in un browser per testare la funzione. Dovresti vedere questa risposta:
```
{"message":"hello world"}
```
Questo è un endpoint API pubblico accessibile su Internet. È consigliabile eliminare l'endpoint dopo il test.
## Utilizzo di AWS CLI ed esbuild per distribuire il TypeScript codice in Lambda
L'esempio seguente dimostra come traspilare e distribuire codice in TypeScript Lambda utilizzando esbuild e. esbuild produce un file con tutte le AWS CLI dipendenze. JavaScript Questo è l'unico file che devi aggiungere all'archivio .zip.
**Prerequisiti**
Per completare le fasi riportate in questa sezione, è necessario:
+ [AWS CLI versione 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ Node.js
+ Un [ruolo di esecuzione](lambda-intro-execution-role.md) per la funzione Lambda
+ Per gli utenti Windows, un'utilità di file zip come [7zip](https://www.7-zip.org/download.html).
**Implementare una funzione di esempio**
1. Sul tuo computer locale, crea una directory di progetto per la nuova funzione.
1. Crea un nuovo progetto Node.js con npm o un gestore di pacchetti di tua scelta.
```
npm init
```
1. Aggiungi i pacchetti [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) e [esbuild](https://esbuild.github.io/) come dipendenze di sviluppo. Il pacchetto `@types/aws-lambda` contiene le definizioni dei tipi per Lambda.
```
npm install -D @types/aws-lambda esbuild
```
1. Crea un nuovo file denominato **index.ts**. Aggiungi il seguente codice al nuovo file. Questo è il codice per la funzione Lambda. La funzione restituisce un messaggio `hello world`. La funzione non crea risorse API Gateway.
**Nota**
L'istruzione `import` importa le definizioni dei tipi da [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda). Non importa il pacchetto NPM `aws-lambda`, che è uno strumento di terzi non correlato. Per ulteriori informazioni, consulta [aws-lambda nel repository](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda). DefinitelyTyped GitHub
```
import { Context, APIGatewayProxyResult, APIGatewayEvent } from 'aws-lambda';
export const handler = async (event: APIGatewayEvent, context: Context): Promise => {
console.log(`Event: ${JSON.stringify(event, null, 2)}`);
console.log(`Context: ${JSON.stringify(context, null, 2)}`);
return {
statusCode: 200,
body: JSON.stringify({
message: 'hello world',
}),
};
};
```
1. Aggiungi uno script di compilazione al file **package.json**. esbuild viene configurato per creare automaticamente il pacchetto di implementazione .zip. Per ulteriori informazioni, consulta la sezione relativa alla [compilazione degli script](https://esbuild.github.io/getting-started/#build-scripts) nella documentazione di esbuild.
------
#### [ Linux and MacOS ]
```
"scripts": {
"prebuild": "rm -rf dist",
"build": "esbuild index.ts --bundle --minify --sourcemap --platform=node --target=es2020 --outfile=dist/index.js",
"postbuild": "cd dist && zip -r index.zip index.js*"
},
```
------
#### [ Windows ]
In questo esempio, il comando `"postbuild"` utilizza l'utilità [7zip](https://www.7-zip.org/download.html) per creare il file con estensione .zip. Utilizza l'utilità zip di Windows preferita e modifica il comando secondo necessità.
```
"scripts": {
"prebuild": "del /q dist",
"build": "esbuild index.ts --bundle --minify --sourcemap --platform=node --target=es2020 --outfile=dist/index.js",
"postbuild": "cd dist && 7z a -tzip index.zip index.js*"
},
```
------
1. Creare il pacchetto.
```
npm run build
```
1. Crea una funzione Lambda utilizzando il pacchetto di implementazione .zip. Sostituisci il testo evidenziato con l'Amazon Resource Name (ARN) del tuo [ruolo di esecuzione](lambda-intro-execution-role.md).
```
aws lambda create-function --function-name hello-world --runtime "nodejs24.x" --role arn:aws:iam::123456789012:role/lambda-ex --zip-file "fileb://dist/index.zip" --handler index.handler
```
1. [Esegui un evento di test](testing-functions.md) per confermare che la funzione restituisca la risposta seguente. Se desideri richiamare questa funzione utilizzando API Gateway, [crea e configura una REST API](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-create-api.html).
```
{
"statusCode": 200,
"body": "{\"message\":\"hello world\"}"
}
```
# Implementa codice trascritto TypeScript in Lambda con immagini di container
[Puoi distribuire il TypeScript codice in una AWS Lambda funzione come immagine del contenitore Node.js.](images-create.md) AWS fornisce [immagini di base](nodejs-image.md#nodejs-image-base) per Node.js per aiutarti a creare l'immagine del contenitore. Queste immagini di base sono precaricate con un runtime del linguaggio e altri componenti necessari per eseguire l'immagine su Lambda. AWS fornisce un Dockerfile per ciascuna delle immagini di base per facilitare la creazione dell'immagine del contenitore.
Se si utilizza un'immagine di base di community o aziendale privata, è necessario [aggiungere il client di interfaccia di runtime (RIC) Node.js](nodejs-image.md#nodejs-image-clients) all'immagine di base per renderla compatibile con Lambda.
Lambda fornisce un emulatore di interfaccia di runtime per i test in locale. Le immagini di AWS base per Node.js includono l'emulatore di interfaccia di runtime. Se utilizzi un'immagine di base alternativa, come Alpine Linux o Debian, puoi [creare il simulatore nella tua immagine](https://github.com/aws/aws-lambda-runtime-interface-emulator/?tab=readme-ov-file#build-rie-into-your-base-image) o[ installarlo sul tuo computer locale](https://github.com/aws/aws-lambda-runtime-interface-emulator/?tab=readme-ov-file#test-an-image-without-adding-rie-to-the-image).
## Utilizzo di un'immagine di base Node.js per creare e impacchettare il codice TypeScript funzionale
### Prerequisiti
Per completare le fasi riportate in questa sezione, è necessario:
+ [AWS CLI versione 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [Docker](https://docs.docker.com/get-docker) (versione minima 25.0.0)
+ Il [plugin buildx](https://github.com/docker/buildx/blob/master/README.md) di Docker.
+ Node.js 22.x
### Creazione di un'immagine da un'immagine di base
**Per creare un'immagine da un'immagine di AWS base per Lambda**
1. Sul tuo computer locale, crea una directory di progetto per la nuova funzione.
1. Crea un nuovo progetto Node.js con `npm` o un gestore di pacchetti a tua scelta.
```
npm init
```
1. Aggiungi i pacchetti [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) e [esbuild](https://esbuild.github.io/) come dipendenze di sviluppo. Il pacchetto `@types/aws-lambda` contiene le definizioni dei tipi per Lambda.
```
npm install -D @types/aws-lambda esbuild
```
1. Aggiungi uno [script di compilazione](https://esbuild.github.io/getting-started/#build-scripts) al file `package.json`.
```
"scripts": {
"build": "esbuild index.ts --bundle --minify --sourcemap --platform=node --target=es2020 --outfile=dist/index.js"
}
```
1. Crea un nuovo file denominato `index.ts`. Aggiungi il codice di esempio seguente al nuovo file. Questo è il codice per la funzione Lambda. La funzione restituisce un messaggio `hello world`.
**Nota**
L'istruzione `import` importa le definizioni dei tipi da [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda). Non importa il pacchetto NPM `aws-lambda`, che è uno strumento di terzi non correlato. Per ulteriori informazioni, consulta [aws-lambda](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda) nel repository. DefinitelyTyped GitHub
```
import { Context, APIGatewayProxyResult, APIGatewayEvent } from 'aws-lambda';
export const handler = async (event: APIGatewayEvent, context: Context): Promise => {
console.log(`Event: ${JSON.stringify(event, null, 2)}`);
console.log(`Context: ${JSON.stringify(context, null, 2)}`);
return {
statusCode: 200,
body: JSON.stringify({
message: 'hello world',
}),
};
};
```
1. Crea un nuovo Dockerfile con la seguente configurazione:
+ Imposta la proprietà `FROM` sull'URI dell'immagine di base.
+ Imposta l'argomento `CMD` per specificare il gestore della funzione Lambda.
Il seguente Dockerfile di esempio utilizza una build multi-fase. Il primo passaggio trascrive il codice in. TypeScript JavaScript Il secondo passaggio produce un'immagine del contenitore che contiene solo JavaScript file e dipendenze di produzione.
Nota che l'esempio Dockerfile non include un'[istruzione USER](https://docs.docker.com/reference/dockerfile/#user). Quando implementi un'immagine di container su Lambda, Lambda definisce automaticamente un utente Linux predefinito con autorizzazioni con privilegi minimi. Questo è diverso dal comportamento standard di Docker, che per impostazione predefinita è l'utente `root` quando non viene fornita alcuna istruzione `USER`.
**Example Dockerfile**
```
FROM public.ecr.aws/lambda/nodejs:22 as builder
WORKDIR /usr/app
COPY package.json index.ts ./
RUN npm install
RUN npm run build
FROM public.ecr.aws/lambda/nodejs:22
WORKDIR ${LAMBDA_TASK_ROOT}
COPY --from=builder /usr/app/dist/* ./
CMD ["index.handler"]
```
1. Crea l'immagine Docker con il comando [docker build](https://docs.docker.com/engine/reference/commandline/build/). L'esempio seguente assegna un nome all'immagine `docker-image` e le assegna il [tag](https://docs.docker.com/engine/reference/commandline/build/#tag) `test`. Per rendere l'immagine compatibile con Lambda, è necessario utilizzare l'`--provenance=false`opzione.
```
docker buildx build --platform linux/amd64 --provenance=false -t docker-image:test .
```
**Nota**
Il comando specifica l’opzione `--platform linux/amd64` per garantire che il container sia compatibile con l'ambiente di esecuzione di Lambda, indipendentemente dall'architettura della macchina di sviluppo. Se intendi creare una funzione Lambda utilizzando l'architettura del set di ARM64 istruzioni, assicurati di modificare il comando per utilizzare invece l'`--platform linux/arm64`opzione.
### (Facoltativo) Test dell'immagine in locale
1. Avvia l'immagine Docker con il comando **docker run**. In questo esempio, `docker-image` è il nome dell'immagine e `test` è il tag.
```
docker run --platform linux/amd64 -p 9000:8080 docker-image:test
```
Questo comando esegue l'immagine come container e crea un endpoint locale in `localhost:9000/2015-03-31/functions/function/invocations`.
**Nota**
Se hai creato l'immagine Docker per l'architettura del set di ARM64 istruzioni, assicurati di utilizzare l'`--platform linux/arm64`opzione invece di. `--platform linux/amd64`
1. Da una nuova finestra di terminale, invia un evento all'endpoint locale.
------
#### [ Linux/macOS ]
Su MacOS o Linux, esegui il comando seguente `curl`:
```
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'
```
Questo comando richiama la funzione con un evento vuoto e restituisce una risposta. Se stai utilizzando il tuo codice della funzione anziché quello di esempio, potresti voler richiamare la funzione con un payload JSON. Esempio:
```
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{"payload":"hello world!"}'
```
------
#### [ PowerShell ]
In PowerShell, esegui il seguente `Invoke-WebRequest` comando:
```
Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{}' -ContentType "application/json"
```
Questo comando richiama la funzione con un evento vuoto e restituisce una risposta. Se stai utilizzando il tuo codice della funzione anziché quello di esempio, potresti voler richiamare la funzione con un payload JSON. Esempio:
```
Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{"payload":"hello world!"}' -ContentType "application/json"
```
------
1. Ottieni l'ID del container.
```
docker ps
```
1. Utilizza il comando [docker kill](https://docs.docker.com/engine/reference/commandline/kill/) per arrestare il container. In questo comando, sostituisci `3766c4ab331c` con l'ID del container del passaggio precedente.
```
docker kill 3766c4ab331c
```
### Implementazione dell'immagine
**Caricamento dell'immagine su Amazon ECR e creazione della funzione Lambda**
1. Esegui il [get-login-password](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecr/get-login-password.html)comando per autenticare la CLI Docker nel tuo registro Amazon ECR.
+ Imposta il `--region` valore nel Regione AWS punto in cui desideri creare il repository Amazon ECR.
+ Sostituiscilo `111122223333` con il tuo ID. Account AWS
```
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-east-1.amazonaws.com
```
1. Crea un repository in Amazon ECR utilizzando il commando [create-repository](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecr/create-repository.html).
```
aws ecr create-repository --repository-name hello-world --region us-east-1 --image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLE
```
**Nota**
Il repository Amazon ECR deve corrispondere alla funzione Lambda. Regione AWS
In caso di esito positivo, dovresti ottenere una risposta simile a questa:
```
{
"repository": {
"repositoryArn": "arn:aws:ecr:us-east-1:111122223333:repository/hello-world",
"registryId": "111122223333",
"repositoryName": "hello-world",
"repositoryUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world",
"createdAt": "2023-03-09T10:39:01+00:00",
"imageTagMutability": "MUTABLE",
"imageScanningConfiguration": {
"scanOnPush": true
},
"encryptionConfiguration": {
"encryptionType": "AES256"
}
}
}
```
1. Copia il `repositoryUri` dall'output del passaggio precedente.
1. Esegui il comando [docker tag](https://docs.docker.com/engine/reference/commandline/tag/) per etichettare l'immagine locale nel repository Amazon ECR come versione più recente. In questo comando:
+ `docker-image:test` è il nome e [tag](https://docs.docker.com/engine/reference/commandline/build/#tag) dell'immagine Docker. Si tratta del nome e del tag dell'immagine specificati nel comando `docker build`.
+ Sostituisci l’`` con l’`repositoryUri` copiato. Assicurati di includere `:latest` alla fine dell'URI.
```
docker tag docker-image:test :latest
```
Esempio:
```
docker tag docker-image:test 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest
```
1. Esegui il comando [docker push](https://docs.docker.com/engine/reference/commandline/push/) per implementare la tua immagine locale sul repository Amazon ECR. Assicurati di includere `:latest` alla fine dell'URI del repository.
```
docker push 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest
```
1. [Crea un ruolo di esecuzione](lambda-intro-execution-role.md#permissions-executionrole-api) per la funzione, se non lo hai già fatto. Il nome della risorsa Amazon (ARN) del ruolo ti occorrerà nel passaggio successivo.
1. Creazione della funzione Lambda Per `ImageUri`, specifica l'URI del repository creato in precedenza. Assicurati di includere `:latest` alla fine dell'URI.
```
aws lambda create-function \
--function-name hello-world \
--package-type Image \
--code ImageUri=111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest \
--role arn:aws:iam::111122223333:role/lambda-ex
```
**Nota**
È possibile creare una funzione utilizzando un'immagine in un AWS account diverso, purché l'immagine si trovi nella stessa regione della funzione Lambda. Per ulteriori informazioni, consulta [Autorizzazioni multiaccount Amazon ECR](images-create.md#configuration-images-xaccount-permissions).
1. Richiama la funzione.
```
aws lambda invoke --function-name hello-world response.json
```
Dovresti ottenere una risposta simile a questa:
```
{
"ExecutedVersion": "$LATEST",
"StatusCode": 200
}
```
1. Per vedere l'output della funzione, controlla il file `response.json`.
Per aggiornare il codice della funzione, devi creare nuovamente l'immagine, caricare la nuova immagine nell'archivio Amazon ECR e quindi utilizzare il [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html)comando per distribuire l'immagine nella funzione Lambda.
Lambda risolve il tag dell'immagine in un digest di immagine specifico. Ciò significa che se punti il tag immagine utilizzato per implementare la funzione su una nuova immagine in Amazon ECR, Lambda non aggiorna automaticamente la funzione per utilizzare la nuova immagine.
Per distribuire la nuova immagine nella stessa funzione Lambda, è necessario utilizzare [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html)il comando, anche se il tag dell'immagine in Amazon ECR rimane lo stesso. Nell'esempio seguente, l'opzione `--publish` crea una nuova versione della funzione utilizzando l'immagine del container aggiornata.
```
aws lambda update-function-code \
--function-name hello-world \
--image-uri 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest \
--publish
```
# Utilizzo dell'oggetto contestuale Lambda per recuperare informazioni TypeScript sulla funzione
Quando Lambda esegue la funzione, passa un oggetto Context al [gestore](typescript-handler.md). Questo oggetto fornisce i metodi e le proprietà che forniscono le informazioni sulla chiamata, sulla funzione e sull'ambiente di esecuzione.
Per abilitare il controllo del tipo per l'oggetto di contesto, è necessario aggiungere il pacchetto [@types /aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) come dipendenza di sviluppo e importare il tipo. `Context` Per ulteriori informazioni, consulta [Definizioni dei tipi per Lambda](lambda-typescript.md#typescript-type-definitions).
**Metodi del contesto**
+ `getRemainingTimeInMillis()`: restituisce il numero di millisecondi rimasti prima del timeout dell'esecuzione.
**Proprietà del contesto**
+ `functionName`: il nome della funzione Lambda.
+ `functionVersion`: la [versione](configuration-versions.md) della funzione.
+ `invokedFunctionArn`: l'Amazon Resource Name (ARN) utilizzato per richiamare la funzione. Indica se l'invoker ha specificato un numero di versione o un alias.
+ `memoryLimitInMB`: la quantità di memoria allocata per la funzione.
+ `awsRequestId`: l'identificatore della richiesta di invocazione.
+ `logGroupName`: il gruppo di log per la funzione.
+ `logStreamName`: il flusso di log per l'istanza della funzione.
+ `identity`: (app per dispositivi mobili) Informazioni relative all'identità Amazon Cognito che ha autorizzato la richiesta.
+ `cognitoIdentityId`: l'identità autenticata di Amazon Cognito.
+ `cognitoIdentityPoolId`: il pool di identità Amazon Cognito che ha autorizzato l'invocazione.
+ `clientContext`: (app per dispositivi mobili) Contesto client fornito a Lambda dall'applicazione client.
+ `client.installation_id`
+ `client.app_title`
+ `client.app_version_name`
+ `client.app_version_code`
+ `client.app_package_name`
+ `env.platform_version`
+ `env.platform`
+ `env.make`
+ `env.model`
+ `env.locale`
+ `Custom`: valori personalizzati impostati dall'applicazione mobile.
+ `callbackWaitsForEmptyEventLoop`— Per impostazione predefinita (`true`), quando si utilizza un gestore di funzioni basato sul callback, Lambda attende che il ciclo di eventi sia vuoto dopo l'esecuzione del callback prima di terminare l'invoca della funzione. Imposta su `false` per inviare la risposta e terminare la chiamata immediatamente dopo l'esecuzione del callback anziché attendere che il ciclo di eventi sia vuoto. Gli eventi eccezionali continuano a verificarsi durante la chiamata successiva. Nota che Lambda supporta gestori di funzioni basati su callback solo per Node.js 22 e runtime precedenti.
**Example File index.js**
La seguente funzione di esempio registra le informazioni di contesto e restituisce la posizione dei log.
Prima di utilizzare questo codice in una funzione Lambda, devi aggiungere il pacchetto [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) come dipendenza di sviluppo. Questo pacchetto contiene le definizioni dei tipi per Lambda. Per ulteriori informazioni, consulta [Definizioni dei tipi per Lambda](lambda-typescript.md#typescript-type-definitions).
```
import { Context } from 'aws-lambda';
export const lambdaHandler = async (event: string, context: Context): Promise => {
console.log('Remaining time: ', context.getRemainingTimeInMillis());
console.log('Function name: ', context.functionName);
return context.logStreamName;
};
```
# Registra e monitora le funzioni TypeScript Lambda
AWS Lambda monitora automaticamente le funzioni Lambda e invia le voci di registro ad Amazon. CloudWatch La funzione Lambda include un gruppo di log CloudWatch Logs e un flusso di log per ogni istanza della funzione. L'ambiente di runtime di Lambda invia al flusso di log i dettagli su ogni invocazione e altri output dal codice della funzione. Per ulteriori informazioni sui CloudWatch registri, consulta. [Lambda invia automaticamente i log delle funzioni a CloudWatch Logs.](monitoring-cloudwatchlogs.md)
Per i log di output dal codice della funzione, puoi utilizzare i metodi nell'[oggetto console](https://nodejs.org/docs/latest-v18.x/api/console.html). Per una registrazione più dettagliata, puoi utilizzare qualunque libreria di registrazione che scrive su `stdout` o `stderr`.
**Topics**
+ [
## Utilizzo di strumenti di registrazione e librerie
](#typescript-tools-libraries)
+ [
## Utilizzo di Powertools per AWS Lambda () e per la registrazione TypeScript strutturata AWS SAM
](#typescript-logging-sam)
+ [
## Utilizzo di Powertools for AWS Lambda (TypeScript) e the AWS CDK per la registrazione strutturata
](#typescript-logging-cdk)
+ [
## Visualizzazione dei log nella console Lambda
](#typescript-logging-console)
+ [
## Visualizzazione dei log nella console CloudWatch
](#typescript-logging-cwconsole)
## Utilizzo di strumenti di registrazione e librerie
[Powertools for AWS Lambda (TypeScript)](https://docs.aws.amazon.com/powertools/typescript/) è un toolkit per sviluppatori per implementare le migliori pratiche Serverless e aumentare la velocità degli sviluppatori. L'[utilità di registrazione](https://docs.powertools.aws.dev/lambda/typescript/latest/features/logger/) fornisce un logger ottimizzato per Lambda che include informazioni aggiuntive sul contesto delle funzioni in tutte le funzioni con output strutturato come JSON. Utilizza l'utility per eseguire le seguenti operazioni:
+ Acquisizione di campi essenziali dal contesto Lambda, avvii a freddo e output di registrazione della struttura come JSON
+ Registrazione degli eventi di chiamata Lambda quando richiesto (disabilitata per impostazione predefinita)
+ Stampa di tutti i log solo per una percentuale di chiamate tramite campionamento dei log (disabilitata per impostazione predefinita)
+ Aggiunta di chiavi supplementari al log strutturato in qualsiasi momento
+ Utilizzo di un formattatore di log personalizzato (Bring Your Own Formatter) per generare i log in una struttura compatibile con Logging RFC dell'organizzazione
## Utilizzo di Powertools per AWS Lambda () e per la registrazione TypeScript strutturata AWS SAM
Segui i passaggi seguenti per scaricare, creare e distribuire un' TypeScript applicazione Hello World di esempio con i moduli [Powertools for AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) integrati utilizzando il. AWS SAM Questa applicazione implementa un backend dell'API di base e utilizza Powertools per l'emissione di log, parametri e tracce. Consiste in un endpoint Gateway Amazon API e in una funzione Lambda. Quando invii una richiesta GET all'endpoint API Gateway, la funzione Lambda richiama, invia log e metriche utilizzando Embedded Metric Format e invia tracce a. CloudWatch AWS X-Ray La funzione restituisce un messaggio `hello world`.
**Prerequisiti**
Per completare le fasi riportate in questa sezione, è necessario:
+ Node.js 2.0 o versione successiva
+ [AWS CLI versione 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS SAM CLI versione 1.75](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html) o successiva. Se disponi di una versione precedente della AWS SAM CLI, consulta [Aggiornamento](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade) della CLI. AWS SAM
**Implementa un'applicazione di esempio AWS SAM**
1. Inizializza l'applicazione utilizzando il modello Hello World. TypeScript
```
sam init --app-template hello-world-powertools-typescript --name sam-app --package-type Zip --runtime nodejs24.x
```
1. Costruisci l'app.
```
cd sam-app && sam build
```
1. Distribuire l'app.
```
sam deploy --guided
```
1. Seguire le istruzioni visualizzate sullo schermo. Per accettare le opzioni predefinite fornite nell'esperienza interattiva, premi `Enter`.
**Nota**
Perché **HelloWorldFunction potrebbe non avere un'autorizzazione definita. Va bene?** , assicurati di entrare`y`.
1. Ottieni l'URL dell'applicazione implementata:
```
aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text
```
1. Richiama l'endpoint dell'API:
```
curl
```
In caso di esito positivo, vedrai questa risposta:
```
{"message":"hello world"}
```
1. Per ottenere i log per la funzione, esegui [sam logs](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-logs.html). Per ulteriori informazioni, consulta l'argomento relativo all'[utilizzo dei log](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-logging.html) nella *Guida per sviluppatori AWS Serverless Application Model *.
```
sam logs --stack-name sam-app
```
L'output del log ha la struttura seguente:
```
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.552000 START RequestId: 70693159-7e94-4102-a2af-98a6343fb8fb Version: $LATEST
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.594000 2025-08-31T09:33:10.557Z 70693159-7e94-4102-a2af-98a6343fb8fb INFO {"_aws":{"Timestamp":1661938390556,"CloudWatchMetrics":[{"Namespace":"sam-app","Dimensions":[["service"]],"Metrics":[{"Name":"ColdStart","Unit":"Count"}]}]},"service":"helloWorld","ColdStart":1}
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.595000 2025-08-31T09:33:10.595Z 70693159-7e94-4102-a2af-98a6343fb8fb INFO {"level":"INFO","message":"This is an INFO log - sending HTTP 200 - hello world response","service":"helloWorld","timestamp":"2025-08-31T09:33:10.594Z"}
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.655000 2025-08-31T09:33:10.655Z 70693159-7e94-4102-a2af-98a6343fb8fb INFO {"_aws":{"Timestamp":1661938390655,"CloudWatchMetrics":[{"Namespace":"sam-app","Dimensions":[["service"]],"Metrics":[]}]},"service":"helloWorld"}
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.754000 END RequestId: 70693159-7e94-4102-a2af-98a6343fb8fb
2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.754000 REPORT RequestId: 70693159-7e94-4102-a2af-98a6343fb8fb Duration: 201.55 ms Billed Duration: 202 ms Memory Size: 128 MB Max Memory Used: 66 MB Init Duration: 252.42 ms
XRAY TraceId: 1-630f2ad5-1de22b6d29a658a466e7ecf5 SegmentId: 567c116658fbf11a Sampled: true
```
1. Questo è un endpoint API pubblico accessibile su Internet. È consigliabile eliminare l'endpoint dopo il test.
```
sam delete
```
### Gestione della conservazione dei log
I gruppi di log non vengono eliminati automaticamente quando si elimina una funzione. Per evitare di archiviare i log a tempo indeterminato, elimina il gruppo di log o configura un periodo di conservazione dopo il quale i log CloudWatch vengono eliminati automaticamente. Per configurare la conservazione dei log, aggiungi quanto segue al tuo modello: AWS SAM
```
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Properties:
# Omitting other properties
LogGroup:
Type: AWS::Logs::LogGroup
Properties:
LogGroupName: !Sub "/aws/lambda/${HelloWorldFunction}"
RetentionInDays: 7
```
## Utilizzo di Powertools for AWS Lambda (TypeScript) e the AWS CDK per la registrazione strutturata
Segui i passaggi seguenti per scaricare, creare e distribuire un' TypeScript applicazione Hello World di esempio con moduli [Powertools for AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) integrati utilizzando. AWS CDK Questa applicazione implementa un backend dell'API di base e utilizza Powertools per l'emissione di log, parametri e tracce. Consiste in un endpoint Gateway Amazon API e in una funzione Lambda. Quando invii una richiesta GET all'endpoint API Gateway, la funzione Lambda richiama, invia log e metriche utilizzando Embedded Metric Format e invia tracce a. CloudWatch AWS X-Ray La funzione restituisce un messaggio `hello world`.
**Prerequisiti**
Per completare le fasi riportate in questa sezione, è necessario:
+ Node.js 2.0 o versione successiva
+ [AWS CLI versione 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS CDK versione 2](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites)
+ [AWS SAM CLI versione 1.75](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html) o successiva. Se disponi di una versione precedente della AWS SAM CLI, consulta [Aggiornamento](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade) della CLI. AWS SAM
**Implementa un'applicazione di esempio AWS CDK**
1. Crea una directory di progetto per la nuova applicazione.
```
mkdir hello-world
cd hello-world
```
1. Inizializza l'app.
```
cdk init app --language typescript
```
1. Aggiungi il pacchetto [@types /aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) come dipendenza di sviluppo.
```
npm install -D @types/aws-lambda
```
1. Installa l'[utilità Logger](https://docs.aws.amazon.com/powertools/typescript/latest/features/logger/) di Powertools.
```
npm install @aws-lambda-powertools/logger
```
1. Apri la directory **lib**. Dovresti vedere un file chiamato **hello-world-stack.ts.** Crea due nuovi file in questa directory: **hello-world.function.ts** e **hello-world.ts**.
1. Apri **hello-world.function.ts** e aggiungi il seguente codice al file. Questo è il codice per la funzione Lambda.
```
import { APIGatewayEvent, APIGatewayProxyResult, Context } from 'aws-lambda';
import { Logger } from '@aws-lambda-powertools/logger';
const logger = new Logger();
export const handler = async (event: APIGatewayEvent, context: Context): Promise => {
logger.info('This is an INFO log - sending HTTP 200 - hello world response');
return {
statusCode: 200,
body: JSON.stringify({
message: 'hello world',
}),
};
};
```
1. Apri **hello-world.ts** e aggiungi il seguente codice al file. Contiene il [NodejsFunction costrutto](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html) che crea la funzione Lambda, configura le variabili di ambiente per Powertools e imposta la conservazione dei log su una settimana. Include anche il [LambdaRestApi costrutto](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.LambdaRestApi.html), che crea l'API REST.
```
import { Construct } from 'constructs';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
import { LambdaRestApi } from 'aws-cdk-lib/aws-apigateway';
import { RetentionDays } from 'aws-cdk-lib/aws-logs';
import { CfnOutput } from 'aws-cdk-lib';
export class HelloWorld extends Construct {
constructor(scope: Construct, id: string) {
super(scope, id);
const helloFunction = new NodejsFunction(this, 'function', {
environment: {
Powertools_SERVICE_NAME: 'helloWorld',
LOG_LEVEL: 'INFO',
},
logRetention: RetentionDays.ONE_WEEK,
});
const api = new LambdaRestApi(this, 'apigw', {
handler: helloFunction,
});
new CfnOutput(this, 'apiUrl', {
exportName: 'apiUrl',
value: api.url,
});
}
}
```
1. Apri **hello-world-stack.ts.** Questo è il codice che definisce lo [stack AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/stacks.html). Sostituisci il codice con il seguente:
```
import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { HelloWorld } from './hello-world';
export class HelloWorldStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
new HelloWorld(this, 'hello-world');
}
}
```
1. Passa alla directory del progetto.
```
cd hello-world
```
1. Distribuisci l'applicazione.
```
cdk deploy
```
1. Ottieni l'URL dell'applicazione implementata:
```
aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?ExportName==`apiUrl`].OutputValue' --output text
```
1. Richiama l'endpoint dell'API:
```
curl
```
In caso di esito positivo, vedrai questa risposta:
```
{"message":"hello world"}
```
1. Per ottenere i log per la funzione, esegui [sam logs](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-logs.html). Per ulteriori informazioni, consulta l'argomento relativo all'[utilizzo dei log](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-logging.html) nella *Guida per sviluppatori AWS Serverless Application Model *.
```
sam logs --stack-name HelloWorldStack
```
L'output del log ha la struttura seguente:
```
2025/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2025-08-31T14:48:37.047000 START RequestId: 19ad1007-ff67-40ce-9afe-0af0a9eb512c Version: $LATEST
2025/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2025-08-31T14:48:37.050000 {
"level": "INFO",
"message": "This is an INFO log - sending HTTP 200 - hello world response",
"service": "helloWorld",
"timestamp": "2025-08-31T14:48:37.048Z",
"xray_trace_id": "1-630f74c4-2b080cf77680a04f2362bcf2"
}
2025/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2025-08-31T14:48:37.082000 END RequestId: 19ad1007-ff67-40ce-9afe-0af0a9eb512c
2025/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2025-08-31T14:48:37.082000 REPORT RequestId: 19ad1007-ff67-40ce-9afe-0af0a9eb512c Duration: 34.60 ms Billed Duration: 35 ms Memory Size: 128 MB Max Memory Used: 57 MB Init Duration: 173.48 ms
```
1. Questo è un endpoint API pubblico accessibile su Internet. È consigliabile eliminare l'endpoint dopo il test.
```
cdk destroy
```
## Visualizzazione dei log nella console Lambda
È possibile utilizzare la console Lambda per visualizzare l'output del log dopo aver richiamato una funzione Lambda.
Se il codice può essere testato dall'editor del **codice** incorporato, troverai i log nei **risultati dell’esecuzione**. Quando utilizzi la funzionalità di test della console per richiamare una funzione, troverai l’**output del log** nella sezione **Dettagli**.
## Visualizzazione dei log nella console CloudWatch
Puoi utilizzare la CloudWatch console Amazon per visualizzare i log di tutte le chiamate di funzioni Lambda.
**Per visualizzare i log sulla console CloudWatch**
1. Apri la [pagina Registra gruppi](https://console.aws.amazon.com/cloudwatch/home?#logs:) sulla CloudWatch console.
1. Scegli il gruppo di log per la tua funzione (***your-function-name*/aws/lambda/**).
1. Creare un flusso di log.
Ogni flusso di log corrisponde a un'[istanza della funzione](lambda-runtime-environment.md). Viene visualizzato un flusso di log quando aggiorni la funzione Lambda e quando vengono create istanze aggiuntive per gestire le chiamate simultanee. Per trovare i log per una chiamata specifica, consigliamo di strumentare la funzione con. AWS X-Ray X-Ray registra i dettagli sulla richiesta e il flusso di log nella traccia.
# TypeScript Codice di tracciamento in AWS Lambda
Lambda si integra con AWS X-Ray per aiutarti a tracciare, eseguire il debug e ottimizzare le applicazioni Lambda. Puoi utilizzare X-Ray per tracciare una richiesta mentre attraversa le risorse nell'applicazione, che possono includere funzioni Lambda e altri servizi AWS .
Per inviare dati di tracciamento a X-Ray, è possibile utilizzare una delle tre librerie SDK:
+ [AWS Distro for OpenTelemetry (ADOT)](https://aws.amazon.com/otel): una distribuzione sicura, pronta per la produzione e supportata dell'SDK (). AWS OpenTelemetry OTel
+ [AWS X-Ray SDK per Node.js](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs.html): un SDK per la generazione e l'invio di dati di traccia a X-Ray.
+ [Powertools for AWS Lambda (TypeScript)](https://docs.aws.amazon.com/powertools/typescript/latest/): un toolkit per sviluppatori per implementare le migliori pratiche Serverless e aumentare la velocità degli sviluppatori.
Ciascuno di essi SDKs offre modi per inviare i dati di telemetria al servizio X-Ray. Puoi quindi utilizzare X-Ray per visualizzare, filtrare e analizzare le metriche delle prestazioni dell'applicazione per identificare i problemi e le opportunità di ottimizzazione.
**Importante**
X-Ray e Powertools per AWS Lambda SDKs fanno parte di una soluzione di strumentazione strettamente integrata offerta da. AWS I livelli Lambda ADOT fanno parte di uno standard di settore per la strumentazione di tracciamento che in generale raccoglie più dati, ma potrebbero non essere adatti a tutti i casi d'uso. È possibile implementare il end-to-end tracciamento in X-Ray utilizzando entrambe le soluzioni. Per saperne di più sulla scelta tra di esse, consulta [Scelta tra AWS Distro for Open Telemetry](https://docs.aws.amazon.com/xray/latest/devguide/xray-instrumenting-your-app.html#xray-instrumenting-choosing) e X-Ray. SDKs
**Topics**
+ [
## Utilizzo di Powertools per () e per il tracciamento AWS Lambda TypeScript AWS SAM
](#typescript-tracing-sam)
+ [
## Usare Powertools for AWS Lambda (TypeScript) e the AWS CDK per tracciare
](#typescript-tracing-cdk)
+ [
## Interpretazione di una traccia X-Ray
](#typescript-tracing-interpretation)
## Utilizzo di Powertools per () e per il tracciamento AWS Lambda TypeScript AWS SAM
Segui i passaggi seguenti per scaricare, creare e distribuire un' TypeScript applicazione Hello World di esempio con i moduli [Powertools for AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) integrati utilizzando il. AWS SAM Questa applicazione implementa un backend dell'API di base e utilizza Powertools per l'emissione di log, parametri e tracce. Consiste in un endpoint Gateway Amazon API e in una funzione Lambda. Quando invii una richiesta GET all'endpoint API Gateway, la funzione Lambda richiama, invia log e metriche utilizzando Embedded Metric Format e invia tracce a. CloudWatch AWS X-Ray La funzione restituisce un messaggio `hello world`.
**Prerequisiti**
Per completare le fasi riportate in questa sezione, è necessario:
+ Node.js
+ [AWS CLI versione 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS SAM CLI versione 1.75](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html) o successiva. Se disponi di una versione precedente della AWS SAM CLI, consulta [Aggiornamento](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade) della CLI. AWS SAM
**Implementa un'applicazione di esempio AWS SAM**
1. Inizializza l'applicazione utilizzando il modello Hello World. TypeScript
```
sam init --app-template hello-world-powertools-typescript --name sam-app --package-type Zip --runtime nodejs24.x --no-tracing
```
1. Costruisci l'app.
```
cd sam-app && sam build
```
1. Distribuire l'app.
```
sam deploy --guided
```
1. Seguire le istruzioni visualizzate sullo schermo. Per accettare le opzioni predefinite fornite nell'esperienza interattiva, premi `Enter`.
**Nota**
Perché **HelloWorldFunction potrebbe non avere un'autorizzazione definita. Va bene?** , assicurati di entrare`y`.
1. Ottieni l'URL dell'applicazione implementata:
```
aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text
```
1. Richiama l'endpoint dell'API:
```
curl
```
In caso di esito positivo, vedrai questa risposta:
```
{"message":"hello world"}
```
1. Per ottenere le tracce per la funzione, esegui [sam traces](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-traces.html).
```
sam traces
```
L'output della traccia ha il seguente aspetto:
```
XRay Event [revision 1] at (2023-01-31T11:29:40.527000) with id (1-11a2222-111a222222cb33de3b95daf9) and duration (0.483s)
- 0.425s - sam-app/Prod [HTTP: 200]
- 0.422s - Lambda [HTTP: 200]
- 0.406s - sam-app-HelloWorldFunction-Xyzv11a1bcde [HTTP: 200]
- 0.172s - sam-app-HelloWorldFunction-Xyzv11a1bcde
- 0.179s - Initialization
- 0.112s - Invocation
- 0.052s - ## app.lambdaHandler
- 0.001s - ### MySubSegment
- 0.059s - Overhead
```
1. Questo è un endpoint API pubblico accessibile su Internet. È consigliabile eliminare l'endpoint dopo il test.
```
sam delete
```
X-Ray non traccia tutte le richieste nell'applicazione. X-Ray applica un algoritmo di campionamento per garantire che il tracciamento avvenga in modo efficiente, continuando allo stesso tempo a fornire un campione rappresentativo di tutte le richieste. La frequenza di campionamento è di una richiesta al secondo e del 5% delle altre richieste. Non è possibile configurare la frequenza di campionamento di X-Ray per le funzioni.
## Usare Powertools for AWS Lambda (TypeScript) e the AWS CDK per tracciare
Segui i passaggi seguenti per scaricare, creare e distribuire un' TypeScript applicazione Hello World di esempio con moduli [Powertools for AWS Lambda (TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) integrati utilizzando. AWS CDK Questa applicazione implementa un backend dell'API di base e utilizza Powertools per l'emissione di log, parametri e tracce. Consiste in un endpoint Gateway Amazon API e in una funzione Lambda. Quando invii una richiesta GET all'endpoint API Gateway, la funzione Lambda richiama, invia log e metriche utilizzando Embedded Metric Format e invia tracce a. CloudWatch AWS X-Ray La funzione restituisce un messaggio `hello world`.
**Prerequisiti**
Per completare le fasi riportate in questa sezione, è necessario:
+ Node.js
+ [AWS CLI versione 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS CDK versione 2](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites)
+ [AWS SAM CLI versione 1.75](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html) o successiva. Se disponi di una versione precedente della AWS SAM CLI, consulta [Aggiornamento](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade) della CLI. AWS SAM
**Implementa un'applicazione di esempio AWS Cloud Development Kit (AWS CDK)**
1. Crea una directory di progetto per la nuova applicazione.
```
mkdir hello-world
cd hello-world
```
1. Inizializza l'app.
```
cdk init app --language typescript
```
1. Aggiungi il pacchetto [@types /aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) come dipendenza di sviluppo.
```
npm install -D @types/aws-lambda
```
1. Installa l'[utilità Tracer](https://docs.aws.amazon.com/powertools/typescript/latest/features/tracer/) di Powertools.
```
npm install @aws-lambda-powertools/tracer
```
1. Apri la directory **lib**. Dovresti vedere un file chiamato **hello-world-stack.ts.** Crea due nuovi file in questa directory: **hello-world.function.ts** e **hello-world.ts**.
1. Apri **hello-world.function.ts** e aggiungi il seguente codice al file. Questo è il codice per la funzione Lambda.
```
import { APIGatewayEvent, APIGatewayProxyResult, Context } from 'aws-lambda';
import { Tracer } from '@aws-lambda-powertools/tracer';
const tracer = new Tracer();
export const handler = async (event: APIGatewayEvent, context: Context): Promise => {
// Get facade segment created by Lambda
const segment = tracer.getSegment();
// Create subsegment for the function and set it as active
const handlerSegment = segment.addNewSubsegment(`## ${process.env._HANDLER}`);
tracer.setSegment(handlerSegment);
// Annotate the subsegment with the cold start and serviceName
tracer.annotateColdStart();
tracer.addServiceNameAnnotation();
// Add annotation for the awsRequestId
tracer.putAnnotation('awsRequestId', context.awsRequestId);
// Create another subsegment and set it as active
const subsegment = handlerSegment.addNewSubsegment('### MySubSegment');
tracer.setSegment(subsegment);
let response: APIGatewayProxyResult = {
statusCode: 200,
body: JSON.stringify({
message: 'hello world',
}),
};
// Close subsegments (the Lambda one is closed automatically)
subsegment.close(); // (### MySubSegment)
handlerSegment.close(); // (## index.handler)
// Set the facade segment as active again (the one created by Lambda)
tracer.setSegment(segment);
return response;
};
```
1. Apri **hello-world.ts** e aggiungi il seguente codice al file. Contiene il [NodejsFunction costrutto](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html) che crea la funzione Lambda, configura le variabili di ambiente per Powertools e imposta la conservazione dei log su una settimana. Include anche il [LambdaRestApi costrutto](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.LambdaRestApi.html), che crea l'API REST.
```
import { Construct } from 'constructs';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
import { LambdaRestApi } from 'aws-cdk-lib/aws-apigateway';
import { CfnOutput } from 'aws-cdk-lib';
import { Tracing } from 'aws-cdk-lib/aws-lambda';
export class HelloWorld extends Construct {
constructor(scope: Construct, id: string) {
super(scope, id);
const helloFunction = new NodejsFunction(this, 'function', {
environment: {
POWERTOOLS_SERVICE_NAME: 'helloWorld',
},
tracing: Tracing.ACTIVE,
});
const api = new LambdaRestApi(this, 'apigw', {
handler: helloFunction,
});
new CfnOutput(this, 'apiUrl', {
exportName: 'apiUrl',
value: api.url,
});
}
}
```
1. Apri **hello-world-stack.ts.** Questo è il codice che definisce lo [stack AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/stacks.html). Sostituisci il codice con il seguente:
```
import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { HelloWorld } from './hello-world';
export class HelloWorldStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
new HelloWorld(this, 'hello-world');
}
}
```
1. Distribuisci l'applicazione.
```
cd ..
cdk deploy
```
1. Ottieni l'URL dell'applicazione implementata:
```
aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?ExportName==`apiUrl`].OutputValue' --output text
```
1. Richiama l'endpoint dell'API:
```
curl
```
In caso di esito positivo, vedrai questa risposta:
```
{"message":"hello world"}
```
1. Per ottenere le tracce per la funzione, esegui [sam traces](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-traces.html).
```
sam traces
```
L'output della traccia ha il seguente aspetto:
```
XRay Event [revision 1] at (2023-01-31T11:50:06.997000) with id (1-11a2222-111a222222cb33de3b95daf9) and duration (0.449s)
- 0.350s - HelloWorldStack-helloworldfunction111A2BCD-Xyzv11a1bcde [HTTP: 200]
- 0.157s - HelloWorldStack-helloworldfunction111A2BCD-Xyzv11a1bcde
- 0.169s - Initialization
- 0.058s - Invocation
- 0.055s - ## index.handler
- 0.000s - ### MySubSegment
- 0.099s - Overhead
```
1. Questo è un endpoint API pubblico accessibile su Internet. È consigliabile eliminare l'endpoint dopo il test.
```
cdk destroy
```
## Interpretazione di una traccia X-Ray
Dopo aver configurato il tracciamento attivo, è possibile osservare richieste specifiche tramite l'applicazione. La [mappa del tracciamento X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-servicemap.html) fornisce informazioni sull'applicazione e su tutti i relativi componenti. L'esempio seguente mostra una traccia dall'applicazione di esempio:
![\[\]](http://docs.aws.amazon.com/it_it/lambda/latest/dg/images/sample-typescript-servicemap.png)