Generierte Web-SDKs verwenden

Firebase Data Connect Client-SDKs ermöglichen Ihnen den direkten Aufruf Ihrer serverseitigen Abfragen und Mutationen über eine Firebase-App. Sie generieren parallel ein benutzerdefiniertes Client-SDK, während Sie die Schemas, Abfragen und Mutationen entwerfen, die Sie für Ihren Data Connect Dienst bereitstellen. Anschließend binden Sie Methoden aus diesem SDK in Ihre Clientlogik ein.

Wie bereits erwähnt, ist es wichtig zu beachten, dass Data Connect Abfragen und Mutationen nicht vom Clientcode gesendet und auf dem Server ausgeführt werden. Stattdessen werden nach der Bereitstellung Data Connect Vorgänge auf dem Server wie Cloud Functions gespeichert. Das bedeutet, dass Sie entsprechende clientseitige Änderungen bereitstellen müssen, um Probleme für bestehende Nutzer zu vermeiden (z. B. bei älteren App-Versionen).

Aus diesem Grund bietet Data Connect eine Entwicklungsumgebung und Tools, mit denen Sie Ihre serverseitig bereitgestellten Schemas, Abfragen und Mutationen prototypisieren können. Außerdem werden während der Prototypenerstellung automatisch clientseitige SDKs generiert.

Wenn Sie die Aktualisierungen für Ihre Dienst- und Client-Apps durchlaufen haben, können sowohl serverseitige als auch clientseitige Aktualisierungen bereitgestellt werden.

Wie sieht der Workflow für die Cliententwicklung aus?

Wenn Sie die Anleitung Erste Schritte befolgt haben, haben Sie bereits den allgemeinen Entwicklungsablauf für Data Connect kennengelernt. In diesem Leitfaden finden Sie detailliertere Informationen zum Generieren von Web-SDKs aus Ihrem Schema und zum Arbeiten mit Clientabfragen und -mutationen.

Sie können die Cliententwicklung mit einem Schnellstart-App -Repository kennenlernen und eine voll funktionsfähige Data Connect App erstellen, indem Sie unserem Codelab für das Web folgen.

Zusammenfassend lässt sich sagen, dass Sie die folgenden Schritte ausführen müssen, um generierte Web-SDKs in Ihren Client-Apps zu verwenden:

1. Firebase zu Ihrer Web-App hinzufügen

Gehen Sie anschließend so vor:

1. App-Schema entwickeln
2. Initialisieren Sie Ihren Clientcode mit dem JavaScript SDK oder React oder Angular Bibliotheken.
3. Installieren Sie für React und Angular Tanstack Query-Pakete installieren.

4. SDK-Generierung einrichten:

   • Mit der Schaltfläche SDK zur App hinzufügen in unserer Data Connect VS Code-Erweiterung
   • Durch Aktualisieren von connector.yaml für das JavaScript SDK oder React oder Angular.

5. Importieren Sie Bibliotheken und generierten Code mit JavaScript SDK oder React oder Angular.

6. Implementieren Sie Aufrufe von Abfragen und Mutationen mit dem JavaScript SDK, oder React oder Angular.

7. Testen Sie, indem Sie den Data Connect Emulator mit dem JavaScript SDK oder React oder Angular einrichten.

Clientcode mit dem Firebase JavaScript SDK implementieren

In diesem Abschnitt wird beschrieben, wie Sie Clients mit dem Firebase JavaScript SDK implementieren können.

Wenn Sie React oder Angular verwenden, finden Sie hier alternative Einrichtungsanleitungen und Links zu zusätzlicher Dokumentation zum Generieren Data Connect von SDKs für Frameworks.

App initialisieren

Initialisieren Sie zuerst Ihre App mit der Standardsequenz von Firebase.

initializeApp({...});

Generiertes JavaScript SDK installieren

Verwenden Sie die Firebase CLI, um Data Connect generierte SDKs in Ihren Apps einzurichten. Der Befehl init sollte alle Apps im aktuellen Ordner erkennen und generierte SDKs automatisch installieren.

firebase init dataconnect:sdk

Verbinden Sie Ihre App mit dem Data Connect Dienst.

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

