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

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

• Il supporto per Node.js 10 è stato interrotto (si tratta di una modifica che comporta un'interruzione).
• 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 del Admin SDK alla v10.

Eseguire l'upgrade di Node.js alla v12 o versioni successive

Con il rilascio dell'SDK Admin Node.js v10, Firebase ha interrotto il supporto per Node.js 10. Gli sviluppatori devono utilizzare Node.js 12 o versioni successive quando utilizzano il 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 12 o versioni successive.

Utilizzare i moduli anziché gli spazi dei nomi

Fin dalla sua nascita, l'SDK Admin Node.js ha offerto un'API stabile strutturata come una gerarchia di spazi dei nomi nidificati. Di conseguenza, potresti aver acquisito familiarità 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 v10, l'SDK Admin Node.js offre più punti di ingresso dei moduli con esportazioni denominate. Consigliamo agli sviluppatori di utilizzare questi nuovi punti di ingresso per accedere alle varie API dell'SDK, anziché utilizzare lo spazio dei nomi globale admin.

Ecco come apparirebbe l'esempio precedente con i nuovi punti di ingresso dei 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');

Utilizzare i punti di ingresso modulari della v10

Tieni presente che, negli esempi precedenti, non stai più importando uno spazio dei nomi admin globale. Al contrario, importi in modo esplicito solo i simboli di cui hai bisogno da diversi punti di ingresso dei moduli. Inoltre, gli sviluppatori TypeScript non devono più utilizzare identificatori di tipo a tripla nidificazione come admin.auth.UserRecord e admin.database.Reference. Poiché ogni tipo appartiene a un solo modulo, puoi importarli semplicemente con i loro nomi brevi, ad esempio UserRecord e Reference.

Ecco tutti i punti di ingresso dei moduli disponibili nell'SDK a partire dalla v10:

• 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 su App

Nell'API legacy, 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 sopra per ottenere istanze di servizio con ambito a un determinato oggetto App ed eseguire altre attività specifiche dell'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 includono il supporto sperimentale per i moduli ES, consentendo anche agli sviluppatori non TypeScript di utilizzare le parole chiave export e import nel codice. A partire dalla versione v10, l'SDK Admin Node.js fornisce anche il supporto per i moduli ES, in modo che gli sviluppatori che implementano i moduli ES su Node.js semplice possano importare l'SDK utilizzando la sintassi import.

Per utilizzare i moduli ES con Admin SDK, assicurati innanzitutto di aver abilitato il supporto ESM per il runtime Node.js. In genere, questa operazione viene eseguita aggiungendo un campo "type": "module" al file package.json. Poi puoi scrivere codice dell'applicazione simile al seguente:

// 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');