升級至 Node.js SDK Admin SDK v10 (模組 SDK)

Admin Node.js SDK 10 版包含兩項重要變更:

  • 停止支援 Node.js 10 (這是破壞性變更)
  • SDK 已採用模組化 API 模式

本指南提供操作說明和相關資訊,協助開發人員將現有的 Node.js 應用程式從舊版 Admin SDK 升級至 v10。

將 Node.js 更新至 v12 以上版本

隨著 Admin Node.js SDK v10 推出,Firebase 已停止支援 Node.js 10。開發人員使用 Admin SDK 時,必須採用 Node.js 12 以上版本。如果您搭配 Cloud Functions for Firebase 使用 Admin Node.js SDK,請確認您的 Node.js 版本已升級為 12 以上。

使用模組而非命名空間

Admin Node.js SDK 自成立以來,已提供以巢狀結構命名空間階層形式提供的穩定版 API。因此,您可能已經熟悉如何編寫如下的程式碼:

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

Admin Node.js SDK 從 v10 開始提供多個模組進入點,具備已命名的匯出功能。建議開發人員透過這些新的進入點存取 SDK 的各種 API,不要使用全域 admin 命名空間。

上述範例使用新模組進入點如下所示:

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

使用 v10 模組進入點

請注意,在上述範例中,您已不再匯入全域 admin 命名空間。而是只從多個模組進入點明確匯入需要的符號。此外,TypeScript 開發人員不再需要使用三重巢狀類型 ID,例如 admin.auth.UserRecordadmin.database.Reference。由於每種類型都隸屬於一個模組,因此只要用其簡稱 (例如 UserRecordReference) 匯入即可。

以下是自 10 版起,SDK 中提供的所有模組進入點:

  • firebase-admin/應用程式
  • firebase-admin/auth
  • firebase-admin/資料庫
  • firebase-admin/firestore
  • firebase-admin/instance-id
  • firebase-admin/machine-learning
  • firebase-admin/messaging
  • firebase-admin/專案管理
  • firebase-admin/remote-config
  • firebase-admin/security-rules
  • firebase-admin/儲存空間

下表列出每個舊版命名空間函式的替換匯入語法:

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

在應用程式中使用匯出的函式,而非方法

在舊版 API 中,App 物件公開了多個方法,例如 app.auth()app.database()。我們建議開發人員避免使用這些方法,改用上述相同的模組進入點,取得限定於特定 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);

支援 ES 模組

Node.js 12 以上版本針對 ES 模組提供實驗性支援,方便非 TypeScript 開發人員在程式碼中使用 exportimport 關鍵字。從 v10 版本開始,Admin Node.js SDK 也提供 ES 模組支援,讓在純 Node.js 上實作 ES 模組的開發人員可以使用 import 語法匯入 SDK。

如要搭配 Admin SDK 使用 ES 模組,請先確認您已為 Node.js 執行階段啟用 ESM 支援。一般的做法是在 package.json 檔案中加入 "type": "module" 欄位。接著,您可以編寫類似下方的應用程式程式碼:

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