שימוש בערכות 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

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

לחלופין, אפשר להשתמש ב-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 באופן הבא.