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

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

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

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

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

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

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

אפשר ללמוד על פיתוח לקוחות באמצעות מאגר אפליקציות להפעלה מהירה ולבנות אפליקציית Data Connect מלאה באמצעות ה-codelab שלנו ל-iOS.

לסיכום, כדי להשתמש ב-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 לאפליקציה) בתוסף Data Connect ל-VS Code
   • עדכון של connector.yaml

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

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

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

יצירת Swift SDK

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

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

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

ב-connector.yaml, מוסיפים את outputDir, package ואת (עבור ה-SDK לאינטרנט) packageJsonDir.

connectorId: "movies"
generate:
  swiftSdk:
    outputDir: "../movies-generated"
    package: "Movies"

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

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

observablePublisher (אופציונלי) מציין את ה-Observable publisher שבו יש להשתמש ב-query refs. הערכים האפשריים הם 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, אפשר להפעיל את Firebase CLI לעדכון אצווה.

במקרים כאלה, צריך להשתמש ב-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, כך שתוכלו להשתמש בהם באיטרטורים.

הערה: הנתון @StateObject לא מתעדכן בזמן אמת. הוא גם לא נדרש כשמשתמשים במאקרו @Observable בתור בעלי האתר.

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

סוגי נתונים בערכות Data Connect SDK

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

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