Menggunakan SDK web yang dihasilkan

Dengan SDK klien Firebase Data Connect, Anda dapat memanggil kueri dan mutasi sisi server secara langsung dari aplikasi Firebase. Anda membuat SDK klien kustom secara paralel saat mendesain skema, kueri, dan mutasi yang di-deploy ke layanan Data Connect. Kemudian, Anda mengintegrasikan metode dari SDK ini ke dalam logika klien Anda.

Seperti yang telah kami sebutkan di tempat lain, penting untuk diperhatikan bahwa kueri dan mutasi tidak dikirimkan oleh kode klien dan dieksekusi di server.Data Connect Sebagai gantinya, saat di-deploy, operasi Data Connect disimpan di server seperti Cloud Functions. Artinya, Anda perlu men-deploy perubahan sisi klien yang sesuai untuk menghindari gangguan pada pengguna yang ada (misalnya, di versi aplikasi yang lebih lama).

Itulah sebabnya Data Connect menyediakan lingkungan dan alat pengembangan yang memungkinkan Anda membuat prototipe skema, kueri, dan mutasi yang di-deploy server. Selain itu, SDK sisi klien akan dibuat secara otomatis saat Anda membuat prototipe.

Setelah Anda melakukan iterasi pembaruan pada aplikasi layanan dan klien, pembaruan sisi server dan klien siap di-deploy.

Apa alur kerja pengembangan klien?

Jika Anda mengikuti Mulai, Anda telah diperkenalkan dengan alur pengembangan keseluruhan untuk Data Connect. Dalam panduan ini, Anda akan menemukan informasi yang lebih mendetail tentang cara membuat SDK Web dari skema Anda dan cara menggunakan kueri dan mutasi klien.

Anda dapat mempelajari pengembangan klien dengan repositori aplikasi panduan memulai dan membuat aplikasi Data Connect berfitur lengkap dengan mengikuti codelab untuk web kami.

Singkatnya, untuk menggunakan Web SDK yang dihasilkan di aplikasi klien, Anda harus mengikuti langkah-langkah prasyarat berikut:

1. Tambahkan Firebase ke aplikasi web Anda.

Kemudian:

1. Kembangkan skema aplikasi Anda.
2. Inisialisasi kode klien Anda dengan JavaScript SDK, atau library React atau Angular.
3. Untuk React dan Angular, instal paket Tanstack Query

4. Siapkan pembuatan SDK:

   • Dengan tombol Tambahkan SDK ke aplikasi di ekstensi Data Connect VS Code kami
   • Dengan mengupdate connector.yaml untuk JavaScript SDK, atau React atau Angular.

5. Impor library dan kode yang dihasilkan dengan JavaScript SDK, atau React atau Angular.

6. Terapkan panggilan ke kueri dan mutasi dengan JavaScript SDK, atau React atau Angular.

7. Lakukan pengujian dengan menyiapkan emulator Data Connect dengan JavaScript SDK, atau React atau Angular.

Menerapkan kode klien dengan Firebase JavaScript SDK

Bagian ini membahas cara mengimplementasikan klien menggunakan Firebase JavaScript SDK.

Jika Anda menggunakan React atau Angular, lihat petunjuk penyiapan alternatif dan link ke dokumentasi tambahan tentang membuat SDK Data Connect untuk framework.

Inisialisasi aplikasi Anda

Pertama, inisialisasi aplikasi Anda menggunakan urutan Firebase standar.

initializeApp({...});

Membuat JavaScript SDK

Seperti kebanyakan project Firebase, pengerjaan kode klien Firebase Data Connect Anda dilakukan di direktori project lokal. Ekstensi VS Code Data Connect dan CLI Firebase adalah alat lokal penting untuk membuat dan mengelola kode klien.

Opsi pembuatan SDK dikaitkan dengan beberapa entri dalam file dataconnect.yaml yang dibuat saat Anda melakukan inisialisasi project.

Menginisialisasi pembuatan SDK

Di connector.yaml, tambahkan outputDir, package, dan (untuk Web SDK) packageJsonDir.

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

outputDir menentukan tempat SDK yang dihasilkan harus dikeluarkan.

package menentukan nama paket.

packageJsonDir menentukan tempat menginstal paket.

