Generierte Web-SDKs verwenden

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Mit 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, während Sie die Schemas, Abfragen und Mutationen entwerfen, die Sie in Ihrem Data Connect-Dienst bereitstellen. Anschließend integrieren Sie Methoden aus diesem SDK in Ihre Clientlogik.

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

Deshalb bietet Data Connect eine Entwicklerumgebung und Tools, mit denen Sie Prototypen Ihrer serverseitig bereitgestellten Schemas, Abfragen und Mutationen erstellen können. Außerdem werden clientseitige SDKs automatisch generiert, während Sie den Prototyp erstellen.

Wenn Sie Updates für Ihre Dienst- und Client-Apps iteriert haben, können sowohl server- als auch clientseitige Updates bereitgestellt werden.

Wie funktioniert der Workflow für die Cliententwicklung?

Wenn Sie der Einstiegsanleitung gefolgt sind, haben Sie den gesamten Entwicklungsablauf für Data Connect kennengelernt. In diesem Leitfaden finden Sie ausführlichere Informationen zum Generieren von Web-SDKs aus Ihrem Schema und zum Arbeiten mit Clientabfragen und ‑mutationen.

Zusammenfassend: Wenn Sie generierte Web-SDKs in Ihren Client-Apps verwenden möchten, müssen Sie die folgenden Voraussetzungen erfüllen:

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

Gehen Sie anschließend so vor:

1. Entwickeln Sie Ihr App-Schema.
2. Initialisiere deinen Clientcode mit dem JavaScript SDK oder den Bibliotheken React oder Angular.
3. Für React und Angular: Tanstack-Abfragepakete installieren

4. So richten Sie die SDK-Generierung ein:

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

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

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

7. Führen Sie einen Test durch, 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.

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

App initialisieren

Initialisieren Sie zuerst Ihre App mit der standardmäßigen Firebase-Sequenz.

initializeApp({...});

JavaScript SDK generieren

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

Die Optionen zur SDK-Generierung sind mit mehreren Einträgen in der dataconnect.yaml-Datei verknüpft, die beim Initialisieren Ihres Projekts generiert wurde.

SDK-Generierung initialisieren

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

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

package gibt den Paketnamen an.

packageJsonDir gibt an, wo das Paket installiert werden soll.

Installieren Sie in diesem Fall firebase@latest, damit diese Peer-Abhängigkeit erfüllt ist.

JavaScript SDK initialisieren

Initiieren Sie Ihre Data Connect-Instanz mit den Informationen, die Sie zum Einrichten von Data Connect verwendet haben. Diese finden Sie in der Firebase-Konsole auf dem Tab „Data Connect“.

Das ConnectorConfig-Objekt

Das SDK erfordert ein Connector-Konfigurationsobjekt.

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

Bibliotheken importieren

Zum Initialisieren des Clientcodes sind zwei Arten von Importen erforderlich: allgemeine Data Connect-Importe und spezifische, generierte SDK-Importe.

Beachten Sie das ConnectorConfig-Objekt, 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 Abfragereferenzen. Sie müssen sie nur importieren und „execute“ darauf anwenden.

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 Funktionen für Aktionskürzel:

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 dann 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 die gleiche 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, z. B. so:

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 für die Verbindung zum Emulator.

Clientcode für React und Angular implementieren

Firebase Data Connect stellt ein generiertes SDK mit Hooks für React und Angular bereit, das Bibliotheken von unseren Partnern bei Invertase und 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-Webanwendung 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.

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

React- oder Angular-SDK generieren

Wie beim Standard-Web-SDK, das oben beschrieben wurde, werden mit Firebase-Tools SDKs automatisch basierend auf Ihrem Schema und Ihren Vorgängen generiert.

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

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

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

Bibliotheken importieren

Es sind vier Importe erforderlich, um Ihren React- oder Angular-Clientcode zu initialisieren: allgemeine Data Connect-Importe, allgemeine TanStack-Importe und spezifische Importe für Ihre JS- und React-generierten SDKs.

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

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

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

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

Sobald 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, beide aus dem generierten SDK.

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

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 für automatisches Aktualisieren mit React und Angular verwenden

Sie können Abfragen so konfigurieren, dass sie automatisch neu geladen werden, wenn sich Daten ändern.

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

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 Ihren generierten Hook übergeben. Beispiel:

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

// 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.

Datentypen im SDK

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

Besondere Hinweise zur SDK-Generierung

Pfade relativ zu node_modules konfigurieren

Da Data Connect npm link zum Installieren des SDK verwendet, muss das generierte SDK in ein Verzeichnis auf derselben Ebene wie der node_modules-Pfad oder in ein untergeordnetes Verzeichnis ausgegeben werden, das auf node_modules zugreifen kann.

Mit anderen Worten: Ihr generiertes SDK muss Zugriff auf das firebase-Knotenmodul haben, damit es richtig funktioniert.

Wenn sich node_modules beispielsweise in my-app/ befindet, sollte das 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

SDKs während des Prototypings aktualisieren

Wenn Sie mit der Data Connect-VS Code-Erweiterung und dem Data Connect-Emulator interaktiv Prototypen erstellen, werden SDK-Quelldateien automatisch generiert und aktualisiert, während Sie Data Connect-Dateien ändern, in denen Schemas, Abfragen und Mutationen definiert sind..gql Dies kann eine nützliche Funktion in Workflows für das Hot-Reloading (Neuladen) sein.

Alternativ können Sie die SDKs über die Befehlszeile neu 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. wenn Sie Projektquellen für CI-Tests vorbereiten, können Sie die Firebase CLI für ein Batch-Update aufrufen.

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