Firebase SQL Connect کیت‌های توسعه نرم‌افزار کارخواه به شما امکان می‌دهند پرسمان‌ها و جهش‌های سمت سرور را مستقیماً از برنامه Firebase فراخوانی کنید. شما یک کیت توسعه نرم‌افزار کارخواه سفارشی را به‌طور موازی با طراحی طرح‌واره‌ها، پرسمان‌ها، و جهش‌هایی که در سرویس SQL Connect خود مستقر می‌کنید، تولید می‌کنید. سپس، روش‌های این کیت توسعه نرم‌افزار را در منطق کارخواه خود ادغام می‌کنید.
همان‌طور که در جای دیگری اشاره کردیم، مهم است توجه داشته باشید که SQL Connect پرس‌وجوها و جهش‌ها توسط کد کارخواه ارسال نمی‌شوند و در سرور اجرا می‌شوند. درعوض، هنگام پیاده‌سازی، عملیات SQL Connect مانند Cloud Functions در سرور ذخیره می‌شود. این یعنی باید تغییرات مربوطه را در سمت کارخواه اعمال کنید تا از ایجاد مشکل برای کاربران فعلی (مثلاً در نسخه‌های قدیمی‌تر برنامه) جلوگیری شود.
به همین دلیل، SQL Connect محیط توسعه نرم‌افزار و ابزارهایی را در اختیارتان قرار می‌دهد که به شما امکان می‌دهد نمونه اولیه طرح‌واره‌ها، پُرسمان‌ها، و جهش‌های مستقرشده در سرور را بسازید. همچنین، درحالی‌که نمونه اولیه می‌سازید، کیت‌های توسعه نرم‌افزار سمت کارخواه را به‌طور خودکار تولید می‌کند.
وقتی به‌روزرسانی‌های سرویس و برنامه‌های مشتری را تکرار کردید، به‌روزرسانی‌های سمت سرور و مشتری آماده استقرار هستند.
گردش کار توسعه کارخواه چیست؟
اگر شروع به کار را دنبال کرده باشید، با جریان کلی توسعه برای SQL Connect آشنا شده‌اید. در این راهنما، اطلاعات دقیق‌تری درباره تولید کیت‌های توسعه نرم‌افزار Android از طرح‌واره‌تان و کار با پُرسمان‌ها و جهش‌های کارخواه پیدا خواهید کرد.
به‌طور خلاصه، برای استفاده از کیت‌های توسعه نرم‌افزار Android تولیدشده در برنامه‌های مشتری، این مراحل پیش‌نیاز را دنبال خواهید کرد:
- Firebase را به برنامه Android خود اضافه کنید.
- SQL Connect را به‌عنوان وابستگی در Gradle پیکربندی کنید.
- افزایه Kotlin Serialization Gradle و وابستگی Gradle را اضافه کنید.
سپس:
- طرح‌واره برنامه‌تان را توسعه دهید.
راه‌اندازی تولید کیت توسعه نرم‌افزار:
- با دکمه افزودن کیت توسعه نرم‌افزار به برنامه در افزونه SQL Connect VS Code ما
- با به‌روزرسانی
connector.yaml
کد کارخواه را مقداردهی اولیه کنید و کتابخانه‌ها را وارد کنید.
شبیه‌ساز SQL Connect را راه‌اندازی و استفاده کنید و تکرار کنید.
تولید کردن Kotlin SDK
از Firebase CLI برای راه‌اندازی کیت‌های توسعه نرم‌افزار تولیدشده SQL Connect در برنامه‌هایتان استفاده کنید.
فرمان init باید همه برنامه‌های موجود در پوشه فعلی را شناسایی کند و
کیت‌های توسعه نرم‌افزار تولیدشده را به‌طور خودکار نصب کند.
firebase init dataconnect:sdk
به‌روزرسانی کیت‌های توسعه نرم‌افزار درحین نمونه‌سازی
اگر افزونه SQL Connect VS Code را نصب کرده باشید، همیشه کیت‌های توسعه نرم‌افزار تولیدشده را به‌روز نگه می‌دارد.
اگر از افزونه SQL Connect VS Code استفاده نمی‌کنید، می‌توانید از واسط خط فرمان Firebase برای به‌روز نگه داشتن کیت‌های توسعه نرم‌افزار تولیدشده استفاده کنید.
firebase dataconnect:sdk:generate --watchتولید کیت‌های توسعه نرم‌افزار در خطوط لوله ساخت
می‌توانید از واسط خط فرمان Firebase برای تولید کیت‌های توسعه نرم‌افزار SQL Connect در فرایندهای ساخت CI/CD استفاده کنید.
firebase dataconnect:sdk:generateراه‌اندازی کد مشتری
SQL Connect را در کد کارخواهتان بگنجانید
برای راه‌اندازی کد کارخواهتان جهت استفاده از SQL Connect و کیت توسعه نرم‌افزار تولیدشده، ابتدا دستورالعمل‌های راه‌اندازی استاندارد 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.2"))
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
مقداردهی اولیه کیت توسعه نرم‌افزار Android SQL Connect
نمونه SQL Connect خود را بااستفاده از اطلاعاتی که برای راه‌اندازی SQL Connect استفاده کردید، مقداردهی اولیه کنید. این اطلاعات را در صفحه پایگاه‌های داده و فضای ذخیره‌سازی > اتصال SQL در کنسول Firebase پیدا کنید.
شیء ConnectorConfig
کیت توسعه نرم‌افزار به شیء پیکربندی اتصال‌دهنده نیاز دارد.
این شیء به‌طور خودکار از serviceId و location در
dataconnect.yaml، و connectorId در connector.yaml تولید شده است.
دریافت نمونه رابط
اکنون که شیء پیکربندی را راه‌اندازی کرده‌اید، نمونه اتصال‌دهنده SQL Connect را
دریافت کنید. کد اتصال‌دهنده شما توسط شبیه‌ساز SQL Connect تولید خواهد شد. اگر نام اتصال‌دهنده شما movies و بسته Kotlin
com.myapplication است، همان‌طور که در connector.yaml مشخص شده است،
شیء اتصال‌دهنده را با فراخوانی زیر بازیابی کنید:
val connector = com.myapplication.MoviesConnector.instance
استفاده از پُرسمان‌ها و جهش‌ها از کیت توسعه نرم‌افزار 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، می‌توانید از ابزار توسعه محلی برای به‌روزرسانی پُرسمان‌ها و کیت‌های توسعه نرم‌افزار استفاده کنید.
اما قبل‌از اینکه نسخه به‌روزشده‌ای از کلاینت‌هایتان را منتشر کنید، کلاینت‌های مستقرشده قدیمی‌تر ممکن است خراب شوند.
نمونه پیاده‌سازی انعطاف‌پذیر
کیت توسعه نرم‌افزار تولیدشده، رسیدگی به مقادیر ناشناخته را اجباری می‌کند زیرا کد مشتری باید شیء 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 فعال کنید. وقتی این ویژگی فعال باشد،
کیت‌های توسعه نرم‌افزار مشتری تولیدشده پاسخ‌های پُرسمان را به‌طور محلی ذخیره می‌کنند، که می‌تواند
تعداد درخواست‌های پایگاه داده‌ای را که برنامه‌تان ایجاد می‌کند کاهش دهد و بخش‌های وابسته به پایگاه داده برنامه‌تان را قادر می‌سازد تا درصورت قطع شدن شبکه کار کنند.
برای فعال کردن ذخیره‌سازی موقت سمت کارخواه، پیکربندی ذخیره‌سازی موقت کارخواه را به پیکربندی متصل‌کننده‌تان اضافه کنید:
generate:
kotlinSdk:
outputDir: "../android"
package: "com.google.firebase.dataconnect.generated"
clientCache:
maxAge: 5s
storage: persistent
این پیکربندی دو پارامتر دارد که هر دو اختیاری هستند:
maxAge: حداکثر سن پاسخ ذخیره‌شده در حافظه نهان قبل‌از اینکه کیت توسعه نرم‌افزار مشتری مقادیر جدید را واکشی کند. مثال: «0»، «30s»، «1h30m».مقدار پیش‌فرض برای
maxAge،0است، یعنی پاسخ‌ها ذخیره موقت می‌شوند، اما کیت توسعه نرم‌افزار کارخواه همیشه مقادیر جدید را واکشی می‌کند. مقادیر ذخیره‌شده در حافظه نهان فقط زمانی استفاده می‌شود کهCACHE_ONLYبرایexecute()مشخص شده باشد.storage: کیت توسعه نرم‌افزار کارخواه را می‌توان به‌گونه‌ای پیکربندی کرد که پاسخ‌ها را درpersistentیا درmemoryذخیره کند. نتایج ذخیره‌شده در حافظه نهانpersistentدرصورت بازراه‌اندازی برنامه باقی می‌ماند. در کیت‌های توسعه نرم‌افزار Android، مقدار پیش‌فرضpersistentاست.
پس‌از به‌روزرسانی پیکربندی ذخیره‌سازی موقت اتصال‌دهنده، کیت‌های توسعه نرم‌افزار کارخواه را بازتولید کنید و برنامه‌تان را بازسازی کنید. پس‌از انجام این کار، 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 در کیت‌های توسعه نرم‌افزار SQL Connect
سرور SQL Connect انواع داده‌های GraphQL رایج و سفارشی را نشان می‌دهد. این موارد در کیت توسعه نرم‌افزار به‌صورت زیر نشان داده می‌شوند.
SQL Connect نوع Kotlin تار تار Int عدد صحیح (عدد صحیح ۳۲ بیتی) شناور Double (64-bit float) بولی بولی شناسه منحصربه‌فرد جهانی java.util.UUID تاریخ com.google.firebase.dataconnect.LocalDate (was java.util.Date until 16.0.0-beta03) مُهر زمان com.google.firebase.Timestamp Int64 طولانی همه com.google.firebase.dataconnect.AnyValue