مرجع واجهة سطر الأوامر في Firebase

توفّر واجهة Firebase CLI (GitHub) مجموعة متنوعة من الأدوات لإدارة مشاريع Firebase وعرضها ونشرها.

قبل استخدام Firebase CLI، عليك إعداد مشروع على Firebase.

إعداد سطر الأوامر (CLI) أو تعديله

تثبيت واجهة سطر أوامر Firebase

يمكنك تثبيت واجهة سطر أوامر Firebase باستخدام طريقة تتوافق مع نظام التشغيل ومستوى الخبرة و/أو حالة الاستخدام. بغض النظر عن طريقة تثبيت CLI، يمكنك الوصول إلى الوظائف نفسها واستخدام الأمر firebase.

Windows macOS Linux

Windows

يمكنك تثبيت Firebase CLI لنظام التشغيل Windows باستخدام أحد الخيارين التاليين:

macOS أو Linux

يمكنك تثبيت Firebase CLI لنظام التشغيل macOS أو Linux باستخدام أحد الخيارَين التاليَين:

تسجيل الدخول واختبار واجهة برمجة التطبيقات Firebase

بعد تثبيت واجهة برمجة التطبيقات، عليك المصادقة. بعد ذلك، يمكنك تأكيد المصادقة من خلال إدراج مشاريعك على Firebase.

1. سجِّل الدخول إلى Firebase باستخدام حسابك على Google من خلال تنفيذ العبارة التالية:

   firebase login

   يربط هذا الأمر جهازك المحلي بـ Firebase ويمنحك إذن الوصول إلى مشاريعك على Firebase.

2. تحقَّق من تثبيت واجهة برمجة التطبيقات بشكلٍ صحيح ووصولها إلى حسابك من خلال إدراج مشاريعك على Firebase. نفِّذ الأمر التالي:

   firebase projects:list

   يجب أن تكون القائمة المعروضة مطابقة لمشاريع Firebase المدرَجة في وحدة تحكُّم Firebase.

التحديث إلى أحدث إصدار من واجهة سطر الأوامر

بشكل عام، عليك استخدام أحدث إصدار من واجهة سطر أوامر Firebase.

تعتمد طريقة تحديث إصدار واجهة برمجة التطبيقات على نظام التشغيل وطريقة تثبيت واجهة برمجة التطبيقات.

استخدام سطر الأوامر مع أنظمة التطوير المتداخل (CI)

تتطلّب واجهة Firebase CLI متصفّحًا لإكمال المصادقة، ولكن واجهة CLI متوافقة تمامًا مع بيئة CI والبيئات الأخرى التي لا تتضمّن واجهة مستخدم.

1. على جهاز مزوّد بمتصفّح، ثبِّت Firebase CLI.

2. ابدأ عملية تسجيل الدخول من خلال تنفيذ الأمر التالي:

   firebase login:ci

3. يُرجى الانتقال إلى عنوان URL المقدَّم، ثم تسجيل الدخول باستخدام حساب Google.

4. اطبع رمزًا مميزًا جديدًا لإعادة التحميل. ولن تتأثر جلسة CLI الحالية.

5. تخزين الرمز المميّز للإخراج بطريقة آمنة يمكن الوصول إليها في نظام التطوير المتكامل (CI)

6. استخدِم هذا الرمز المميّز عند تنفيذ أوامر firebase. يمكنك استخدام أحد الخيارين التاليين:

   • الخيار 1: تخزين الرمز المميّز كمتغيّر بيئة FIREBASE_TOKEN سيستخدم نظامك الرمز المميّز تلقائيًا.

   • الخيار 2: يمكنك تنفيذ جميع أوامر firebase باستخدام الخيار --token TOKEN في نظام التطوير المتكامل (CI).
     في ما يلي ترتيب الأولوية لتحميل الرمز المميّز: العلامة ومتغيّر البيئة ومشروع Firebase المطلوب.

بدء مشروع على Firebase

تتطلّب العديد من المهام الشائعة التي يتم تنفيذها باستخدام واجهة برمجة التطبيقات (CLI)، مثل النشر في أحد مشاريع Firebase، دليل مشروع. يمكنك إنشاء دليل مشروع باستخدام الأمر firebase init. يكون دليل المشروع عادةً هو الدليل نفسه مثل دليل التحكّم في المصدر، وبعد تشغيل firebase init، يحتوي الدليل على ملف firebase.jsonملف ملف الإعدادات.

لبدء مشروع جديد على Firebase، شغِّل الأمر التالي من داخل directory التطبيق:

firebase init

