Upgrade auf das Node.js Admin SDK v10 (modulares SDK)

Version 10 des Admin Node.js SDK enthält zwei wichtige Änderungen:

  • Unterstützung für Node.js 10 wird eingestellt (Breaking Change)
  • Das SDK verwendet ein modulares API-Muster.

Dieser Leitfaden enthält Anleitungen und Informationen, die Entwicklern helfen, vorhandene Node.js-Apps von früheren Versionen des Admin SDK auf Version 10 zu aktualisieren.

Node.js auf Version 12 oder höher aktualisieren

Mit der Veröffentlichung von Admin Node.js SDK v10 hat Firebase die Unterstützung für Node.js 10 eingestellt. Entwickler müssen Node.js 12 oder höher verwenden, wenn sie die Admin SDK nutzen. Wenn Sie das Admin Node.js SDK zusammen mit Cloud Functions for Firebase verwenden, müssen Sie Ihre Node.js-Version auf 12 oder höher aktualisieren.

Module anstelle von Namespaces verwenden

Seit seiner Einführung bietet das Admin Node.js SDK eine stabile API, die als verschachtelte Namespace-Hierarchie strukturiert ist. Daher haben Sie vielleicht schon Code geschrieben, der so aussieht:

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

Ab Version 10 bietet das Admin Node.js SDK mehrere Moduleinstiegspunkte mit benannten Exporten. Wir empfehlen Entwicklern, diese neuen Einstiegspunkte für den Zugriff auf die verschiedenen APIs des SDK zu verwenden, anstatt den globalen admin-Namespace zu nutzen.

So würde das obige Beispiel mit den neuen Moduleinstiegspunkten aussehen:

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

Modulare Einstiegspunkte von Version 10 verwenden

Beachten Sie, dass Sie in den obigen Beispielen keinen globalen admin-Namespace mehr importieren. Stattdessen importieren Sie explizit nur die Symbole, die Sie von mehreren Moduleinstiegspunkten benötigen. Außerdem müssen TypeScript-Entwickler keine dreifach geschachtelten Typkennungen wie admin.auth.UserRecord und admin.database.Reference mehr verwenden. Da jeder Typ zu genau einem Modul gehört, können Sie sie einfach über ihre Kurznamen wie UserRecord und Reference importieren.

Hier sind alle Moduleinstiegspunkte aufgeführt, die im SDK ab Version 10 verfügbar sind:

  • 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

In der folgenden Tabelle finden Sie die Ersatz-Importsyntax für jede der Legacy-Namespace-Funktionen:

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();

Exportierte Funktionen anstelle von Methoden für App verwenden

In der alten API wurden für das App-Objekt eine Reihe von Methoden wie app.auth() und app.database() bereitgestellt. Wir empfehlen Entwicklern, diese Methoden nicht zu verwenden, sondern stattdessen die oben beschriebenen Moduleinstiegspunkte zu nutzen, um Dienstinstanzen zu erhalten, die auf ein bestimmtes App-Objekt beschränkt sind, und andere appspezifische Aufgaben auszuführen.

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

Unterstützung von ES-Modulen

Node.js 12 und höher bieten experimentelle Unterstützung für ES-Module, sodass auch Entwickler, die kein TypeScript verwenden, die Schlüsselwörter export und import in ihrem Code verwenden können. Ab Version 10 bietet das Admin Node.js SDK auch Unterstützung für ES-Module, sodass Entwickler, die ES-Module in reinem Node.js implementieren, das SDK mit der import-Syntax importieren können.

Wenn Sie ES-Module mit dem Admin SDK verwenden möchten, müssen Sie zuerst die ESM-Unterstützung für Ihre Node.js-Laufzeit aktivieren. Dazu wird normalerweise ein "type": "module"-Feld in die package.json-Datei eingefügt. Anschließend können Sie Anwendungscode schreiben, der so aussieht:

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