Les SDK client Firebase Data Connect vous permettent d'appeler vos requêtes et mutations côté serveur directement depuis une application Firebase. Vous générez un SDK client personnalisé en parallèle de la conception des schémas, des requêtes et des mutations que vous déployez sur votre service Firebase Data Connect.Data Connect 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 requêtes et les mutations Data Connectne sont pas envoyées par le code client et exécutées sur le serveur. En revanche, une fois déployées, les opérations Data Connect 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 votre prototype.
Une fois que vous avez effectué des mises à jour itératives de vos applications de service et client, les mises à jour côté serveur et côté client sont prêtes à être déployées.
Qu'est-ce que le workflow de développement client ?
Si vous avez suivi la section Premiers pas, vous avez découvert le flux de développement global pour Data Connect. Dans ce guide, vous trouverez des informations plus détaillées sur la génération de SDK Flutter à partir de votre schéma, ainsi que sur l'utilisation des requêtes et mutations client.
En résumé, pour utiliser les SDK Flutter générés dans vos applications clientes, vous devez suivre les étapes préalables suivantes :
- Ajoutez Firebase à votre application Flutter.
- Installez la CLI flutterfire
dart pub global activate flutterfire_cli. - Exécutez
flutterfire configure.
Puis :
- Développez le schéma de votre application.
Configurez la génération du SDK :
- Avec le bouton Ajouter le SDK à l'application de notre extension VS Code Data Connect
- En mettant à jour votre
connector.yaml.
Initialisez votre code client et importez les bibliothèques.
Configurez et utilisez l'émulateur Data Connect, puis itérez.
Générer votre SDK Flutter
Comme pour la plupart des projets Firebase, le code client Firebase Data Connect est développé dans un répertoire de projet local. L'extension VS Code Data Connect et la CLI Firebase sont des outils locaux importants pour générer et gérer le code client.
Les options de génération du SDK sont associées à plusieurs entrées du fichier dataconnect.yaml généré lors de l'initialisation de votre projet.
Initialiser la génération du SDK
Dans votreconnector.yaml, ajoutez vos outputDir, package et (pour le SDK Web) packageJsonDir.
connectorId: movies
generate:
dartSdk:
outputDir: ../../lib/generated # Feel free to change this to a different path
package: movies
outputDir indique l'emplacement où le SDK généré doit être placé. Ce chemin d'accès est relatif au répertoire contenant le fichier connector.yaml lui-même.
Si vous le souhaitez, vous pouvez fournir un chemin absolu vers votre outputDir.
package spécifie le nom du package.
Mettre à jour les SDK lors du prototypage
Si vous créez des prototypes de manière interactive avec l'extension VS Code Data Connect et son émulateur Data Connect, les fichiers sources du SDK sont automatiquement générés et mis à jour lorsque vous modifiez les fichiers .gql définissant les schémas, les requêtes et les mutations. Cette fonctionnalité peut être utile dans les workflows de rechargement à chaud.
.gql et faire en sorte que les sources du SDK soient également mises à jour automatiquement.
Vous pouvez également utiliser l'interface de ligne de commande pour régénérer les SDK chaque fois que des fichiers .gql sont modifiés :
firebase dataconnect:sdk:generate --watchGénérez des SDK pour l'intégration et pour les versions de production.
Dans certains cas, par exemple lorsque vous préparez des sources de projet à envoyer pour des tests CI, vous pouvez appeler l'interface de ligne de commande Firebase pour une mise à jour par lot.
Dans ce cas, utilisez firebase dataconnect:sdk:generate.
Configurer le code client
Initialiser votre application Data Connect
Commencez par initialiser votre application en suivant les instructions de configuration Firebase standards.
Ensuite, installez le plug-in Data Connect :
flutter pub add firebase_data_connectInitialiser le SDK Flutter Data Connect
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).
Importer des bibliothèques
Deux ensembles d'importations sont nécessaires pour initialiser votre code client : les importations générales Data Connect et les importations spécifiques du SDK généré.
// general imports
import 'package:firebase_data_connect/firebase_data_connect.dart';
// generated queries and mutations from SDK
import 'generated/movies.dart';
Utiliser des requêtes côté client
Le code généré inclura déjà des références de requête prédéfinies. Il vous suffit de les importer et d'appeler execute sur eux.
import 'generated/movies.dart';
await MoviesConnector.instance.listMovies().execute();
Appeler les méthodes de requête du SDK
Voici un exemple d'utilisation de ces fonctions de raccourci d'action :
import 'generated/movies.dart';
function onBtnClick() {
// This will call the generated Dart from the CLI and then make an HTTP request to the server.
MoviesConnector.instance.listMovies().execute().then(data => showInUI(data)); // == MoviesConnector.instance.listMovies().ref().execute();
}
Champs facultatifs
Certaines requêtes peuvent comporter des champs facultatifs. Dans ce cas, le SDK Flutter expose une méthode de création et devra être défini séparément.
Par exemple, le champ rating est facultatif lors de l'appel de createMovie. Vous devez donc le fournir dans la fonction du compilateur.
await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi"}).rating(5).execute();
S'abonner aux modifications
Vous pouvez vous abonner aux modifications (qui seront mises à jour chaque fois que vous exécuterez une requête).
QueryRef<ListMoviesData, void> listRef = MoviesConnector.instance.listMovies().ref();
// subscribe will immediately invoke the query if no execute was called on it previously.
listRef.subscribe().listen((data) {
updateUIWithMovies(data.movies);
});
await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();
await listRef.execute(); // will update the subscription above`
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 change, vous pouvez ajouter de nouvelles valeurs d'énumération acceptées. Par exemple, imaginez que vous décidiez d'ajouter une valeur FULLSCREEN à l'énumération AspectRatio plus tard dans le cycle de vie de votre application.
Dans le workflow Data Connect, vous pouvez utiliser des outils de développement local pour mettre à jour vos requêtes et vos SDK.
Toutefois, avant de publier une version mise à jour de vos clients, il est possible que les anciens clients déployés ne fonctionnent plus.
Exemple d'implémentation résiliente
Le SDK généré force la gestion des valeurs inconnues. Autrement dit, le code client doit décompresser l'objet EnumValue en Known ou Unknown.
final result = await MoviesConnector.instance.listMovies().execute();
if (result.data != null && result.data!.isNotEmpty) {
handleEnumValue(result.data![0].aspectratio);
}
void handleEnumValue(EnumValue<AspectRatio> aspectValue) {
if (aspectValue.value != null) {
switch(aspectValue.value!) {
case AspectRatio.ACADEMY:
print("This movie is in Academy aspect");
break;
case AspectRatio.WIDESCREEN:
print("This movie is in Widescreen aspect");
break;
case AspectRatio.ANAMORPHIC:
print("This movie is in Anamorphic aspect");
break;
case AspectRatio.IMAX:
print("This movie is in IMAX aspect");
}
} else {
print("Unknown aspect ratio detected: ${aspectValue.stringValue}");
}
}
Utiliser des mutations côté client
Les mutations sont accessibles de la même manière que les requêtes.
await MoviesConnector.instance.createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi" }).rating(5).execute();
Prototyper et tester vos applications Flutter
Instrumenter les clients pour qu'ils utilisent un émulateur local
Vous pouvez utiliser l'émulateur Data Connect, que ce soit à partir de l'extension VS Code Data Connect ou de la CLI.
L'instrumentation de l'application pour se connecter à l'émulateur est la même dans les deux scénarios.
import 'package:firebase_data_connect/firebase_data_connect.dart';
import 'generated/movies.dart';
MoviesConnector.instance.dataConnect
.useDataConnectEmulator('127.0.0.1', 9399);
// Make calls from your app
QueryRef<ListMoviesData, void> ref = MoviesConnector.instance.listMovies.ref();
Pour passer aux ressources de production, mettez en commentaire les lignes de connexion à l'émulateur.
Types de données dans le SDK Dart
Le serveur Data Connect représente les types de données GraphQL courants. Elles sont représentées dans le SDK comme suit.
| Type de connexion de données | Dart |
|---|---|
| Horodatage | firebase_data_connect.Timestamp |
| Int (32 bits) | int |
| Date | DateTime |
| UUID | chaîne |
| Int64 | int |
| Float | double |
| Booléen | Bool |
| Tous | firebase_data_connect.AnyValue |