يرشدك الأمر firebase init خلال عملية إعداد دليل مشروعك وبعض منتجات Firebase. أثناء بدء المشروع، يطلب منك Firebase CLI إكمال المهام التالية:

• اختَر منتجات Firebase المطلوبة لإعدادها في مشروعك على Firebase.

  تطلب منك هذه الخطوة ضبط إعدادات لملفات معيّنة ل المنتجات المحدّدة. لمزيد من التفاصيل حول هذه الإعدادات، راجِع مستندات المنتج المعنيّ (مثل، Hosting). يُرجى العِلم أنّه يمكنك دائمًا تشغيل firebase init لاحقًا لإعداد المزيد من منتجات Firebase.

• اختَر مشروعًا تلقائيًا على Firebase.

  تربط هذه الخطوة دليل المشروع الحالي بمشروع Firebase لكي تتم تنفيذ الأوامر الخاصة بالمشروع (مثل firebase deploy) في مشروع Firebase المناسب.

  من الممكن أيضًا ربط مشاريع متعددة في Firebase (مثل مشروع تنظيم ومشروع اختبار علني) بدليل المشروع نفسه.

في نهاية عملية الإعداد، تنشئ Firebase تلقائيًا المملفَّين التاليين في ملف ‎"جذر" دليل التطبيق على الجهاز:

• ملف إعدادات firebase.json يسرد إعدادات مشروعك

• ملف .firebaserc لتخزين الأسماء البديلة لمشروعك

ملف firebase.json

ينشئ الأمر firebase init ملف إعدادات firebase.json في الدليل الجذر لدليل مشروعك.

يجب استخدام ملف firebase.json لنشر مواد العرض باستخدام Firebase CLI لأنّه يحدّد الملفات والإعدادات التي يتم نشرها من دليل مشروعك إلى مشروعك على Firebase. بما أنّه يمكن تحديد بعض الإعدادات في ملف المشروعات الدليل أو في وحدة تحكّمFirebase، احرص على حلّ أي تعارضات محتملة في عملية النشر.

يمكنك ضبط معظم خيارات Firebase Hosting مباشرةً في ملف firebase.json. ومع ذلك، بالنسبة إلى خدمات Firebase الأخرى التي يمكن نشرها باستخدام واجهة برمجة التطبيقات Firebase، يُنشئ الأمر firebase init ملفات محدّدة يمكنك من خلالها تحديد الإعدادات لتلك الخدمات، مثل ملف index.js لخدمة Cloud Functions. يمكنك أيضًا إعداد مخطّطات الربط قبل النشر أو بعد النشر في ملف firebase.json.

في ما يلي مثال على ملف firebase.json بالإعدادات التلقائية في حال تحديدFirebase Hosting وCloud Firestore وCloud Functions for Firebase (مع تحديد خيارات مصدر TypeScript وlint) أثناء الإعداد.

{
  "hosting": {
    "public": "public",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ]
  },
  "firestore": {
      "rules": "firestore.rules",
      "indexes": "firestore.indexes.json"
  },
  "functions": {
    "predeploy": [
      "npm --prefix \"$RESOURCE_DIR\" run lint",
      "npm --prefix \"$RESOURCE_DIR\" run build"
    ]
  }
}

في حين أنّه يتم استخدام firebase.json تلقائيًا، يمكنك تمرير العلامة --config PATH لتحديد ملف إعداداتبديل.

ضبط قواعد بيانات Cloud Firestore متعددة

عند تشغيل firebase init، سيحتوي ملف firebase.json على مفتاح firestore واحد يتوافق مع قاعدة البيانات التلقائية لمشروعك، كما هو موضّح أعلاه.

إذا كان مشروعك يحتوي على قواعد بيانات Cloud Firestore متعددة، عدِّل ملف firebase.json لربط ملفات مصادر فهرس Cloud Firestore Security Rules و مختلفة لكل قاعدة بيانات. عدِّل الملف باستخدام مصفوفة JSON، مع إدخال واحد لكل قاعدة بيانات.

      "firestore": [
        {
          "database": "(default)",
          "rules": "firestore.default.rules",
          "indexes": "firestore.default.indexes.json"
        },
        {
          "database": "ecommerce",
          "rules": "firestore.ecommerce.rules",
          "indexes": "firestore.ecommerce.indexes.json"
        }
      ],

Cloud Functions ملفّات يجب تجاهلها عند النشر

في وقت نشر الدالة، تحدِّد واجهة سطر الأوامر تلقائيًا قائمة بالملفات في الدليل functions التي يجب تجاهلها. ويؤدي ذلك إلى منع نشر ملفات غير ضرورية في الخلفية قد تؤدي إلى زيادة حجم البيانات التي يتم نشرها.

