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

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

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

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

تثبيت واجهة سطر الأوامر 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) بشكل كامل مع واجهة CI وغيرها من البيئات التي بلا واجهة مستخدم رسومية.

1. على جهاز مزود بمتصفح، تثبيت واجهة سطر الأوامر Firebase

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، شغِّل الأمر التالي من داخل دليل التطبيق:

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 واجهة سطر الأوامر لأنه يحدد الملفات والإعدادات من دليل مشروعك التي يتم نشرها مشروع على 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 وفحص الأخطاء) أثناء الإعداد.

{
  "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 production (المنشورة) لمحاكاة 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" عملية نشر الرموز البرمجية والأصول في 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 مع الأوامر والخيارات التالية حذف الدوال المنشورة سابقًا:

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

  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 طلبات