استخدام حِزم Flutter SDK التي تم إنشاؤها

تتيح لك حِزم تطوير البرامج (SDK) للعملاء في Firebase SQL Connect استدعاء طلبات البحث والتعديلات من جهة الخادم مباشرةً من تطبيق Firebase. يمكنك إنشاء حزمة تطوير برامج (SDK) مخصّصة للعملاء بالتوازي مع تصميم المخططات وطلبات البحث والتعديلات التي يتم نشرها في خدمة SQL Connect. بعد ذلك، يمكنك دمج الطرق من حزمة تطوير البرامج (SDK) هذه في منطق العميل.

كما ذكرنا في مكان آخر، من المهم ملاحظة أن SQL Connect الاستعلامات والطفرات لا يتم إرسالها بواسطة رمز العميل وتنفيذها على الخادم. بدلاً من ذلك، عند نشر عمليات SQL Connect، يتم تخزينها على الخادم مثل Cloud Functions. وهذا يعني أنّه عليك نشر التغييرات المقابلة من جهة العميل لتجنُّب حدوث مشاكل لدى المستخدمين الحاليين (على سبيل المثال، في إصدارات التطبيق القديمة).

لهذا السبب، يوفّر لك SQL Connect بيئة تطوير وأدوات تتيح لك إنشاء نماذج أولية للمخططات وطلبات البحث والتعديلات التي يتم نشرها على الخادم. وتنشئ أيضًا حِزم تطوير برامج (SDK) من جهة العميل تلقائيًا أثناء إنشاء النماذج الأولية.

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

ما هو سير عمل تطوير العميل؟

إذا اتّبعت الخطوات الواردة في قسم البدء، ستتعرّف على عملية التطوير الشاملة لـ SQL Connect. في هذا الدليل، ستجد معلومات أكثر تفصيلاً عن إنشاء حِزم تطوير البرامج (SDK) لـ Flutter من المخطط والتعامل مع طلبات البحث والتعديلات من جهة العميل.

باختصار، لاستخدام حزم تطوير البرامج (SDK) التي تم إنشاؤها في Flutter في تطبيقات العملاء، عليك اتّباع الخطوات الأساسية التالية:

1. أضِف Firebase إلى تطبيق Flutter.
2. ثبِّت واجهة سطر الأوامر (CLI) لـ flutterfire dart pub global activate flutterfire_cli.
3. شغِّل flutterfire configure.

بعد ذلك:

1. طوِّر مخطّط تطبيقك.

2. إعداد عملية إنشاء حزمة تطوير البرامج (SDK):

   • باستخدام الزر إضافة حزمة تطوير البرامج (SDK) إلى التطبيق في إضافة SQL Connect VS Code
   • تعديل connector.yaml

3. بدء رمز العميل واستيراد المكتبات

4. تنفيذ طلبات البحث والتغييرات

5. إعداد محاكي SQL Connect واستخدامه وتكرار العملية

إنشاء حزمة تطوير البرامج (SDK) لـ Flutter

استخدِم واجهة سطر الأوامر (CLI) في Firebase لإعداد حِزم تطوير البرامج (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) لـ SQL Connect Flutter

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

إنّ عملية إعداد التطبيق للاتصال بالمحاكي هي نفسها في كلا السيناريوهَين.

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 الشائعة. ويتم تمثيلها في حزمة تطوير البرامج على النحو التالي.