Usa gli SDK web generati

Nota: Firebase Data Connect è in Anteprima pubblica. Data Connect sarà soggetto ai "Termini delle offerte pre-GA" nella sezione Termini specifici dei servizi dei Termini di servizio della piattaforma Google Cloud. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Gli SDK client di Firebase Data Connect ti consentono di chiamare le query e le mutazioni lato server direttamente da un'app Firebase. Generi un SDK client personalizzato in parallelo mentre progetti gli schemi, le query e le mutazioni da eseguire nel tuo servizio Data Connect. Poi, integra i metodi di questo SDK nella logica del client.

Come accennato altrove, è importante notare che le query e le mutazioni Data Connect non vengono inviate dal codice client ed eseguite sul server. Al contrario, quando vengono di cui è stato eseguito il deployment, le operazioni Data Connect vengono memorizzate sul server come Cloud Functions. Ciò significa che devi implementare le modifiche lato client corrispondenti per evitare di interrompere gli utenti esistenti (ad esempio, nelle versioni precedenti dell'app).

Per questo motivo, Data Connect fornisce un ambiente di sviluppo e strumenti che ti consentono di creare un prototipo di schemi, query e mutazioni di cui è stato eseguito il deployment sul server. Inoltre, genera automaticamente gli SDK lato client durante la creazione del prototipo.

Una volta eseguite le iterazioni degli aggiornamenti delle app di servizio e client, gli aggiornamenti sia lato server sia lato client sono pronti per il deployment.

Implementa il codice client con l'SDK Firebase JavaScript

Questa sezione illustra come implementare i client utilizzando l'SDK Firebase JavaScript.

Se utilizzi React, consulta le istruzioni di configurazione alternative e i link alla documentazione aggiuntiva sulla generazione di SDK React per Data Connect.

Inizializza l'app

Per prima cosa, inizializza l'app utilizzando la sequenza Firebase standard.

initializeApp({...});

Generare l'SDK JavaScript

Come per la maggior parte dei progetti Firebase, il codice clientFirebase Data Connect viene modificato in una directory del progetto locale. Sia l'estensione Data Connect per VS Code sia la CLI Firebase sono importanti strumenti locali per la generazione e la gestione del codice client.

Le opzioni di generazione dell'SDK sono associate a diverse voci nel file dataconnect.yaml generato durante l'inizializzazione del progetto.

Inizializza la generazione dell'SDK

In connector.yaml, aggiungi outputDir, package e (per l'SDK web) packageJsonDir.

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

outputDir specifica dove deve essere generato l'output dell'SDK.

package specifica il nome del pacchetto.

packageJsonDir specifica dove installare il pacchetto.

Nota: per la generazione, aggiungiamo "firebase": "^10.14.0" come peerDependency. A seconda del tuo gestore delle dipendenze (ad es. pnpm), queste dipendenze potrebbero non essere installate automaticamente.

In questo caso, installa firebase@latest per assicurarti che questa dipendenza peer sia soddisfatta.

Inizializza l'SDK JavaScript

Inizializza l'istanza Data Connect utilizzando le informazioni che hai utilizzato per configurare Data Connect (tutte disponibili nella scheda Data Connect della console Firebase).

Oggetto ConnectorConfig

L'SDK richiede un oggetto di configurazione del connettore.

Questo oggetto viene generato automaticamente da serviceId e location in dataconnect.yaml e da connectorId in connector.yaml.

Importare librerie

Per inizializzare il codice client sono necessarie due serie di importazioni: le importazioni Data Connect generali e le importazioni SDK generate specifiche.

Tieni presente l'oggetto ConnectorConfig incluso nelle importazioni generali.

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

Utilizzare le query dall'SDK JavaScript

Il codice generato sarà già dotato di riferimenti a query predefiniti. Devi solo importarli ed eseguire chiamate su di essi.

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

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

Chiama i metodi di query dell'SDK

Ecco un esempio di utilizzo di queste funzioni di scorciatoia per le azioni:

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

Iscriversi alle modifiche

Puoi iscriverti alle modifiche (che verranno aggiornate ogni volta che esegui una query).

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`

Utilizzare le mutazioni dell'SDK JavaScript

Le mutazioni sono accessibili nello stesso modo delle query.

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@movie-app/movies';

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

Connettiti all'emulatore Data Connect

Se vuoi, puoi connetterti all'emulatore chiamando connectDataConnectEmulator e passando l'istanza Data Connect, come segue:

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

Per passare alle risorse di produzione, commenta le righe per la connessione all'emulatore.

Nota: la chiamata a getDataConnect è obbligatoria solo se vuoi connetterti all'emulatore Data Connect. In caso contrario, l'SDK generato creerà automaticamente un'istanza dell'oggetto DataConnect.

Implementare il codice client per React

Firebase Data Connect fornisce un SDK generato con hook per React utilizzando una biblioteca disponibile dai nostri partner di Invertase, TanStack Query Firebase.

Questa libreria fornisce un insieme di hook che semplificano notevolmente la gestione delle attività asincrone con Firebase nelle tue applicazioni.

Inizializza l'app

Innanzitutto, come per qualsiasi app web Firebase, inizializza l'app utilizzando la sequenza Firebase standard.

initializeApp({...});

Installa i pacchetti Firebase di TanStack Query

Installa i pacchetti per TanStack Query nel tuo progetto.

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

Generare l'SDK React

Come per l'SDK web standard, come descritto in precedenza, gli strumenti Firebase gestiscono la generazione automatica degli SDK in base allo schema e alle operazioni.

Per generare un SDK React per il tuo progetto, aggiungi una chiave react al connector.yaml file di configurazione.

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

Importare librerie

Per inizializzare il codice client React sono necessari quattro set di importazioni: importazioni Data Connect generali, importazioni TanStack generali e importazioni specifiche per gli SDK generati da JS e React.

Tieni presente il tipo ConnectorConfig incluso nelle importazioni generali.

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

Utilizzare query e mutazioni nel client React

Una volta completata la configurazione, puoi incorporare i metodi dell'SDK React generato.

Nello snippet seguente, nota il metodo usecon prefisso useListAllMovies dell'SDK React generato. Tutte queste operazioni use nell'SDK generato, sia le query che le mutazioni, chiamano le associazioni di query TanStack:

• Le query chiamano e restituiscono l'hook TanStack useDataConnectQuery
• Le mutazioni chiamano e restituiscono l'hook useDataConnectMutation TanStack

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

Connettiti all'emulatore Data Connect

Se vuoi, puoi connetterti all'emulatore chiamando connectDataConnectEmulator e poi passando l'istanza Data Connect all'hook generato, come segue:

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

Per passare alle risorse di produzione, commenta le righe per la connessione all'emulatore.

Nota: la chiamata a getDataConnect è obbligatoria solo se vuoi connetterti all'emulatore Data Connect. In caso contrario, l'SDK generato creerà automaticamente un'istanza dell'oggetto DataConnect.

Tipi di dati nell'SDK

Il server Data Connect rappresenta i tipi di dati GraphQL comuni. Questi parametri sono rappresentati nell'SDK come segue.

Tipo di Data Connect	TypeScript
Timestamp	stringa
Data	stringa
UUID	stringa
Int64	stringa
Doppio	Numero
In virgola mobile	Numero

Considerazioni speciali per la generazione dell'SDK

Configura i percorsi relativi a node_modules

Per l'SDK JavaScript, poiché Data Connect utilizza npm link per installare l'SDK, l'SDK generato deve essere in output in una directory allo stesso livello del percorso node_modules o in una directory secondaria che può accedere a node_modules.

In altre parole, l'SDK generato deve avere accesso al modulo node firebase per funzionare correttamente.

Ad esempio, se hai node_modules in my-app/, la directory di output deve essere my-app/js-email-generated in modo che js-email-generated possa eseguire l'importazione dalla cartella principale node_modules.

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"

In alternativa, se hai un monorepo in cui i moduli sono ospitati nella directory principale, puoi collocare la directory di output in qualsiasi cartella del monorepo.

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

Nota: puoi fornire un percorso assoluto alle directory se il progetto è configurato in una struttura di directory separata.

Aggiornare gli SDK durante la prototipazione

Se stai creando una prototipazione in modo interattivo con l'estensione VS Code di Data Connect e il relativo emulatore Data Connect, i file di codice sorgente dell'SDK vengono generati e aggiornati automaticamente mentre modifichi i file Data Connect che definiscono schemi, query e mutazioni..gql Questa può essere una funzionalità utile nei flussi di lavoro di (ri)caricamento a caldo.

In altri scenari, se utilizzi l'emulatore Data Connect dall'interfaccia a riga di comando Firebase, puoi impostare una sorveglianza sugli aggiornamenti di .gql e anche aggiornare automaticamente le sorgenti SDK.

In alternativa, puoi utilizzare la CLI per rigenerare gli SDK ogni volta che i file .gql vengono modificati:

firebase dataconnect:sdk:generate --watch

Genera SDK per l'integrazione e per le release di produzione

In alcuni scenari, ad esempio per preparare le origini del progetto da inviare per i test CI, puoi chiamare la CLI Firebase per un aggiornamento collettivo.

In questi casi, utilizza firebase dataconnect:sdk:generate.

Considerazioni su altri framework

Angular

Durante la generazione del codice, Angular CLI non rileva le nuove modifiche a causa del codice di ottimizzazione delle dipendenze. Per risolvere il problema, dovrai modificare il tuo angular.json.

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