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

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

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

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

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

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

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

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

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

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

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

לאחר מכן:

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

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

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

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

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

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

יצירת 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 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