Catatan: untuk pembuatan, kami menambahkan "firebase": "^10.14.0" sebagai peerDependency. Bergantung pada pengelola dependensi Anda (yaitu pnpm), dependensi ini mungkin tidak diinstal secara otomatis.

Dalam hal ini, instal firebase@latest untuk memastikan dependensi peer ini terpenuhi.

Menginisialisasi JavaScript SDK

Lakukan inisialisasi instance Data Connect menggunakan informasi yang Anda gunakan untuk menyiapkan Koneksi Data (semua tersedia di tab Koneksi Data konsol Firebase).

Objek ConnectorConfig

SDK memerlukan objek konfigurasi konektor.

Objek ini dibuat secara otomatis dari serviceId dan location di dataconnect.yaml, dan connectorId di connector.yaml.

Mengimpor library

Ada dua set impor yang diperlukan untuk melakukan inisialisasi kode klien Anda: impor Data Connect umum dan impor SDK spesifik yang dihasilkan.

Perhatikan objek ConnectorConfig yang disertakan dalam impor umum.

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

Menggunakan kueri dari JavaScript SDK

Kode yang dihasilkan akan dilengkapi dengan Referensi Kueri yang telah ditentukan sebelumnya. Yang perlu Anda lakukan hanyalah mengimpor dan memanggil eksekusi pada kode tersebut.

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

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

Memanggil metode kueri SDK

Berikut adalah contoh penggunaan fungsi pintasan tindakan ini:

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

Berlangganan perubahan

