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

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

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

In dieser Anleitung finden Sie Informationen und Anweisungen, 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 des Admin Node.js SDK Version 10 hat Firebase die Unterstützung für Node.js 10 eingestellt. Entwickler müssen Node.js 12 oder höher verwenden, wenn sie das Admin SDK nutzen. Wenn Sie das Admin Node.js SDK zusammen mit Cloud Functions for Firebase, stellen Sie sicher, dass Sie Ihre Node.js-Version auf 12 oder höher aktualisiert haben.

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 sind Sie möglicherweise mit dem Schreiben von Code vertraut, 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 zu verwenden, um auf die verschiedenen APIs des SDK zuzugreifen, anstatt den globalen admin-Namespace zu verwenden.

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

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

Hier sind alle Moduleinstiegspunkte, die ab Version 10 im SDK 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

Die folgende Tabelle zeigt die Ersatzimportsyntax für jede der Legacy-Namespace-Funktionen:

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

Exportierte Funktionen anstelle von Methoden für App verwenden

In der Legacy-API hat 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 abzurufen, die auf ein bestimmtes App-Objekt beschränkt sind, und andere appspezifische Aufgaben auszuführen.

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

Unterstützung für ES-Module

Node.js 12 und höher bieten experimentelle Unterstützung für ES-Module, sodass auch Nicht-TypeScript-Entwickler 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. Dies erfolgt in der Regel durch Hinzufügen eines "type": "module" Felds zu Ihrer package.json-Datei. Dann 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');