تتيح لك حِزم تطوير البرامج (SDK) للعميل Firebase SQL Connect استدعاء طلبات البحث والتعديلات من جهة الخادم مباشرةً من تطبيق Firebase. يمكنك إنشاء حزمة تطوير برامج (SDK) مخصّصة للعميل بالتوازي مع تصميم المخططات وطلبات البحث والتعديلات التي تنشرها في خدمة SQL Connect. بعد ذلك، يمكنك دمج طرق من حزمة تطوير البرامج (SDK) هذه في منطق العميل.
كما ذكرنا في مكان آخر، من المهم ملاحظة أنّه لا يتم إرسال SQL Connect طلبات البحث والتعديلات من خلال رمز العميل وتنفيذها على الخادم. بدلاً من ذلك، عند نشر عمليات SQL Connect، يتم تخزينها على الخادم مثل Cloud Functions. وهذا يعني أنّه عليك نشر التغييرات المقابلة من جهة العميل لتجنُّب إيقاف التطبيق لدى المستخدمين الحاليين (على سبيل المثال، على إصدارات التطبيق القديمة).
لهذا السبب، يوفّر لك SQL Connect بيئة تطوير و أدوات تتيح لك إنشاء نماذج أولية للمخططات وطلبات البحث والتعديلات التي تنشرها على الخادم. كما أنّه ينشئ حِزم تطوير برامج (SDK) من جهة العميل تلقائيًا أثناء إنشاء النماذج الأولية.
بعد تكرار التعديلات على خدمتك وتطبيقات العميل، يصبح بإمكانك نشر التعديلات من جهة الخادم والعميل.
ما هي سير عمل تطوير العميل؟
إذا اتّبعت الخطوات الواردة في مقالة البدء، تعرّفت على سير عمل التطوير العام لخدمة SQL Connect. في هذا الدليل، ستجد معلومات أكثر تفصيلاً حول إنشاء حِزم تطوير برامج (SDK) من Flutter من المخطط واستخدام طلبات البحث والتعديلات من جهة العميل.
باختصار، لاستخدام حِزم تطوير برامج (SDK) من Flutter التي تم إنشاؤها في تطبيقات العميل، عليك اتّباع الخطوات الأساسية التالية:
- أضِف Firebase إلى تطبيق Flutter.
- ثبِّت أداة سطر الأوامر flutterfire CLI
dart pub global activate flutterfire_cli. - نفِّذ الأمر
flutterfire configure.
بعد ذلك:
- طوِّر مخطط تطبيقك.
اضبط عملية إنشاء حزمة تطوير البرامج (SDK):
- باستخدام الزر إضافة حزمة تطوير برامج (SDK) إلى التطبيق في إضافة SQL Connect لبرنامج VS Code
- من خلال تعديل ملف
connector.yaml
اضبط محاكي SQL Connect واستخدِمه و كرِّر العملية.
إنشاء حزمة تطوير برامج (SDK) من Flutter
استخدِم Firebase CLI لإعداد حِزم تطوير برامج (SDK) التي تم إنشاؤها في SQL Connect في تطبيقاتك.
يجب أن يرصد الأمر init جميع التطبيقات في المجلد الحالي وأن يثبِّت حِزم تطوير البرامج (SDK) التي تم إنشاؤها تلقائيًا.
firebase init dataconnect:sdk
تعديل حِزم تطوير البرامج (SDK) أثناء إنشاء النماذج الأولية
إذا كانت إضافة SQL Connect لبرنامج VS Code مثبَّتة، ستحرص دائمًا على أن تكون حِزم تطوير البرامج (SDK) التي تم إنشاؤها حديثة.
إذا كنت لا تستخدم إضافة SQL Connect لبرنامج VS Code، يمكنك استخدام Firebase CLI للحفاظ على حِزم تطوير البرامج (SDK) التي تم إنشاؤها حديثة.
firebase dataconnect:sdk:generate --watchإنشاء حِزم تطوير برامج (SDK) في مسارات الإصدار
يمكنك استخدام Firebase CLI لإنشاء حِزم تطوير برامج (SDK) SQL Connect في عمليات الإصدار في التكامل المستمر/النشر المستمر (CI/CD).
firebase dataconnect:sdk:generateإعداد رمز العميل
بدء تطبيق SQL Connect
ابدأ أولاً تطبيقك باستخدام الـ تعليمات الإعداد العادية في Firebase.
بعد ذلك، ثبِّت مكوّن SQL Connect الإضافي:
flutter pub add firebase_data_connectبدء حزمة تطوير برامج (SDK) من Flutter في SQL Connect
ابدأ مثيل SQL Connect باستخدام المعلومات التي استخدمتها لإعداد SQL Connect. يمكنك العثور على هذه المعلومات في قواعد البيانات ومساحة التخزين > SQL Connect صفحة في وحدة تحكُّم Firebase.
استيراد المكتبات
هناك مجموعتان من عمليات الاستيراد اللازمة لبدء رمز العميل، وهما عمليات الاستيراد العامة SQL Connect وعمليات استيراد حزمة تطوير البرامج (SDK) المحدّدة التي تم إنشاؤها.
// general imports
import 'package:firebase_data_connect/firebase_data_connect.dart';
// generated queries and mutations from SDK
import 'generated/movies.dart';
استخدام طلبات البحث من جهة العميل
سيأتي الرمز الذي تم إنشاؤه مع مراجع طلبات بحث محدّدة مسبقًا. كل ما عليك فعله هو استيرادها واستدعاء execute عليها.
import 'generated/movies.dart';
await MoviesConnector.instance.listMovies().execute();
استدعاء طرق طلبات البحث في حزمة تطوير البرامج (SDK)
إليك مثال على استخدام دوال اختصار الإجراءات هذه:
import 'generated/movies.dart';
function onBtnClick() {
// This will call the generated Dart from the CLI and then make an HTTP request to the server.
MoviesConnector.instance.listMovies().execute().then(data => showInUI(data)); // == MoviesConnector.instance.listMovies().ref().execute();
}
الحقول الاختيارية
قد تتضمّن بعض طلبات البحث حقولاً اختيارية. في هذه الحالات، تعرض حزمة تطوير البرامج (SDK) من Flutter طريقة إنشاء، ويجب ضبطها بشكل منفصل.
على سبيل المثال، الحقل rating اختياري عند استدعاء createMovie، لذا عليك تقديمه في دالة الإنشاء.
await MoviesConnector.instance.createMovie( title: 'Empire Strikes Back', releaseYear: 1980, genre: 'Sci-Fi').rating(5).execute();
الاشتراك في التغييرات
يمكنك الاطّلاع على مقالة تلقّي آخر المعلومات من SQL Connect في الوقت الفعلي.
التعامل مع التغييرات في حقول التعداد
يمكن أن يحتوي مخطط التطبيق على عمليات تعداد، يمكن الوصول إليها من خلال طلبات بحث GraphQL.
مع تغيُّر تصميم التطبيق، يمكنك إضافة قيم جديدة متوافقة مع التعداد. على سبيل المثال، تخيَّل أنك قرّرت لاحقًا في دورة حياة تطبيقك إضافة قيمة FULLSCREEN إلى التعداد AspectRatio.
في سير عمل SQL Connect، يمكنك استخدام أدوات التطوير المحلية لـ تعديل طلبات البحث وحِزم تطوير البرامج (SDK).
ومع ذلك، قبل إصدار إصدار معدَّل من برامج العميل، قد تتوقف برامج العميل القديمة التي تم نشرها.
مثال على التنفيذ المرن
تفرض حزمة تطوير البرامج (SDK) التي تم إنشاؤها التعامل مع القيم غير المعروفة. أي يجب أن يفك رمز العميل غلاف العنصر EnumValue إلى Known أو Unknown.
final result = await MoviesConnector.instance.listMovies().execute();
if (result.data != null && result.data!.isNotEmpty) {
handleEnumValue(result.data![0].aspectratio);
}
void handleEnumValue(EnumValue<AspectRatio> aspectValue) {
if (aspectValue.value != null) {
switch(aspectValue.value!) {
case AspectRatio.ACADEMY:
print('This movie is in Academy aspect');
break;
case AspectRatio.WIDESCREEN:
print('This movie is in Widescreen aspect');
break;
case AspectRatio.ANAMORPHIC:
print('This movie is in Anamorphic aspect');
break;
case AspectRatio.IMAX:
print('This movie is in IMAX aspect');
}
} else {
print('Unknown aspect ratio detected: ${aspectValue.stringValue}');
}
}
تفعيل التخزين المؤقت من جهة العميل
SQL Connect تتضمّن ميزة اختيارية للتخزين المؤقت من جهة العميل، يمكنك تفعيلها من خلال تعديل ملف connector.yaml. عند تفعيل هذه الميزة، ستخزّن حِزم تطوير البرامج (SDK) من جهة العميل التي تم إنشاؤها ردود طلبات البحث محليًا، ما يمكن أن يقلّل عدد طلبات قاعدة البيانات التي يقدّمها تطبيقك ويسمح لأجزاء التطبيق التي تعتمد على قاعدة البيانات بالعمل عند انقطاع الشبكة.
لتفعيل التخزين المؤقت من جهة العميل، أضِف إعدادات التخزين المؤقت من جهة العميل إلى إعدادات الموصّل:
generate:
javascriptSdk:
outputDir: ../dart/
package: "dataconnect_generated"
clientCache:
maxAge: 5s
storage: memory
يتضمّن هذا الإعداد معلَمتَين، وكلاهما اختياري:
maxAge: الحد الأقصى لعمر الردّ المخزّن مؤقتًا قبل أن تجلب حزمة تطوير البرامج (SDK) من جهة العميل قيمًا جديدة. أمثلة: "0" و"30s" و"1h30m"القيمة التلقائية لـ
maxAgeهي0، ما يعني أنّه يتم تخزين الردود مؤقتًا، ولكن ستجلب حزمة تطوير البرامج (SDK) من جهة العميل دائمًا قيمًا جديدة. لن يتم استخدام القيم المخزّنة مؤقتًا إلا عند تحديدCACHE_ONLYللسمةexecute()والنتيجة الأولية التي يتم عرضها منsubscribe().storage: يمكن ضبط حزمة تطوير البرامج (SDK) من جهة العميل لتخزين الردود مؤقتًا إما في مساحة التخزينpersistentأو فيmemory. ستبقى النتائج المخزّنة مؤقتًا في مساحة التخزينpersistentبعد إعادة تشغيل التطبيق. عند استهداف أجهزة Android أو iOS، تكون القيمة التلقائية هيpersistent. عند استهداف متصفّحات الويب، لا تتوفّر سوى مساحة التخزينmemory.
بعد تعديل إعدادات التخزين المؤقت للموصّل، أعِد إنشاء حِزم تطوير البرامج (SDK) من جهة العميل وأعِد إنشاء تطبيقك. بعد إجراء ذلك، سيخزّن كل من execute() وsubscribe() الردود مؤقتًا ويستخدم القيم المخزّنة مؤقتًا وفقًا للسياسة التي ضبطتها. يحدث ذلك تلقائيًا بشكل عام، بدون أي خطوات إضافية من جانبك، ولكن يُرجى العِلم بما يلي:
يكون السلوك التلقائي لـ
execute()كما هو موضّح أعلاه: إذا تم تخزين نتيجة مؤقتًا لطلب بحث ولم تكن القيمة المخزّنة مؤقتًا أقدم منmaxAge، استخدِم القيمة المخزّنة مؤقتًا. يُعرف هذا السلوك التلقائي باسم سياسةPREFER_CACHE.يمكنك أيضًا تحديد عمليات استدعاء فردية لـ
execute()لعرض القيم المخزّنة مؤقتًا فقط (CACHE_ONLY) أو لجلب قيم جديدة من الخادم بشكل غير مشروط (SERVER_ONLY).await queryRef.execute(fetchPolicy: QueryFetchPolicy.cacheOnly);await queryRef.execute(fetchPolicy: QueryFetchPolicy.serverOnly);عند استدعاء
subscribe()، سيتم دائمًا عرض المحتوى المخزّن مؤقتًا على الفور إذا كان متوفرًا، بغض النظر عن إعدادmaxAge. ستُعلم عمليات الاستدعاء اللاحقة لـexecute()المستمعين وفقًا لـmaxAgeالذي تم ضبطه.
استخدام التعديلات من جهة العميل
يمكن الوصول إلى التعديلات بالطريقة نفسها التي يمكن الوصول بها إلى طلبات البحث.
await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();
إنشاء نماذج أولية لتطبيقات Flutter واختبارها
إعداد برامج العميل لاستخدام محاكي محلي
يمكنك استخدام محاكي SQL Connect، سواء من إضافة SQL Connect لبرنامج VS Code أو من سطر الأوامر.
إنّ إعداد التطبيق للاتصال بالمحاكي هو نفسه في كلتا الحالتَين.
import 'package:firebase_data_connect/firebase_data_connect.dart';
import 'generated/movies.dart';
MoviesConnector.instance.dataConnect
.useDataConnectEmulator('127.0.0.1', 9399);
// Make calls from your app
QueryRef<ListMoviesData, void> ref = MoviesConnector.instance.listMovies.ref();
للتبديل إلى موارد الإنتاج، علِّق على الأسطر الخاصة بالاتصال بالمحاكي.
أنواع البيانات في حزمة تطوير البرامج (SDK) من Dart
يمثّل خادم SQL Connect أنواع بيانات GraphQL الشائعة. ويتم تمثيلها في حزمة تطوير البرامج (SDK) على النحو التالي.
| نوع SQL Connect | Dart |
|---|---|
| الطابع الزمني | firebase_data_connect.Timestamp |
| عدد صحيح (32 بت) | int |
| التاريخ | DateTime |
| معرِّف فريد عالمي (UUID) | string |
| Int64 | int |
| عائم | double |
| قيمة منطقية | bool |
| أي | firebase_data_connect.AnyValue |