کیت‌های توسعه نرم‌افزار (SDK) کلاینت Firebase Data Connect به شما امکان می‌دهند کوئری‌ها و جهش‌های سمت سرور خود را مستقیماً از یک برنامه Firebase فراخوانی کنید. شما همزمان با طراحی طرحواره‌ها، کوئری‌ها و جهش‌هایی که در سرویس Data Connect خود پیاده‌سازی می‌کنید، یک SDK کلاینت سفارشی ایجاد می‌کنید. سپس، متدهای این SDK را در منطق کلاینت خود ادغام می‌کنید.
همانطور که در جای دیگری اشاره کردیم، توجه به این نکته مهم است که کوئری‌ها و جهش‌های Data Connect توسط کد کلاینت ارسال و روی سرور اجرا نمی‌شوند. در عوض، هنگام استقرار، عملیات Data Connect مانند توابع ابری روی سرور ذخیره می‌شوند. این بدان معناست که برای جلوگیری از اختلال در عملکرد کاربران موجود (به عنوان مثال، در نسخه‌های قدیمی‌تر برنامه)، باید تغییرات مربوطه در سمت کلاینت را اعمال کنید.
به همین دلیل است که Data Connect یک محیط توسعه‌دهنده و ابزار در اختیار شما قرار می‌دهد که به شما امکان می‌دهد طرح‌ها، کوئری‌ها و جهش‌های مستقر در سرور خود را نمونه‌سازی کنید. همچنین، همزمان با نمونه‌سازی شما، SDKهای سمت کلاینت را به طور خودکار تولید می‌کند.
وقتی به‌روزرسانی‌های مکرر را برای سرویس و برنامه‌های کلاینت خود انجام دادید، به‌روزرسانی‌های سمت سرور و کلاینت آماده‌ی استقرار هستند.
گردش کار توسعه کلاینت چیست؟
اگر بخش « شروع به کار» را دنبال کرده باشید، با جریان کلی توسعه برای Data Connect آشنا شده‌اید. در این راهنما، اطلاعات دقیق‌تری در مورد تولید SDKهای اندروید از طرحواره خود و کار با کوئری‌ها و جهش‌های کلاینت پیدا خواهید کرد.
به طور خلاصه، برای استفاده از SDK های تولید شده اندروید در برنامه های کلاینت خود، این مراحل پیش نیاز را دنبال خواهید کرد:
- فایربیس را به برنامه اندروید خود اضافه کنید.
- Data Connect به عنوان یک وابستگی در Gradle پیکربندی کنید.
- افزونه‌ی Gradle مربوط به Kotlin Serialization و وابستگی Gradle را اضافه کنید.
سپس:
- طرحواره برنامه خود را توسعه دهید.
تنظیم تولید SDK:
- با دکمه‌ی «افزودن SDK به برنامه» در افزونه‌ی Data Connect VS Code ما
- با به‌روزرسانی
connector.yamlخود
کد کلاینت خود را مقداردهی اولیه کنید و کتابخانه‌ها را وارد کنید .
شبیه‌ساز Data Connect را راه‌اندازی و استفاده کنید و مراحل را تکرار کنید.
کیت توسعه نرم‌افزار کاتلین (Kotlin SDK) خود را ایجاد کنید
از رابط خط فرمان Firebase CLI) برای تنظیم SDK های تولید شده توسط Data Connect در برنامه‌های خود استفاده کنید. دستور init باید تمام برنامه‌های موجود در پوشه فعلی را شناسایی کرده و SDK های تولید شده را به طور خودکار نصب کند.
firebase init dataconnect:sdk
به‌روزرسانی SDKها هنگام نمونه‌سازی اولیه
اگر افزونه‌ی Data Connect VS Code را نصب کرده باشید، این افزونه همیشه SDKهای تولید شده را به‌روز نگه می‌دارد.
اگر از افزونه Data Connect VS Code استفاده نمی‌کنید، می‌توانید از Firebase CLI برای به‌روز نگه داشتن SDKهای تولید شده استفاده کنید.
firebase dataconnect:sdk:generate --watchتولید SDK در خطوط لوله ساخت
شما می‌توانید از Firebase CLI برای تولید SDK های Data Connect در فرآیندهای ساخت CI/CD استفاده کنید.
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:34.4.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
مقداردهی اولیه SDK اندروید Data Connect
نمونه 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 اندروید خود استفاده کنید
با شیء کانکتور، می‌توانید کوئری‌ها و جهش‌ها را همانطور که در کد منبع 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)
همچنین می‌توانید با استفاده از فراخوانی متد execute() مربوط به کوئری، یک Flow جمع‌آوری کنید که تنها زمانی نتیجه‌ای تولید می‌کند که نتیجه‌ی یک کوئری جدید بازیابی شود.
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
مدیریت تغییرات در فیلدهای شمارشی
طرحواره یک برنامه می‌تواند شامل شمارشگرها باشد که می‌توانند توسط کوئری‌های GraphQL شما قابل دسترسی باشند.
با تغییر طراحی یک برنامه، ممکن است مقادیر جدیدی که توسط enum پشتیبانی می‌شوند را اضافه کنید. برای مثال، تصور کنید که بعداً در چرخه حیات برنامه خود تصمیم می‌گیرید یک مقدار FULLSCREEN به enum مربوط به AspectRatio اضافه کنید.
در گردش کار Data Connect ، می‌توانید از ابزار توسعه محلی برای به‌روزرسانی کوئری‌ها و SDKهای خود استفاده کنید.
با این حال، قبل از اینکه نسخه به‌روز شده‌ای از کلاینت‌های خود را منتشر کنید، کلاینت‌های قدیمی‌تر ممکن است از کار بیفتند.
مثال پیاده‌سازی انعطاف‌پذیر
SDK تولید شده، مدیریت مقادیر ناشناخته را اجباری می‌کند، زیرا کد مشتری باید شیء EnumValue را از حالت فشرده خارج کند، که برای مقادیر enum شناخته شده، 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()
)
نمونه اولیه برنامه اندروید خود را بسازید و آزمایش کنید
کلاینت‌های Instrument برای استفاده از یک شبیه‌ساز محلی
شما می‌توانید از شبیه‌ساز Data Connect ، چه از طریق افزونه Data 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
برای تغییر به منابع عملیاتی، خطوط مربوط به اتصال به شبیه‌ساز را کامنت کنید.
انواع داده‌ها در SDK های Data Connect
سرور Data Connect انواع داده رایج و سفارشی GraphQL را نشان می‌دهد. این داده‌ها در SDK به شرح زیر نمایش داده شده‌اند.
| نوع اتصال داده | کاتلین |
|---|---|
| رشته | رشته |
| بین المللی | عدد صحیح (عدد صحیح ۳۲ بیتی) |
| شناور | دابل (اعشار ۶۴ بیتی) |
| بولی | بولی |
| شناسه کاربری | شناسه کاربری جاوا (java.util.UUID) |
| تاریخ | com.google.firebase.dataconnect.LocalDate (تا نسخه ۱۶.۰.۰-بتا۰۳ با نام java.util.Date شناخته می‌شد) |
| مهر زمانی | com.google.firebase.Timestamp |
| بین‌رشته‌ای64 | طولانی |
| هر | com.google.firebase.dataconnect.AnyValue |