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

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

توفّر واجهة سطر الأوامر أوامر يمكن استخدامها لتنفيذ مجموعة متنوعة من Data Connect المهام، مثل إنشاء مشروع Data Connect جديد، وإعداد دليل عمل محلي مطابق، وإعداد محاكي Data Connect، وإدراج موارد Data Connect، وإنشاء حِزم SDK للعملاء وغير ذلك.

أوامر الإعداد

إضافة Data Connect إلى مشروع على Firebase

firebase init

استخدِم firebase init لإعداد إعدادات مشروع محلي جديد. تؤدي سير العمل هذا إلى إنشاء ملفات إعداد Firebase أو تعديلها في دليلك.

firebase init

يرشدك مسار عمل firebase init خلال عملية إعداد خدمة وقاعدة بيانات، كما يتيح لك خيار تثبيت محاكي Data Connect وإعداد حِزم SDK التي تم إنشاؤها.

إعداد الخدمة وقاعدة البيانات

إذا اخترت dataconnect لإعداد المنتج، سيطلب منك واجهة سطر الأوامر إدخال اسم وموقع جغرافي جديدَين للخدمة، وما إذا كنت تريد ربط مثيل حالي من Cloud SQL for PostgreSQL أو إنشاء مثيل جديد.

في حال ربط مثيل حالي، يتحقّق واجهة سطر الأوامر من الإعدادات المتوافقة، مثل مصادقة "إدارة الهوية وإمكانية الوصول" وعناوين IP العامة.

إعداد Local Emulator Suite

يتيح مسار واجهة سطر الأوامر إعداد المحاكيات، بما في ذلك محاكي Data Connect.

Data Connect أوامر المحاكي

بدء تشغيل Data Connect المحاكي

emulators:start/exec

firebase emulators:start/exec

استخدِم إصدار Local Emulator Suite من محاكي Data Connect في "وضع التفاعل" مع start أو في "الوضع غير التفاعلي" المستند إلى النصوص البرمجية مع exec.

تصدير بيانات PostgreSQL المحلية واستيرادها

لإتاحة النماذج الأولية والاختبارات المحلية، والتكامل المستمر، يمكنك تصدير البيانات المخزّنة في نسخة محلية من قاعدة البيانات واستيرادها بين عمليات التطوير المتكررة وعمليات الاختبار.

يتم تخزين عمليات التصدير كلقطات من قاعدة بيانات PostgreSQL المحلية.

توفّر Data Connect ثلاث طرق للتصدير أو الاستيراد:

• تم ضبط عملية التصدير/الاستيراد التلقائي في firebase.json لتوفير نُسخ احتياطية من اللقطات عند إيقاف المحاكي وتشغيله
• التصدير/الاستيراد اليدوي باستخدام واجهة سطر الأوامر
• التصدير/الاستيراد اليدوي باستخدام واجهة إضافة VS Code

تم ضبط عملية التصدير والاستيراد التلقائية في firebase.json

للاحتفاظ بنسخة احتياطية من البيانات بين جلسات التطوير، حدِّد موقعًا للاحتفاظ بنسخة احتياطية تلقائية أثناء تسلسل firebase init. يتم تخزين هذا الموقع الجغرافي في firebase.json ضمن الحقل emulators.dataconnect.dataDir. سيتم تلقائيًا حفظ أي تغييرات في البيانات تُجريها هنا بين عمليات تشغيل المحاكي، ما يجعلها مفيدة أثناء الاختبار والاستكشاف على الجهاز المحلي.

التصدير اليدوي: emulators:export وemulators:start/exec --import

أثناء تشغيل Data Connect المحاكي، شغِّل الأمر firebase emulators:export في نافذة طرفية منفصلة لحفظ لقطة من بياناتك. بعد ذلك، يمكنك بدء المحاكي من اللقطة باستخدام العلامة --import.

# Export data from local emulator from a separate terminal
firebase emulators:export --only dataconnect <export_directory>

