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

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

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

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

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

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

كما هو الحال مع معظم مشاريع Firebase، يتم تنفيذ العمل على Firebase Data Connect العميل الرمز البرمجي في دليل مشروع على الجهاز. إنّ كلًّا من Firebase CLI وإضافة Data Connect في VS Code مهمّان على مستوى الأدوات المحلية لإنشاء رمز العميل وإدارته.

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

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

في connector.yaml، أضِف outputDir وpackage و (بالنسبة إلى حزمة تطوير البرامج (SDK) على الويب) packageJsonDir.

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 التي تحدّد المخططات وطلبات البحث والعمليات. يمكن أن تكون هذه ميزة مفيدة في سير عمل (إعادة) التحميل السريع.

في سيناريوهات أخرى، إذا كنت تستخدم محاكي Data Connect من سطر أوامر Firebase، يمكنك ضبط ميزة "مراقبة" على تحديثات .gql وتعديل مصادر SDK تلقائيًا.

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

firebase dataconnect:sdk:generate --watch

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

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

في هذه الحالات، استخدِم 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("com.google.firebase:firebase-dataconnect:16.0.0-beta03")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1")
implementation("com.google.firebase:firebase-auth:23.1.0") // Optional
implementation("com.google.firebase:firebase-appcheck:18.0.0") // Optional

إعداد Data Connect حزمة تطوير البرامج (SDK) لنظام التشغيل Android

ابدأ تشغيل مثيل 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

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

باستخدام عنصر الموصّل، يمكنك تنفيذ طلبات البحث والتغييرات كما هو محدّد في ملف برمجة تطبيقات 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

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

أنواع البيانات في حِزم SDK من Data Connect

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

نوع ربط البيانات	Kotlin
سلسلة	سلسلة
Int	Int (عدد صحيح 32 بت)
عائم	مزدوج (قيمة عددية عائمة بسعة 64 بت)
منطقي	منطقي
معرِّف فريد عالمي (UUID)	java.util.UUID
التاريخ	com.google.firebase.dataconnect.LocalDate (كان java.util.Date حتى الإصدار 16.0.0-beta03)
الطابع الزمني	com.google.firebase.Timestamp
Int64	طويلة
أي	com.google.firebase.dataconnect.AnyValue