از SDK های Android تولید شده استفاده کنید

کیت‌های توسعه نرم‌افزار (SDK) کلاینت Firebase SQL Connect به شما امکان می‌دهند کوئری‌ها و جهش‌های سمت سرور خود را مستقیماً از یک برنامه Firebase فراخوانی کنید. شما همزمان با طراحی طرح‌ها، کوئری‌ها و جهش‌هایی که در سرویس SQL Connect خود پیاده‌سازی می‌کنید، یک SDK کلاینت سفارشی نیز به صورت موازی ایجاد می‌کنید. سپس، متدهای این SDK را در منطق کلاینت خود ادغام می‌کنید.

همانطور که در جای دیگری اشاره کردیم، توجه به این نکته مهم است که کوئری‌ها و جهش‌های SQL Connect توسط کد کلاینت ارسال و روی سرور اجرا نمی‌شوند. در عوض، هنگام استقرار، عملیات SQL Connect مانند توابع ابری روی سرور ذخیره می‌شوند. این بدان معناست که برای جلوگیری از اختلال در عملکرد کاربران موجود (به عنوان مثال، در نسخه‌های قدیمی‌تر برنامه)، باید تغییرات مربوطه در سمت کلاینت را اعمال کنید.

به همین دلیل است که SQL Connect یک محیط توسعه‌دهنده و ابزار را در اختیار شما قرار می‌دهد که به شما امکان می‌دهد طرح‌ها، کوئری‌ها و جهش‌های مستقر در سرور خود را نمونه‌سازی کنید. همچنین، همزمان با نمونه‌سازی شما، SDKهای سمت کلاینت را به طور خودکار تولید می‌کند.

وقتی به‌روزرسانی‌های مکرر را برای سرویس و برنامه‌های کلاینت خود انجام دادید، به‌روزرسانی‌های سمت سرور و کلاینت آماده‌ی استقرار هستند.

گردش کار توسعه کلاینت چیست؟

اگر بخش «شروع به کار» را دنبال کرده باشید، با جریان کلی توسعه SQL Connect آشنا شده‌اید. در این راهنما، اطلاعات دقیق‌تری در مورد تولید SDKهای اندروید از طرحواره خود و کار با کوئری‌ها و جهش‌های کلاینت خواهید یافت.

به طور خلاصه، برای استفاده از SDK های تولید شده اندروید در برنامه های کلاینت خود، این مراحل پیش نیاز را دنبال خواهید کرد:

  1. فایربیس را به برنامه اندروید خود اضافه کنید.
  2. SQL Connect به عنوان یک وابستگی در Gradle پیکربندی کنید.
  3. افزونه‌ی Gradle مربوط به Kotlin Serialization و وابستگی Gradle را اضافه کنید.

سپس:

  1. طرحواره برنامه خود را توسعه دهید.

  2. تنظیم تولید SDK:

  3. کد کلاینت خود را مقداردهی اولیه کنید و کتابخانه‌ها را وارد کنید .

  4. فراخوانی‌های کوئری‌ها و جهش‌ها را پیاده‌سازی کنید .

  5. شبیه‌ساز SQL Connect را راه‌اندازی و استفاده کنید و مراحل را تکرار کنید.

کیت توسعه نرم‌افزار کاتلین (Kotlin SDK) خود را ایجاد کنید

از رابط خط فرمان Firebase CLI) برای تنظیم 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:34.12.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 اندروید SQL Connect

نمونه 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 اندروید خود استفاده کنید

با شیء کانکتور، می‌توانید کوئری‌ها و جهش‌ها را همانطور که در کد منبع 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 اضافه کنید.

در گردش کار SQL 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()
)

فعال کردن حافظه پنهان سمت کلاینت

SQL Connect یک ویژگی ذخیره‌سازی (caching) اختیاری در سمت کلاینت دارد که می‌توانید با ویرایش فایل 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های اندروید، پیش‌فرض 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)

    نمونه اولیه برنامه اندروید خود را بسازید و آزمایش کنید

    کلاینت‌های Instrument برای استفاده از یک شبیه‌ساز محلی

    شما می‌توانید از شبیه‌ساز 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 کاتلین
    رشته رشته
    بین المللی عدد صحیح (عدد صحیح ۳۲ بیتی)
    شناور دابل (اعشار ۶۴ بیتی)
    بولی بولی
    شناسه کاربری شناسه کاربری جاوا (java.util.UUID)
    تاریخ com.google.firebase.dataconnect.LocalDate (تا نسخه ۱۶.۰.۰-بتا۰۳ با نام java.util.Date شناخته می‌شد)
    مهر زمانی com.google.firebase.Timestamp
    بین‌رشته‌ای64 طولانی
    هر com.google.firebase.dataconnect.AnyValue