שימוש ב-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.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

מאתחלים את 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