שימוש בערכות SDK שנוצרו על ידי iOS

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

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

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

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

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

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

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

1. מוסיפים את Firebase לאפליקציית iOS.

2. כדי להשתמש ב-SDK שנוצר, צריך להגדיר אותו כהסתמכות ב-Xcode.

   בסרגל הניווט העליון של Xcode, בוחרים באפשרות File > Add Package Dependencies > Add Local (קובץ > הוספת תלות בחבילה > הוספה מקומית), ובוחרים את התיקייה שמכילה את הקובץ Package.swift שנוצר.

לאחר מכן:

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

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

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

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

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

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

יצירת Swift 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 בצינורות עיבוד נתונים

אפשר להשתמש ב-Firebase CLI כדי ליצור SQL Connect SDK בתהליכי build של CI/CD.

firebase dataconnect:sdk:generate

אתחול SQL Connect iOS SDK

מאתחלים את מופע SQL Connect באמצעות המידע שבו השתמשתם כדי להגדיר את SQL Connect. אפשר למצוא את המידע הזה בדף Databases & Storage >‏ SQL Connect במסוף Firebase.

קבלת מופע של מחבר

הקוד של המחבר ייווצר על ידי האמולטור SQL Connect. אם שם המחבר הוא movies והחבילה היא movies, כמו שמצוין ב-connector.yaml, צריך לאחזר את אובייקט המחבר באמצעות הקריאה:

let connector = DataConnect.moviesConnector

הטמעה של שאילתות ומוטציות

באמצעות אובייקט המחבר, אפשר להריץ שאילתות ומוטציות כפי שמוגדר בקוד המקור של 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
  }
}

אחרי כן תוכלו ליצור סרט באופן הבא:

let mutationResult = try await connector.createMovieMutation.execute(
  title: "Empire Strikes Back",
  releaseYear: 1980,
  genre: "Sci-Fi",
  rating: 5)

print("Movie ID: \(mutationResult.data.movie_insert.id)")

כדי לאחזר סרט, תשתמשו בהפניה לשאילתה. כל ההפניות לשאילתות הן Observable publishers. בהתאם להגדרות של בעל התוכן הדיגיטלי (ראו connector.yaml)), הוא תומך במאקרו @Observable (iOS 17 ואילך) או מטמיע את פרוטוקול ObservableObject. אם לא מציינים ערך, ברירת המחדל היא מאקרו @Observable שנתמך ב-iOS מגרסה 17 ואילך.

בתצוגת SwiftUI, אפשר לקשר את תוצאות השאילתה באמצעות המשתנה data שפורסם של הפניה לשאילתה, ולקרוא לשיטה execute() של השאילתה כדי לעדכן את הנתונים. המשתנה data יתאים לצורת הנתונים שהוגדרה בהגדרת שאילתת GQL.

כל התוצאות שאוחזרו תואמות לפרוטוקול Decodable. אם כללתם את המפתח הראשי של האובייקט באחזור GQL, האובייקטים הם גם Identifiable, כך שתוכלו להשתמש בהם באיטרטורים.

struct ListMovieView: View {
    @StateObject private var queryRef = connector.listMoviesByGenreQuery.ref(genre: "Sci-Fi")
    var body: some View {
        VStack {
            Button {
                Task {
                    do {
                        try await refresh()
                    } catch {
                        print("Failed to refresh: \(error)")
                    }
                }
            } label: {
                Text("Refresh")
            }
                // use the query results in a view
            ForEach(queryRef.data?.movies ?? [], id: \.self.id) { movie in
                    Text(movie.title)
                }
            }
    }
    @MainActor
    func refresh() async throws {
        _ = try await queryRef.execute()
    }
}

השאילתות תומכות גם בביצוע חד-פעמי.

let resultData = try await DataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre: "Sci-Fi")

הרשמה לקבלת עדכונים על שינויים

איך מקבלים עדכונים בזמן אמת מ-SQL Connect

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

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

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

בתהליך העבודה של SQL Connect, אפשר להשתמש בכלים לפיתוח מקומי כדי לעדכן את השאילתות ואת ערכות ה-SDK.

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

דוגמה להטמעה עמידה

