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 sur votre service Data Connect. Vous intégrez ensuite les méthodes de ce SDK dans votre logique client.
Comme nous l'avons indiqué ailleurs, il est important de noter que les requêtes et les mutations Data Connect ne sont pas envoyées par le code client et exécutées sur le serveur. Au lieu de cela, lors du déploiement, 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 créer des prototypes de 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 le prototypage.
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.
Générer votre SDK Swift
Comme pour la plupart des projets Firebase, le travail sur le code client Firebase Data Connect se déroule dans un répertoire de projet local. L'extension VS Code Data Connect et la CLI Firebase sont tous deux des outils locaux importants pour générer et gérer le code client.
Les options de génération de SDK sont associées à plusieurs entrées dans le fichier dataconnect.yaml généré lorsque vous avez initialisé 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:
swiftSdk:
outputDir: "../movies-generated"
package: "Movies"
outputDir spécifie l'emplacement où le SDK généré doit être généré. Si aucun répertoire de sortie n'est spécifié, le dossier du connecteur est utilisé comme répertoire de sortie par défaut.
package spécifie le nom du package qui sera généré. Le générateur crée un dossier portant le nom du package, contenant Package.swift et le code généré.
observablePublisher (facultatif) spécifie l'éditeur Observable à utiliser dans les références de requête. Les valeurs possibles sont observableMacro (iOS 17 et versions ultérieures) et observableObject (version antérieure à iOS 17). Si aucune valeur n'est spécifiée, la valeur par défaut est observableMacro.
Mettre à jour les SDK lors du prototypage
Si vous effectuez un prototypage interactif avec l'extension Data Connect pour VS Code 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 qui définissent les schémas, les requêtes et les mutations. Cette fonctionnalité peut s'avérer utile dans les workflows de (re)chargement à chaud.
.gql et mettre à jour automatiquement les sources du SDK.
Vous pouvez également utiliser la CLI pour regénérer les SDK chaque fois que des fichiers .gql sont modifiés:
firebase dataconnect:sdk:generate --watch
Générer des SDK pour l'intégration et les versions de production
Dans certains cas, par exemple lorsque vous préparez les sources de projet à envoyer pour les tests de CI, vous pouvez appeler la CLI Firebase pour une mise à jour par lot.
Dans ce cas, utilisez firebase dataconnect:sdk:generate.
Configurer le code client
Pour configurer votre code client pour utiliser Data Connect et votre SDK généré, suivez d'abord les instructions de configuration standards de Firebase.
Ouvrez ensuite votre espace de travail d'applications à l'aide de Xcode.
Dans la barre de navigation supérieure, sélectionnez File > Add Package Dependencies > Add Local (Fichier > Ajouter des dépendances de package > Ajouter local), puis choisissez le dossier contenant le fichier source Package.swift généré.
Initialiser le SDK iOS 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).
Obtenir une instance de connecteur
Le code de votre connecteur sera généré par l'émulateur Data Connect. Si le nom de votre connecteur est movies et que le package est movies, comme spécifié dans connector.yaml, récupérez l'objet du connecteur en appelant:
let connector = DataConnect.moviesConnector
Exécuter des requêtes et des mutations
Avec l'objet connecteur, vous pouvez exécuter des requêtes et des mutations comme défini dans le code source GraphQL. Supposons que les opérations suivantes soient définies pour votre connecteur:
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 un film comme suit:
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)")
Pour récupérer un film, vous devez utiliser une référence de requête. Toutes les références de requête sont des éditeurs observables. Selon l'éditeur configuré (voir connector.yaml)), il est compatible avec la macro @Observable (iOS 17 et versions ultérieures) ou implémente le protocole ObservableObject. Si aucune valeur n'est spécifiée, la valeur par défaut est la macro @Observable compatible avec iOS 17 et versions ultérieures.
Dans une vue SwiftUI, vous pouvez lier les résultats de la requête à l'aide de la variable data publiée de la référence de la requête et appeler la méthode execute() de la requête pour mettre à jour les données. La variable data correspond à la forme des données définies dans la définition de votre requête GQL.
Tous les résultats récupérés respectent le protocole Decodable. Si vous avez inclus la clé primaire de l'objet dans votre récupération GQL, les objets sont également Identifiable, ce qui vous permet de les utiliser dans des itérateurs.
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()
}
}
Les requêtes acceptent également l'exécution unique.
let resultData = try await DataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre: "Sci-Fi")
Créer un prototype et tester votre application iOS
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 la connecter à l'émulateur est la même dans les deux scénarios.
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 app
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 de connexion Data Connect | Swift |
|---|---|
| Chaîne | Chaîne |
| Int | Int |
| Float | Double |
| Booléen | Bool |
| UUID | UUID |
| Date | FirebaseDataConnect.LocalDate |
| Horodatage | FirebaseCore.Timestamp |
| Int64 | Int64 |
| Tous | FirebaseDataConnect.AnyValue |