Generierte iOS-SDKs verwenden

Mit den Firebase Data Connect-Client-SDKs können Sie Ihre serverseitigen Abfragen und Mutationen direkt über eine Firebase-App aufrufen. Sie generieren ein benutzerdefiniertes Client-SDK parallel zur Entwicklung der Schemas, Abfragen und Mutationen, die Sie für Ihren Data Connect-Dienst bereitstellen. Anschließend binden Sie Methoden aus diesem SDK in Ihre Clientlogik ein.

Wie bereits erwähnt, ist es wichtig zu beachten, dass Data Connect-Abfragen und ‑Mutationen nicht vom Clientcode gesendet und auf dem Server ausgeführt werden. Stattdessen werden Data Connect-Vorgänge bei der Bereitstellung auf dem Server wie Cloud Functions gespeichert. Das bedeutet, dass Sie entsprechende clientseitige Änderungen bereitstellen müssen, um zu vermeiden, dass bestehende Nutzer (z. B. in älteren App-Versionen) beeinträchtigt werden.

Data Connect bietet Ihnen daher eine Entwicklungsumgebung und Tools, mit denen Sie Prototypen Ihrer serverbasierten Schemas, Abfragen und Mutationen erstellen können. Außerdem werden clientseitige SDKs automatisch generiert, während Sie Prototypen erstellen.

Wenn Sie die Aktualisierungen für Ihren Dienst und Ihre Client-Apps durchlaufen haben, können sowohl serverseitige als auch clientseitige Aktualisierungen bereitgestellt werden.

Wie sieht der Workflow für die Cliententwicklung aus?

Wenn Sie dem Startleitfaden gefolgt sind, haben Sie den allgemeinen Entwicklungsablauf für Data Connect kennengelernt. In dieser Anleitung finden Sie detailliertere Informationen zum Generieren von Swift-SDKs aus Ihrem Schema und zum Arbeiten mit Clientabfragen und ‑Mutationen.

Zusammenfassend lässt sich sagen, dass Sie die folgenden Voraussetzungen erfüllen müssen, um generierte Swift-SDKs in Ihren Client-Apps zu verwenden:

1. Fügen Sie Ihrer iOS-App Firebase hinzu.

2. Wenn Sie das generierte SDK verwenden möchten, konfigurieren Sie es als Abhängigkeit in Xcode.

   Wählen Sie in der oberen Navigationsleiste von Xcode File > Add Package Dependencies > Add Local aus und wählen Sie den Ordner mit der generierten Package.swift aus.

Gehen Sie anschließend so vor:

1. App-Schema entwickeln

2. SDK-Generierung einrichten:

   • Mit der Schaltfläche SDK zur App hinzufügen in unserer Data Connect-VS Code-Erweiterung
   • connector.yaml aktualisieren

3. Clientcode initialisieren und Bibliotheken importieren

4. Aufrufe für Abfragen und Mutationen implementieren

5. Data Connect-Emulator einrichten und verwenden und Iterationen durchführen.

Swift-SDK generieren

Wie bei den meisten Firebase-Projekten findet die Arbeit an Ihrem Firebase Data Connect-Clientcode in einem lokalen Projektverzeichnis statt. Sowohl die Data Connect VS Code-Erweiterung als auch die Firebase-CLI sind wichtige lokale Tools zum Generieren und Verwalten von Clientcode.

Die Optionen für die SDK-Generierung sind an mehrere Einträge in der Datei dataconnect.yaml gebunden, die beim Initialisieren des Projekts generiert wurde.

SDK-Generierung initialisieren

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

outputDir gibt an, wohin das generierte SDK ausgegeben werden soll. Wenn nicht angegeben, wird der Connector-Ordner als Standardausgabeverzeichnis verwendet.

package gibt den Namen des zu generierenden Pakets an. Der Generator erstellt einen Ordner mit dem Namen des Pakets, der Package.swift und generierten Code enthält.

observablePublisher (optional) gibt den Observable-Publisher an, der in Abfrageverweisen verwendet werden soll. Mögliche Werte sind observableMacro (iOS 17+) und observableObject (vor iOS 17). Der Standardwert, wenn keiner angegeben ist, ist observableMacro.

SDKs während der Prototyperstellung aktualisieren

Wenn Sie mit der VS Code-Erweiterung „Data Connect“ und dem Data Connect-Emulator interaktiv Prototypen erstellen, werden SDK-Quelldateien automatisch generiert und aktualisiert, während Sie .gql-Dateien mit Schemas, Abfragen und Mutationen ändern. Dies kann bei Hot-Reload-Workflows nützlich sein.

Alternativ können Sie die CLI verwenden, um SDKs immer dann neu zu generieren, wenn .gql-Dateien geändert werden:

firebase dataconnect:sdk:generate --watch

SDKs für die Integration und für Produktionsversionen generieren

In einigen Fällen, z. B. beim Vorbereiten von Projektquellen für CI-Tests, können Sie die Firebase CLI für eine Batchaktualisierung aufrufen.

Verwenden Sie in diesen Fällen firebase dataconnect:sdk:generate.

Data Connect iOS SDK initialisieren

Initialisieren Sie Ihre Data Connect-Instanz mit den Informationen, die Sie zum Einrichten von Data Connect verwendet haben. Alle Informationen sind in der Firebase-Konsole auf dem Tab „Data Connect“ verfügbar.

Connector-Instanz abrufen

Der Code für Ihren Connector wird vom Data Connect-Emulator generiert. Wenn Ihr Connectorname movies und das Paket movies ist, wie in connector.yaml angegeben, rufen Sie das Connectorobjekt mit folgendem Aufruf ab:

let connector = DataConnect.moviesConnector

Abfragen und Mutationen implementieren

Mit dem Connector-Objekt können Sie Abfragen und Mutationen ausführen, die im GraphQL-Quellcode definiert sind. Angenommen, für Ihren Connector sind die folgenden Vorgänge definiert:

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
  }
}

So erstellen Sie einen Film:

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)")

Um einen Film abzurufen, verwenden Sie einen Abfrageverweis. Alle Abfrageverweise sind Observable-Publisher. Je nach konfiguriertem Publisher (siehe connector.yaml)) wird entweder das Makro @Observable (iOS 17+) unterstützt oder das Protokoll ObservableObject implementiert. Wenn keine Angabe erfolgt, wird standardmäßig das Makro @Observable verwendet, das unter iOS 17 und höher unterstützt wird.

In einer SwiftUI-Ansicht können Sie die Abfrageergebnisse mit der veröffentlichten data-Variablen der Abfragereferenz binden und die execute()-Methode der Abfrage aufrufen, um die Daten zu aktualisieren. Die Variable data entspricht der Form der Daten, die in Ihrer GQL-Abfragedefinition definiert wurde.

Alle abgerufenen Ergebnisse entsprechen dem Decodable-Protokoll. Wenn Sie den Primärschlüssel des Objekts in Ihren GQL-Abruf aufgenommen haben, sind die Objekte auch Identifiable, sodass Sie sie in Iteratoren verwenden können.

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()
    }
}

Abfragen unterstützen auch die einmalige Ausführung.

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

iOS-App prototypisieren und testen

Clients für die Verwendung eines lokalen Emulators instrumentieren

Sie können den Data Connect-Emulator über die Data Connect VS Code-Erweiterung oder über die CLI verwenden.

Die Instrumentierung der App für die Verbindung zum Emulator ist in beiden Szenarien identisch.

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

Datentypen in Data Connect-SDKs

Der Data Connect-Server stellt allgemeine und benutzerdefinierte GraphQL-Datentypen dar. Im SDK werden sie so dargestellt: