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

يقدّم الإصدار 10 من حزمة تطوير البرامج (SDK) الخاصة بـ Admin Node.js تغييرَين مهمَّين:

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

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

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

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

يوضّح الجدول التالي بنية الاستيراد البديلة لكل دالة من دوال مساحة الاسم القديمة:

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

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

في واجهة برمجة التطبيقات القديمة، كان العنصر 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

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