استخدام حِزم تطوير البرامج (SDK) لنظام التشغيل Android التي تم إنشاؤها

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

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

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

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

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

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

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

1. أضِف Firebase إلى تطبيقك على Android.
2. اضبط Data Connect كعنصر تابع في Gradle.
3. أضِف المكوّن الإضافي Kotlin Serialization Gradle وتبعيات Gradle.

بعد ذلك:

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

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

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

3. تهيئة رمز العميل واستيراد المكتبات

4. تنفيذ طلبات البحث والتعديلات

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

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

كما هو الحال مع معظم مشاريع Firebase، يتم العمل على رمز Firebase Data Connectالعميل في دليل مشروع محلي. يُعدّ كل من إضافة Data Connect في Visual Studio Code وواجهة سطر الأوامر Firebase أداتَين محليتَين مهمتَين لإنشاء رمز العميل وإدارته.

يتم ربط خيارات إنشاء حزمة SDK بعدة إدخالات في ملف dataconnect.yaml الذي تم إنشاؤه عند إعداد مشروعك.

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

connectorId: movies
generate:
  kotlinSdk:
    outputDir: ../../../src/main/java/com/myapplication
    package: com.myapplication

استبدِل outputDir بمسار الدليل الذي سيتم وضع الرمز الذي تم إنشاؤه فيه، وهذا المسار نسبي بالنسبة إلى الدليل الذي يحتوي على ملف connector.yaml نفسه. استبدِل package بعبارة حزمة Kotlin التي سيتم استخدامها في الملفات التي تم إنشاؤها، أو احذف package لاستخدام حزمة تلقائية.

تحديث حِزم SDK أثناء إنشاء النماذج الأولية

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

بدلاً من ذلك، يمكنك استخدام واجهة سطر الأوامر لإعادة إنشاء حِزم تطوير البرامج (SDK) كلما تم تغيير ملفات ‎ .gql:

firebase dataconnect:sdk:generate --watch

إنشاء حِزم SDK لعملية الدمج وإصدارات الإنتاج

في بعض السيناريوهات، مثل إعداد مصادر المشاريع لإرسالها إلى اختبارات CI، يمكنك استدعاء واجهة سطر الأوامر Firebase لإجراء تعديل مجمّع.

في هذه الحالات، استخدِم firebase dataconnect:sdk:generate.

إعداد رمز العميل

تضمين Data Connect في رمز العميل

لإعداد رمز العميل لاستخدام Data Connect وحزمة تطوير البرامج (SDK) التي تم إنشاؤها، اتّبِع أولاً تعليمات الإعداد العادية في Firebase.

بعد ذلك، أضِف ما يلي إلى القسم plugins في app/build.gradle.kts:

// The Firebase team tests with version 1.8.22; however, other 1.8 versions,
// and all newer versions are expected work too.
kotlin("plugin.serialization") version "1.8.22" // MUST match the version of the Kotlin compiler

بعد ذلك، أضِف ما يلي إلى القسم dependencies في app/build.gradle.kts:

implementation(platform("com.google.firebase:firebase-bom:33.16.0"))
implementation("com.google.firebase:firebase-dataconnect")
implementation("com.google.firebase:firebase-auth") // Optional
implementation("com.google.firebase:firebase-appcheck") // Optional
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3") // Newer versions should work too
implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1") // Newer versions should work too

إعداد Data Connect Android SDK

ابدأ مثيل Data Connect باستخدام المعلومات التي استخدمتها لإعداد Data Connect (تتوفّر جميعها في علامة التبويب Data Connect في وحدة تحكّم Firebase).

عنصر ConnectorConfig

يتطلّب حزمة تطوير البرامج (SDK) كائن إعدادات الموصل.

يتم إنشاء هذا العنصر تلقائيًا من serviceId وlocation في dataconnect.yaml، ومن connectorId في connector.yaml.

الحصول على مثيل موصّل

بعد إعداد عنصر الإعداد، احصل على مثيل Data Connect لأداة الربط. سيتم إنشاء رمز الموصل بواسطة محاكي Data Connect. إذا كان اسم الموصّل هو movies وكانت حزمة Kotlin هي com.myapplication، كما هو موضّح في connector.yaml، يمكنك استرداد عنصر الموصّل من خلال استدعاء:

val connector = com.myapplication.MoviesConnector.instance

استخدام طلبات البحث وعمليات التعديل من حزمة تطوير البرامج (SDK) لنظام التشغيل Android

باستخدام عنصر الموصل، يمكنك تنفيذ طلبات البحث وعمليات التعديل كما هو محدّد في رمز مصدر GraphQL. لنفترض أنّ الموصل يتضمّن العمليات التالية المحدّدة:

mutation createMovie($title: String!, $releaseYear: Int!, $genre: String!, $rating: Int!) {
  movie_insert(data: {
    title: $title
    releaseYear: $releaseYear
    genre: $genre
    rating: $rating
  })
}

query getMovieByKey($key: Movie_Key!) {
  movie(key: $key) { id title }
}

query listMoviesByGenre($genre: String!) {
  movies(where: {genre: {eq: $genre}}) {
    id
    title
  }
}

يمكنك بعد ذلك إنشاء فيلم واسترداده على النحو التالي:

val connector = MoviesConnector.instance

val addMovieResult1 = connector.createMovie.execute(
  title = "Empire Strikes Back",
  releaseYear = 1980,
  genre = "Sci-Fi",
  rating = 5
)

val movie1 = connector.getMovieByKey.execute(addMovieResult1.data.key)

println("Empire Strikes Back: ${movie1.data.movie}")

يمكنك أيضًا استرداد أفلام متعددة:

val connector = MoviesConnector.instance

val addMovieResult2 = connector.createMovie.execute(
  title="Attack of the Clones",
  releaseYear = 2002,
  genre = "Sci-Fi",
  rating = 5
)

val listMoviesResult = connector.listMoviesByGenre.execute(genre = "Sci-Fi")

println(listMoviesResult.data.movies)

يمكنك أيضًا جمع Flow لن يؤدي إلى ظهور نتيجة إلا عند استرداد نتيجة طلب بحث جديدة باستخدام طلب إلى طريقة execute() الخاصة بطلب البحث.

val connector = MoviesConnector.instance

connector.listMoviesByGenre.flow(genre = "Sci-Fi").collect { data ->
  println(data.movies)
}

connector.createMovie.execute(
  title="A New Hope",
  releaseYear = 1977,
  genre = "Sci-Fi",
  rating = 5
)

connector.listMoviesByGenre.execute(genre = "Sci-Fi") // will cause the Flow to get notified

إنشاء نموذج أولي لتطبيق Android واختباره

تجهيز البرامج لاستخدام محاكي محلي

يمكنك استخدام محاكي Data Connect، سواء من إضافة Data Connect VS Code أو من واجهة سطر الأوامر.

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

val connector = MoviesConnector.instance

// Connect to the emulator on "10.0.2.2:9399"
connector.dataConnect.useEmulator()

// (alternatively) if you're running your emulator on non-default port:
connector.dataConnect.useEmulator(port = 9999)

// Make calls from your app

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

أنواع البيانات في حِزم تطوير البرامج (SDK) التي تحمل الرقم Data Connect

يمثّل خادم Data Connect أنواع بيانات GraphQL الشائعة والمخصّصة. يتم تمثيل هذه القيم في حزمة SDK على النحو التالي.