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 à 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 Data 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 Data 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, Data Connect opérations 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 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 Data 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 ces é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 Add SDK to app (Ajouter le SDK à l'application) dans notre extension Data Connect VS Code
   • 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, ou React ou Angular.

6. Implémentez des appels aux requêtes et mutations avec le SDK JavaScript, ou 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 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 les documents supplémentaires sur la génération de Data Connect SDK 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 CLI Firebase pour configurer les SDK générés par Data Connect dans vos applications. La commande init doit détecter toutes les applications du dossier actuel et installer les SDK générés automatiquement.

firebase init dataconnect:sdk

Associez 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 de la création de prototypes

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

Si vous n'utilisez pas l'extension Data Connect VS Code, vous pouvez utiliser l'interface 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 l'interface 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 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é sera déjà fourni avec des références de requête prédéfinies. Il vous suffit de les importer et d'exécuter l'appel.

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 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 é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 Data 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

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

Vous pouvez également vous connecter à l'émulateur en appelant connectDataConnectEmulator, puis en transmettant l'Data 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.

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 de bibliothèques disponibles auprès de nos partenaires 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.

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 Data 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 ConnectorConfig type 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 Data Connect

Vous pouvez également vous connecter à l'émulateur en appelant connectDataConnectEmulator puis en transmettant l'Data 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.

Types de données dans le SDK

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

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

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

Si vous n'utilisez pas l'extension Data Connect VS Code, vous pouvez utiliser l'interface 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 l'interface CLI Firebase pour générer des SDK Data Connect dans les processus de compilation CI/CD.

firebase dataconnect:sdk:generate