تتيح لك حِزم تطوير البرامج (SDK) للعملاء في Firebase SQL Connect استدعاء طلبات البحث والتعديلات من جهة الخادم مباشرةً من تطبيق Firebase. يمكنك إنشاء حزمة تطوير برامج (SDK) مخصّصة للعملاء بالتوازي مع تصميم المخططات وطلبات البحث والتعديلات التي يتم نشرها في خدمة SQL Connect. بعد ذلك، يمكنك دمج الطرق من حزمة تطوير البرامج (SDK) هذه في منطق العميل.
كما ذكرنا في مكان آخر، من المهم ملاحظة أن SQL Connect الاستعلامات والطفرات لا يتم إرسالها بواسطة رمز العميل وتنفيذها على الخادم. بدلاً من ذلك، عند نشر عمليات SQL Connect، يتم تخزينها على الخادم مثل Cloud Functions. وهذا يعني أنّه عليك نشر التغييرات المقابلة من جهة العميل لتجنُّب حدوث مشاكل لدى المستخدمين الحاليين (على سبيل المثال، في إصدارات التطبيق القديمة).
لهذا السبب، يوفّر لك SQL Connect بيئة مطوّر وأدوات تتيح لك إنشاء نماذج أولية للمخططات وطلبات البحث والتعديلات التي يتم نشرها على الخادم. وتنشئ أيضًا حِزم تطوير برامج (SDK) من جهة العميل تلقائيًا أثناء إنشاء النماذج الأولية.
بعد تكرار التحديثات على تطبيقات الخدمة والعميل، تصبح التحديثات من جهة الخادم والعميل جاهزة للنشر.
ما هو سير عمل تطوير العميل؟
إذا اتّبعت الخطوات الواردة في قسم البدء، ستتعرّف على عملية التطوير الشاملة لـ SQL Connect. في هذا الدليل، ستجد معلومات أكثر تفصيلاً حول إنشاء حِزم تطوير برامج (SDK) لنظام التشغيل Android من المخطط والتعامل مع طلبات البحث والتعديلات من العميل.
باختصار، لاستخدام حِزم تطوير البرامج (SDK) لنظام التشغيل Android التي تم إنشاؤها في تطبيقات العميل، عليك اتّباع الخطوات الأساسية التالية:
- أضِف Firebase إلى تطبيق Android.
- اضبط SQL Connect كعنصر تابع في Gradle.
- أضِف المكوّن الإضافي Kotlin Serialization Gradle واعتمادية Gradle.
بعد ذلك:
- طوِّر مخطّط تطبيقك.
إعداد عملية إنشاء حزمة تطوير البرامج (SDK):
- باستخدام الزر إضافة حزمة تطوير البرامج (SDK) إلى التطبيق في إضافة SQL Connect VS Code
- تحديث
connector.yaml
إعداد محاكي SQL Connect واستخدامه وتكرار العملية
إنشاء حزمة Kotlin SDK
استخدِم واجهة سطر الأوامر (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 في رمز العميل
لإعداد رمز العميل لاستخدام SQL 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:35.0.1"))
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
إعداد حزمة تطوير البرامج (SDK) لـ "SQL Connect" على Android
ابدأ مثيل SQL Connect باستخدام المعلومات التي استخدمتها لإعداد SQL Connect. يمكنك العثور على هذه المعلومات في صفحة قواعد البيانات ومساحة التخزين > SQL Connect في وحدة تحكّم "Firebase".
عنصر ConnectorConfig
تتطلّب حزمة تطوير البرامج (SDK) عنصر إعدادات الموصل.
يتم إنشاء هذا العنصر تلقائيًا من serviceId وlocation في
dataconnect.yaml، وconnectorId في connector.yaml.
الحصول على مثيل موصِّل
بعد إعداد عنصر الضبط، يمكنك الحصول على مثيل موصِّل SQL Connect. سيتم إنشاء الرمز الخاص بالموصل بواسطة محاكي SQL 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
الاشتراك في التغييرات في الوقت الفعلي
يُرجى الاطّلاع على الحصول على آخر الأخبار في الوقت الفعلي من "SQL Connect".
التعامل مع التغييرات في حقول التعداد
يمكن أن يحتوي مخطط التطبيق على تعدادات، والتي يمكن الوصول إليها من خلال طلبات بحث GraphQL.
مع تغيُّر تصميم التطبيق، يمكنك إضافة قيم جديدة مسموح بها للتعداد. على سبيل المثال،
لنفترض أنك قررت لاحقًا في مراحل نشاط تطبيقك إضافة
قيمة FULLSCREEN إلى تعداد AspectRatio.
في سير عمل SQL Connect، يمكنك استخدام أدوات التطوير المحلية لتعديل طلبات البحث وحزم تطوير البرامج (SDK).
ومع ذلك، قبل إصدار نسخة محدّثة من برامج العميل، قد تتعطّل برامج العميل القديمة التي تم نشرها.
مثال على عملية تنفيذ مرنة
تفرض حزمة SDK التي تم إنشاؤها معالجة القيم غير المعروفة لأنّ رمز العميل يجب أن يفكّ حزمة الكائن EnumValue، والذي يكون إما EnumValue.Known لقيم التعداد المعروفة أو EnumValue.Unknown للقيم غير المعروفة.
val result = connector.listMoviesByAspectRatio.execute(AspectRatio.WIDESCREEN)
val encounteredAspectRatios = mutableSetOf<String>()
result.data.movies
.mapNotNull { it.otherAspectRatios }
.forEach { otherAspectRatios ->
otherAspectRatios
.filterNot { it.value == AspectRatio.WIDESCREEN }
.forEach {
when (it) {
is EnumValue.Known -> encounteredAspectRatios.add(it.value.name)
is EnumValue.Unknown ->
encounteredAspectRatios.add("[unknown ratio: ${it.stringValue}]")
}
}
}
println(
"Widescreen movies also include additional aspect ratios: " +
encounteredAspectRatios.sorted().joinToString()
)
تفعيل التخزين المؤقت من جهة العميل
يتضمّن SQL Connect ميزة اختيارية للتخزين المؤقت من جهة العميل، ويمكنك تفعيلها من خلال تعديل ملف connector.yaml. عند تفعيل هذه الميزة،
ستخزّن حِزم SDK للعميل التي تم إنشاؤها ردود طلبات البحث مؤقتًا على الجهاز، ما قد يقلّل
من عدد طلبات قاعدة البيانات التي يرسلها تطبيقك ويتيح
للأجزاء التي تعتمد على قاعدة البيانات في تطبيقك العمل عند انقطاع الاتصال بالشبكة.
لتفعيل التخزين المؤقت من جهة العميل، أضِف إعدادات التخزين المؤقت من جهة العميل إلى إعدادات الموصّل:
generate:
kotlinSdk:
outputDir: "../android"
package: "com.google.firebase.dataconnect.generated"
clientCache:
maxAge: 5s
storage: persistent
يحتوي هذا الإعداد على مَعلمتَين اختياريتَين:
maxAge: الحد الأقصى لعمر الاستجابة المخزّنة مؤقتًا قبل أن تجلب حزمة تطوير البرامج (SDK) للعميل قيمًا جديدة. أمثلة: "0" أو "30s" أو "1h30m".القيمة التلقائية لـ
maxAgeهي0، ما يعني أنّه يتم تخزين الردود مؤقتًا، ولكن حزمة تطوير البرامج (SDK) للعميل ستجلب دائمًا القيم الجديدة. لن يتم استخدام القيم المخزّنة مؤقتًا إلا عند تحديدCACHE_ONLYعلىexecute().storage: يمكن ضبط حزمة تطوير البرامج (SDK) للعميل لتخزين الردود مؤقتًا إما في مساحة تخزينpersistentأو فيmemory. ستبقى النتائج المخزّنة مؤقتًا في مساحة تخزين "persistent" حتى بعد إعادة تشغيل التطبيق. في حزم تطوير البرامج (SDK) لنظام التشغيل Android، تكون القيمة التلقائية هيpersistent.
بعد تعديل إعدادات التخزين المؤقت للموصِّل، أعِد إنشاء حِزم تطوير البرامج (SDK) للعميل
وأعِد إنشاء تطبيقك. بعد إجراء ذلك، سيخزِّن execute()
الردود مؤقتًا
ويستخدم القيم المخزَّنة مؤقتًا وفقًا للسياسة التي أعددتها. يحدث هذا عادةً بشكل تلقائي، بدون أي خطوات إضافية من جانبك، ولكن يُرجى ملاحظة ما يلي:
الإعداد التلقائي لـ
execute()هو كما هو موضّح أعلاه: إذا تم تخزين نتيجة لطلب بحث مؤقتًا ولم تكن القيمة المخزّنة مؤقتًا أقدم منmaxAge، يتم استخدام القيمة المخزّنة مؤقتًا. يُطلق على هذا الإعداد التلقائي اسم سياسةPREFER_CACHE.يمكنك أيضًا تحديد عمليات استدعاء فردية لـ
execute()إما لعرض القيم المخزّنة مؤقتًا فقط (CACHE_ONLY) أو لجلب القيم الجديدة من الخادم بدون شروط (SERVER_ONLY).val queryResult = queryRef.execute(QueryRef.FetchPolicy.CACHE_ONLY)val queryResult = queryRef.execute(QueryRef.FetchPolicy.SERVER_ONLY)إنشاء نموذج أولي لتطبيق Android واختباره
إعداد برامج العملاء لاستخدام محاكي محلي
يمكنك استخدام محاكي SQL Connect، سواء من إضافة SQL Connect VS Code أو من واجهة سطر الأوامر (CLI).
إنّ عملية إعداد التطبيق للاتصال بالمحاكي هي نفسها في كلا السيناريوهَين.
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للتبديل إلى موارد الإنتاج، يمكنك الإشارة إلى أسطر الرموز باعتبارها تعليقًا للاتصال بالمحاكي.
أنواع SQL في حِزم تطوير البرامج (SDK) في SQL Connect
يمثّل خادم SQL Connect أنواع بيانات GraphQL الشائعة والمخصّصة. ويتم تمثيلها في حزمة تطوير البرامج (SDK) على النحو التالي.
النوع: SQL Connect Kotlin سلسلة سلسلة Int Int (عدد صحيح 32 بت) عائم Double (64-bit float) قيمة منطقية قيمة منطقية معرِّف فريد عالمي (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