الترقية إلى الإصدار 10 من حزمة تطوير البرامج (SDK) للمشرف على Node.js (حزمة تطوير برامج (SDK) نموذجية)

يقدّم الإصدار 10 من حزمة Admin Node.js SDK تغييرَين مهمّين:

  • إيقاف دعم Node.js 10 (هذا تغيير جذري)
  • استخدام حزمة SDK لنمط واجهات برمجة التطبيقات المكوّنة من وحدات

يوفّر هذا الدليل تعليمات ومعلومات لمساعدة المطوّرين في ترقية تطبيقات Node.js الحالية من الإصدارات السابقة من Admin SDK إلى الإصدار 10.

تحديث Node.js إلى الإصدار 12 أو إصدار أحدث

مع إصدار حزمة تطوير البرامج (SDK) لإصدار Admin Node.js 10، أوقفت Firebase استخدام Node.js 10. على المطوّرين استخدام الإصدار 12 من Node.js أو إصدار أحدث عند استخدام Admin SDK. إذا كنت تستخدِم حزمة SDK المخصّصة للمشرفين من Node.js مع Cloud Functions for Firebase، تأكّد من ترقية إصدار Node.js إلى 12 أو إصدار أحدث.

استخدام الوحدات بدلاً من مساحات الاسماء

منذ إنشائها، قدّمت حزمة Admin Node.js SDK واجهة برمجة تطبيقات ثابتة منظَّمة كسلسل هرمي لمجال الاسم. نتيجةً لذلك، ربما تكون قد تعرّفت على كتابة رمز برمجي يبدو على النحو التالي:

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

اعتبارًا من الإصدار 10، تقدّم حزمة Admin Node.js SDK نقاط دخول متعددة للمَعلمات مع عمليات التصدير المُسمّاة. ننصح مطوّري البرامج باستخدام نقاط الإدخال الجديدة هذه للوصول إلى واجهات برمجة التطبيقات المتنوعة في حزمة SDK، بدلاً من استخدام مساحة الاسم العالمية 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');

استخدام نقاط الدخول المُركّبة في الإصدار 10

يُرجى العِلم أنّه في الأمثلة أعلاه، لم تعُد تستورد مساحة اسم admin شاملة. بدلاً من ذلك، يمكنك استيراد الرموز التي تحتاج إليها فقط من عدة نقاط دخول للوحدة النمطية. بالإضافة إلى ذلك، لم يعد مطوّرو TypeScript مضطرين إلى استخدام معرّفات الأنواع الثلاثية المُدمجة، مثل 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/messaging
  • firebase-admin/project-management
  • firebase-admin/remote-config
  • firebase-admin/security-rules
  • firebase-admin/storage

يعرض الجدول التالي بنية الاستيراد البديلة لكلٍّ من دوال ملف تعريف الارتباط القديمة:

الإصدار 9 الإصدار 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();

استخدام الدوالّ التي تمّ تصديرها بدلاً من الطرق في التطبيق

في واجهة برمجة التطبيقات القديمة، كان كائن App يعرِض عددًا من الطرق مثل app.auth() وapp.database(). ننصح المطوّرين بتجنُّب استخدام هذين الأسلوبين، واستخدام نقاط دخول الوحدة نفسها الموضّحة أعلاه للحصول على مثيلات الخدمة التي تستهدف عنصر App معيّنًا، وتنفيذ مهام أخرى خاصة بالتطبيق.

الإصدار 9 الإصدار 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);

توافق وحدات ES

يتوفّر في الإصدار 12 من Node.js والإصدارات الأحدث دعم تجريبي لحِزم ES، ما يتيح حتى للمطوّرين الذين لا يستخدمون TypeScript استخدام الكلمات الرئيسية export وimport في رمزهم البرمجي. اعتبارًا من الإصدار 10، توفّر حزمة Admin Node.js SDK أيضًا دعمًا لوحدات ES، حتى يتمكّن المطوّرون الذين ينفذون وحدات ES على Node.js البسيط من استيراد حزمة SDK باستخدام بنية import.

لاستخدام وحدات ES مع Admin SDK، تأكَّد أولاً من تفعيل ميزة ESM لوقت تشغيل Node.js. ويتم ذلك عادةً من خلال إضافة حقل "type": "module" إلى ملف package.json. يمكنك بعد ذلك كتابة رمز التطبيق الذي يبدو على النحو التالي:

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