Generierte Web-SDKs verwenden

Mit den Firebase Data Connect-Client-SDKs können Sie Ihre serverseitigen Abfragen und Mutationen direkt über eine Firebase-App aufrufen. Sie generieren ein benutzerdefiniertes Client-SDK parallel zur Entwicklung der Schemas, Abfragen und Mutationen, 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 Data Connect-Vorgänge bei der Bereitstellung auf dem Server wie Cloud Functions gespeichert. Das bedeutet, dass Sie entsprechende clientseitige Änderungen bereitstellen müssen, um zu vermeiden, dass bestehende Nutzer (z. B. in älteren App-Versionen) beeinträchtigt werden.

Data Connect bietet Ihnen daher eine Entwicklungsumgebung und Tools, mit denen Sie Prototypen Ihrer serverbasierten Schemas, Abfragen und Mutationen erstellen können. Außerdem werden clientseitige SDKs automatisch generiert, während Sie Prototypen erstellen.

Wenn Sie die Aktualisierungen für Ihren Dienst und Ihre 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 dem Startleitfaden gefolgt sind, haben Sie 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.

Mit einem Repository für eine Kurzanleitung können Sie die Cliententwicklung lernen und eine Data Connect-App mit allen Funktionen erstellen, indem Sie unserem Codelab für das Web folgen.

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

1. Fügen Sie Ihrer Web-App Firebase hinzu.

Gehen Sie anschließend so vor:

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

4. SDK-Generierung einrichten:

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

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

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

7. Testen Sie, indem Sie den Data Connect-Emulator mit dem JavaScript SDK, 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 alternative Einrichtungsanleitungen und Links zu zusätzlicher Dokumentation zum Generieren von Data Connect-SDKs für Frameworks.

App initialisieren

Initialisieren Sie Ihre App zuerst mit der Standard-Firebase-Sequenz.

initializeApp({...});

JavaScript SDK generieren

Wie bei den meisten Firebase-Projekten findet die Arbeit an Ihrem Firebase Data Connect-Clientcode in einem lokalen Projektverzeichnis statt. Sowohl die Data Connect VS Code-Erweiterung als auch die Firebase-CLI sind wichtige lokale Tools zum Generieren und Verwalten von Clientcode.

Die Optionen für die SDK-Generierung sind an mehrere Einträge in der Datei dataconnect.yaml gebunden, die beim Initialisieren des Projekts generiert wurde.

SDK-Generierung initialisieren

Fügen Sie in Ihrem connector.yaml Ihre outputDir, package und (für das Web-SDK) packageJsonDir hinzu.

generate:
  javascriptSdk:
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

outputDir gibt an, wohin das generierte SDK ausgegeben werden soll.

package gibt den Paketnamen an.

packageJsonDir gibt an, wo das Paket installiert werden soll.

Hinweis :Für die Generierung fügen wir "firebase": "^10.14.0" als peerDependency hinzu. Je nach Abhängigkeitsmanager (z.B. pnpm) werden diese Abhängigkeiten möglicherweise nicht automatisch installiert.

Installieren Sie in diesem Fall firebase@latest, um diese Peer-Abhängigkeit zu erfüllen.

JavaScript SDK initialisieren

Initialisieren Sie Ihre Data Connect-Instanz mit den Informationen, die Sie zum Einrichten von Data Connect verwendet haben. Alle Informationen sind in der Firebase-Konsole auf dem Tab „Data Connect“ verfügbar.

Das ConnectorConfig-Objekt

Für das SDK ist ein Connector-Konfigurationsobjekt erforderlich.

Dieses Objekt wird automatisch aus serviceId und location in dataconnect.yaml sowie connectorId in connector.yaml generiert.

Bibliotheken importieren

Es sind zwei Importsätze erforderlich, um Ihren Clientcode zu initialisieren: allgemeine Data Connect-Importe und spezifische, generierte SDK-Importe.

Beachten Sie das Objekt ConnectorConfig, das in den allgemeinen Importen 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 '@myorg/myconnector';

Abfragen aus dem JavaScript-SDK verwenden

Der generierte Code enthält bereits vordefinierte Query-Refs. Sie müssen sie nur importieren und „execute“ aufrufen.

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@movie-app/movies';

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

SDK-Abfragemethoden aufrufen

Hier ein Beispiel für die Verwendung dieser Aktionskürzel-Funktionen:

