Gestione delle dipendenze

Node.js Python

Una funzione può utilizzare moduli Node.js esterni e dati locali. Le dipendenze in Node.js vengono gestite con npm ed espresse in un file di metadati denominato 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 nel progetto viene trovato un file package-lock.json, yarn.lock o pnpm-lock.yaml, questo 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 poi importata nella funzione:

JavaScriptTypeScript

const escapeHtml = require('escape-html');

// Return a greeting with the input HTML-escaped.
exports.hello = functions.https.onRequest((req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});

import * as escapeHtml from 'escape-html';

// Return a greeting with the input HTML-escaped.
export let hello = functions.https.onRequest((req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
}

Inclusione di moduli Node.js locali

Puoi anche includere moduli Node.js locali all'interno della funzione. Puoi ottenere questo risultato dichiarando il modulo in package.json utilizzando il prefisso file:. Nel seguente esempio, mymodule fa riferimento al nome del modulo e mymoduledir è la directory contenente il modulo:

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

Il codice di questo modulo locale deve essere archiviato in un luogo diverso dalla node_modules cartella all'interno della directory principale della funzione.

Nota: l'interfaccia a riga di comando di Firebase ignora la cartella node_modules locale durante il deployment della funzione.

Passaggi aggiuntivi per TypeScript

TypeScript è più utile quando utilizzi librerie con informazioni sui tipi. In questo modo, TypeScript può rilevare gli errori di sintassi e gli editor possono darti suggerimenti di completamento automatico migliori. Alcune librerie, come firebase-admin e firebase-functions, sono fornite con le definizioni di TypeScript incluse.

Molte librerie non forniscono una propria definizione di TypeScript. Il progetto DefinitelyTyped fornisce definizioni gestite dalla community per le librerie Node più utilizzate. DefinitelyTyped pubblica queste definizioni con lo stesso nome del pacchetto NPM, ma all'interno dell'organizzazione "@types". Ad esempio, puoi installare le informazioni sul tipo per la raccolta uuid con quanto segue:

npm install @types/uuid

Man mano che acquisisci familiarità con TypeScript, potresti trovarti a combinare entrambe le installazioni:

npm install uuid @types/uuid

Le dipendenze di tipo devono essere dello stesso tipo della dipendenza della libreria. Ad esempio, non devi salvare uuid come dipendenza normale e @types/uuid come dipendenza di sviluppo o dipendenza peer.

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.

Se stai scrivendo funzioni in TypeScript, utilizza l'istruzione import nello stesso modo per caricare qualsiasi modulo Node.js che hai installato.

Utilizzo di moduli privati

Puoi utilizzare un modulo npm privato fornendo le impostazioni per l'autenticazione con il registry in un file .npmrc nella directory della funzione. Se utilizzi Yarn 2.0 o versioni successive come gestore dei pacchetti, questo file si chiama .yarnrc.yml.

Moduli privati di Artifact Registry

Un repository di 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 di Artifact Registry per l'account di servizio Cloud Build. Devi solo elencare il repository Artifact Registry in .npmrc senza generare credenziali aggiuntive. 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 dei pacchetti Yarn 1. Se utilizzi Yarn 2.0 o versioni successive, devi solo elencare il repository Artifact Registry in .yarnrc.yml senza credenziali aggiuntive. Ad esempio:

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

Moduli privati di altri repository

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

Non includere il file .npmrc se non utilizzi repository privati, poiché questo può aumentare il tempo di implementazione delle funzioni.

Nota: se utilizzi autorizzazioni personalizzate (ad esempio quelle necessarie per il VPC), assicurati di consentire esplicitamente alle tue funzioni di accedere al repository privato di destinazione.

Formato file

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

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Sostituisci:

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

• AUTH_TOKEN: il token di autorizzazione per il tuo registry npm. Può trattarsi del valore di testo letterale del token o della stringa di testo ${NPM_TOKEN}, che npm sostituisce con il valore effettivo del token dall'ambiente.

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

Creare la funzione con dipendenze del fornitore

Le dipendenze del fornitore sono quelle il cui codice sorgente è incluso direttamente nel pacchetto di codice sorgente e viene ricostruito insieme al tuo codice. Puoi creare dipendenze Node.js di terze parti e saltarne l'installazione durante il deployment utilizzando la variabile di ambiente di compilazione GOOGLE_VENDOR_NPM_DEPENDENCIES.

Prerequisiti per le dipendenze del fornitore

1. Assicurati di avere una funzione funzionante con tutte le dipendenze che vuoi che il fornitore definisca nel file package.json.

2. Installa queste dipendenze localmente eseguendo

       npm install
   

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

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

5. Esegui il deployment della funzione e delle dipendenze del 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 che stai eseguendo il deployment
   • RUNTIME_NAME: il nome del runtime Node.js su cui eseguire la funzione di cui è stato eseguito il deployment. Deve essere la stessa versione di Node.js utilizzata nell'ambiente di sviluppo locale

Il pacchetto del framework Functions è una dipendenza obbligatoria per le funzioni. Per build più rapide, consigliamo di acquistare questo pacchetto. In caso contrario, viene scaricato e installato al momento della compilazione della funzione.

Se specifichi un motore npm nel file package.json, la versione di npm specificata viene scaricata in fase di compilazione. Per eliminare questo comportamento, rimuovilo dal file package.json.