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

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

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

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

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

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

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

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

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