import { listMovies } from '@movie-app/movies';
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`

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 '@movie-app/movies';

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

Verbindung zum Data Connect-Emulator herstellen

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

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@myorg/myconnector'; // Replace with your package name

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

// Make calls from your app

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

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

Clientcode für React und Angular implementieren

Firebase Data Connect bietet ein generiertes SDK mit Hooks für React und Angular, das Bibliotheken unserer Partner 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

Wie bei jeder Firebase-Web-App müssen Sie Ihre App zuerst mit der standardmäßigen Firebase-Sequenz initialisieren.

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 (siehe oben) werden SDKs in Firebase-Tools automatisch auf Grundlage Ihres Schemas und Ihrer Vorgänge generiert.

Wenn Sie ein React SDK für Ihr Projekt generieren möchten, fügen Sie Ihrer Konfigurationsdatei connector.yaml einen react-Schlüssel hinzu.

Reagieren

generate:
  javascriptSdk:
    react: true
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

Angular

generate:
  javascriptSdk:
    angular: true
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

Bibliotheken importieren

Es sind vier Importsätze erforderlich, um Ihren React- oder Angular-Clientcode zu initialisieren: 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 Importen 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 '@myorg/myconnector';

// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@myorg/connector/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 '@myorg/myconnector';

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

Verwenden von Abfragen und Mutationen in Ihrem React- oder Angular-Client

Nachdem die Einrichtung abgeschlossen ist, können Sie Methoden aus dem generierten SDK einbinden.

Im folgenden Snippet sehen Sie die Methode useListAllMovies mit dem Präfix use für React und die Methode injectListAllMovies mit dem Präfix inject 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 den TanStack useDataConnectQuery-Hook auf und geben ihn zurück.
• Mutationen rufen den TanStack-Hook useDataConnectMutation auf und geben ihn zurück.

import { useListAllMovies } from '@movies-app/movies/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 die Einrichtung jedoch manuell vornehmen möchten, können Sie dazu den folgenden Code verwenden:

import { injectAllMovies, connectorConfig } from '@movies-app/movies/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 automatisch neu geladen werden, wenn sich Daten ändern.

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

Verbindung zum Data Connect-Emulator herstellen

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

Reagieren

import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@movies-app/movies';
import { useListAllMovies } from '@movies-app/movies/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 aus, die für die Verbindung zum Emulator zuständig sind.

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

Datentypen im SDK

Der Data Connect-Server stellt allgemeine GraphQL-Datentypen dar. Sie werden im SDK so dargestellt:

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

Besondere Überlegungen zur SDK-Generierung

Pfade relativ zu node_modules konfigurieren

Da für das JavaScript SDK Data Connect zum Installieren Ihres SDK verwendet wird, muss das generierte SDK in einem Verzeichnis auf derselben Ebene wie Ihr node_modules-Pfad oder in einem untergeordneten Verzeichnis ausgegeben werden, das auf node_modules zugreifen kann.npm link

Das generierte SDK muss also Zugriff auf das firebase-Node-Modul haben, damit es richtig funktioniert.

Wenn Sie beispielsweise node_modules in my-app/ haben, sollte Ihr Ausgabeverzeichnis my-app/js-email-generated sein, damit js-email-generated aus dem übergeordneten Ordner node_modules importieren kann.

my-app/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  js-email-generated/

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../js-email-generated"
    package: "@myapp/my-connector"

Wenn Sie ein Monorepo haben, in dem Ihre Module im Stammverzeichnis gehostet werden, können Sie das Ausgabeverzeichnis in einem beliebigen Ordner in Ihrem Monorepo platzieren.

my-monorepo/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  my-app/
    js-email-generated/
  package.json

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../my-app/js-email-generated" # You can also output to ../../js-email-generated

Hinweis :Sie können einen absoluten Pfad zu Verzeichnissen angeben, wenn Ihr Projekt in einer separaten Verzeichnisstruktur eingerichtet ist.

SDKs während der Prototyperstellung aktualisieren

Wenn Sie mit der VS Code-Erweiterung „Data Connect“ und dem Data Connect-Emulator interaktiv Prototypen erstellen, werden SDK-Quelldateien automatisch generiert und aktualisiert, während Sie .gql-Dateien mit Schemas, Abfragen und Mutationen ändern. Dies kann bei Hot-Reload-Workflows nützlich sein.

In anderen Szenarien, wenn Sie den Data Connect-Emulator über die Firebase-Befehlszeile verwenden, können Sie eine Beobachtung für .gql-Updates festlegen und SDK-Quellen automatisch aktualisieren lassen.

Alternativ können Sie die CLI verwenden, um SDKs immer dann neu zu generieren, wenn .gql-Dateien geändert werden:

firebase dataconnect:sdk:generate --watch

SDKs für die Integration und für Produktionsversionen generieren

In einigen Fällen, z. B. beim Vorbereiten von Projektquellen für CI-Tests, können Sie die Firebase CLI für eine Batchaktualisierung aufrufen.

Verwenden Sie in diesen Fällen firebase dataconnect:sdk:generate.