استخدام حِزم 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

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