SDK های مشتری Firebase Data Connect به شما امکان می دهند پرس و جوها و جهش های سمت سرور خود را مستقیماً از یک برنامه Firebase فراخوانی کنید. همزمان با طراحی طرحواره ها، پرس و جوها و جهش هایی که در سرویس Data Connect خود مستقر می کنید، یک SDK مشتری سفارشی ایجاد می کنید. سپس، شما متدها را از این SDK در منطق کلاینت خود ادغام می کنید.
همانطور که در جاهای دیگر ذکر کردیم، توجه به این نکته مهم است که کوئری‌ها و جهش‌های Data Connect توسط کد مشتری ارسال نمی‌شوند و روی سرور اجرا نمی‌شوند. در عوض، هنگام استقرار، عملیات Data Connect مانند توابع ابری در سرور ذخیره می شود. این بدان معناست که شما باید تغییرات سمت کلاینت مربوطه را برای جلوگیری از شکستن کاربران موجود (مثلاً در نسخه‌های قدیمی‌تر برنامه) اعمال کنید.
به همین دلیل است که Data Connect یک محیط توسعه‌دهنده و ابزاری را در اختیار شما قرار می‌دهد که به شما امکان می‌دهد طرح‌واره‌ها، پرسش‌ها و جهش‌های مستقر در سرور خود را نمونه‌سازی کنید. همچنین در حالی که شما نمونه سازی می کنید، SDK های سمت سرویس گیرنده را به طور خودکار تولید می کند.
هنگامی که به‌روزرسانی‌های سرویس و برنامه‌های سرویس گیرنده خود را تکرار کردید، به‌روزرسانی‌های سمت سرور و سرویس گیرنده آماده اجرا هستند.
گردش کار توسعه مشتری چیست؟
اگر شروع به کار را دنبال کنید، با جریان کلی توسعه برای Data Connect آشنا شده اید. در این راهنما، اطلاعات دقیق تری در مورد تولید Android SDK از طرح و کار با جستارها و جهش های مشتری پیدا خواهید کرد.
به طور خلاصه، برای استفاده از SDK های Android تولید شده در برنامه های مشتری خود، این مراحل پیش نیاز را دنبال می کنید:
- Firebase را به برنامه اندروید خود اضافه کنید.
- Data Connect به عنوان یک وابستگی در Gradle پیکربندی کنید.
- افزونه Kotlin Serialization Gradle و وابستگی 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 برای تولید Data Connect SDK در فرآیندهای ساخت 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.1.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() query بازیابی شود.
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 را باز کند، که یا EnumValue.Known شناخته شده برای مقادیر enum شناخته شده یا 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()
)
برنامه اندروید خود را نمونه اولیه و آزمایش کنید
کلاینت های ابزار برای استفاده از شبیه ساز محلی
می توانید از شبیه ساز 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
برای تغییر به منابع تولید، خطوطی را برای اتصال به شبیه ساز بیان کنید.
انواع داده در Data Connect SDKs
سرور Data Connect نشان دهنده انواع داده های رایج و سفارشی GraphQL است. این موارد در SDK به شرح زیر نشان داده شده است.
| نوع اتصال داده | کاتلین |
|---|---|
| رشته | رشته |
| بین المللی | Int (عدد صحیح 32 بیتی) |
| شناور | دوبل (64 بیت شناور) |
| بولی | بولی |
| UUID | java.util.UUID |
| تاریخ | com.google.firebase.dataconnect.LocalDate (تا 16.0.0-beta03 java.util.Date بود) |
| مهر زمان | com.google.firebase.Timestamp |
| Int64 | طولانی |
| هر | com.google.firebase.dataconnect.AnyValue |