SDKs während der Prototypenerstellung aktualisieren

Wenn Sie die Data Connect VS Code-Erweiterung installiert haben, werden generierte SDKs immer auf dem neuesten Stand gehalten.

Wenn Sie die Data Connect VS Code-Erweiterung nicht verwenden, können Sie generierte SDKs mit der Firebase CLI auf dem neuesten Stand halten.

firebase dataconnect:sdk:generate --watch

SDKs in Build-Pipelines generieren

Mit der Firebase CLI können Sie Data Connect SDKs in CI/CD-Build-Prozessen generieren.

firebase dataconnect:sdk:generate

Bibliotheken importieren

Zum Initialisieren Ihres Clientcodes sind zwei Importsätze erforderlich: allgemeine Data Connect Imports und spezifische, generierte SDK-Imports.

Beachten Sie das Objekt ConnectorConfig, das in den allgemeinen Imports enthalten ist.

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

Hinweis: Generierte JavaScript-Client-SDKs verwenden dieselben Namen für Schnittstellen und Vorgänge wie generierte Node.js-Admin-SDKs. Achten Sie darauf, die richtige Bibliothek für Ihre Plattform zu importieren. Wenn Sie beide Bibliotheken in derselben Datei verwenden müssen, verwenden Sie einen Importalias oder einen Namespace-Import für eine oder beide Bibliotheken.

import { listMovies as adminListMovies } from '@dataconnect/admin-generated';
Or:
import * as Admin from '@dataconnect/admin-generated';

Abfragen aus dem JavaScript SDK verwenden

Der generierte Code enthält bereits vordefinierte Abfragereferenzen. Sie müssen sie nur importieren und ausführen.

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

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

SDK-Abfragemethoden aufrufen

Hier ein Beispiel mit diesen Aktions-Shortcuts:

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

Änderungen abonnieren

