Gli SDK client Firebase SQL Connect ti consentono di chiamare le query e le mutazioni lato server direttamente da un'app Firebase. Generi un SDK client personalizzato in parallelo mentre progetti gli schemi, le query e le mutazioni di cui esegui il deployment nel tuo servizio SQL Connect. Poi, integra i metodi di questo SDK nella logica del client.
Come abbiamo già accennato, è importante notare che le query e le mutazioni di SQL Connect non vengono inviate dal codice client ed eseguite sul server. Invece, quando viene eseguito il deployment, le operazioni SQL Connect vengono archiviate sul server come Cloud Functions. Ciò significa che devi implementare le modifiche lato client corrispondenti per evitare di interrompere l'esperienza degli utenti esistenti (ad esempio, su versioni precedenti dell'app).
Ecco perché SQL Connect ti fornisce un ambiente di sviluppo e strumenti che ti consentono di creare prototipi di schemi, query e mutazioni di cui è stato eseguito il deployment sul server. Inoltre, genera automaticamente gli SDK lato client durante la prototipazione.
Dopo aver eseguito l'iterazione degli aggiornamenti delle app di servizio e client, gli aggiornamenti lato server e lato client sono pronti per il deployment.
Qual è il flusso di lavoro per lo sviluppo del client?
Se hai seguito la guida introduttiva, hai conosciuto il flusso di sviluppo generale per SQL Connect. In questa guida troverai informazioni più dettagliate sulla generazione di SDK Android dal tuo schema e sull'utilizzo di query e mutazioni client.
In sintesi, per utilizzare gli SDK Android generati nelle tue app client, devi seguire questi passaggi preliminari:
- Aggiungi Firebase alla tua app per Android.
- Configura SQL Connect come dipendenza in Gradle.
- Aggiungi il plug-in Kotlin Serialization per Gradle e la dipendenza Gradle.
Quindi:
- Sviluppa lo schema dell'app.
Configura la generazione dell'SDK:
- Con il pulsante Aggiungi SDK all'app nell'estensione SQL Connect per VS Code
- Aggiornando il tuo
connector.yaml
Configura e utilizza l'emulatore SQL Connect ed esegui l'iterazione.
Genera l'SDK Kotlin
Utilizza l'interfaccia a riga di comando Firebase per configurare gli SDK generati da SQL Connect nelle tue app.
Il comando init dovrebbe rilevare tutte le app nella cartella corrente e installare automaticamente gli SDK generati.
firebase init dataconnect:sdk
Aggiorna gli SDK durante la prototipazione
Se hai installato l'estensione VS Code di SQL Connect, gli SDK generati verranno sempre mantenuti aggiornati.
Se non utilizzi l'estensione SQL Connect per VS Code, puoi utilizzare l'interfaccia a riga di comando di Firebase per mantenere aggiornati gli SDK generati.
firebase dataconnect:sdk:generate --watchGenera SDK nelle pipeline di build
Puoi utilizzare l'interfaccia a riga di comando di Firebase per generare SDK SQL Connect nei processi di build CI/CD.
firebase dataconnect:sdk:generateConfigura il codice client
Incorpora SQL Connect nel codice client
Per configurare il codice client in modo da utilizzare SQL Connect e l'SDK generato, segui innanzitutto le istruzioni di configurazione standard di Firebase.
Poi, aggiungi quanto segue alla sezione plugins in app/build.gradle.kts:
// 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
Poi, aggiungi quanto segue alla sezione dependencies in app/build.gradle.kts:
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
Inizializza l'SDK Android SQL Connect
Inizializza l'istanza SQL Connect utilizzando le informazioni che hai utilizzato per configurare SQL Connect. Trova queste informazioni nella pagina Database e spazio di archiviazione > SQL Connect della console Firebase.
L'oggetto ConnectorConfig
L'SDK richiede un oggetto di configurazione del connettore.
Questo oggetto viene generato automaticamente da serviceId e location in
dataconnect.yaml e connectorId in connector.yaml.
Recupero di un'istanza del connettore
Ora che hai configurato un oggetto di configurazione, ottieni un'istanza del connettore SQL Connect. Il codice per il connettore verrà generato dall'emulatore SQL Connect. Se il nome del connettore è movies e il pacchetto Kotlin è com.myapplication, come specificato in connector.yaml, recupera l'oggetto connettore chiamando:
val connector = com.myapplication.MoviesConnector.instance
Utilizza query e mutazioni dall'SDK Android
Con l'oggetto connettore, puoi eseguire query e mutazioni come definito nel codice sorgente GraphQL. Supponiamo che il connettore abbia definito le seguenti operazioni:
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
}
}
puoi creare e recuperare un filmato come segue:
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}")
Puoi anche recuperare più filmati:
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)
Puoi anche raccogliere un Flow che produrrà un risultato solo quando viene recuperato un nuovo risultato della query utilizzando una chiamata al metodo execute() della query.
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
Iscriviti alle modifiche in tempo reale
Consulta Ricevi aggiornamenti in tempo reale da SQL Connect.
Gestisci le modifiche ai campi di enumerazione
Lo schema di un'app può contenere enumerazioni, a cui possono accedere le query GraphQL.
Man mano che il design di un'app cambia, puoi aggiungere nuovi valori supportati per l'enum. Ad esempio, immagina che in un secondo momento del ciclo di vita della tua applicazione decidi di aggiungere un valore FULLSCREEN all'enum AspectRatio.
Nel workflow SQL Connect, puoi utilizzare gli strumenti per sviluppatori locali per aggiornare le query e gli SDK.
Tuttavia, prima di rilasciare una versione aggiornata dei client, i client di cui è stato eseguito il deployment in precedenza potrebbero non funzionare.
Esempio di implementazione resiliente
L'SDK generato forza la gestione dei valori sconosciuti, poiché il codice del cliente deve eseguire l'unwrapping dell'oggetto EnumValue, che è EnumValue.Known per i valori enum noti o EnumValue.Unknown per i valori sconosciuti.
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()
)
Abilita la memorizzazione nella cache lato client
SQL Connect ha una funzionalità di memorizzazione nella cache lato client facoltativa, che puoi attivare modificando il file connector.yaml. Quando questa funzionalità è abilitata, gli SDK client generati memorizzano nella cache locale le risposte alle query, il che può ridurre il numero di richieste al database effettuate dalla tua app e consentire il funzionamento delle parti dell'app che dipendono dal database quando la disponibilità della rete viene interrotta.
Per attivare la memorizzazione nella cache lato client, aggiungi una configurazione di memorizzazione nella cache del client alla configurazione del connettore:
generate:
kotlinSdk:
outputDir: "../android"
package: "com.google.firebase.dataconnect.generated"
clientCache:
maxAge: 5s
storage: persistent
Questa configurazione ha due parametri, entrambi facoltativi:
maxAge: l'età massima che può avere una risposta memorizzata nella cache prima che l'SDK client recuperi i valori aggiornati. Esempi: "0", "30s", "1h30m".Il valore predefinito per
maxAgeè0, il che significa che le risposte vengono memorizzate nella cache, ma l'SDK client recupererà sempre i valori aggiornati. I valori memorizzati nella cache verranno utilizzati solo quandoCACHE_ONLYè impostato suexecute().storage: l'SDK client può essere configurato per memorizzare nella cache le risposte nello spazio di archiviazionepersistento inmemory. I risultati memorizzati nella cache dello spazio di archiviazionepersistentverranno mantenuti anche dopo il riavvio dell'app. Negli SDK Android, il valore predefinito èpersistent.
Dopo aver aggiornato la configurazione della memorizzazione nella cache del connettore, rigenera gli SDK client e ricrea l'app. Al termine, execute() memorizzerà nella cache le risposte e utilizzerà i valori memorizzati nella cache in base alla policy configurata. In genere, questo avviene automaticamente, senza ulteriori passaggi da parte tua. Tuttavia, tieni presente quanto segue:
Il comportamento predefinito di
execute()è quello descritto sopra: se un risultato viene memorizzato nella cache per una query e il valore memorizzato nella cache non è precedente amaxAge, utilizza il valore memorizzato nella cache. Questo comportamento predefinito è chiamato policyPREFER_CACHE.Puoi anche specificare per singole chiamate di
execute()di fornire solo valori memorizzati nella cache (CACHE_ONLY) o di recuperare incondizionatamente nuovi valori dal server (SERVER_ONLY).val queryResult = queryRef.execute(QueryRef.FetchPolicy.CACHE_ONLY)val queryResult = queryRef.execute(QueryRef.FetchPolicy.SERVER_ONLY)Crea un prototipo e testa la tua app per Android
Strumenta i client per utilizzare un emulatore locale
Puoi utilizzare l'emulatore SQL Connect, dall'estensione VS Code di SQL Connect o dalla CLI.
La strumentazione dell'app per la connessione all'emulatore è la stessa per entrambi gli scenari.
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 appPer passare alle risorse di produzione, commenta le righe per la connessione all'emulatore.
Tipi SQL negli SDK SQL Connect
Il server SQL Connect rappresenta i tipi di dati GraphQL comuni e personalizzati. Questi sono rappresentati nell'SDK come segue.
Tipo di SQL Connect Kotlin Stringa Stringa Int Int (numero intero a 32 bit) In virgola mobile Double (64-bit float) Booleano Booleano UUID java.util.UUID Data com.google.firebase.dataconnect.LocalDate (era java.util.Date fino alla versione 16.0.0-beta03) Timestamp com.google.firebase.Timestamp Int64 Lungo Qualsiasi com.google.firebase.dataconnect.AnyValue