Mit Firebase SQL Connect-Client-SDKs können Sie Ihre serverseitigen Abfragen und Mutationen direkt aus einer Firebase-App aufrufen. Sie generieren ein benutzerdefiniertes Client-SDK parallel zum Entwerfen 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 an anderer Stelle 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 wie Cloud Functions auf dem Server gespeichert. Das bedeutet, dass Sie entsprechende clientseitige Änderungen bereitstellen müssen, um Probleme bei bestehenden Nutzern (z. B. bei älteren App-Versionen) zu vermeiden.
Deshalb bietet SQL Connect Ihnen eine Entwicklungsumgebung und Tools, mit denen Sie Prototypen Ihrer auf dem Server bereitgestellten Schemas, Abfragen und Mutationen erstellen können. Außerdem werden während des Prototypings automatisch clientseitige SDKs generiert.
Wenn Sie die Updates für Ihre Dienst- und Client-Apps iteriert haben, können sowohl die serverseitigen als auch die clientseitigen Updates bereitgestellt werden.
Wie sieht der Workflow für die Cliententwicklung aus?
Wenn Sie die Erste Schritte-Anleitung befolgt haben, haben Sie den allgemeinen Entwicklungsablauf für SQL Connect kennengelernt. In diesem Leitfaden finden Sie detailliertere Informationen zum Generieren von Android SDKs aus Ihrem Schema und zum Arbeiten mit Clientabfragen und ‑mutationen.
Zusammenfassend sind die folgenden Schritte erforderlich, um generierte Android SDKs in Ihren Client-Apps zu verwenden:
- Fügen Sie Firebase zu Ihrer Android-App hinzu.
- Konfigurieren Sie SQL Connect als Abhängigkeit in Gradle.
- Fügen Sie das Gradle-Plug-in für die Kotlin-Serialisierung und die Gradle-Abhängigkeit hinzu.
Gehen Sie anschließend so vor:
- Entwickeln Sie Ihr App-Schema.
SDK-Generierung einrichten:
- Mit dem Button SDK zu App hinzufügen in unserer SQL Connect VS Code-Erweiterung
connector.yamlaktualisieren
SQL Connect-Emulator einrichten und verwenden und iterieren.
Kotlin SDK generieren
Verwenden Sie die Firebase-Befehlszeile, um von SQL Connect generierte SDKs in Ihren Anwendungen einzurichten.
Der Befehl init sollte alle Apps im aktuellen Ordner erkennen und generierte SDKs automatisch installieren.
firebase init dataconnect:sdk
SDKs beim Erstellen von Prototypen aktualisieren
Wenn Sie die VS Code-Erweiterung für SQL Connect installiert haben, werden die generierten SDKs immer auf dem neuesten Stand gehalten.
Wenn Sie die VS Code-Erweiterung SQL Connect nicht verwenden, können Sie die Firebase CLI verwenden, um generierte SDKs auf dem neuesten Stand zu 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:generateClientcode einrichten
SQL Connect in den Clientcode einbinden
Wenn Sie Ihren Clientcode für die Verwendung von SQL Connect und dem generierten SDK einrichten möchten, folgen Sie zuerst der Standardanleitung für die Firebase-Einrichtung.
Fügen Sie dann Folgendes in den Abschnitt plugins in app/build.gradle.kts ein:
// The Firebase team tests with version 1.8.22; however, other 1.8 versions,
// and all newer versions are expected work too.
kotlin("plugin.serialization") version "1.8.22" // MUST match the version of the Kotlin compiler
Fügen Sie dann Folgendes in den Abschnitt dependencies in app/build.gradle.kts ein:
implementation(platform("com.google.firebase:firebase-bom:35.0.1"))
implementation("com.google.firebase:firebase-dataconnect")
implementation("com.google.firebase:firebase-auth") // Optional
implementation("com.google.firebase:firebase-appcheck") // Optional
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3") // Newer versions should work too
implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1") // Newer versions should work too
SQL Connect Android 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 und Speicher > SQL Connect.
Das ConnectorConfig-Objekt
Das SDK erfordert ein Connector-Konfigurationsobjekt.
Dieses Objekt wird automatisch aus serviceId und location in dataconnect.yaml sowie connectorId in connector.yaml generiert.
Connector-Instanz abrufen
Nachdem Sie ein Konfigurationsobjekt eingerichtet haben, rufen Sie eine SQL Connect-Connector-Instanz ab. Der Code für Ihren Connector wird vom SQL Connect-Emulator generiert. Wenn der Name Ihres Connectors movies und das Kotlin-Paket com.myapplication ist, wie in connector.yaml angegeben, rufen Sie das Connector-Objekt so ab:
val connector = com.myapplication.MoviesConnector.instance
Abfragen und Mutationen aus Ihrem Android SDK verwenden
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
}
}
können Sie einen Film so erstellen und abrufen:
val connector = MoviesConnector.instance
val addMovieResult1 = connector.createMovie.execute(
title = "Empire Strikes Back",
releaseYear = 1980,
genre = "Sci-Fi",
rating = 5
)
val movie1 = connector.getMovieByKey.execute(addMovieResult1.data.key)
println("Empire Strikes Back: ${movie1.data.movie}")
Sie können auch mehrere Filme abrufen:
val connector = MoviesConnector.instance
val addMovieResult2 = connector.createMovie.execute(
title="Attack of the Clones",
releaseYear = 2002,
genre = "Sci-Fi",
rating = 5
)
val listMoviesResult = connector.listMoviesByGenre.execute(genre = "Sci-Fi")
println(listMoviesResult.data.movies)
Sie können auch ein Flow erfassen, das nur dann ein Ergebnis liefert, wenn ein neues Abfrageergebnis über einen Aufruf der execute()-Methode der Abfrage abgerufen wird.
val connector = MoviesConnector.instance
connector.listMoviesByGenre.flow(genre = "Sci-Fi").collect { data ->
println(data.movies)
}
connector.createMovie.execute(
title="A New Hope",
releaseYear = 1977,
genre = "Sci-Fi",
rating = 5
)
connector.listMoviesByGenre.execute(genre = "Sci-Fi") // will cause the Flow to get notified
Echtzeitänderungen abonnieren
Weitere Informationen finden Sie unter Echtzeit-Updates von SQL Connect erhalten.
Umgang mit Änderungen an Aufzählungsfeldern
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 möchten später im Lebenszyklus Ihrer Anwendung den Wert FULLSCREEN zum Enum AspectRatio hinzufügen.
Im SQL 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, können ältere bereitgestellte Clients fehlerhaft sein.
Beispiel für eine ausfallsichere Implementierung
Das generierte SDK erzwingt die Verarbeitung unbekannter Werte, da der Code des Kunden das EnumValue-Objekt entpacken muss. Dieses ist entweder EnumValue.Known für bekannte Enum-Werte oder EnumValue.Unknown für unbekannte Werte.
val result = connector.listMoviesByAspectRatio.execute(AspectRatio.WIDESCREEN)
val encounteredAspectRatios = mutableSetOf<String>()
result.data.movies
.mapNotNull { it.otherAspectRatios }
.forEach { otherAspectRatios ->
otherAspectRatios
.filterNot { it.value == AspectRatio.WIDESCREEN }
.forEach {
when (it) {
is EnumValue.Known -> encounteredAspectRatios.add(it.value.name)
is EnumValue.Unknown ->
encounteredAspectRatios.add("[unknown ratio: ${it.stringValue}]")
}
}
}
println(
"Widescreen movies also include additional aspect ratios: " +
encounteredAspectRatios.sorted().joinToString()
)
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 die Abfrageantworten lokal im Cache speichern. Dadurch kann die Anzahl der Datenbankanfragen Ihrer App reduziert werden und die datenbankabhängigen Teile Ihrer App können auch dann funktionieren, wenn die Netzwerkverfügbarkeit unterbrochen ist.
Wenn Sie das clientseitige Caching aktivieren möchten, fügen Sie Ihrer Connector-Konfiguration eine Client-Caching-Konfiguration hinzu:
generate:
kotlinSdk:
outputDir: "../android"
package: "com.google.firebase.dataconnect.generated"
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 im Cache gespeichert 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 inmemoryim Cache gespeichert werden. Impersistent-Speicher im Cache gespeicherte Ergebnisse bleiben auch nach einem Neustart der App erhalten. In Android SDKs ist der Standardwertpersistent.
Nachdem Sie die Caching-Konfiguration Ihres Connectors aktualisiert haben, generieren Sie Ihre Client-SDKs neu und erstellen Sie Ihre Anwendung neu. Danach speichert execute() Antworten im Cache und verwendet die im Cache gespeicherten Werte gemäß der von Ihnen konfigurierten Richtlinie. Dies geschieht in der Regel automatisch, ohne dass Sie zusätzliche Schritte ausführen 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 im Cache gespeicherte Wert nicht älter alsmaxAgeist, wird der im Cache gespeicherte Wert verwendet. Dieses Standardverhalten wird alsPREFER_CACHE-Richtlinie bezeichnet.Sie können auch für einzelne Aufrufe von
execute()angeben, dass entweder nur im Cache gespeicherte Werte (CACHE_ONLY) bereitgestellt oder bedingungslos neue Werte vom Server (SERVER_ONLY) abgerufen werden sollen.val queryResult = queryRef.execute(QueryRef.FetchPolicy.CACHE_ONLY)val queryResult = queryRef.execute(QueryRef.FetchPolicy.SERVER_ONLY)Android-App prototypisieren und testen
Clients für die Verwendung eines lokalen Emulators instrumentieren
Sie können den SQL Connect-Emulator entweder über die VS Code-Erweiterung von SQL Connect oder über die Befehlszeile verwenden.
Die Instrumentierung der App für die Verbindung mit dem Emulator ist für beide Szenarien gleich.
val connector = MoviesConnector.instance // Connect to the emulator on "10.0.2.2:9399" connector.dataConnect.useEmulator() // (alternatively) if you're running your emulator on non-default port: connector.dataConnect.useEmulator(port = 9999) // Make calls from your appWenn Sie zu Produktionsressourcen wechseln möchten, kommentieren Sie die Zeilen für die Verbindung zum Emulator aus.
SQL-Typen in SQL Connect SDKs
Der SQL Connect-Server stellt gängige und benutzerdefinierte GraphQL-Datentypen dar. Diese werden im SDK so dargestellt:
SQL Connect-Typ Kotlin String String Integer Int (32-Bit-Ganzzahl) Float Double (64-Bit-Gleitkommazahl) Boolesch Boolesch UUID java.util.UUID Datum com.google.firebase.dataconnect.LocalDate (bis 16.0.0-beta03 java.util.Date) Zeitstempel com.google.firebase.Timestamp Int64 Lang Beliebig com.google.firebase.dataconnect.AnyValue