Specifica le dipendenze in Node.js

Una funzione può utilizzare moduli Node.js esterni e dati locali. Le dipendenze in Node.js sono gestite con npm ed espresse in un file di metadati chiamato package.json. I runtime Node.js di Cloud Functions supportano l'installazione utilizzando npm, yarn o pnpm.

Per specificare una dipendenza per la funzione, aggiungila al file package.json.

Nota: se all'interno del progetto viene rilevato un file package-lock.json, yarn.lock o pnpm-lock.yaml, il file di blocco verrà rispettato quando le dipendenze vengono installate utilizzando npm ci, yarn install o pnpm install.

In questo esempio, una dipendenza è elencata nel file package.json:

{
  "dependencies": {
    "escape-html": "^1.0.3"
  }
}

La dipendenza viene quindi importata nella funzione:

const functions = require('@google-cloud/functions-framework');
const escapeHtml = require('escape-html');

/**
 * Responds to an HTTP request using data from the request body parsed according
 * to the "content-type" header.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
functions.http('helloHttp', (req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});

Il framework delle funzioni è una dipendenza obbligatoria per tutte le funzioni. Anche se Cloud Functions la installa per tuo conto al momento della creazione della funzione, ti consigliamo di includerla come dipendenza esplicita per maggiore chiarezza.

Se la tua funzione si basa su dipendenze private, ti consigliamo di eseguire il mirroring di functions-framework nel registro privato. Includi functions-framework con mirroring come dipendenza dalla funzione per evitare di installare il pacchetto dalla rete internet pubblica.

Utilizzo di npm per installare i moduli Node.js localmente

Il modo più semplice per installare un modulo Node.js localmente è utilizzare il comando npm install nella cartella contenente la funzione Cloud Function. Ad esempio, il seguente comando aggiunge il modulo uuid:

npm install uuid

Questa operazione combina due passaggi:

1. Contrassegna l'ultima versione del modulo come dipendenza nel file package.json. Questo è molto importante: Cloud Functions installa solo i moduli dichiarati nel tuo file package.json.
2. Il modulo viene scaricato nella directory node_modules. In questo modo puoi utilizzare il modulo per lo sviluppo locale.

Se non hai installato npm sulla tua macchina, ricevi npm.

Nota: sono disponibili pacchetti di Gestione dei partner di rete per diversi prodotti Google Cloud. Consulta l'elenco qui.

Configurazione delle dipendenze del deployment

Puoi installare le dipendenze di produzione per NPM, Yarn o Pnpm:

Gestione dei partner di rete

Quando esegui il deployment della funzione, Cloud Functions installa le dipendenze dichiarate nel file package.json utilizzando il comando npm install:

npm install --production

Filato

Nel runtime Node.js 8 e versioni successive, se esiste un file yarn.lock, Cloud Functions utilizza invece il comando yarn install:

yarn install --production

Pnpm

Nel runtime Node.js 8 e versioni successive, se esiste un file pnpm-lock.yaml, Cloud Functions utilizza invece il comando pnpm install:

pnpm install

Nota: le dipendenze dichiarate nelle sottodirectory non vengono installate. Se utilizzi un monorepo, ti consigliamo di eseguire uno script di build personalizzato durante il deployment per installare queste dipendenze.

Esecuzione di passi di build personalizzati durante il deployment

Dopo il deployment, puoi eseguire un passaggio di compilazione personalizzato durante il processo di compilazione della funzione aggiungendo uno script gcp-build nel file package.json.

Quando viene eseguito questo script, sono disponibili le dipendenze nei campi dependencies e devDependencies del file package.json. Dopo aver eseguito il passaggio di build personalizzato, Cloud Functions rimuove e rigenera la cartella node_modules installando solo le dipendenze di produzione dichiarate nel campo dependencies del file package.json.

Se non è presente uno script gcp-build in package.json, Cloud Functions si limita a installare le dipendenze di produzione.

Utilizzo dei pacchetti di sistema

Il runtime Node.js include anche una serie di pacchetti di sistema nell'ambiente di esecuzione. Se la funzione utilizza una dipendenza che richiede un pacchetto non in elenco, puoi richiedere un pacchetto.

Nota: puoi anche eseguire il deployment di versioni containerizzate delle tue funzioni Cloud Functions Node.js in Cloud Run utilizzando il framework delle funzioni.

Inclusi i moduli Node.js locali

Puoi anche includere moduli Node.js locali nella funzione. A tale scopo, dichiara il modulo in package.json utilizzando il prefisso file:. Nell'esempio seguente, mymodule si riferisce al nome del modulo e mymoduledir è la directory contenente il modulo:

{
  "dependencies": {
    "mymodule": "file:mymoduledir"
  }
}

Il codice per questo modulo locale deve essere archiviato in una posizione diversa dalla cartella node_modules all'interno della directory root della funzione.

Nota: se esegui il deployment utilizzando lo strumento a riga di comando gcloud, gcloud crea automaticamente un file .gcloudignore nella directory della funzione. Per impostazione predefinita, la cartella node_modules viene aggiunta a questo .gcloudignore e non viene caricata come parte del deployment. Non è necessario includere la cartella node_modules quando carichi manualmente il codice come file ZIP: puoi eseguire correttamente il deployment della funzione senza la cartella node_modules.

Caricamento dei moduli Node.js

Utilizza la funzione Node.js require() per caricare qualsiasi modulo Node.js che hai installato. Puoi anche utilizzare la funzione require() per importare i file locali di cui esegui il deployment insieme alla funzione.

Utilizzo di moduli privati

Puoi utilizzare un modulo npm privato fornendo le impostazioni per l'autenticazione con il registro in un file .npmrc nella directory della funzione. Se utilizzi Yarn v2 o versioni successive come gestore di pacchetti, questo file è denominato .yarnrc.yml.

Moduli privati da Artifact Registry

Un repository dei pacchetti Node.js di Artifact Registry può ospitare moduli privati per la tua funzione. Quando esegui il deployment di una funzione Cloud Functions, il processo di compilazione genera automaticamente le credenziali Artifact Registry per l'account di servizio Cloud Build. Devi solo elencare il repository Artifact Registry nel tuo .npmrc senza generare ulteriori credenziali. Ad esempio:

@SCOPE:registry=https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
//REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME:always-auth=true

Questo approccio funziona anche per il gestore di pacchetti Yarn v1. Se utilizzi Yarn v2 o versioni successive, devi solo elencare il repository Artifact Registry nel tuo .yarnrc.yml senza credenziali aggiuntive. Ad esempio:

npmScopes:
  SCOPE:
    npmRegistryServer: https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
    npmAlwaysAuth: true

Moduli privati da altri repository

La documentazione di npm spiega come creare token di accesso personalizzati di sola lettura. Sconsigliamo di utilizzare il file .npmrc creato nella home directory perché contiene un token di lettura-scrittura. Le autorizzazioni di scrittura non sono necessarie durante il deployment e potrebbero rappresentare un rischio per la sicurezza.

Non includere il file .npmrc se non utilizzi repository privati, in quanto i tempi di deployment delle funzioni potrebbero aumentare.

Nota: se utilizzi autorizzazioni personalizzate (come quelle necessarie per VPC), assicurati di consentire in modo esplicito alle funzioni di accedere al repository privato di destinazione.

Formato file

Se utilizzi un file .npmrc per impostare un token di autenticazione personalizzato, il file deve includere la riga riportata di seguito.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Sostituisci:

• REGISTRY_DOMAIN: il nome di dominio del registry npm privato. Se il repository è ospitato con npmjs.org, imposta questo campo su registry.npmjs.org.

• AUTH_TOKEN: il token di autorizzazione per il registro npm. Può essere il valore di testo letterale del token o la stringa di testo ${NPM_TOKEN}, che npm sostituisce con il valore effettivo del token dell'ambiente.

  Puoi impostare la variabile di ambiente $NPM_TOKEN con l'argomento --set-build-env-vars sul comando gcloud functions deploy. Per ulteriori dettagli sul token di autenticazione NPM, consulta il tutorial per Gestione dei partner di rete sui moduli privati.

Crea la tua funzione con le dipendenze fornite dal fornitore

Le dipendenze fornite dai fornitori sono quelle il cui codice sorgente è incluso direttamente nel pacchetto di codice sorgente e ricreate insieme al tuo codice. Puoi creare dipendenze Node.js fornite dal fornitore e saltare l'installazione durante il deployment utilizzando la variabile di ambiente di build GOOGLE_VENDOR_NPM_DEPENDENCIES.

Prerequisiti per le dipendenze fornite dal fornitore

1. Assicurati di avere una funzione funzionante con tutte le dipendenze definite dal fornitore nel file package.json.

2. Installa queste dipendenze localmente eseguendo

       npm install
   

3. Rimuovi node_modules dal file .gcloudignore nella tua directory di lavoro.

4. Esegui il deployment della funzione, assicurandoti che la versione locale di Node.js sia la stessa specificata durante il deployment.

5. Esegui il deployment della funzione e delle dipendenze fornite dal fornitore con il seguente comando:

     gcloud functions deploy FUNCTION_NAME \
       --runtime RUNTIME_NAME \
       --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true
   

   Sostituisci:

   • FUNCTION_NAME: il nome della funzione Cloud Functions di cui stai eseguendo il deployment
   • RUNTIME_NAME: il nome del runtime Node.js in cui eseguire la funzione di cui hai eseguito il deployment. Deve essere la stessa versione Node.js che hai utilizzato nell'ambiente di sviluppo locale

Il pacchetto del framework Functions è una dipendenza obbligatoria per le funzioni. Per build più veloci, consigliamo di fornire questo pacchetto al fornitore. In caso contrario, viene scaricata e installata al momento della creazione della funzione.

Se specifichi un motore npm nel file package.json, la versione specificata di npm viene scaricata al momento della build. Per eliminare questo comportamento, rimuovilo dal file package.json.