第 10 版 Admin Node.js SDK 引進了兩項重要變更:
- 停止支援 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 以上版本。如果您同時使用 Admin Node.js SDK 與 Cloud Functions for Firebase,請確定已將 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');
從 v10 版開始,Admin Node.js SDK 提供多個模組進入點和已命名的匯出項目。我們建議開發人員使用這些新的進入點存取 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.UserRecord
和 admin.database.Reference
。由於每個類型都只有一個模組,因此只要使用簡稱 (例如 UserRecord
和 Reference
) 即可匯入。
以下是 SDK 自第 10 版起提供的所有模組進入點:
- firebase-admin/app
- firebase-admin/auth
- firebase-admin/database
- firebase-admin/firestore
- firebase-admin/instance-id
- firebase-admin/machine-learning
- firebase-admin/訊息
- firebase-admin/project-management
- firebase-admin/remote-config
- firebase-admin/security-rules
- firebase-admin/storage
下表列出每個舊版命名空間函式的替換匯入語法:
v9 | v10 |
---|---|
admin.initializeApp()
|
import { initializeApp } from 'firebase-admin/app'
|
admin.app()
|
import { getApp } from 'firebase-admin/ap'
|
admin.credential.cert()
|
import { cert } from 'firebase-admin/app'
|
admin.auth()
|
import { getAuth } from 'firebase-admin/auth'
|
admin.database()
|
import { getDatabase } from 'firebase-admin/database'
|
admin.firestore()
|
import { getFirestore } from 'firebase-admin/firestore'
|
admin.instanceId()
|
import { getInstanceId } from 'firebase-admin/instance-id'
|
admin.machineLearning()
|
import { getMachineLearning } from 'firebase-admin/machine-learning'
|
admin.messaging()
|
import { getMessaging } from 'firebase-admin/messaging'
|
admin.projectManagement()
|
import { getProjectManagement } from 'firebase-admin/project-management'
|
admin.remoteConfig()
|
import { getRemoteConfig } from 'firebase-admin/remote-config'
|
admin.securityRules()
|
import { getSecurityRules } from 'firebase-admin/security-rules'
|
admin.storage()
|
import { getStorage } from 'firebase-admin/storage'
|
在應用程式中使用匯出的函式 (而非方法)
在舊版 API 中,App
物件公開了許多方法,例如 app.auth()
和 app.database()
。我們建議開發人員避免使用這些方法,而是改用上述的模組進入點,取得範圍限定為指定 App
物件的服務執行個體,並執行其他應用程式專屬工作。
v9 | v10 |
---|---|
app.auth()
|
import { getAuth } from 'firebase-admin/auth';
|
app.database()
|
import { getDatabase } from 'firebase-admin/database';
|
app.database(url)
|
import { getDatabaseWithUrl } from 'firebase-admin/database';
|
app.firestore()
|
import { getFirestore } from 'firebase-admin/firestore'
|
app.instanceId()
|
import { getInstanceId } from 'firebase-admin/instance-id'
|
app.machineLearning()
|
import { getMachineLearning } from 'firebase-admin/machine-learning'
|
app.messaging()
|
import { getMessaging } from 'firebase-admin/messaging'
|
app.projectManagement()
|
import { getProjectManagement } from 'firebase-admin/project-management'
|
app.remoteConfig()
|
import { getRemoteConfig } from 'firebase-admin/remote-config'
|
app.securityRules()
|
import { getSecurityRules } from 'firebase-admin/security-rules'
|
app.storage()
|
import { getStorage } from 'firebase-admin/storage'
|
app.delete()
|
import { deleteApp } from 'firebase-admin/app';
|
ES 模組支援
Node.js 12 以上版本提供 ES 模組的實驗性支援,即使是非 TypeScript 開發人員也能在程式碼中使用 export
和 import
關鍵字。從 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');