Utiliser les SDK iOS générés

Les SDK client Firebase SQL 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 SQL 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 SQL 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, les SQL Connect opérations sont stockées sur le serveur comme Cloud Functions. Cela signifie que vous devez déployer les modifications correspondantes côté client pour éviter de perturber les utilisateurs existants (par exemple, sur les anciennes versions de l'application).

C'est pourquoi SQL 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 SQL Connect. Dans ce guide, vous trouverez des informations plus détaillées sur la génération de SDK Swift à partir de votre schéma, ainsi que sur l'utilisation des requêtes et des mutations client.

En résumé, pour utiliser les SDK Swift générés dans vos applications clientes, vous devez suivre les étapes préalables suivantes :

  1. Ajoutez Firebase à votre application iOS.

  2. Pour utiliser le SDK généré, configurez-le comme dépendance dans Xcode.

    Dans la barre de navigation supérieure de Xcode, sélectionnez File > Add Package Dependencies > Add Local (Fichier > Ajouter des dépendances de package > Ajouter un élément local), puis choisissez le dossier contenant le fichier Package.swift généré.

Puis :

  1. Développez le schéma de votre application.

  2. Configurez la génération du SDK :

  3. Initialisez votre code client et importez des bibliothèques.

  4. Implémentez des appels aux requêtes et aux mutations.

  5. Configurez et utilisez l'émulateur SQL Connect et itérez.

Générez votre SDK Swift

Utilisez la Firebase CLI pour configurer les SQL Connect générés 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

Mettez à jour les SDK lors de la création de prototypes

Si l'extension SQL Connect VS Code est installée, elle maintient toujours les SDK générés à jour.

Si vous n'utilisez pas l'extension SQL Connect VS Code, vous pouvez utiliser la CLI Firebase pour maintenir les SDK générés à jour.

firebase dataconnect:sdk:generate --watch

Générez des SDK dans les pipelines de compilation

Vous pouvez utiliser la CLI Firebase pour générer des SQL Connect SDK dans les processus de compilation CI/CD.

firebase dataconnect:sdk:generate

Initialisez le SDK iOSSQL Connect

Initialisez votre SQL Connect instance à l'aide des informations que vous avez utilisées pour configurer SQL Connect (toutes disponibles dans l'onglet SQL Connect de la console Firebase).

Obtenir une instance de connecteur

Le code de votre connecteur sera généré par l' SQL Connect émulateur. 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 connecteur en appelant :

let connector = DataConnect.moviesConnector

Implémentez des requêtes et des mutations

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 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 utiliserez une référence de requête. Toutes les références de requête sont des éditeurs observables. En fonction de l'éditeur configuré (voir connector.yaml), ils sont compatibles avec la macro @Observable (iOS 17+) ou implémentent le ObservableObject protocole. La valeur par défaut, si aucune n'est spécifiée, est la macro @Observable compatible avec iOS 17+.

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 requête et appeler la méthode execute() de la requête pour mettre à jour les données. La variable data correspondra à la forme des données définies dans votre définition de requête GQL.

Tous les résultats récupérés sont conformes au protocole Decodable. Si vous avez inclus la clé primaire de l'objet dans votre extraction 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 sont également compatibles avec l'exécution unique. 

let resultData = try await DataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre: "Sci-Fi")

Gérez 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 SQL 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 les énumérations générées contiennent une valeur _UNKNOWN, et Swift applique des instructions de commutation exhaustives.

do {
    let result = try await DataConnect.moviesConnector.listMovies.execute()
    if let data = result.data {
        for movie in data.movies {
            switch movie.aspectratio {
                case .ACADEMY: print("academy")
                case .WIDESCREEN: print("widescreen")
                case .ANAMORPHIC: print("anamorphic")
                case ._UNKNOWN(let unknownAspect): print(unknownAspect)
            }
        }
    }
} catch {
    // handle error
}

Activez la mise en cache côté client

SQL 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 permet aux parties de votre application qui dépendent 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:
  swiftSdk:
    outputDir: "../ios"
    package: "FirebaseDataConnectGenerated"
    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 maxAge est 0, 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 lorsque CACHE_ONLY est spécifié pour execute().

  • storage: le SDK client peut être configuré pour mettre en cache les réponses dans un stockage persistent ou dans la memory. Les résultats mis en cache dans le stockage persistent sont conservés lors des redémarrages de l'application. Dans les SDK iOS, la valeur par défaut est persistent.

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 que maxAge, utilisez la valeur mise en cache. Ce comportement par défaut est appelé règle PREFER_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 inconditionnellement de nouvelles valeurs à partir du serveur (SERVER_ONLY).

    try await execute(fetchPolicy: .cacheOnly)

    try await execute(fetchPolicy: .serverOnly)

    Créez un prototype et testez votre application iOS

    Instrumentez les clients pour utiliser un émulateur local

    Vous pouvez utiliser l'émulateur SQL Connect, que ce soit à partir de l' extension SQL 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.

    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 SQL Connect

    Le serveur SQL Connect représente les types de données GraphQL courants et personnalisés. Ils sont représentés dans le SDK comme suit.

    Type SQL Connect Swift
    Chaîne String
    Int Int
    Float Double
    Booléen Bool
    UUID UUID
    Date FirebaseDataConnect.LocalDate
    Horodatage FirebaseCore.Timestamp
    Int64 Int64
    Tous FirebaseDataConnect.AnyValue