# Import data from local directory, here using emulators:exec
firebase emulators:exec ./<your-test-script>.sh --only dataconnect --import <import_directory>

التصدير والاستيراد اليدوي: إضافة VS Code

في واجهة مستخدم إضافة VS Code، أثناء تشغيل المحاكي، استخدِم الزر تصدير بيانات المحاكي لتصدير محتويات قاعدة البيانات الحالية. موقع التصدير التلقائي هو الدليل exportedData في جذر دليل مشروعك.

يمكنك استيراد هذه البيانات باستخدام واجهة سطر الأوامر، كما هو موضّح في القسم السابق. يمكنك أيضًا استيراد هذه البيانات قبل بدء المحاكي من خلال VS Code بالنقر على الرابط إعداد المحاكي وضبط مسار الاستيراد.

أوامر إدارة المخططات والموصلات

يحتوي هذا القسم على معلومات مرجعية حول واجهة سطر الأوامر للأوامر التي تستخدمها لإدارة المخططات والموصلات.

للاطّلاع على حالات الاستخدام والتعليمات المقترَحة المتعلقة بهذه الأوامر، راجِع دليل إدارة المخطط والموصّل.

نشر المخططات والموصلات

تفعيل

firebase deploy

ينشر هذا الأمر موارد لخدمات "ربط البيانات" مفهرسة في ملف firebase.json. يتم إجراء نقل بيانات المخطط وتعديل الموصل إذا لزم الأمر.

باستخدام العلامات –-only، يمكنك تمرير قيم مفصولة بفواصل لنشر أي مجموعة فرعية من الموارد التي تريدها.

firebase deploy --only dataconnect:service1:schema,dataconnect:service2

عرض الخدمات والمخططات والموصّلات في Data Connect

dataconnect:services:list

firebase dataconnect:services:list

يعرض هذا الأمر معلومات أساسية عن الخدمات والمخططات والموصلات التي تم نشرها في أحد المشاريع.

مقارنة مخطّطات SQL ونقلها

عند تشغيل firebase deploy، تنفِّذ واجهة سطر الأوامر مقارنة لمخطط SQL قبل نشر التعديلات. يمكنك أيضًا إجراء المقارنة والتعديل مباشرةً باستخدام مجموعة من أوامر dataconnect:sql.

dataconnect:sql:diff

firebase dataconnect:sql:diff

يقارن هذا الأمر المخطط المحلي لإحدى الخدمات بالمخطط الحالي لقاعدة بيانات Cloud SQL المقابلة. يطبع هذا الأمر الأوامر التي سيتم تنفيذها لنقل قاعدة البيانات إلى المخطط الجديد.

dataconnect:sql:migrate

firebase dataconnect:sql:migrate

يطبّق هذا الأمر تغييرات المخطط المحلية على قاعدة بيانات Cloud SQL الخاصة بالخدمة.

عند إعداد مشروع جديد Data Connect محلي، باستخدام ملف dataconnect.yaml التلقائي، فإنّ سلوك الأمر dataconnect:sql:migrate هو أن يطلب منك إجراء أي تغييرات مطلوبة، ثم يطلب منك إجراء أي تغييرات اختيارية، قبل تنفيذ التغييرات. يمكنك تعديل هذا السلوك لتضمين التغييرات الاختيارية أو تجاهلها دائمًا من خلال تعديل إعدادات dataconnect.yaml، كما هو موضّح في نقل مخطط في الوضع الصارم أو المتوافق.

في البيئات التفاعلية، تعرض واجهة سطر الأوامر كل عبارة SQL الخاصة بنقل البيانات (وما إذا كانت مدمرة) وتطلب التغييرات التي تريد تطبيقها. إنّ تمرير العلامة --force يعادل قبول جميع الطلبات.

في البيئات غير التفاعلية:

