Esegui l'upgrade all'SDK Admin Node.js v10 (SDK modulare)

La versione 10 dell'SDK Node.js per amministratore introduce due modifiche importanti:

  • Il supporto di Node.js 10 non è più disponibile (si tratta di una modifica incompatibile)
  • L'SDK ha adottato un pattern API modulare

Questa guida fornisce istruzioni e informazioni per aiutare gli sviluppatori a eseguire l'upgrade delle app Node.js esistenti dalle versioni precedenti di Admin SDK alla versione 10.

Aggiorna Node.js alla versione 12 o successiva

Con il rilascio della versione 10 dell'SDK Node.js per Firebase, Firebase ha interrotto il supporto per Node.js 10. Gli sviluppatori devono utilizzare Node.js 12 o versioni successive quando utilizzano Admin SDK. Se utilizzi l'SDK Node.js Admin insieme a Cloud Functions for Firebase, assicurati di avere eseguito l'upgrade della versione di Node.js a 12 o versioni successive.

Utilizza i moduli anziché gli spazi dei nomi

Fin dalla sua creazione, l'SDK Admin Node.js ha offerto un'API stabile strutturata come gerarchia di spazi dei nomi nidificati. Di conseguenza, potresti aver familiarizzato con la scrittura di codice simile al seguente:

// Import the global admin namespace
import * as admin from 'firebase-admin';

const app: admin.app.App = admin.initializeApp();

const token: string = await admin.auth().createCustomToken('alice');

const user: admin.auth.UserRecord = await admin.auth().getUser('bob');

A partire dalla versione 10, l'SDK Node.js per gli amministratori offre più punti di contatto del modulo con le esportazioni con nome. Consigliamo agli sviluppatori di utilizzare questi nuovi punti di contatto per accedere alle varie API dell'SDK, anziché utilizzare lo spazio dei nomi admin globale.

Ecco come apparirebbe l'esempio riportato sopra con i nuovi punti di accesso al modulo:

TypeScript

// Import only what you need
import { initializeApp, App } from 'firebase-admin/app';
import { getAuth, UserRecord } from 'firebase-admin/auth';

const app: App = initializeApp();

const token: string = await getAuth().createCustomToken('alice');

const user: UserRecord = getAuth().getUser('bob');

Node.js

// Import only what you need
const { initializeApp } = require('firebase-admin/app');
const { getAuth } = require('firebase-admin/auth');

const app = initializeApp();

const token = await getAuth().createCustomToken('alice');

const user = getAuth().getUser('bob');

Utilizzo dei punti di contatto modulari della versione 10

Tieni presente che, negli esempi precedenti, non importi più uno spazio dei nomi admin globale. Importa invece esplicitamente solo i simboli di cui hai bisogno da diversi punti di contatto del modulo. Inoltre, gli sviluppatori TypeScript non devono più utilizzare identificatori di tipo nidificati tre volte come admin.auth.UserRecord e admin.database.Reference. Poiché ogni tipo appartiene a un solo modulo, puoi importarli semplicemente utilizzando i relativi nomi brevi, come UserRecord e Reference.

Di seguito sono riportati tutti i punti di contatto del modulo disponibili nell'SDK a partire dalla versione 10:

  • firebase-admin/app
  • firebase-admin/auth
  • firebase-admin/database
  • firebase-admin/firestore
  • firebase-admin/instance-id
  • firebase-admin/machine-learning
  • firebase-admin/messaging
  • firebase-admin/project-management
  • firebase-admin/remote-config
  • firebase-admin/security-rules
  • firebase-admin/storage

La tabella seguente mostra la sintassi di importazione sostitutiva per ciascuna delle funzioni dello spazio dei nomi legacy:

v9 v10
admin.initializeApp() import { initializeApp } from 'firebase-admin/app'

initializeApp();

admin.app() import { getApp } from 'firebase-admin/ap'

getApp();

admin.credential.cert() import { cert } from 'firebase-admin/app'

cert();

admin.auth() import { getAuth } from 'firebase-admin/auth'

getAuth();

admin.database() import { getDatabase } from 'firebase-admin/database'

getDatabase();

admin.firestore() import { getFirestore } from 'firebase-admin/firestore'

getFirestore();

admin.instanceId() import { getInstanceId } from 'firebase-admin/instance-id'

getInstanceId();

admin.machineLearning() import { getMachineLearning } from 'firebase-admin/machine-learning'

getMachineLearning();

admin.messaging() import { getMessaging } from 'firebase-admin/messaging'

getMessaging()

admin.projectManagement() import { getProjectManagement } from 'firebase-admin/project-management'

getProjectManagement();

admin.remoteConfig() import { getRemoteConfig } from 'firebase-admin/remote-config'

getRemoteConfig();

admin.securityRules() import { getSecurityRules } from 'firebase-admin/security-rules'

getSecurityRules()

admin.storage() import { getStorage } from 'firebase-admin/storage'

getStorage();

Utilizzare le funzioni esportate anziché i metodi nell'app

Nell'API precedente, l'oggetto App esponeva una serie di metodi come app.auth() e app.database(). Consigliamo agli sviluppatori di evitare di utilizzare questi metodi e di utilizzare invece gli stessi punti di contatto del modulo descritti sopra per ottenere istanze di servizio con ambito limitato a un determinato oggetto App ed eseguire altre attività specifiche per l'app.

v9 v10
app.auth() import { getAuth } from 'firebase-admin/auth';

getAuth(app);

app.database() import { getDatabase } from 'firebase-admin/database';

getDatabase(app);

app.database(url) import { getDatabaseWithUrl } from 'firebase-admin/database';

getDatabaseWithUrl(url, app);

app.firestore() import { getFirestore } from 'firebase-admin/firestore'

getFirestore(app);

app.instanceId() import { getInstanceId } from 'firebase-admin/instance-id'

getInstanceId(app);

app.machineLearning() import { getMachineLearning } from 'firebase-admin/machine-learning'

getMachineLearning(app);

app.messaging() import { getMessaging } from 'firebase-admin/messaging'

getMessaging(app);

app.projectManagement() import { getProjectManagement } from 'firebase-admin/project-management'

getProjectManagement(app);

app.remoteConfig() import { getRemoteConfig } from 'firebase-admin/remote-config'

getRemoteConfig(app);

app.securityRules() import { getSecurityRules } from 'firebase-admin/security-rules'

getSecurityRules(app);

app.storage() import { getStorage } from 'firebase-admin/storage'

getStorage(app);

app.delete() import { deleteApp } from 'firebase-admin/app';

deleteApp(app);

Supporto dei moduli ES

Node.js 12 e versioni successive sono dotati di supporto sperimentale per i moduli ES, che consente anche agli sviluppatori non TypeScript di utilizzare le parole chiave export e import nel loro codice. A partire dalla versione 10, l'SDK Node.js per gli amministratori fornisce anche il supporto dei moduli ES, in modo che gli sviluppatori che implementano moduli ES su Node.js normale possano importare l'SDK utilizzando la sintassi import.

Per utilizzare i moduli ES con Admin SDK, assicurati innanzitutto di aver attivato il supporto ESM per il runtime Node.js. Questa operazione viene in genere eseguita aggiungendo un campo "type": "module" al file package.json. A questo punto puoi scrivere il codice dell'applicazione che ha il seguente aspetto:

// With {type: module} in the package.json...

// Import only what you need
import { initializeApp }  from 'firebase-admin/app';
import { getAuth } from 'firebase-admin/auth';

const app = initializeApp();

const token = await getAuth().createCustomToken('alice');

const user = getAuth().getUser('bob');