ה-SDK שנוצר מחייב טיפול בערכים לא ידועים, כי ה-enums שנוצרו מכילים ערך _UNKNOWN, ו-Swift מחייבת הצהרות switch מקיפות.

do {
    let result = try await DataConnect.moviesConnector.listMovies.execute()
    if let data = result.data {
        for movie in data.movies {
            switch movie.aspectratio {
                case .ACADEMY: print("academy")
                case .WIDESCREEN: print("widescreen")
                case .ANAMORPHIC: print("anamorphic")
                case ._UNKNOWN(let unknownAspect): print(unknownAspect)
            }
        }
    }
} catch {
    // handle error
}

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

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

כדי להפעיל שמירת נתונים במטמון בצד הלקוח, מוסיפים הגדרה של שמירת נתונים במטמון בצד הלקוח להגדרת המחבר:

generate:
  swiftSdk:
    outputDir: "../ios"
    package: "FirebaseDataConnectGenerated"
    clientCache:
      maxAge: 5s
      storage: persistent

במסגרת ההגדרה הזו יש שני פרמטרים, שניהם אופציונליים:

• ‫maxAge: הגיל המקסימלי של תגובה שנשמרה במטמון לפני שערכת ה-SDK של הלקוח מאחזרת ערכים חדשים. דוגמאות: '0',‏ '30s',‏ '1h30m'.

  ערך ברירת המחדל של maxAge הוא 0, כלומר התשובות נשמרות במטמון, אבל ה-SDK של הלקוח תמיד יאחזר ערכים עדכניים. הערכים שנשמרו במטמון ישמשו רק אם המשתנה CACHE_ONLY מוגדר לערך execute().

• ‫storage: אפשר להגדיר את ה-SDK של הלקוח כך שיאחסן תשובות במטמון באחסון persistent או ב-memory. התוצאות שנשמרות במטמון באחסון persistent יישארו גם אחרי הפעלה מחדש של האפליקציה. ב-SDK ל-iOS, ברירת המחדל היא persistent.

אחרי שמעדכנים את הגדרות השמירה במטמון של המחבר, צריך ליצור מחדש את ה-SDK של הלקוח ולבנות מחדש את האפליקציה. לאחר מכן, execute() ישמור במטמון את התגובות וישתמש בערכים שנשמרו במטמון בהתאם למדיניות שהגדרתם. בדרך כלל זה קורה באופן אוטומטי, בלי שתצטרכו לבצע פעולות נוספות. עם זאת, חשוב לשים לב לנקודות הבאות:

• התנהגות ברירת המחדל של execute() היא כפי שמתואר למעלה: אם תוצאה נשמרת במטמון עבור שאילתה והערך במטמון לא ישן יותר מ-maxAge, נעשה שימוש בערך במטמון. פעולת ברירת המחדל הזו נקראת מדיניות PREFER_CACHE.

  אפשר גם לציין הפעלות ספציפיות של execute() כדי להציג רק ערכים שמורים במטמון (CACHE_ONLY) או כדי לאחזר ללא תנאי ערכים חדשים מהשרת (SERVER_ONLY).

  try await execute(fetchPolicy: .cacheOnly)
  

  try await execute(fetchPolicy: .serverOnly)
  

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

  אתם יכולים להשתמש באמולטור המקומי כדי לבדוק את האפליקציה וליצור אב טיפוס שלה.

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

  אפשר להשתמש באמולטור SQL Connect, דרך התוסף SQL Connect ל-VS Code או דרך CLI.

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

  let connector = DataConnect.moviesConnector
  // Connect to the emulator on "127.0.0.1:9399"
  connector.useEmulator()
  
  // (alternatively) if you're running your emulator on non-default port:
  connector.useEmulator(port: 9999)
  
  // Make calls from your app
  

  סוגי נתונים בערכות SDK של SQL Connect

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

  SQL Connect סוג	Swift
  מחרוזת	מחרוזת
  Int	Int
  Float	זוגית
  בוליאני	בוליאני
  מזהה ייחודי אוניברסלי (UUID)	מזהה ייחודי אוניברסלי (UUID)
  תאריך	FirebaseDataConnect.LocalDate
  חותמת זמן	FirebaseCore.Timestamp
  Int64	Int64
  הכול	FirebaseDataConnect.AnyValue