• بدون --force، يتم إجراء تغييرات غير مدمرة فقط. في حال حدوث تغييرات مدمرة، سيتم إيقاف واجهة سطر الأوامر بدون إجراء أي تغييرات.
• باستخدام --force، يتم إجراء جميع التغييرات. إذا تضمّن ذلك أي تغييرات مدمرة، سيتم عرضها وسيُطلب منك تحديد ما إذا كنت تريد المتابعة، ما لم يتم توفير العلامة --force.

كما هو الحال مع علامات --only الأخرى، يمكنك تقديم خدمات متعددة مفصولة بفواصل.

نقل مخطط في الوضع المتشدد أو وضع التوافق

تتضمّن عمليات نقل البيانات في مخطط Data Connect وضعَين مختلفَين للتحقّق من صحة المخطط، هما: الوضع الصارم والوضع المتوافق. يتطلّب التحقّق من صحة الوضع الصارم أن يتطابق مخطط قاعدة البيانات تمامًا مع مخطط التطبيق قبل أن يتم نشر مخطط التطبيق. يتطلّب التحقّق من صحة وضع التوافق أن يكون مخطط قاعدة البيانات متوافقًا مع مخطط التطبيق، ما يعني أنّه سيتم ترك العناصر في قاعدة البيانات التي لا يستخدمها مخطط التطبيق بدون تعديل.

تتوفّر أوضاع التحقّق من صحة المخطّط وأفضل الممارسات لنقل المخطّط في دليل إدارة المخطّط والموصل.

يتم تحديد وضع التحقّق من الصحة باستخدام المفتاح schemaValidation في ملف dataconnect.yaml. إذا لم يتم تحديد schemaValidation، ستطبّق واجهة سطر الأوامر تغييرات متوافقة وستطلب منك التأكيد قبل تنفيذ أي تغييرات صارمة. يمكنك الاطّلاع على مرجع الإعدادات.

إدارة التغييرات على الموصلات

عند تشغيل firebase deploy، تبدأ واجهة سطر الأوامر في تعديل الموصلات السارية. تحلّل واجهة سطر الأوامر التغييرات التي تطرأ على كل أداة ربط، وتصدر مجموعة من رسائل التقييم بشأن التغييرات التي قد تؤدي إلى سلوك غير متوقّع (رسائل بمستوى تحذير) أو أعطال (رسائل بمستوى عطل) في الإصدارات السابقة من رمز العميل.

في البيئات التفاعلية، تعرض واجهة سطر الأوامر تقييم كل أداة ربط وتطلب منك إدخال التغييرات التي تريد تطبيقها. إنّ تمرير العلامة --force يعادل قبول جميع التقييمات.

في البيئات غير التفاعلية:

• إذا حدثت تقييمات على مستوى التحذير فقط (تغييرات محتملة في السلوك)، سيتم نشر جميع الموصلات وسيتم تسجيل التحذيرات في الجهاز.
• في حال حدوث أي تقييمات على مستوى التوقف، لن يتم نشر أي موصّلات وسيتم تسجيل التحذيرات في الجهاز. يمكنك تجاهل ذلك باستخدام العلامة --force.

تدقيق رمز التفويض

تساعدك Data Connect في تدقيق استراتيجية التفويض من خلال تحليل رمز الموصل عند النشر على الخادم باستخدام firebase deploy من واجهة سطر الأوامر Firebase. يمكنك استخدام عملية التدقيق هذه لمساعدتك في مراجعة قاعدة الرموز البرمجية.

عند نشر الموصلات، ستعرض واجهة سطر الأوامر تقييمات لرموز العمليات الحالية والمعدَّلة والجديدة في الموصل.

بالنسبة إلى العمليات المعدَّلة والجديدة، تصدر واجهة سطر الأوامر تحذيرات وتطلب منك التأكيد عند استخدام مستويات وصول معيّنة في عملياتك الجديدة، أو عند تعديل العمليات الحالية لاستخدام مستويات الوصول هذه.

تظهر التحذيرات والإشعارات دائمًا في الحالات التالية:

