Menggunakan SDK web yang dihasilkan

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

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

Itulah sebabnya SQL Connect menyediakan lingkungan dan alat developer yang memungkinkan Anda membuat prototipe skema, kueri, dan mutasi yang di-deploy server. SDK sisi klien juga 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 yang dimaksud dengan alur kerja pengembangan klien?

Jika Anda mengikuti Memulai, Anda akan diperkenalkan dengan alur pengembangan keseluruhan untuk SQL Connect. Dalam panduan ini, Anda akan menemukan informasi yang lebih mendetail tentang pembuatan SDK Web dari skema dan penggunaan kueri serta mutasi klien.

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

1. Menambahkan Firebase ke aplikasi web.

Kemudian:

1. Mengembangkan skema aplikasi.
2. Menginisialisasi kode klien dengan JavaScript SDK.
3. Menyiapkan pembuatan SDK:
   • Dengan tombol Add SDK to app di ekstensi SQL Connect VS Code.
   • Dengan memperbarui connector.yaml untuk JavaScript SDK.
4. Mengimpor library dan kode yang dibuat dengan JavaScript SDK.
5. Mengimplementasikan panggilan ke kueri dan mutasi dengan JavaScript SDK.
6. Menguji dengan menyiapkan emulator SQL Connect dengan JavaScript SDK.

Mengimplementasikan 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 pembuatan SQL Connect SDK untuk framework.

Menginisialisasi aplikasi Anda

Pertama, inisialisasi aplikasi Anda menggunakan urutan Firebase standar .

initializeApp({...});

Menginstal JavaScript SDK yang dibuat

Gunakan Firebase CLI untuk menyiapkan SDK yang dibuat SQL Connect di aplikasi Anda. Perintah init akan mendeteksi semua aplikasi di folder saat ini dan menginstal SDK yang dibuat secara otomatis.

firebase init dataconnect:sdk

Hubungkan aplikasi Anda ke layanan SQL Connect.

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

const dataConnect = getDataConnect(connectorConfig);
// [Optionally] Configure the SDK to use Data Connect local emulator.
connectDataConnectEmulator(dataConnect, 'localhost', 9399);

Memperbarui SDK saat membuat prototipe

Jika Anda telah menginstal ekstensi SQL Connect VS Code, ekstensi tersebut akan selalu memperbarui SDK yang dibuat.

Jika tidak menggunakan ekstensi SQL Connect VS Code, Anda dapat menggunakan Firebase CLI untuk memperbarui SDK yang dibuat.

firebase dataconnect:sdk:generate --watch

Membuat SDK dalam pipeline build

Anda dapat menggunakan Firebase CLI untuk membuat SQL Connect SDK dalam proses build CI/CD.

firebase dataconnect:sdk:generate

Mengimpor library

Ada dua kumpulan impor yang diperlukan untuk menginisialisasi kode klien Anda: impor umum SQL Connect dan impor SDK spesifik yang dibuat.

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 '@dataconnect/generated';

Menggunakan kueri dari JavaScript SDK

Kode yang dibuat akan dilengkapi dengan Query Ref yang telah ditentukan sebelumnya. Anda hanya perlu mengimpor dan memanggil eksekusi di dalamnya.

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@dataconnect/generated';

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 '@dataconnect/generated';
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

Lihat Mendapatkan update real-time dari SQL Connect.

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 nanti dalam siklus proses aplikasi, Anda memutuskan untuk menambahkan nilai FULLSCREEN ke enum AspectRatio.

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

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

Contoh implementasi yang tangguh

Selalu tambahkan cabang default ke pernyataan switch atas nilai enum, atau cabang else ke blok if/else if yang dibandingkan dengan nilai enum. Hal ini tidak diterapkan oleh bahasa JavaScript/TypeScript, tetapi merupakan cara untuk membuat kode klien yang tangguh 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 '@dataconnect/generated';

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

Menghubungkan ke emulator SQL Connect

Jika ingin, Anda dapat menghubungkan ke emulator dengan memanggil connectDataConnectEmulator lalu meneruskan SQL Connect instance, seperti berikut:

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

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.

Mengaktifkan caching sisi klien

SQL Connect memiliki fitur caching sisi klien opsional, yang Anda dapat aktifkan dengan mengedit file connector.yaml. Jika fitur ini diaktifkan, SDK klien yang dibuat akan menyimpan respons kueri secara lokal dalam cache, yang dapat mengurangi jumlah permintaan database yang dibuat aplikasi Anda dan memungkinkan bagian aplikasi yang bergantung pada database berfungsi saat ketersediaan jaringan terganggu.

Untuk mengaktifkan caching sisi klien, tambahkan konfigurasi caching klien ke konfigurasi konektor Anda:

generate:
  javascriptSdk:
    outputDir: ../web/
    package: "@dataconnect/generated"
    clientCache:
      maxAge: 5s
      storage: memory

Konfigurasi ini memiliki dua parameter, keduanya opsional:

• maxAge: Usia maksimum respons yang di-cache sebelum SDK klien mengambil nilai baru. Contoh: "0", "30s", "1h30m".

  Nilai default untuk maxAge adalah 0, yang berarti respons di-cache, tetapi SDK klien akan selalu mengambil nilai baru. Nilai yang di-cache hanya akan digunakan jika CACHE_ONLY ditentukan ke executeQuery() dan hasil awal yang ditampilkan dari subscribe().

