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

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

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

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

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

יצירת SDK ל-Swift

כמו ברוב הפרויקטים ב-Firebase, העבודה על קוד הלקוח של Firebase Data Connect מתבצעת בספריית פרויקט מקומית. גם התוסף של Data Connect ל-VS Code וגם ה-CLI של Firebase הם כלים מקומיים חשובים ליצירה ולניהול של קוד לקוח.

אפשרויות היצירה של ה-SDK ממופות למספר רשומות בקובץ dataconnect.yaml שנוצר כשאתם מאתחלים את הפרויקט.

אתחול היצירה של SDK

ב-connector.yaml, מוסיפים את outputDir, את package ואת packageJsonDir (ל-SDK לאינטרנט). 
connectorId: "movies"
generate:
  swiftSdk:
    outputDir: "../movies-generated"
    package: "Movies"

outputDir מציין לאן צריך להוציא את ה-SDK שנוצר. אם לא מציינים ספרייה, המערכת משתמשת בספריית המחבר כספריית הפלט שמוגדרת כברירת מחדל.

package מציין את שם החבילה שתיווצר. הגנרטור ייצור תיקייה בשם החבילה, שתכלול את Package.swift ואת הקוד שנוצר.

observablePublisher (אופציונלי) מציין את בעל התוכן הדיגיטלי ב-Observable שבו רוצים להשתמש בהפניות לשאילתות. הערכים האפשריים הם observableMacro (iOS מגרסה 17 ואילך) ו-observableObject (לפני iOS מגרסה 17). ערך ברירת המחדל, אם לא צוין ערך אחר, הוא observableMacro.

עדכון חבילות SDK במהלך פיתוח אב טיפוס

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

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

לחלופין, אפשר להשתמש ב-CLI כדי ליצור מחדש את ערכות ה-SDK בכל פעם שקובצי ה-gql משתנים:

firebase dataconnect:sdk:generate --watch

יצירת ערכות SDK לשילוב ולגרסאות ייצור

במקרים מסוימים, כמו הכנת מקורות של פרויקטים לשליחה לבדיקות CI, אפשר להפעיל את ה-CLI של Firebase כדי לבצע עדכון באצווה.

במקרים כאלה, צריך להשתמש ב-firebase dataconnect:sdk:generate.

הגדרת קוד לקוח

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

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

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

אתחול של Data Connect iOS SDK

מאתחלים את המכונה של Data Connect באמצעות המידע ששימש להגדרת Data Connect (הכול זמין בכרטיסייה Data Connect במסוף Firebase).

אחזור מכונה של מחבר

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

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

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

אפשר להשתמש במהדמ של Data Connect דרך התוסף של Data 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 של Data Connect

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

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