Anda dapat berlangganan perubahan (yang akan diperbarui setiap kali Anda menjalankan kueri).

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`

Menangani perubahan pada kolom enumerasi

Skema aplikasi dapat berisi enumerasi, yang dapat diakses oleh kueri GraphQL Anda.

Saat desain aplikasi berubah, Anda dapat menambahkan nilai yang didukung enum baru. Misalnya, bayangkan bahwa di kemudian hari dalam siklus proses aplikasi, Anda memutuskan untuk menambahkan nilai FULLSCREEN ke enum AspectRatio.

Dalam alur kerja Data Connect, Anda dapat menggunakan alat pengembangan lokal untuk memperbarui kueri dan SDK.

Namun, sebelum Anda merilis versi terbaru klien, klien lama yang di-deploy mungkin rusak.

Contoh penerapan yang tangguh

Selalu tambahkan cabang default ke pernyataan switch di atas nilai enum, atau cabang else ke blok if/else if yang membandingkan nilai enum. Hal ini tidak diterapkan oleh bahasa JavaScript/TypeScript, tetapi merupakan cara untuk membuat kode klien menjadi andal jika nilai enum baru ditambahkan.

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

Menggunakan mutasi dari JavaScript SDK

Mutasi dapat diakses dengan cara yang sama seperti kueri.

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

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

Menghubungkan ke emulator Data Connect

Atau, Anda dapat terhubung ke emulator dengan memanggil connectDataConnectEmulator, lalu meneruskan instance Data Connect seperti ini:

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

Untuk beralih ke resource produksi, beri komentar pada baris untuk menghubungkan ke emulator.

Catatan: Panggilan getDataConnect hanya diperlukan jika Anda ingin terhubung ke emulator Data Connect. Jika tidak, SDK yang dihasilkan akan otomatis membuat instance objek DataConnect untuk Anda.

Menerapkan kode klien untuk React dan Angular

Firebase Data Connect menyediakan SDK yang dibuat dengan hook untuk React dan Angular menggunakan library yang tersedia dari partner kami di Invertase, TanStack Query Firebase.

Library ini menyediakan serangkaian hook yang sangat memudahkan penanganan tugas asinkron dengan Firebase di aplikasi Anda.

Inisialisasi aplikasi Anda

Pertama, seperti aplikasi web Firebase lainnya, lakukan inisialisasi aplikasi Anda menggunakan urutan Firebase standar.

initializeApp({...});

Menginstal paket TanStack Query Firebase

menginstal paket untuk TanStack Query di project Anda.

Reaksi

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

Membuat SDK React atau Angular

Seperti SDK web standar, seperti yang dijelaskan sebelumnya, alat Firebase menangani pembuatan SDK secara otomatis berdasarkan skema dan operasi Anda.

Untuk membuat React SDK untuk project Anda, tambahkan kunci react ke file konfigurasi connector.yaml Anda.

Reaksi

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

Mengimpor library

Ada empat set impor yang diperlukan untuk menginisialisasi kode klien React atau Angular Anda: impor Data Connect umum, impor TanStack umum, dan impor khusus untuk SDK yang dihasilkan JS dan React.

Perhatikan jenis ConnectorConfig yang disertakan dalam impor umum.

Reaksi

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

Menggunakan kueri dan mutasi di klien React atau Angular Anda

Setelah penyiapan selesai, Anda dapat menggabungkan metode dari SDK yang dihasilkan.

Dalam cuplikan berikut, perhatikan metode berawalan use, yaitu useListAllMovies untuk React dan metode berawalan inject, yaitu injectListAllMovies untuk Angular, keduanya dari SDK yang dihasilkan.

Reaksi

Semua operasi tersebut di SDK yang dihasilkan, baik kueri maupun mutasi, memanggil binding TanStackQuery:

• Memanggil dan menampilkan hookTanStack useDataConnectQuery
• Mutasi memanggil dan menampilkan hook TanStack useDataConnectMutation

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

Catatan: ng add @angular/fire akan melakukannya secara otomatis untuk Anda, tetapi jika Anda memilih untuk menyiapkannya secara manual, Anda dapat melakukannya dengan kode berikut:

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

Menggunakan kueri muat ulang otomatis dengan React dan Angular

Anda dapat mengonfigurasi kueri agar dimuat ulang secara otomatis saat data berubah.

Reaksi

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

Menghubungkan ke emulator Data Connect

Secara opsional, Anda dapat terhubung ke emulator dengan memanggil connectDataConnectEmulator, lalu meneruskan instance Data Connect ke hook yang dihasilkan, seperti berikut:

Reaksi

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

Untuk beralih ke resource produksi, beri komentar pada baris untuk menghubungkan ke emulator.

Catatan: Panggilan getDataConnect hanya diperlukan jika Anda ingin terhubung ke emulator Data Connect. Jika tidak, SDK yang dihasilkan akan otomatis membuat instance objek DataConnect untuk Anda.

Jenis data di SDK

Server Data Connect menampilkan jenis data GraphQL umum. Ini ditampilkan di SDK sebagai berikut.

Jenis Koneksi Data	TypeScript
Stempel waktu	string
Tanggal	string
UUID	string
Int64	string
Ganda	Angka
Float	Angka

Pertimbangan khusus untuk pembuatan SDK

Mengonfigurasi jalur relatif terhadap node_modules

Untuk JavaScript SDK, karena Data Connect menggunakan npm link untuk menginstal SDK Anda, SDK yang dihasilkan harus di-output ke direktori di level yang sama dengan jalur node_modules atau di direktori turunan yang dapat mengakses node_modules.

Dengan kata lain, SDK yang dihasilkan harus memiliki akses ke modul node firebase agar berfungsi dengan benar.

Misalnya, jika Anda memiliki node_modules di my-app/, direktori output Anda harus my-app/js-email-generated sehingga js-email-generated dapat mengimpor dari folder node_modules induknya.

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"

Atau, jika Anda memiliki monorepo tempat modul dihosting di root, Anda dapat menempatkan direktori output di folder mana pun di 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

Catatan: Anda dapat memberikan jalur absolut ke direktori jika project Anda disiapkan dalam struktur direktori terpisah.

Memperbarui SDK saat membuat prototipe

Jika Anda membuat prototipe secara interaktif dengan ekstensi VS Code Data Connect dan emulator Data Connect-nya, file sumber SDK akan otomatis dibuat dan diperbarui saat Anda mengubah file .gql yang menentukan skema, kueri, dan mutasi. Hal ini dapat menjadi fitur yang berguna dalam alur kerja pemuatan ulang (re)panas.

Dalam skenario lain, jika Anda menggunakan emulator Data Connect dari CLI Firebase, Anda dapat menyetel pengamatan pada update .gql dan juga memperbarui sumber SDK secara otomatis.

Atau, Anda dapat menggunakan CLI untuk membuat ulang SDK setiap kali file .gql diubah:

firebase dataconnect:sdk:generate --watch

Membuat SDK untuk integrasi dan rilis produksi

Dalam beberapa skenario, seperti menyiapkan sumber project untuk dikirimkan ke pengujian CI, Anda dapat memanggil Firebase CLI untuk update batch.

Dalam kasus ini, gunakan firebase dataconnect:sdk:generate.