Generierte Web-SDKs verwenden

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 Fehler bei bestehenden Nutzern 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.

Clientcode mit dem Firebase JavaScript SDK implementieren

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

Wenn du React verwendest, findest du hier eine alternative Einrichtungsanleitung und Links zu zusätzlicher Dokumentation zum Erstellen von React SDKs für Data Connect.

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 VS Code-Erweiterung für Data Connect 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 implementieren

Firebase Data Connect bietet ein generiertes SDK mit Hooks für React, das eine Bibliothek von unseren Partnern von 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-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

React 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: "../../"

Bibliotheken importieren

Es sind vier Importe erforderlich, um den React-Clientcode zu initialisieren: allgemeine Data Connect-Importe, allgemeine TanStack-Importe und spezifische Importe für die von 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";

Abfragen und Mutationen in Ihrem React-Client verwenden

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

Beachten Sie im folgenden Snippet die Methode useListAllMovies mit dem Präfix use aus dem generierten React SDK. Alle use-Vorgänge im generierten SDK, sowohl Abfragen als auch Mutationen, rufen TanStack-Abfragebindungen auf:

• Abfragen rufen den TanStack useDataConnectQuery-Hook auf und geben ihn zurück
• Mutationen rufen den TanStack-useDataConnectMutation-Hook 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>
}

Verbindung zum Data Connect-Emulator herstellen

Optional kannst du eine Verbindung zum Emulator herstellen, indem du connectDataConnectEmulator aufrufst und dann die Data Connect-Instanz an deinen generierten Hook übergibst. 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);

function App() {
  ...
  const { isLoading, data, error } = useListAllMovies(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 Überlegungen 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 .gql-Dateien ändern, in denen Schemas, Abfragen und Mutationen definiert werden. 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. bei der Vorbereitung von Projektquellen für CI-Tests, können Sie die Firebase CLI für ein Batch-Update aufrufen.

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

Weitere Hinweise zu Frameworks

Angular

Beim Generieren von Code werden durch den Code zur Abhängigkeitsoptimierung keine neuen Änderungen erkannt.Angular CLI Um das Problem zu beheben, müssen Sie angular.json ändern.

  "projects": {
    "myproject": {
      "architect": {
        "serve:": {
          "prebundle": {
            "exclude": ["@movie-app/movies"]
          }
        }
      }
    }
  }