Mit den Firebase SQL 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 in Ihrem SQL 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 SQL Connect-Abfragen und ‑Mutationen nicht vom Clientcode gesendet und auf dem Server ausgeführt werden. Stattdessen werden SQL 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.
SQL 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.
Nachdem Sie die Updates für Ihre Dienst- und Client-Apps durchlaufen haben, können sowohl serverseitige als auch clientseitige Updates bereitgestellt werden.
Wie sieht der Workflow für die Client-Entwicklung aus?
Wenn Sie die Kurzanleitung durchgearbeitet haben, kennen Sie den allgemeinen Entwicklungsablauf für SQL Connect. In diesem Leitfaden 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:
- Fügen Sie Firebase zu Ihrer iOS-App hinzu.
Wenn Sie das generierte SDK verwenden möchten, müssen Sie es in Xcode als Abhängigkeit konfigurieren.
Wählen Sie in der oberen Navigationsleiste von Xcode File > Add Package Dependencies > Add Local aus und wählen Sie den Ordner mit dem generierten
Package.swiftaus.
Gehen Sie anschließend so vor:
- App-Schema entwickeln
SDK-Generierung einrichten:
- Mit dem Button SDK zur App hinzufügen in unserer VS Code-Erweiterung für SQL Connect
- Aktualisieren Sie Ihr
connector.yaml.
SQL Connect-Emulator einrichten und verwenden und Iterationen durchführen.
Swift-SDK generieren
Verwenden Sie die Firebase-Befehlszeile, um von SQL 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 SQL Connect-VS Code-Erweiterung installiert haben, werden generierte SDKs immer auf dem neuesten Stand gehalten.
Wenn Sie die SQL 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 --watchSDKs in Build-Pipelines generieren
Sie können die Firebase CLI verwenden, um SQL Connect-SDKs in CI/CD-Build-Prozessen zu generieren.
firebase dataconnect:sdk:generateSQL Connect iOS SDK initialisieren
Initialisieren Sie Ihre SQL Connect-Instanz mit den Informationen, die Sie zum Einrichten von SQL Connect verwendet haben. Diese Informationen finden Sie in der Firebase-Konsole auf der Seite Datenbanken & Speicher > SQL Connect.
Connector-Instanz abrufen
Der Code für Ihren Connector wird vom SQL Connect-Emulator generiert. Wenn der Name Ihres Connectors movies und das Paket movies ist, wie in connector.yaml angegeben, rufen Sie das Connector-Objekt 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 Abfragereferenz. 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 nichts angegeben ist, 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.
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 abonnieren
Weitere Informationen finden Sie unter Echtzeitupdates von SQL Connect erhalten.
Änderungen an Aufzählungsfeldern 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 SQL Connect-Workflow können Sie lokale Entwicklungstools verwenden, um Ihre Abfragen und SDKs zu aktualisieren.
Wenn Sie jedoch eine aktualisierte Version Ihrer Clients veröffentlichen, funktionieren ältere bereitgestellte Clients möglicherweise nicht mehr.
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
SQL 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 Ihrer App reduziert werden. Außerdem können die datenbankabhängigen Teile Ihrer App auch dann ausgeführt werden, 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
maxAgeist0. Das bedeutet, dass Antworten zwischengespeichert werden, das Client-SDK aber immer aktuelle Werte abruft. Die im Cache gespeicherten Werte werden nur verwendet, wennCACHE_ONLYaufexecute()festgelegt ist.storage: Das Client-SDK kann so konfiguriert werden, dass Antworten entweder impersistent-Speicher oder inmemoryzwischengespeichert werden. Impersistent-Speicher zwischengespeicherte Ergebnisse bleiben auch nach einem Neustart der App erhalten. In iOS-SDKs ist der Standardwertpersistent.
Nachdem Sie die Caching-Konfiguration Ihres Connectors aktualisiert haben, müssen Sie die 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 weitere Schritte unternehmen müssen. 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 alsmaxAgeist, wird der Cachewert verwendet. Dieses Standardverhalten wird alsPREFER_CACHE-Richtlinie bezeichnet.Sie können auch für einzelne Aufrufe von
execute()angeben, ob nur im Cache gespeicherte Werte bereitgestellt (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
Sie können den lokalen Emulator verwenden, um Ihre Anwendung zu testen und Prototypen zu erstellen.
Clients für die Verwendung eines lokalen Emulators instrumentieren
Sie können den SQL Connect-Emulator entweder über die VS Code-Erweiterung „SQL Connect“ oder über die CLI verwenden.
Die Instrumentierung der App für die Verbindung zum Emulator ist in beiden Szenarien gleich.
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 appDatentypen in SQL Connect-SDKs
Der SQL Connect-Server stellt allgemeine und benutzerdefinierte GraphQL-Datentypen dar. Im SDK werden sie so dargestellt:
SQL Connect-Typ Swift String String Integer Integer Float Doppelt Boolesch Bool UUID UUID Datum FirebaseDataConnect.LocalDate Zeitstempel FirebaseCore.Timestamp Int64 Int64 Beliebig FirebaseDataConnect.AnyValue