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) Probleme haben.

Data Connect bietet Ihnen daher eine Entwicklungsumgebung und Tools, mit denen Sie Prototypen für Ihre auf dem Server bereitgestellten Schemas, Abfragen und Mutationen erstellen können. Außerdem werden clientseitige SDKs automatisch generiert, während Sie Prototypen erstellen.

Nachdem Sie die Updates für Ihren Dienst und Ihre Client-Apps durchlaufen haben, können Sie sowohl serverseitige als auch clientseitige Updates bereitstellen.

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.

Mit einem Repository für eine Schnellstart-App können Sie die Cliententwicklung erlernen und eine Data Connect-App mit allen Funktionen erstellen, indem Sie unserem Codelab für iOS folgen.

Zusammenfassend lässt sich sagen, dass Sie zum Verwenden generierter Swift-SDKs in Ihren Client-Apps die folgenden Voraussetzungen erfüllen müssen:

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
   • Aktualisieren Sie Ihr connector.yaml.

3. Clientcode initialisieren und Bibliotheken importieren

4. Aufrufe für Abfragen und Mutationen implementieren

5. Data Connect-Emulator einrichten und verwenden und iterieren.

Swift-SDK generieren

Verwenden Sie die Firebase-Befehlszeile, um Data Connect-generierte SDKs in Ihren Apps einzurichten. Mit dem Befehl init sollten alle Apps im aktuellen Ordner erkannt und die generierten SDKs automatisch installiert werden.

firebase init dataconnect:sdk

SDKs während der Prototyperstellung aktualisieren

Wenn Sie die Data Connect VS Code-Erweiterung installiert haben, werden generierte SDKs immer auf dem neuesten Stand gehalten.

Wenn Sie die Data Connect VS Code-Erweiterung nicht verwenden, können Sie die generierten SDKs mit der Firebase-Befehlszeile auf dem neuesten Stand halten.

firebase dataconnect:sdk:generate --watch

SDKs in Build-Pipelines generieren

Sie können die Firebase CLI verwenden, um Data Connect-SDKs in CI/CD-Build-Prozessen zu generieren.

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 auf dem Tab Data Connect der Firebase-Konsole 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 eine Abfrage-Referenz. 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 mithilfe 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.

Hinweis :Das @StateObject wird nicht in Echtzeit aktualisiert. Sie ist auch nicht erforderlich, wenn Sie als Publisher ein @Observable-Makro verwenden.

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

Änderungen an Enumerationsfeldern verarbeiten

Das Schema einer App kann Aufzählungen enthalten, auf die über Ihre GraphQL-Abfragen zugegriffen werden kann.

Wenn sich das Design einer App ändert, können Sie neue unterstützte Enum-Werte hinzufügen. Angenommen, Sie entscheiden sich später im Lebenszyklus Ihrer Anwendung, der AspectRatio-Enumeration den Wert FULLSCREEN hinzuzufügen.

Im Data Connect-Workflow können Sie lokale Entwicklungstools verwenden, um Ihre Abfragen und SDKs zu aktualisieren.

Bevor Sie jedoch eine aktualisierte Version Ihrer Clients veröffentlichen, kann es sein, dass ältere bereitgestellte Clients nicht mehr funktionieren.

Beispiel für eine robuste Implementierung

Das generierte SDK erzwingt die Verarbeitung unbekannter Werte, da die generierten Enums einen _UNKNOWN-Wert enthalten und Swift erschöpfende Switch-Anweisungen erzwingt.

do {
    let result = try await DataConnect.moviesConnector.listMovies.execute()
    if let data = result.data {
        for movie in data.movies {
            switch movie.aspectratio {
                case .ACADEMY: print("academy")
                case .WIDESCREEN: print("widescreen")
                case .ANAMORPHIC: print("anamorphic")
                case ._UNKNOWN(let unknownAspect): print(unknownAspect)
            }
        }
    }
} catch {
    // handle error
}

Clientseitiges Caching aktivieren

Data Connect bietet eine optionale clientseitige Caching-Funktion, die Sie durch Bearbeiten der Datei connector.yaml aktivieren können. Wenn diese Funktion aktiviert ist, werden die generierten Client-SDKs Antwortdaten lokal im Cache speichern. Dadurch kann die Anzahl der Datenbankanfragen, die von Ihrer App gesendet werden, reduziert werden. Außerdem können die datenbankabhängigen Teile Ihrer App auch dann funktionieren, wenn die Netzwerkverfügbarkeit unterbrochen wird.

Wenn Sie das clientseitige Caching aktivieren möchten, fügen Sie Ihrer Connector-Konfiguration eine Client-Caching-Konfiguration hinzu:

generate:
  swiftSdk:
    outputDir: "../ios"
    package: "FirebaseDataConnectGenerated"
    clientCache:
      maxAge: 5s
      storage: persistent

Diese Konfiguration hat zwei Parameter, die beide optional sind:

• maxAge: Das maximale Alter einer im Cache gespeicherten Antwort, bevor das Client-SDK neue Werte abruft. Beispiele: „0“, „30s“, „1h30m“

  Der Standardwert für maxAge ist 0. Das bedeutet, dass Antworten zwischengespeichert werden, das Client-SDK aber immer aktuelle Werte abruft. Die im Cache gespeicherten Werte werden nur verwendet, wenn CACHE_ONLY auf execute() festgelegt ist.

• storage: Das Client-SDK kann so konfiguriert werden, dass Antworten entweder im persistent-Speicher oder in memory zwischengespeichert werden. Im persistent-Speicher zwischengespeicherte Ergebnisse bleiben auch nach Neustarts der App erhalten. In iOS SDKs ist der Standardwert persistent.

Nachdem Sie die Caching-Konfiguration Ihres Connectors aktualisiert haben, müssen Sie Ihre Client-SDKs neu generieren und Ihre App neu erstellen. Danach werden in execute() Antworten gemäß der von Ihnen konfigurierten Richtlinie im Cache gespeichert und gecachte Werte verwendet. Das geschieht in der Regel automatisch, ohne dass Sie dafür noch etwas zu tun brauchen. Beachten Sie jedoch Folgendes:

• Das Standardverhalten von execute() ist wie oben beschrieben: Wenn ein Ergebnis für eine Abfrage im Cache gespeichert ist und der Cachewert nicht älter als maxAge ist, wird der Cachewert verwendet. Dieses Standardverhalten wird als PREFER_CACHE-Richtlinie bezeichnet.

  Sie können auch für einzelne Aufrufe von execute() angeben, ob nur Werte aus dem Cache bereitgestellt werden sollen (CACHE_ONLY) oder ob bedingungslos neue Werte vom Server abgerufen werden sollen (SERVER_ONLY).

  try await execute(fetchPolicy: .cacheOnly)
  

  try await execute(fetchPolicy: .serverOnly)
  

  Prototyp Ihrer iOS-Anwendung erstellen 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. Sie werden im SDK so dargestellt:

  Data Connect-Typ	Swift
  String	String
  Integer	Integer
  Float	Doppelt
  Boolesch	Bool
  UUID	UUID
  Datum	FirebaseDataConnect.LocalDate
  Zeitstempel	FirebaseCore.Timestamp
  INT64	INT64
  Beliebig	FirebaseDataConnect.AnyValue