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

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

  • Il supporto per Node.js 10 non è più disponibile (questa è una modifica definitiva)
  • 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 la release v10 dell'SDK Admin Node.js, Firebase non supporta più Node.js 10. Gli sviluppatori devono utilizzare Node.js 12 o versioni successive quando utilizzano Admin SDK. Se utilizzi l'SDK Admin Node.js insieme a Cloud Functions for Firebase, assicurati di aver eseguito l'upgrade della versione di Node.js alla versione 12 o successiva.

Utilizza i moduli anziché gli spazi dei nomi

Sin dalla sua creazione, l'SDK Admin Node.js ha offerto un'API stabile strutturata come gerarchia degli spazi dei nomi nidificata. 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 di Amministrazione 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 l'aspetto dell'esempio precedente con i nuovi punti di contatto per i moduli:

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 stai più importando 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 dei tipi con tripla nidificazione, 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 Versione 10
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 ingresso dei moduli descritti in precedenza per ottenere istanze di servizio con un determinato oggetto App ed eseguire altre attività specifiche dell'app.

Versione 9 Versione 10
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 includono il supporto sperimentale per i moduli ES, consentendo 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 li implementano 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');