في ما يلي قائمة الملفات التي يتم تجاهلها تلقائيًا، والتي تظهر بتنسيق JSON:

"ignore": [
  ".git",
  ".runtimeconfig.json",
  "firebase-debug.log",
  "firebase-debug.*.log",
  "node_modules"
]

في حال إضافة قيم مخصّصة خاصة بك إلى ignore في firebase.json، تأكَّد من الاحتفاظ بقائمة الملفات الموضّحة أعلاه (أو إضافتها إذا لم تكن متوفّرة).

إدارة الأسماء البديلة للمشاريع

يمكنك ربط عدة مشاريع على Firebase بدليل المشروع نفسه. على سبيل المثال، قد تحتاج إلى استخدام مشروع Firebase واحد للتنظيم ومشروع آخر للإصدار العلني. باستخدام بيئات المشاريع المختلفة، يمكنك التحقّق من التغييرات قبل نشرها في قناة الإصدار العلني. يتيح لك الأمر firebase use التبديل بين العناوين البديلة وإنشاء عناوين بديلة جديدة.

إضافة اسم مستعار للمشروع

عند اختيار مشروع Firebase أثناء تهيئة المشروع، يتم تلقائيًامنح المشروع الاسم المعرِّف default. ومع ذلك، للسماح بتنفيذ الأوامر الخاصة بالمشروع في مشروع مختلف على Firebase مع الاستمرار في استخدام دليل المشروع نفسه، نفِّذ الأمر التالي من داخل دليل مشروعك:

firebase use --add

• عرض المحتوى الثابت لتطبيقك المستضاف على Firebase
• استخدِم Cloud Functions لإنشاء محتوى ديناميكي لأجل Firebase Hosting وتريد استخدام الدوالّ العلنية (المُنشرة) لبروتوكول HTTP لمحاكاة Hosting على عنوان URL محلي.

firebase serve --only hosting

محاكاة مشروعك باستخدام وظائف HTTP المحلية

نفِّذ أيًا من الأوامر التالية من دليل مشروعك لمحاكاة مشروعك باستخدام وظائف HTTP المحلية.

• لمحاكاة وظائف HTTP والاستضافة للاختبار على عناوين URL محلية، استخدِم أيًا مما يلي من الأوامر التالية:

  firebase serve

  firebase serve --only functions,hosting // uses a flag

• لمحاكاة وظائف HTTP فقط، استخدِم الأمر التالي:

  firebase serve --only functions

الاختبار من الأجهزة المحلية الأخرى

بشكلٍ تلقائي، لا يستجيب firebase serve إلا للطلبات الواردة من localhost. ويعني ذلك أنّه ستتمكّن من الوصول إلى المحتوى المستضاف من متصفّح الويب على جهاز الكمبيوتر، ولكن ليس من الأجهزة الأخرى على شبكتك. إذا أردت إجراء الاختبار من أجهزة محلية أخرى، استخدِم العلامة --host على النحو التالي:

firebase serve --host 0.0.0.0  // accepts requests to any host

النشر في مشروع على Firebase

تدير واجهة Firebase CLI عملية نشر الرموز البرمجية ومواد العرض في مشروعك على Firebase، بما في ذلك:

• الإصدارات الجديدة من Firebase Hosting موقعك الإلكتروني
• Cloud Functions for Firebase جديدة أو معدَّلة أو حالية
• مخطّطات وموصّلات جديدة أو معدَّلة لـ Firebase Data Connect
• القواعد المتعلّقة بـ Firebase Realtime Database
• القواعد المتعلّقة بـ Cloud Storage for Firebase
• القواعد المتعلّقة بـ Cloud Firestore
• مؤشرات Cloud Firestore

للنشر في مشروع على Firebase، نفِّذ الأمر التالي من دليل مشروعك:

firebase deploy

يمكنك اختياريًا إضافة تعليق إلى كل عملية من عمليات النشر. سيتم عرض هذا التعليق مع معلومات النشر الأخرى في Firebase Hosting صفحة مشروعك. على سبيل المثال:

firebase deploy -m "Deploying the best new feature ever."

عند استخدام الأمر firebase deploy، يُرجى مراعاة ما يلي:

• لنشر الموارد من دليل مشروع، يجب أن يحتوي دليل المشروع على ملف firebase.json. يتم إنشاء هذا الملف تلقائيًا باستخدام الأمر firebase init.

• ينشئ firebase deploy إصدارًا تلقائيًا لجميع الموارد القابلة للنشر في دليل مشروعك. لنشر خدمات أو ميزات Firebase معيّنة، استخدِم النشر الجزئي.

