Les SDK client Firebase Data Connect vous permettent d'appeler vos requêtes et mutations côté serveur directement à partir d'une application Firebase. Vous générez un SDK client personnalisé en parallèle lorsque vous concevez les schémas, les requêtes et les mutations que vous déployez dans votre Data Connect service. Ensuite, vous intégrez les méthodes de ce SDK dans votre logique client.
Comme nous l'avons mentionné ailleurs, il est important de noter que les Data Connect requêtes et les mutations ne sont pas envoyées par le code client et exécutées sur le serveur. Au lieu de cela, une fois déployées, Data Connect opérations sont stockées sur le serveur comme Cloud Functions. Cela signifie que vous devez déployer les modifications côté client correspondantes pour éviter de perturber les utilisateurs existants (par exemple, sur les anciennes versions de l'application).
C'est pourquoi Data Connect vous fournit un environnement de développement et des outils qui vous permettent de prototyper vos schémas, requêtes et mutations déployés sur le serveur. Il génère également automatiquement des SDK côté client pendant que vous créez des prototypes.
Une fois que vous avez itéré les mises à jour de votre service et de vos applications clientes, les mises à jour côté serveur et côté client sont prêtes à être déployées.
Quel est le workflow de développement client ?
Si vous avez suivi la section Premiers pas, vous avez découvert le flux de développement global de Data Connect. Dans ce guide, vous trouverez des informations plus détaillées sur la génération de SDK Android à partir de votre schéma, ainsi que sur l'utilisation des requêtes et des mutations client.
En résumé, pour utiliser les SDK Android générés dans vos applications clientes, vous devez suivre les étapes préalables suivantes :
- Ajoutez Firebase à votre application Android.
- Configurez Data Connect en tant que dépendance dans Gradle.
- Ajoutez le plug-in Gradle de sérialisation Kotlin et la dépendance Gradle.
Puis :
- Développez le schéma de votre application.
Configurez la génération du SDK :
- Avec le bouton Add SDK to app (Ajouter le SDK à l'application) de notre extension Data Connect VS Code
- En mettant à jour votre
connector.yaml
Initialisez votre code client et importez des bibliothèques.
Générez votre SDK Kotlin
Utilisez la CLI Firebase pour configurer les SDK générés par Data Connect dans vos applications.
La commande init doit détecter toutes les applications du dossier actuel et installer automatiquement les SDK générés.
firebase init dataconnect:sdk
Mettre à jour les SDK lors de la création de prototypes
Si l'extension Data Connect VS Code est installée, elle maintient toujours les SDK générés à jour.
Si vous n'utilisez pas l'extension Data Connect VS Code, vous pouvez utiliser la CLI Firebase pour maintenir les SDK générés à jour.
firebase dataconnect:sdk:generate --watchGénérer des SDK dans des pipelines de compilation
Vous pouvez utiliser la CLI Firebase pour générer des Data Connect SDK dans les processus de compilation CI/CD.
firebase dataconnect:sdk:generateConfigurer le code client
Intégrer Data Connect à votre code client
Pour configurer votre code client afin qu'il utilise Data Connect et votre SDK généré, suivez d'abord les instructions de configuration Firebase standards.
Ajoutez ensuite les éléments suivants à la section plugins de 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
Ajoutez ensuite les éléments suivants à la section dependencies de app/build.gradle.kts :
implementation(platform("com.google.firebase:firebase-bom:34.11.0"))
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
Initialiser le Data Connect SDK Android
Initialisez votre instance Data Connect à l'aide des informations que vous avez utilisées pour configurer Data Connect (toutes disponibles dans l'onglet Data Connect de la console Firebase).
L'objet ConnectorConfig
Le SDK nécessite un objet de configuration de connecteur.
Cet objet est généré automatiquement à partir de serviceId et location dans dataconnect.yaml, et de connectorId dans connector.yaml.
Obtenir une instance de connecteur
Maintenant que vous avez configuré un objet de configuration, obtenez une instance de connecteur Data Connect. Le code de votre connecteur sera généré par l'
Data Connect émulateur. Si le nom de votre connecteur est movies et que le package Kotlin est com.myapplication, comme spécifié dans connector.yaml, récupérez l'objet connecteur en appelant :
val connector = com.myapplication.MoviesConnector.instance
Utiliser des requêtes et des mutations à partir de votre SDK Android
Avec l'objet connecteur, vous pouvez exécuter des requêtes et des mutations telles que définies dans le code source GraphQL. Supposons que votre connecteur comporte les opérations suivantes :
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
}
}
Vous pouvez ensuite créer et récupérer un film comme suit :
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}")
Vous pouvez également récupérer plusieurs films :
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)
Vous pouvez également collecter un Flow qui ne produira un résultat que lorsqu'un nouveau résultat de requête sera récupéré à l'aide d'un appel à la méthode execute() de la requête.
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
Gérer les modifications apportées aux champs d'énumération
Le schéma d'une application peut contenir des énumérations, auxquelles vos requêtes GraphQL peuvent accéder.
À mesure que la conception d'une application évolue, vous pouvez ajouter de nouvelles valeurs compatibles avec l'énumération. Par exemple, imaginez que plus tard dans le cycle de vie de votre application, vous décidez d'ajouter une valeur FULLSCREEN à l'énumération AspectRatio.
Dans le workflow Data Connect, vous pouvez utiliser des outils de développement locaux pour mettre à jour vos requêtes et vos SDK.
Toutefois, avant de publier une version mise à jour de vos clients, les anciens clients déployés peuvent cesser de fonctionner.
Exemple d'implémentation résiliente
Le SDK généré force la gestion des valeurs inconnues, car le code du client doit
décompresser l'objet EnumValue, qui est soit EnumValue.Known pour les valeurs d'énumération
connues, soit EnumValue.Unknown pour les valeurs inconnues.
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()
)
Activer la mise en cache côté client
Data Connect dispose d'une fonctionnalité de mise en cache côté client facultative, que vous
pouvez activer en modifiant le fichier connector.yaml. Lorsque cette fonctionnalité est activée, les SDK client générés mettent en cache localement les réponses aux requêtes, ce qui peut réduire le nombre de requêtes de base de données effectuées par votre application et permettre aux parties de votre application dépendantes de la base de données de fonctionner lorsque la disponibilité du réseau est interrompue.
Pour activer la mise en cache côté client, ajoutez une configuration de mise en cache client à la configuration de votre connecteur :
generate:
kotlinSdk:
outputDir: "../android"
package: "com.google.firebase.dataconnect.generated"
clientCache:
maxAge: 5s
storage: persistent
Cette configuration comporte deux paramètres, tous deux facultatifs :
maxAge: âge maximal qu'une réponse mise en cache peut avoir avant que le SDK client ne récupère de nouvelles valeurs. Exemples : "0", "30s", "1h30m".La valeur par défaut de
maxAgeest0, ce qui signifie que les réponses sont mises en cache, mais que le SDK client récupère toujours de nouvelles valeurs. Les valeurs mises en cache ne seront utilisées que lorsqueCACHE_ONLYest spécifié pourexecute().storage: le SDK client peut être configuré pour mettre en cache les réponses dans un stockagepersistentou dans lamemory. Les résultats mis en cache dans le stockagepersistentsont conservés lors des redémarrages de l'application. Dans les SDK Android, la valeur par défaut estpersistent.
Après avoir mis à jour la configuration de mise en cache de votre connecteur, régénérez vos SDK client
et recréez votre application. Une fois cette opération effectuée, execute()
mettra en cache
les réponses et utilisera les valeurs mises en cache conformément à la règle que vous avez configurée. Cela se produit généralement automatiquement, sans aucune autre action de votre part. Toutefois, notez les points suivants :
Le comportement par défaut de
execute()est décrit ci-dessus : si un résultat est mis en cache pour une requête et que la valeur mise en cache n'est pas plus ancienne quemaxAge, utilisez la valeur mise en cache. Ce comportement par défaut est appelé règlePREFER_CACHE.Vous pouvez également spécifier des appels individuels à
execute()pour ne diffuser que les valeurs mises en cache (CACHE_ONLY) ou pour récupérer sans condition de nouvelles valeurs à partir du serveur (SERVER_ONLY).val queryResult = queryRef.execute(QueryRef.FetchPolicy.CACHE_ONLY)val queryResult = queryRef.execute(QueryRef.FetchPolicy.SERVER_ONLY)Créer un prototype et tester votre application Android
Instrumenter les clients pour utiliser un émulateur local
Vous pouvez utiliser l'émulateur Data Connect, que ce soit à partir de l' extension Data Connect VS Code ou de la CLI.
L'instrumentation de l'application pour se connecter à l'émulateur est la même dans les deux cas.
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 appPour passer aux ressources de production, commentez les lignes de connexion à l'émulateur.
Types de données dans les SDK Data Connect
Le serveur Data Connect représente les types de données GraphQL courants et personnalisés. Ils sont représentés dans le SDK comme suit.
Type Data Connect Kotlin Chaîne String Int Int (entier 32 bits) Float Double (float 64 bits) Booléen Boolean UUID java.util.UUID Date com.google.firebase.dataconnect.LocalDate (était java.util.Date jusqu'à la version 16.0.0-beta03) Horodatage com.google.firebase.Timestamp Int64 Long Tous com.google.firebase.dataconnect.AnyValue