שימוש ב-SDKs של Android שנוצרו

ערכות ה-SDK של הלקוח ב-Firebase SQL Connect מאפשרות להפעיל את השאילתות והמוטציות בצד השרת ישירות מאפליקציית Firebase. אתם יוצרים ערכת SDK מותאמת אישית של הלקוח במקביל לתכנון הסכימות, השאילתות והמוטציות שאתם פורסים בשירות SQL Connect. לאחר מכן, משלבים שיטות מה-SDK הזה בלוגיקה של הלקוח.

כמו שציינו במקומות אחרים, חשוב לציין שSQL Connect שאילתות ומוטציות לא נשלחות על ידי קוד הלקוח ומבוצעות בשרת. במקום זאת, כשפורסים את הפעולות של SQL Connect, הן מאוחסנות בשרת כמו פונקציות של Cloud Functions. זה אומר שצריך לפרוס שינויים תואמים בצד הלקוח כדי לא לפגוע במשתמשים קיימים (לדוגמה, בגרסאות ישנות יותר של האפליקציה).

לכן, SQL Connect מספק סביבת פיתוח וכלים שמאפשרים ליצור אב טיפוס של הסכימות, השאילתות והמוטציות שנפרסו בשרת. הוא גם יוצר ערכות SDK בצד הלקוח באופן אוטומטי, בזמן שאתם יוצרים אב טיפוס.

אחרי שמעדכנים את השירות ואת אפליקציות הלקוח, העדכונים בצד השרת ובצד הלקוח מוכנים לפריסה.

מהו תהליך העבודה לפיתוח לקוח?

אם פעלתם לפי ההוראות במאמר תחילת העבודה, אתם כבר מכירים את תהליך הפיתוח הכולל של SQL Connect. במדריך הזה מוסבר בפירוט איך ליצור ערכות Android SDK מהסכימה, ואיך לעבוד עם שאילתות ומוטציות של לקוחות.

לסיכום, כדי להשתמש בערכות Android SDK שנוצרו באפליקציות הלקוח, צריך לבצע את השלבים הבאים:

  1. מוסיפים את Firebase לאפליקציה ל-Android.
  2. מגדירים את SQL Connect כתלות ב-Gradle.
  3. מוסיפים את הפלאגין Kotlin Serialization Gradle ואת התלות ב-Gradle.

לאחר מכן:

  1. מפתחים את הסכימה של האפליקציה.

  2. מגדירים את יצירת ה-SDK:

  3. מאתחלים את קוד הלקוח ומייבאים ספריות.

  4. מטמיעים קריאות לשאילתות ולמוטציות.

  5. מגדירים את האמולטור של 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 בצינורות עיבוד נתונים של גרסאות build

אתם יכולים להשתמש ב-Firebase CLI כדי ליצור ערכות SDK של SQL Connect בתהליכי build של 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.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

אתחול של SQL Connect Android SDK

מאתחלים את המכונה של SQL Connect באמצעות המידע ששימש להגדרת SQL Connect. המידע הזה מופיע בדף Databases & Storage > 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

שימוש בשאילתות ובמוטציות מ-Android 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)

אפשר גם לאסוף Flow שיפיק תוצאה רק כשתוצאת שאילתה חדשה מאוחזרת באמצעות קריאה ל-method‏ 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.

אם העיצוב של האפליקציה משתנה, אתם יכולים להוסיף ערכים נתמכים חדשים של enum. לדוגמה, נניח שבשלב מאוחר יותר במחזור החיים של האפליקציה, אתם מחליטים להוסיף ערך FULLSCREEN ל-enum של AspectRatio.

בתהליך העבודה של SQL 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()
)

הפעלת שמירה במטמון בצד הלקוח

ב-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 יישארו גם אחרי הפעלה מחדש של האפליקציה. ב-Android 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)

    יצירת אב טיפוס ובדיקה של אפליקציה ל-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 ביט)
    Float Double (נקודה צפה של 64 ביט)
    בוליאני בוליאני
    מזהה ייחודי אוניברסלי (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