تعارضات النشر لقواعد الأمان

بالنسبة إلى Firebase Realtime Database وCloud Storage for Firebase وCloud Firestore، يمكنك تحديد قواعد الأمان إما في دليل المشروع المحلي أو في وحدة تحكّم Firebase.

هناك خيار آخر لتجنُّب تعارضات النشر وهو استخدام النشر الجزئي وتحديد القواعد فقط في وحدة تحكّم Firebase.

حصص النشر

من الممكن (على الرغم من أنّه من غير المرجّح) أن تتجاوز حصة تحدّ من معدّل أو حجم عمليات نشر Firebase. على سبيل المثال، عند نشر أعداد كبيرة جدًا من الدوال، قد تتلقّى HTTP 429 Quota رسالة خطأ. لحلّ هذه المشاكل، جرِّب استخدام النشر الجزئي.

التراجع عن عملية نشر

يمكنك التراجع عن عملية نشر Firebase Hosting من Firebase Hosting صفحة مشروعك من خلال اختيار إجراء التراجع للإصدار المطلوب.

لا يمكن حاليًا التراجع عن إصدارات قواعد الأمان لتطبيق Firebase Realtime Database أو Cloud Storage for Firebase أو Cloud Firestore.

نشر خدمات Firebase محدّدة

إذا كنت تريد فقط نشر خدمات أو ميزات Firebase معيّنة، يمكنك استخدام قائمة مفصولة بفواصل في علامة على الأمر firebase deploy. على سبيل المثال، ينشر الأمر التالي قواعد أمان Firebase Hosting وCloud Storage للمحتوى.

firebase deploy --only hosting,storage

يسرد الجدول التالي الخدمات والميزات المتاحة للاستخدام في عملية الطرح الجزئي. تتطابق الأسماء الواردة في العلامات مع المفاتيح في ملف الإعدادات firebase.json.

نشر دوالّ معيّنة

عند نشر الدوالّ، يمكنك استهداف دوالّ معيّنة. على سبيل المثال:

firebase deploy --only functions:function1

firebase deploy --only functions:function1,functions:function2

هناك خيار آخر وهو تجميع الدوالّ في مجموعات تصدير في ملف /functions/index.js. يتيح لك تجميع الدوالّ نشر عدة دوالّ باستخدام أمر واحد.

على سبيل المثال، يمكنك كتابة الدالتَين التاليتَين لتعريف groupA و groupB:

var functions = require('firebase-functions/v1');

exports.groupA = {
  function1: functions.https.onRequest(...),
  function2: functions.database.ref('\path').onWrite(...)
}
exports.groupB = require('./groupB');

في هذا المثال، يحتوي ملف functions/groupB.js منفصل على دوال إضافية تحدّد على وجه التحديد الدوال في groupB. على سبيل المثال:

var functions = require('firebase-functions/v1');

exports.function3 = functions.storage.object().onChange(...);
exports.function4 = functions.analytics.event('in_app_purchase').onLog(...);

في هذا المثال، يمكنك نشر جميع دوال groupA من خلال تنفيذ العبارة التالية من دليل المشروع:

firebase deploy --only functions:groupA

أو يمكنك استهداف دالة معيّنة ضمن مجموعة من خلال تنفيذ العبارة التالية:

firebase deploy --only functions:groupA.function1,groupB.function4

حذف الدوالّ

تتيح لك واجهة Firebase CLI الأوامر والخيارات التالية ل حذف الدوالّ التي تم نشرها سابقًا:

• لحذف جميع الدوال التي تتطابق مع الاسم المحدّد في جميع المناطق:

  firebase functions:delete FUNCTION-1_NAME

• لحذف دالة محدّدة تعمل في منطقة غير تلقائية:

  firebase functions:delete FUNCTION-1_NAME --region REGION_NAME

• حذف أكثر من دالة واحدة:

  firebase functions:delete FUNCTION-1_NAME FUNCTION-2_NAME

• لحذف مجموعة دوال محدّدة:

  firebase functions:delete GROUP_NAME

• تخطّي طلب التأكيد:

  firebase functions:delete FUNCTION-1_NAME --force

إعداد المهام البرمجية قبل النشر وبعده

يمكنك ربط النصوص البرمجية لنظام التشغيل Shell بأمر firebase deploy لتنفيذ المهام المتعلقة بالنشر المُسبَق أو ما بعد النشر. على سبيل المثال، يمكن أن يُستخدم نص برمجي قبل النشر لتحويل رمز TypeScript إلى JavaScript، ويمكن أن يُستخدم إجراء لاحق للنشر لإرسال إشعارات إلى المدراء بشأن عمليات نشر محتوى الموقع الإلكتروني الجديد إلى Firebase Hosting.

