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

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

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

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

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

مع إصدار حزمة Admin Node.js SDK الإصدار 10، أوقفت Firebase دعم Node.js 10. على المطوّرين استخدام Node.js 12 أو إصدار أحدث عند استخدام Admin SDK. إذا كنت تستخدم حزمة Admin Node.js SDK مع 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 يعرض عددًا من الطرق، مثل 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

يتضمّن Node.js 12 والإصدارات الأحدث دعمًا تجريبيًا لوحدات 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');