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

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

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

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

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

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

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

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

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

לאחר מכן:

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

2. הגדרת יצירת SDK:

   • באמצעות הלחצן Add SDK to app (הוספת SDK לאפליקציה) בתוסף Data Connect ל-VS Code
   • עדכון של connector.yaml

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

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

5. מגדירים את האמולטור Data Connect ומשתמשים בו וחוזרים על התהליך.

יצירת Kotlin SDK

משתמשים ב-CLI‏ Firebase כדי להגדיר ערכות 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 כדי ליצור ערכות SDK של Data Connect בתהליכי בנייה של 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.2.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

שימוש בשאילתות ובמוטציות מ-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 שייצור תוצאה רק כשמאחזרים תוצאת שאילתה חדשה באמצעות קריאה לשיטה 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

טיפול בשינויים בשדות של ספירה

סכימה של אפליקציה יכולה להכיל מניינים שאפשר לגשת אליהם באמצעות שאילתות GraphQL.

יכול להיות שתוסיפו ערכים חדשים של enum נתמכים ככל שהעיצוב של האפליקציה ישתנה. לדוגמה, נניח שבהמשך מחזור החיים של האפליקציה, אתם מחליטים להוסיף ערך FULLSCREEN לאנום 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()
)

יצירת אב-טיפוס ובדיקה של אפליקציית Android

הגדרת לקוחות לשימוש באמולטור מקומי

אתם יכולים להשתמש באמולטור 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 SDK

שרת Data Connect מייצג סוגי נתונים נפוצים ומותאמים אישית של GraphQL. הם מיוצגים ב-SDK באופן הבא.