Runtime di Node.js

La funzione Cloud Run viene eseguita in un ambiente costituito da una versione del sistema operativo, oltre a pacchetti aggiuntivi, supporto per le lingue e la libreria Functions Framework che supporta e richiama la funzione. Questo ambiente è identificato dalla versione della lingua ed è noto come runtime.

Per informazioni sui runtime in generale e per scoprire quale versione di Ubuntu viene utilizzata da ciascun runtime Node.js, consulta l'ambiente di esecuzione di Cloud Run Functions.

Per iniziare a creare ed eseguire il deployment di funzioni Cloud Run con Node.js, consulta la guida rapida.

Per creare e testare le funzioni sul tuo sistema locale, consulta Eseguire funzioni con Functions Framework.

Seleziona il runtime

Le funzioni Cloud Run supportano diverse versioni di Node.js, elencate nella pagina Supporto del runtime. Puoi selezionare il runtime Node.js preferito per la tua funzione durante il deployment:

• Per informazioni dettagliate sul deployment da Google Cloud CLI, consulta Eseguire il deployment di una funzione Cloud Run.

• Per informazioni dettagliate sul deployment dalla console Google Cloud, consulta la guida rapida della console Google Cloud.

Ambiente di esecuzione

L'ambiente di esecuzione include il runtime, il sistema operativo, i pacchetti e una libreria che invoca la funzione.

Node.js 18 e le versioni successive utilizzano un ambiente di esecuzione basato su Ubuntu 22.04. Le versioni precedenti a Node.js 18 sono basate su Ubuntu 18.04. Per ulteriori informazioni, consulta Ambiente di esecuzione delle funzioni Cloud Run.

La libreria che richiama la funzione è il Framework Functions di Node.js.

Struttura del codice sorgente

Affinché le funzioni Cloud Run trovino la definizione della tua funzione, ogni runtime ha determinati requisiti di struttura per il codice sorgente. Per ulteriori informazioni, consulta Scrivere funzioni Cloud Run.

Specifica delle dipendenze

Puoi specificare le dipendenze per le funzioni elencandole in un file package.json. Per ulteriori informazioni, consulta la sezione Specificare le dipendenze in Node.js.

Script di build NPM

Per impostazione predefinita, il runtime di Node.js esegue npm run build se viene rilevato uno script build in package.json. Se hai bisogno di un maggiore controllo sui passaggi di compilazione prima di avviare l'applicazione, puoi fornire un passaggio di compilazione personalizzato aggiungendo uno script gcp-build al file package.json.

Puoi impedire alla build di eseguire lo script npm run build in uno dei seguenti modi:

• Aggiunta di uno script gcp-build con un valore vuoto nel file package.json: "gcp-build":"".

• Impostare la variabile di ambiente di compilazione GOOGLE_NODE_RUN_SCRIPTS sulla stringa vuota per impedire l'esecuzione di tutti gli script.

Completamento della funzione asincrona

Quando lavori con attività asincrone che richiedono callback o oggetti Promise, devi informare esplicitamente il runtime che la funzione ha completato l'esecuzione di queste attività. Puoi farlo in diversi modi, come mostrato nei seguenti esempi. L'aspetto fondamentale è che il codice deve attendere il completamento della tâche asincrona o di Promise prima di restituire il valore; in caso contrario, il componente asincrono della funzione potrebbe essere interrotto prima del completamento.

Funzioni basate su eventi

Valore restituito implicito

  exports.implicitlyReturning = async (event, context) => {
    return await asyncFunctionThatReturnsAPromise();
  };

Ritorno esplicito

  exports.explicitlyReturning = function (event, context) {
    return asyncFunctionThatReturnsAPromise();
  };

Funzioni HTTP

Node.js

// OK: await-ing a Promise before sending an HTTP response
await Promise.resolve();

// WRONG: HTTP functions should send an
// HTTP response instead of returning.
return Promise.resolve();

// HTTP functions should signal termination by returning an HTTP response.
// This should not be done until all background tasks are complete.
res.send(200);
res.end();

// WRONG: this may not execute since an
// HTTP response has already been sent.
return Promise.resolve();

Attenzione: se non segnali correttamente il termine della funzione, la funzione potrebbe terminare in anticipo o continuare a funzionare fino al raggiungimento del timeout. Per ulteriori informazioni, consulta la guida alla risoluzione dei problemi.

Utilizzare il middleware per gestire le richieste HTTP

Le funzioni Cloud Run HTTP di Node.js forniscono oggetti request e response compatibili con ExpressJS per semplificare l'utilizzo delle richieste HTTP. Le funzioni Cloud Run leggono automaticamente il corpo della richiesta, pertanto riceverai sempre il corpo di una richiesta indipendentemente dal tipo di media. Ciò significa che le richieste HTTP devono essere considerate completamente lette al momento dell'esecuzione del codice. Il nidificazione delle applicazioni ExpressJS deve essere utilizzata con questo avvertimento: in particolare, il middleware che si aspetta che il corpo di una richiesta non sia letto potrebbe non comportarsi come previsto.

Utilizzare i moduli ES

I moduli ECMAScript (moduli ES o ESM) sono una funzionalità non segnalata standard del TC39 nella versione 14 e successive di Node per il caricamento dei moduli JavaScript. A differenza di CommonJS, ESM fornisce un'API asincrona per il caricamento dei moduli. Fornisce inoltre un miglioramento della sintassi popolare con le istruzioni import e export che possono essere utilizzate all'interno di una funzione Cloud Run (anziché le istruzioni require).

Per utilizzare ESM all'interno di una funzione Cloud Run, devi dichiarare "type": "module" all'interno di package.json.

{
  ...
  "type": "module",
  ...
}

Dopodiché puoi utilizzare le istruzioni import e export.

Nota: scopri di più sull'utilizzo dei moduli ES.