لإعداد أدوات الربط قبل النشر أو بعد النشر، أضِف نصوص bash البرمجية إلى ملف إعدادات firebase.json. يمكنك تحديد النصوص البرمجية الموجزة مباشرةً في ملف firebase.json، أو يمكنك الإشارة إلى ملفات أخرى في دليل مشروعك.

على سبيل المثال، النص البرمجي التالي هو تعبير firebase.json لمهمّة بعد النشر تُرسِل رسالة Slack عند النشر الناجح إلى Firebase Hosting.

"hosting": {
  // ...

  "postdeploy": "./messageSlack.sh 'Just deployed to Firebase Hosting'",
  "public": "public"
}

يتوفّر ملف نص البرمجة messageSlack.sh في دليل المشروع، ويظهر بالشكل التالي:

curl -X POST -H 'Content-type: application/json' --data '{"text":"$1"}'
     \https://SLACK_WEBHOOK_URL

يمكنك إعداد علامتَي الربط predeploy وpostdeploy لأيّ من مواد العرض التي يمكنك نشرها. يُرجى العِلم أنّ تشغيل firebase deploy يؤدي إلى بدء جميع مهام ما قبل النشر وما بعد النشر المحدّدة فيملف firebase.json. لتنفيذ المهام المرتبطة فقط بأحد خدمات Firebase، استخدِم أوامر النشر الجزئي.

تُطبع كلتا علامتَي الربط predeploy وpostdeploy مخرجات النصوص البرمجية العادية ورسائل الخطأ في وحدة التحكّم الطرفية. في حالات الفشل، يُرجى مراعاة ما يلي:

• إذا تعذّر إكمال أحد أدوات الربط الخاصة بالنشر المُسبَق على النحو المتوقّع، يتم إلغاء عملية النشر.
• إذا تعذّر النشر لأي سبب، لن يتم تنشيط عمليات الربط بعد النشر.

متغيّرات البيئة

ضمن النصوص البرمجية التي يتم تشغيلها في علامتَي الربط predeploy وpostdeploy، تتوفّر متغيّرات الاطّلاع التالية:

• $GCLOUD_PROJECT: رقم تعريف المشروع النشط
• $PROJECT_DIR: الدليل الجذر الذي يحتوي على ملف firebase.json
• $RESOURCE_DIR: (لنصوص hosting وfunctions فقط) الموقع الجغرافي للدليل الذي يحتوي على موارد Hosting أو Cloud Functions المطلوب نشرها

إدارة نُسخ متعددة من Realtime Database

يمكن أن يتضمّن مشروع Firebase نُسخ متعددة من Firebase Realtime Database. تتفاعل أوامر واجهة سطر الأوامر بشكلٍ تلقائي مع مثيل قاعدة البيانات التلقائي.

ومع ذلك، يمكنك التفاعل مع مثيل قاعدة بيانات غير تلقائي باستخدام العلامة --instance DATABASE_NAME. تتيح الطلبات التالية استخدام العلامة --instance:

• firebase database:get
• firebase database:profile
• firebase database:push
• firebase database:remove
• firebase database:set
• firebase database:update

مرجع الأوامر

الأوامر الإدارية لواجهة سطر الأوامر

أوامر إدارة المشاريع

النشر والتطوير المحلي

تتيح لك هذه الأوامر نشر موقعك الإلكتروني على Firebase Hosting والتفاعل معه.

App Distribution الأوامر

App Hosting الأوامر

أوامر Authentication (إدارة المستخدمين)

Cloud Firestore الأوامر

Cloud Functions for Firebase الأوامر

لمزيد من المعلومات، يُرجى الرجوع إلى مستندات إعدادات البيئة.

Crashlytics الأوامر

Data Connect الأوامر

يمكنك الاطّلاع على مزيد من التفاصيل حول هذه الأوامر وحالات استخدامها في Data Connect دليل CLI المرجعي.

Extensions الأوامر

Extensions أوامر الناشر

Hosting الأوامر

Realtime Database الأوامر

يُرجى العِلم أنّه يمكنك إنشاء مثيل Realtime Database أولي تلقائي في وحدة تحكّم Firebase أو باستخدام عملية firebase init العمل العامة أو عملية firebase init database المحدّدة.

بعد إنشاء النُسخ، يمكنك إدارتها كما هو موضّح في مقالة إدارة نُسخ متعددة من Realtime Database.

Remote Config الأوامر