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