Utiliser les SDK Web 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 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 opérations SQL Connect sont stockées sur le serveur comme des 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 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 pour SQL Connect. Dans ce guide, vous trouverez des informations plus détaillées sur la génération de SDK Web à partir de votre schéma et sur l'utilisation des requêtes et mutations client.

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

1. Ajoutez Firebase à votre application Web.

Puis :

1. Développez le schéma de votre application.
2. Initialisez votre code client avec le SDK JavaScript.
3. Configurez la génération du SDK :
   • Avec le bouton Add SDK to app (Ajouter un SDK à l'application) dans l'extension SQL Connect VS Code.
   • En mettant à jour votre connector.yaml pour le SDK JavaScript.
4. Importez des bibliothèques et du code généré avec le SDK JavaScript.
5. Implémentez des appels aux requêtes et mutations avec le SDK JavaScript.
6. Testez en configurant l'émulateur SQL Connect avec le SDK JavaScript.

Implémenter le code client avec le Firebase JavaScript SDK

Cette section explique comment implémenter des clients à l'aide du Firebase JavaScript SDK.

Si vous utilisez React ou Angular, consultez les autres instructions de configuration et les liens vers la documentation supplémentaire sur la génération de SDK pour les frameworks.SQL Connect

Initialiser l'application

Commencez par initialiser votre application à l'aide de la séquence Firebase standard.

initializeApp({...});

Installer le SDK JavaScript généré

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

Connectez votre application au service SQL Connect.

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

const dataConnect = getDataConnect(connectorConfig);
// [Optionally] Configure the SDK to use Data Connect local emulator.
connectDataConnectEmulator(dataConnect, 'localhost', 9399);

Mettre à 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érer des SDK dans des 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

Importer des bibliothèques

Deux ensembles d'importations sont nécessaires pour initialiser votre code client : les importations générales SQL Connect et les importations de SDK spécifiques générées.

Notez l'objet ConnectorConfig inclus dans les importations générales.

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// generated queries and mutations from SDK
import { listMovies, ListMoviesResponse, createMovie, connectorConfig } from '@dataconnect/generated';

Utiliser des requêtes à partir du SDK JavaScript

Le code généré est déjà fourni avec des références de requête prédéfinies. Il vous suffit de les importer et d'appeler l'exécution.

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@dataconnect/generated';

const ref = listMoviesRef();
const { data } = await executeQuery(ref);
console.log(data.movies);

Appeler des méthodes de requête du SDK

Voici un exemple d'utilisation de ces fonctions de raccourci d'action :

import { listMovies } from '@dataconnect/generated';
function onBtnClick() {
// This will call the generated JS from the CLI and then make an HTTP request out
// to the server.
  listMovies().then(data => showInUI(data)); // == executeQuery(listMoviesRef);
}

S'abonner aux modifications

Consultez Obtenir des informations en temps réel à partir de SQL Connect.

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 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 clients déployés plus anciens peuvent cesser de fonctionner.

Exemple d'implémentation résiliente

Ajoutez toujours une branche default à une instruction switch sur les valeurs d'énumération, ou une branche else à un bloc if/else if comparant les valeurs d'énumération. Cela n'est pas appliqué par le langage JavaScript/TypeScript, mais c'est le moyen de rendre le code client robuste dans le cas où de nouvelles valeurs d'énumération sont ajoutées.

const queryResult = await getOldestMovie();

if (queryResult.data) {
  // we can use a switch statement's "default" case to check for unexpected values
  const oldestMovieAspectRatio = queryResult.data.originalAspectRatio;
  switch (oldestMovieAspectRatio) {
      case AspectRatio.ACADEMY:
      case AspectRatio.WIDESCREEN:
      case AspectRatio.ANAMORPHIC:
        console.log('This movie was filmed in Academy, widescreen or anamorphic aspect ratio!');
        break;
      default:
        // the default case will catch FULLSCREEN, UNAVAILABLE or _UNKNOWN
        // it will also catch unexpected values the SDK isn't aware of, such as CINEMASCOPE
        console.log('This movie was was NOT filmed in Academy, widescreen or anamorphic.');
        break;
  }

  // alternatively, we can check to see if the returned enum value is a known value
  if (!Object.values(AspectRatio).includes(oldestMovieAspectRatio)) {
    console.log(`Unrecognized aspect ratio: ${oldestAspectRatio}`);
  }
} else {
  console.log("no movies found!");
}

Utiliser des mutations à partir du SDK JavaScript

Les mutations sont accessibles de la même manière que les requêtes.

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@dataconnect/generated';

const { data } = await executeMutation(createMovieRef({ movie: 'Empire Strikes Back' }));

Se connecter à l'émulateur SQL Connect

Vous pouvez également vous connecter à l'émulateur en appelant connectDataConnectEmulator puis en transmettant l'SQL Connect instance, comme suit :

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);`

// Make calls from your app

Pour passer aux ressources de production, commentez les lignes de connexion à l'émulateur.

Activer 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 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:
  javascriptSdk:
    outputDir: ../web/
    package: "@dataconnect/generated"
    clientCache:
      maxAge: 5s
      storage: memory

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 sont utilisées que lorsque CACHE_ONLY est spécifié pour executeQuery() et le résultat initial renvoyé par subscribe().

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

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 cela fait, executeQuery() et subscribe() mettront en cache les réponses et utiliseront 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 executeQuery() 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 à executeQuery() 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).

  await executeQuery(queryRef, QueryFetchPolicy.CACHE_ONLY);
  

  await executeQuery(queryRef, QueryFetchPolicy.SERVER_ONLY);
  

• Lorsque vous appelez subscribe(), il renvoie toujours immédiatement le contenu mis en cache s'il existe, quel que soit le paramètre maxAge. Les appels suivants à executeQuery() avertissent les écouteurs en fonction du maxAge configuré.

Types de données dans le SDK

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

Générer des SDK React et Angular avec TanStack

Firebase SQL Connect fournit un SDK généré avec des hooks pour React et Angular à l'aide de bibliothèques disponibles auprès de nos partenaires Invertase, TanStack Query Firebase.

Cette bibliothèque fournit un ensemble de hooks qui facilitent considérablement la gestion des tâches asynchrones avec Firebase dans vos applications.

TanStack est fourni avec sa propre implémentation de la mise en cache côté client et des abonnements en temps réel, qui peuvent fonctionner avec SQL Connect's compatibilité en temps réel intégrée, mais avec quelques difficultés. Nous vous recommandons d'utiliser les liaisons basées sur TanStack ou SQL Connect's la compatibilité en temps réel intégrée, mais pas les deux.

Notez que l'implémentation en temps réel de SQL Connect's présente certains avantages par rapport aux liaisons TanStack :

• Mise en cache normalisée : SQL Connect implémente la mise en cache normalisée, ce qui améliore la cohérence des données, ainsi que l'efficacité de la mémoire et du réseau par rapport à la mise en cache au niveau des requêtes. Avec la mise en cache normalisée, si une entité est mise à jour dans une zone de votre application, elle est également mise à jour dans d'autres zones qui utilisent cette entité.
• Invalidation à distance : SQL Connect peut invalider à distance les entités mises en cache   sur tous les appareils abonnés.

Initialiser l'application

Tout d'abord, comme pour toute application Web Firebase, initialisez votre application à l'aide de la séquence Firebase standard.

initializeApp({...});

Installer les packages TanStack Query Firebase

Installez les packages pour TanStack Query dans votre projet.

npm i --save @tanstack/react-query @tanstack-query-firebase/react
npm i --save firebase@latest # Note: React has a peer dependency on ^11.3.0

ng add @angular/fire

Générer votre SDK React ou Angular

Comme pour le SDK Web standard, décrit précédemment, les outils Firebase gèrent la génération automatique de SDK en fonction de votre schéma et de vos opérations.

Si vous venez d'ajouter React ou Angular à votre projet, réexécutez firebase init dataconnect:sdk pour reconfigurer les SDK générés afin d'inclure les liaisons de framework supplémentaires.

Importer des bibliothèques

Quatre ensembles d'importations sont nécessaires pour initialiser votre code client React ou Angular : les importations SQL Connect générales, les importations TanStack générales, et les importations spécifiques pour vos SDK JS et React générés.

Notez le type ConnectorConfig inclus dans les importations générales.

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@dataconnect/generated';

// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@dataconnect/generated/react";

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@dataconnect/generated';

// generated React hooks from SDK
import { injectListAllMovies, injectCreateMovie } from "@dataconnect/generated/angular";

Utiliser des requêtes et des mutations dans votre client React ou Angular

Une fois la configuration terminée, vous pouvez intégrer des méthodes à partir du SDK généré.

Dans l'extrait de code suivant, notez la méthode préfixée use useListAllMovies pour React et la méthode préfixée inject injectListAllMovies pour Angular, toutes deux issues du SDK généré.

import { useListAllMovies } from '@dataconnect/generated/react';

function MyComponent() {
  const { isLoading, data, error } = useListAllMovies();
  if(isLoading) {
    return <div>Loading...</div>
  }
  if(error) {
    return <div> An Error Occurred: {error} </div>
  }
}

// App.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import MyComponent from './my-component';

function App() {
  const queryClient = new QueryClient();
  return <QueryClientProvider client={queryClient}>
    <MyComponent />
  </QueryClientProvider>
}

import { injectAllMovies, connectorConfig } from '@dataconnect/generated/angular';
import { provideDataConnect, getDataConnect } from '@angular/fire/data-connect';
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";
const queryClient = new QueryClient();
...
providers: [
  ...
  provideTanStackQuery(queryClient),
  provideDataConnect(() => {
    const dc = getDataConnect(connectorConfig);
    return dc;
  })
]

Utiliser des requêtes de rechargement automatique avec React et Angular

Vous pouvez configurer les requêtes pour qu'elles se rechargent automatiquement lorsque les données changent.

export class MovieListComponent {
  movies = useListAllMovies();
}

export class AddPostComponent {
  const mutation = useCreateMovie({ invalidate: [listAllMoviesRef()] });
  addMovie() {
    // The following will automatically cause TanStack to reload its listAllMovies query
    mutation.mutate({ title: 'The Matrix });
  }
}

// class
export class MovieListComponent {
  movies = injectListAllMovies();
}

// template
@if (movies.isPending()) {
    Loading...
}
@if (movies.error()) {
    An error has occurred: {{  movies.error() }}
}
@if (movies.data(); as data) {
    @for (movie of data.movies; track movie.id) {
    <mat-card appearance="outlined">
        <mat-card-content>{{movie.description}}</mat-card-content>
    </mat-card>
    } @empty {
        <h2>No items!</h2>
    }
}

Se connecter à l'émulateur SQL Connect

Vous pouvez également vous connecter à l'émulateur en appelant connectDataConnectEmulator puis en transmettant l'SQL Connect instance à votre hook généré, comme suit :

import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';
import { useListAllMovies } from '@dataconnect/generated/react';

const dc = getDataConnect(connectorConfig);
connectDataConnectEmulator(dc, 'localhost', 9399);

class AppComponent() {
  ...
  const { isLoading, data, error } = useListAllMovies(dc);
  ...
}

// app.config.ts
import { provideDataConnect } from '@angular/fire/data-connect';
import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
provideDataConnect(() => {
  const dc = getDataConnect(connectorConfig);
  connectDataConnectEmulator(dc, 'localhost', 9399);
  return dc;
}),

Pour passer aux ressources de production, commentez les lignes de connexion à l'émulateur.

Mettre à 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érer des SDK dans des 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