Utiliser les SDK Web générés

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 la logique de votre 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 correspondantes côté client 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. Ce guide fournit des informations plus détaillées sur la génération de SDK Web à partir de votre schéma, ainsi que sur l'utilisation des requêtes et mutations client.

Vous pouvez apprendre à développer des clients avec un dépôt d'application de démarrage rapide et créer une application Data Connect complète en suivant notre atelier de programmation pour le Web.

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 ou les bibliothèques React ou Angular.
3. Pour React et Angular, installez les packages Tanstack Query.

4. 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 pour le SDK JavaScript, ou React ou Angular.

5. Importez des bibliothèques et du code généré avec le SDK JavaScript, React ou Angular.

6. Implémentez des appels aux requêtes et aux mutations avec le SDK JavaScript, React ou Angular.

7. Testez en configurant l'émulateur Data Connect avec le SDK JavaScript, ou React ou Angular.

Implémenter le code client avec le SDK Firebase JavaScript

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

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 Data Connect pour les frameworks.

Initialiser votre application

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

initializeApp({...});

Installer le SDK JavaScript généré

Utilisez l'interface de ligne de commande Firebase pour configurer les SDK générés Data Connect dans vos applications. La commande init devrait 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 Data 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 du prototypage

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

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

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 SDK Data Connect 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 Data Connect et les importations spécifiques du SDK généré.

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é 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 { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@dataconnect/generated';

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

Appeler les 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

Vous pouvez vous abonner aux modifications (qui seront mises à jour chaque fois que vous exécuterez une requête).

const listRef = listAllMoviesRef();

// subscribe will immediately invoke the query if no execute was called on it previously.
subscribe(listRef, ({ data }) => {
 updateUIWithMovies(data.movies);
});

await createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi", rating: 5 });\
await listMovies(); // 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

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 au cas où de nouvelles valeurs d'énumération seraient 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 Data Connect

Vous pouvez éventuellement vous connecter à l'émulateur en appelant connectDataConnectEmulator, puis en transmettant l'instance Data Connect, 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, mettez en commentaire les lignes de connexion à l'émulateur.

Remarque : L'appel de getDataConnect n'est requis que si vous souhaitez vous connecter à l'émulateur Data Connect. Sinon, le SDK généré créera automatiquement une instance de l'objet DataConnect pour vous.

Implémenter le code client pour React et Angular

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

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

Initialiser votre 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.

React

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

Angular

ng add @angular/fire

Générer votre SDK React ou Angular

Comme pour le SDK Web standard décrit plus haut, les outils Firebase gèrent la génération automatique des 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 générales Data Connect, 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.

React

// 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";

Angular

// 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 suivant, notez la méthode préfixée par use, useListAllMovies, pour React et la méthode préfixée par inject, injectListAllMovies, pour Angular, toutes deux issues du SDK généré.

React

Toutes les opérations de ce type dans le SDK généré, qu'il s'agisse de requêtes ou de mutations, appellent les liaisons TanStackQuery :

• Les requêtes appellent et renvoient lehook TanStack useDataConnectQuery.
• Les mutations appellent et renvoient le hook useDataConnectMutation de TanStack.

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>
}

Angular

Remarque : ng add @angular/fire le fera automatiquement pour vous, mais si vous choisissez de le configurer manuellement, vous pouvez le faire avec le code suivant :

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 d'actualisation automatique avec React et Angular

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

React

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 });
  }
}

Angular

// 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 Data Connect

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

React

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);
  ...
}

Angular

// 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, mettez en commentaire les lignes de connexion à l'émulateur.

Remarque : L'appel de getDataConnect n'est requis que si vous souhaitez vous connecter à l'émulateur Data Connect. Sinon, le SDK généré créera automatiquement une instance de l'objet DataConnect pour vous.

Types de données dans le SDK

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	TypeScript
Horodatage	chaîne
Date	chaîne
UUID	chaîne
Int64	chaîne
Double	Nombre
Float	Nombre

Mettre à jour les SDK lors du prototypage

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

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

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 SDK Data Connect dans les processus de compilation CI/CD.

firebase dataconnect:sdk:generate