Sie können Änderungen abonnieren, die jedes Mal aktualisiert werden, wenn Sie eine Abfrage ausführen.

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`

Änderungen an Enumerationsfeldern verarbeiten

Das Schema einer App kann Enumerationen enthalten, auf die mit Ihren GraphQL-Abfragen zugegriffen werden kann.

Wenn sich das Design einer App ändert, können Sie neue unterstützte Enumerationswerte hinzufügen. Angenommen, Sie entscheiden sich später im Lebenszyklus Ihrer Anwendung, der Enumeration AspectRatio den Wert `FULLSCREEN` hinzuzufügen.

Im Data Connect Workflow können Sie lokale Entwicklungstools verwenden, um Ihre Abfragen und SDKs zu aktualisieren.

Bevor Sie jedoch eine aktualisierte Version Ihrer Clients veröffentlichen, können ältere bereitgestellte Clients Probleme verursachen.

Beispiel für eine robuste Implementierung

Fügen Sie immer einen default Zweig zu einer switch Anweisung für die Enumerationswerte oder einen else Zweig zu einem if/else if Block hinzu, der mit den Enumerationswerten verglichen wird. Dies wird von der JavaScript/TypeScript-Sprache nicht erzwungen, ist aber die Möglichkeit, Clientcode robust zu gestalten, falls neue Enumerationswerte hinzugefügt werden.

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

Mutationen aus dem JavaScript SDK verwenden

Auf Mutationen kann auf dieselbe Weise wie auf Abfragen zugegriffen werden.

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

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

Mit dem Data Connect Emulator verbinden

Optional können Sie eine Verbindung zum Emulator herstellen, indem Sie connectDataConnectEmulator aufrufen und dann die Data Connect Instanz übergeben, wie hier gezeigt:

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

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

// Make calls from your app

Wenn Sie zu Produktionsressourcen wechseln möchten, kommentieren Sie die Zeilen für die Verbindung zum Emulator aus.

Hinweis: Der Aufruf von getDataConnect ist nur erforderlich, wenn Sie eine Verbindung zum Data Connect Emulator herstellen möchten. Andernfalls wird vom generierten SDK automatisch eine Instanz des Objekts DataConnect erstellt.

Clientcode für React und Angular implementieren

Firebase Data Connect bietet ein generiertes SDK mit Hooks für React und Angular, das Bibliotheken von unseren Partnern bei Invertase, TanStack Query Firebase verwendet.

Diese Bibliothek bietet eine Reihe von Hooks, die die Verarbeitung asynchroner Aufgaben mit Firebase in Ihren Anwendungen erheblich erleichtern.

App initialisieren

Initialisieren Sie Ihre App wie bei jeder Firebase-Web-App mit der Standardsequenz von Firebase.

initializeApp({...});

TanStack Query Firebase-Pakete installieren

Installieren Sie Pakete für TanStack Query in Ihrem Projekt.

Reagieren

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

React- oder Angular-SDK generieren

Wie beim Standard-Web-SDK, das bereits früher beschrieben wurde, übernimmt das Firebase Tooling die automatische Generierung von SDKs basierend auf Ihrem Schema und Ihren Vorgängen.

Wenn Sie Ihrem Projekt gerade React oder Angular hinzugefügt haben, führen Sie firebase init dataconnect:sdk noch einmal aus, um die generierten SDKs so zu konfigurieren, dass die zusätzlichen Framework-Bindungen enthalten sind.

Bibliotheken importieren

Zum Initialisieren Ihres React- oder Angular Clientcodes sind vier Importsätze erforderlich: allgemeine Data Connect Imports, allgemeine TanStack-Imports, und spezifische Imports für Ihre generierten JS- und React-SDKs.

Beachten Sie den Typ ConnectorConfig, der in den allgemeinen Imports enthalten ist.

Reagieren

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

Abfragen und Mutationen in Ihrem React- oder Angular-Client verwenden

Nach Abschluss der Einrichtung können Sie Methoden aus dem generierten SDK einbinden.

Beachten Sie im folgenden Snippet die Methode mit dem Präfix use (useListAllMovies) für React und die Methode mit dem Präfix inject (injectListAllMovies) für Angular, die beide aus dem generierten SDK stammen.

Reagieren

Alle diese Vorgänge im generierten SDK, sowohl Abfragen als auch Mutationen, rufen TanStackQuery-Bindungen auf:

• Abfragen rufen denTanStack useDataConnectQuery Hook auf und geben ihn zurück.
• Mutationen rufen den TanStack useDataConnectMutation Hook auf und geben ihn zurück.

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

Hinweis: ng add @angular/fire erledigt das automatisch für Sie. Wenn Sie es jedoch manuell einrichten möchten, können Sie das mit dem folgenden Code tun:

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

Abfragen mit automatischem Neuladen mit React und Angular verwenden

Sie können Abfragen so konfigurieren, dass sie bei Datenänderungen automatisch neu geladen werden.

Reagieren

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

Mit dem Data Connect Emulator verbinden

Optional können Sie eine Verbindung zum Emulator herstellen, indem Sie connectDataConnectEmulator aufrufen und dann die Data Connect Instanz an Ihren generierten Hook übergeben, wie hier gezeigt:

Reagieren

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

Wenn Sie zu Produktionsressourcen wechseln möchten, kommentieren Sie die Zeilen für die Verbindung zum Emulator aus.

Hinweis: Der Aufruf von getDataConnect ist nur erforderlich, wenn Sie eine Verbindung zum Data Connect Emulator herstellen möchten. Andernfalls wird vom generierten SDK automatisch eine Instanz des Objekts DataConnect erstellt.

Clientseitiges Caching aktivieren

Data Connect bietet eine optionale clientseitige Caching-Funktion, die Sie aktivieren können, indem Sie die Datei connector.yaml bearbeiten. Wenn diese Funktion aktiviert ist, werden die generierten Client-SDKs Abfrageantworten lokal im Cache speichern. Dadurch kann die Anzahl der Datenbankanfragen Ihrer App reduziert werden und die datenbankabhängigen Teile Ihrer App funktionieren auch dann, wenn die Netzwerkverfügbarkeit unterbrochen ist.

React-, Next.js- und Angular-Entwickler: Die React- und Angular-SDKs von Data Connect verarbeiten das Caching mit den TanStack-Bibliotheken, die nicht mit der nativen Caching-Funktion von Data Connect kompatibel sind. Wenn Sie React oder Angular verwenden, empfehlen wir, das Caching nicht wie in diesem Abschnitt beschrieben zu aktivieren, sondern stattdessen die von TanStack bereitgestellte Funktion zu verwenden.

Wenn Sie das clientseitige Caching aktivieren möchten, fügen Sie Ihrer Connector-Konfiguration eine Client-Caching-Konfiguration hinzu:

generate:
  javascriptSdk:
    outputDir: ../web/
    package: "@dataconnect/generated"
    clientCache:
      maxAge: 5s
      storage: memory

Diese Konfiguration hat zwei Parameter, die beide optional sind:

• maxAge: Das maximale Alter einer im Cache gespeicherten Antwort, bevor das Client-SDK neue Werte abruft. Beispiele: „0“, „30s“, „1h30m“.

  Der Standardwert für maxAge ist 0. Das bedeutet, dass Antworten im Cache gespeichert werden, das Client-SDK aber immer neue Werte abruft. Die im Cache gespeicherten Werte werden nur verwendet, wenn CACHE_ONLY für executeQuery() und das erste Ergebnis angegeben wird, das von subscribe() zurückgegeben wird.

• storage: Das Client-SDK kann so konfiguriert werden, dass Antworten entweder im persistent-Speicher oder im memory-Speicher im Cache gespeichert werden. Im persistent-Speicher im Cache gespeicherte Ergebnisse bleiben auch nach einem Neustart der App erhalten. In Web-SDKs wird nur der memory-Speicher unterstützt.

Nachdem Sie die Caching-Konfiguration Ihres Connectors aktualisiert haben, generieren Sie Ihre Client-SDKs neu und erstellen Sie Ihre App neu. Danach werden mit executeQuery() und subscribe() Antworten im Cache gespeichert und im Cache gespeicherte Werte gemäß der konfigurierten Richtlinie verwendet. Das geschieht in der Regel automatisch, ohne dass Sie dafür noch etwas tun müssen. Beachten Sie jedoch Folgendes:

• Das Standardverhalten von executeQuery() ist wie oben beschrieben: Wenn ein Ergebnis für eine Abfrage im Cache gespeichert ist und der im Cache gespeicherte Wert nicht älter als maxAge ist, wird der im Cache gespeicherte Wert verwendet. Dieses Standardverhalten wird als PREFER_CACHE-Richtlinie bezeichnet.

  Sie können auch für einzelne Aufrufe von executeQuery() angeben, dass entweder nur im Cache gespeicherte Werte bereitgestellt werden (CACHE_ONLY) oder dass bedingungslos neue Werte vom Server abgerufen werden (SERVER_ONLY).

  await executeQuery(queryRef, QueryFetchPolicy.CACHE_ONLY);
  

  await executeQuery(queryRef, QueryFetchPolicy.SERVER_ONLY);
  

• Wenn Sie subscribe() aufrufen, wird immer sofort der im Cache gespeicherte Inhalt zurückgegeben, falls vorhanden, unabhängig von der Einstellung maxAge. Nachfolgende Aufrufe von executeQuery() benachrichtigen Listener gemäß der konfigurierten maxAge.

Datentypen im SDK

Der Data Connect Server stellt allgemeine GraphQL-Datentypen dar. Diese werden im SDK wie folgt dargestellt.

Data Connect Typ	TypeScript
Zeitstempel	String
Datum	String
UUID	String
INT64	String
Doppelt	Zahl
Float	Zahl

SDKs während der Prototypenerstellung aktualisieren

Wenn Sie die Data Connect VS Code-Erweiterung installiert haben, werden generierte SDKs immer auf dem neuesten Stand gehalten.

Wenn Sie die Data Connect VS Code-Erweiterung nicht verwenden, können Sie generierte SDKs mit der Firebase CLI auf dem neuesten Stand halten.

firebase dataconnect:sdk:generate --watch

SDKs in Build-Pipelines generieren

Mit der Firebase CLI können Sie Data Connect SDKs in CI/CD-Build-Prozessen generieren.

firebase dataconnect:sdk:generate