Runtime di Node.js

La tua funzione Cloud Run viene eseguita in un ambiente costituito da una versione del sistema operativo più pacchetti aggiuntivi, supporto dei linguaggi e la libreria del framework di Functions che supporta e richiama la tua funzione. Questo ambiente è identificato dalla versione del linguaggio ed è noto come runtime.

Per informazioni sui runtime in generale e per scoprire quale versione di Ubuntu utilizza ogni runtime Node.js, consulta 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 sistema locale, consulta Esegui funzioni con il framework di Functions.

Seleziona il runtime

Cloud Run Functions supporta diverse versioni di Node.js, elencate nella pagina Supporto di 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 Esegui il deployment di una funzione Cloud Run.

Ambiente di esecuzione

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

Node.js 18 e versioni successive utilizzano un ambiente di esecuzione basato su Ubuntu 22.04. Le versioni precedenti a Node.js 18 si basano su Ubuntu 18.04. Per saperne di più, consulta Ambiente di esecuzione di Cloud Run Functions.

La libreria che richiama la tua funzione è il framework di Functions per Node.js.

Struttura del codice sorgente

Affinché Cloud Run Functions trovi la definizione della tua funzione, ogni runtime ha determinati requisiti di struttura per il codice sorgente. Per saperne di più, consulta Scrittura di funzioni Cloud Run.

Specifica le dipendenze

Puoi specificare le dipendenze per le tue funzioni elencandole in un file package.json. Per saperne di più, consulta Specifica delle dipendenze in Node.js.

Script di build NPM

Per impostazione predefinita, il runtime 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 build prima di avviare l'applicazione, puoi fornire un passaggio di build personalizzato aggiungendo uno script gcp-build al file package.json.

Puoi impedire l'esecuzione dello script npm run build nella build in questi modi:

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

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

Completamento della funzione asincrono

Quando lavori con attività asincrone che coinvolgono callback o oggetti Promise, devi comunicare esplicitamente al runtime che la tua funzione ha terminato l'esecuzione di queste attività. Puoi farlo in diversi modi, come mostrato negli esempi seguenti. Il punto chiave è che il codice deve attendere il completamento dell'attività asincrona o di Promise prima di restituire un valore. In caso contrario, il componente asincrono della funzione potrebbe essere terminato prima del completamento.

Funzioni basate su eventi

Restituzione implicita

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

Restituzione esplicita

  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();

Utilizza 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. Cloud Run Functions legge automaticamente il corpo della richiesta, quindi 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 nesting delle app ExpressJS deve essere utilizzato tenendo conto di questo: in particolare, il middleware che prevede che il corpo di una richiesta non venga letto potrebbe non comportarsi come previsto.

Utilizza i moduli ES

I moduli ECMAScript (moduli ES o ESM) sono una funzionalità TC39 standard e senza flag nella versione 14 o 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 popolare miglioramento della sintassi con le istruzioni import e export che possono essere utilizzate all'interno di una funzione Cloud Run (al posto delle 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.