• PUBLIC

وتظهر التحذيرات والإشعارات على مستويات الوصول التالية عندما لا يتم تحسينها باستخدام الفلاتر التي تستخدم auth.uid:

• USER
• USER_ANON
• USER_EMAIL_VERIFIED

لمزيد من المعلومات حول التفويض، يُرجى الرجوع إلى دليل التفويض والشهادة.

أوامر حزمة تطوير البرامج (SDK)

إنشاء حِزم SDK

dataconnect:sdk:generate

firebase dataconnect:sdk:generate

ينشئ هذا الأمر حِزم SDK المكتوبة التي تم تعريفها في connector.yaml.

يمكنك أيضًا الاطّلاع على أدلة استخدام حِزم تطوير البرامج (SDK) على الويب وحِزم تطوير البرامج (SDK) لنظام التشغيل Android وحِزم تطوير البرامج (SDK) لنظام التشغيل iOS.

باستخدام العلامات –only، يمكنك تمرير قيم مفصولة بفواصل.

firebase dataconnect:sdk:generate –-only connector1, connector1:kotlin

أوامر إدارة Cloud SQL

منح أدوار SQL في Cloud SQL

تعمل Data Connect على مثيل PostgreSQL الخاص بك المستضاف على Cloud SQL. تساعدك أوامر أدوار SQL في إدارة الأذونات على جداول قاعدة البيانات.

dataconnect:sql:setup

firebase dataconnect:sql:setup

يضبط هذا الأمر الأذونات الأولية والعامة للجداول في قاعدة البيانات.

يفترض سير العمل التلقائي لتوفير قواعد البيانات وإدارتها أنّ مشروعك يستخدم قاعدة بيانات جديدة (greenfield)، وعندما تستدعي firebase deploy، ستعرض Data Connect تغييرات مخطط قاعدة البيانات التي سيتم إجراؤها، وستنفّذ أي عمليات نقل بعد موافقتك. إذا كان هذا هو المسار المفضّل لديك، سيطلب منك dataconnect:sql:setup منح أذونات، بما في ذلك ملكية مخطط superuser.

بالنسبة إلى قواعد البيانات الحالية (التي تم إنشاؤها قبل استخدام هذا المنتج)، قد يكون لديك سير عمل خاص بك لنقل المخططات، وقد تريد الاحتفاظ بملكية المخطط بنفسك. إذا كنت تفضّل هذا المسار، احرص على الرفض عند ظهور dataconnect:sql:setup السؤال عمّا إذا كان Data Connect سيتولّى عمليات نقل بيانات SQL نيابةً عنك. نتيجةً للرفض، سيحصل Data Connect على إذن الوصول إلى read وwrite فقط من جداول قاعدة البيانات، ولكن ستظل مسؤولاً عن ملكية المخطط وعمليات نقل البيانات.

لمزيد من المناقشة وحالات الاستخدام، يُرجى الاطّلاع على إدارة الخدمات وقواعد البيانات.

dataconnect:sql:grant

firebase dataconnect:sql:grant

في بعض الحالات، قد تحتاج إلى الوصول إلى قاعدة البيانات مباشرةً للاستعلام عن البيانات التي أنشأتها تطبيقات Data Connect أو تعديلها. لإجراء ذلك، عليك منح أحد الأدوار المحدّدة في هذا القسم إلى المستخدم أو حساب الخدمة المطلوب.

للحصول على تفاصيل حول الأدوار الممنوحة، يُرجى الاطّلاع على أدوار مستخدم PostgreSQL.

الخيارات العامة

تنطبق الخيارات العامة التالية على جميع الأوامر:

• يؤدي الخيار --json إلى تبديل إخراج واجهة سطر الأوامر إلى JSON لتحليله بواسطة أدوات أخرى.
• تتجاوز --noninteractive و--interactive، حسب الحاجة، عملية الرصد التلقائي لبيئات غير TTY.