• storage: SDK klien dapat dikonfigurasi untuk menyimpan respons dalam cache di penyimpanan persistent atau di memory. Hasil yang di-cache di penyimpanan persistent akan tetap ada saat aplikasi dimulai ulang. Di SDK web, hanya penyimpanan memory yang didukung.

Setelah memperbarui konfigurasi caching konektor, buat ulang SDK klien dan bangun kembali aplikasi Anda. Setelah melakukannya, executeQuery() dan subscribe() akan menyimpan respons dalam cache dan menggunakan nilai yang di-cache sesuai dengan kebijakan yang Anda konfigurasi. Hal ini umumnya terjadi secara otomatis, tanpa langkah tambahan dari Anda. Namun, perhatikan hal berikut:

• Perilaku default executeQuery() adalah seperti yang dijelaskan di atas: jika hasil di-cache untuk kueri dan nilai yang di-cache tidak lebih lama dari maxAge, gunakan nilai yang di-cache. Perilaku default ini disebut kebijakan PREFER_CACHE.

  Anda juga dapat menentukan ke pemanggilan individual executeQuery() untuk hanya menayangkan nilai yang di-cache (CACHE_ONLY) atau untuk mengambil nilai baru dari server tanpa syarat (SERVER_ONLY).

  await executeQuery(queryRef, QueryFetchPolicy.CACHE_ONLY);
  

  await executeQuery(queryRef, QueryFetchPolicy.SERVER_ONLY);
  

• Saat Anda memanggil subscribe(), konten yang di-cache akan selalu langsung ditampilkan jika ada, terlepas dari setelan maxAge. Panggilan berikutnya ke executeQuery() akan memberi tahu pemroses sesuai dengan maxAge yang dikonfigurasi.

Jenis data di SDK

Server SQL Connect mewakili jenis data GraphQL umum. Jenis data ini direpresentasikan di SDK sebagai berikut.

Membuat SDK React dan Angular dengan TanStack

Firebase SQL 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 kumpulan hook yang sangat memudahkan penanganan tugas asinkron dengan Firebase di aplikasi Anda.

TanStack dilengkapi dengan implementasi caching sisi klien dan langganan real-time sendiri, yang dapat berfungsi bersama SQL Connect's dukungan real-time bawaan, tetapi hanya dengan beberapa kesulitan. Sebaiknya gunakan binding berbasis TanStack atau SQL Connect's dukungan real-time bawaan, tetapi tidak keduanya.

Perhatikan bahwa implementasi real-time SQL Connect's sendiri memiliki beberapa keunggulan dibandingkan binding TanStack:

• Caching yang dinormalkan: SQL Connect mengimplementasikan caching yang dinormalkan, yang meningkatkan konsistensi data serta efisiensi memori dan jaringan dibandingkan dengan caching tingkat kueri. Dengan caching yang dinormalkan, jika entity diperbarui di satu area aplikasi, entity tersebut juga akan diperbarui di area lain yang menggunakan entity tersebut.
• Pembatalan jarak jauh: SQL Connect dapat membatalkan entity yang di-cache dari jarak jauh di semua perangkat yang berlangganan.

Menginisialisasi aplikasi Anda

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

initializeApp({...});

Menginstal paket TanStack Query Firebase

Instal paket untuk TanStack Query di project Anda.

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

Membuat SDK React atau Angular

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

Jika Anda baru menambahkan React atau Angular ke project, jalankan kembali firebase init dataconnect:sdk untuk mengonfigurasi ulang SDK yang dibuat agar menyertakan binding framework tambahan.

Mengimpor library

Ada empat kumpulan impor yang diperlukan untuk menginisialisasi kode klien React atau Angular Anda: impor SQL Connectumum, impor TanStack umum, dan impor spesifik untuk SDK yang dibuat JS dan React.

Perhatikan jenis ConnectorConfig yang disertakan dalam impor umum.

// 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 '@dataconnect/generated';

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

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

Menggunakan kueri dan mutasi di klien React atau Angular

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

Dalam cuplikan berikut, perhatikan metode dengan awalan use useListAllMovies untuk React dan metode dengan awalan inject injectListAllMovies untuk Angular, keduanya dari SDK yang dibuat.

import { useListAllMovies } from '@dataconnect/generated/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 '@dataconnect/generated/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 untuk dimuat ulang secara otomatis saat data berubah.

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

Menghubungkan ke emulator SQL Connect

Jika ingin, Anda dapat menghubungkan ke emulator dengan memanggil connectDataConnectEmulator, lalu meneruskan SQL Connect instance ke hook yang dibuat, seperti berikut:

import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';
import { useListAllMovies } from '@dataconnect/generated/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;
}),

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

Memperbarui SDK saat membuat prototipe

Jika Anda telah menginstal ekstensi SQL Connect VS Code, ekstensi tersebut akan selalu memperbarui SDK yang dibuat.

Jika tidak menggunakan ekstensi SQL Connect VS Code, Anda dapat menggunakan Firebase CLI untuk memperbarui SDK yang dibuat.

firebase dataconnect:sdk:generate --watch

Membuat SDK dalam pipeline build

Anda dapat menggunakan Firebase CLI untuk membuat SQL Connect SDK dalam proses build CI/CD.

firebase dataconnect:sdk:generate