Dengan SDK klien Firebase SQL Connect, Anda dapat memanggil kueri dan mutasi sisi server langsung dari aplikasi Firebase. Anda membuat SDK klien kustom secara paralel saat mendesain skema, kueri, dan mutasi yang di-deploy ke layanan SQL Connect. Kemudian, Anda mengintegrasikan metode dari SDK ini ke dalam logika klien Anda.
Seperti yang telah kami sebutkan di bagian lain, perlu diperhatikan bahwa SQL Connect kueri dan mutasi tidak dikirimkan oleh kode klien dan dieksekusi di server. Sebagai gantinya, saat di-deploy, operasi SQL 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, pada versi aplikasi yang lebih lama).
Itulah sebabnya SQL Connect menyediakan lingkungan pengembangan dan alat developer yang memungkinkan Anda membuat prototipe skema, kueri, dan mutasi yang di-deploy di server. Cloud Endpoints juga membuat SDK sisi klien secara otomatis, saat Anda membuat prototipe.
Setelah Anda mengulangi update pada aplikasi layanan dan klien, update sisi server dan klien siap di-deploy.
Bagaimana alur kerja pengembangan klien?
Jika Anda mengikuti Memulai, Anda akan diperkenalkan dengan keseluruhan alur pengembangan untuk SQL Connect. Dalam panduan ini, Anda akan menemukan informasi yang lebih mendetail tentang cara membuat Web SDK dari skema Anda serta menggunakan kueri dan mutasi klien.
Singkatnya, untuk menggunakan Web SDK yang dihasilkan di aplikasi klien, Anda harus mengikuti langkah-langkah prasyarat berikut:
- Tambahkan Firebase ke aplikasi web Anda.
Kemudian:
- Mengembangkan skema aplikasi Anda.
- Lakukan inisialisasi kode klien Anda dengan JavaScript SDK.
- Siapkan pembuatan SDK:
- Dengan tombol Add SDK to app di ekstensi VS Code SQL Connect.
- Dengan mengupdate
connector.yamluntuk JavaScript SDK.
- Impor library dan kode yang dihasilkan dengan JavaScript SDK.
- Terapkan panggilan ke kueri dan mutasi dengan JavaScript SDK.
- Uji, dengan menyiapkan emulator SQL Connect menggunakan JavaScript SDK.
Mengimplementasikan kode klien dengan Firebase JavaScript SDK
Bagian ini membahas cara menerapkan klien menggunakan Firebase JavaScript SDK.
Jika Anda menggunakan React atau Angular, lihat petunjuk penyiapan alternatif dan link ke dokumentasi tambahan tentang membuat SDK SQL Connect untuk framework.
Inisialisasi aplikasi Anda
Pertama, lakukan inisialisasi aplikasi Anda menggunakan urutan Firebase standar.
initializeApp({...});
Menginstal JavaScript SDK yang dihasilkan
Gunakan Firebase CLI untuk menyiapkan SDK yang dihasilkan SQL Connect di aplikasi Anda.
Perintah init akan mendeteksi semua aplikasi di folder saat ini dan menginstal
SDK yang dihasilkan 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);
Mengupdate SDK saat membuat prototipe
Jika Anda telah menginstal ekstensi VS Code SQL Connect, ekstensi ini akan selalu memperbarui SDK yang dihasilkan.
Jika tidak menggunakan ekstensi VS Code SQL Connect, Anda dapat menggunakan Firebase CLI untuk terus memperbarui SDK yang dihasilkan.
firebase dataconnect:sdk:generate --watchMembuat SDK di pipeline build
Anda dapat menggunakan Firebase CLI untuk membuat SDK SQL Connect dalam proses build CI/CD.
firebase dataconnect:sdk:generateMengimpor library
Ada dua set impor yang diperlukan untuk melakukan inisialisasi kode klien Anda: impor SQL Connect umum dan impor SDK yang dihasilkan secara spesifik.
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 dihasilkan akan dilengkapi dengan Referensi Kueri yang telah ditentukan sebelumnya. Anda hanya perlu mengimpor dan memanggil eksekusi pada model tersebut.
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 info terbaru secara real-time dari SQL Connect.
Menangani perubahan pada kolom enumerasi
Skema aplikasi dapat berisi enumerasi, yang dapat diakses oleh kueri GraphQL Anda.
Seiring perubahan desain aplikasi, Anda dapat menambahkan nilai yang didukung enum yang 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 developer lokal untuk memperbarui kueri dan SDK.
Namun, sebelum Anda merilis versi klien yang diupdate, klien lama yang di-deploy mungkin akan rusak.
Contoh implementasi yang tangguh
Selalu tambahkan cabang default ke pernyataan switch di 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 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 '@dataconnect/generated';
const { data } = await executeMutation(createMovieRef({ movie: 'Empire Strikes Back' }));
Menghubungkan ke emulator SQL Connect
Atau, Anda dapat terhubung ke emulator dengan memanggil
connectDataConnectEmulator, lalu meneruskan instance SQL Connect,
seperti ini:
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, jadikan baris untuk menghubungkan ke emulator sebagai komentar.
Mengaktifkan caching sisi klien
SQL Connect memiliki fitur caching sisi klien opsional, yang dapat Anda aktifkan dengan mengedit file connector.yaml. Jika fitur ini diaktifkan,
SDK klien yang dihasilkan akan meng-cache respons kueri secara lokal, 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 bersifat opsional:
maxAge: Usia maksimum respons yang di-cache sebelum SDK klien mengambil nilai baru. Contoh: "0", "30s", "1h30m".Nilai default untuk
maxAgeadalah0, yang berarti respons di-cache, tetapi SDK klien akan selalu mengambil nilai baru. Nilai yang di-cache hanya akan digunakan jikaCACHE_ONLYditentukan keexecuteQuery()dan hasil awal ditampilkan darisubscribe().storage: SDK klien dapat dikonfigurasi untuk meng-cache respons di penyimpananpersistentatau dimemory. Hasil yang di-cache di penyimpananpersistentakan dipertahankan setiap kali aplikasi dimulai ulang. Di SDK web, hanya penyimpananmemoryyang didukung.
Setelah memperbarui konfigurasi caching konektor, buat ulang SDK klien dan build ulang aplikasi Anda. Setelah melakukannya, executeQuery() dan subscribe() akan meng-cache respons 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 darimaxAge, gunakan nilai yang di-cache. Perilaku default ini disebut kebijakanPREFER_CACHE.Anda juga dapat menentukan pemanggilan
executeQuery()satu per satu untuk hanya menyajikan nilai yang di-cache (CACHE_ONLY) atau untuk mengambil nilai baru tanpa syarat dari server (SERVER_ONLY).await executeQuery(queryRef, QueryFetchPolicy.CACHE_ONLY);await executeQuery(queryRef, QueryFetchPolicy.SERVER_ONLY);Saat Anda memanggil
subscribe(), konten yang di-cache akan selalu segera ditampilkan jika ada, terlepas dari setelanmaxAge. Panggilan berikutnya keexecuteQuery()akan memberi tahu pemroses sesuai denganmaxAgeyang dikonfigurasi.
Jenis data di SDK
Server SQL Connect mewakili jenis data GraphQL umum. Hal ini direpresentasikan dalam SDK sebagai berikut.
| Jenis SQL Connect | TypeScript |
|---|---|
| Stempel waktu | string |
| Tanggal | string |
| UUID | string |
| Int64 | string |
| Ganda | Angka |
| Float | Angka |
Membuat SDK React dan Angular dengan TanStack
Firebase SQL Connect menyediakan SDK yang dihasilkan 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.
TanStack dilengkapi dengan implementasi caching sisi klien dan langganan real-time-nya sendiri, yang dapat berfungsi bersama dukungan real-time bawaan SQL Connect, tetapi dengan beberapa kesulitan. Sebaiknya gunakan binding berbasis TanStack atau dukungan real-time bawaan SQL Connect, tetapi bukan keduanya.
Perhatikan bahwa implementasi real-time SQL Connect sendiri memiliki beberapa keunggulan dibandingkan binding TanStack:
- Caching yang dinormalisasi: SQL Connect mengimplementasikan caching yang dinormalisasi, yang meningkatkan konsistensi data serta efisiensi memori dan jaringan dibandingkan dengan caching tingkat kueri. Dengan caching yang dinormalisasi, jika suatu entity diperbarui di satu area aplikasi, entity tersebut juga akan diperbarui di area lain yang menggunakan entity tersebut.
- Invalidasi jarak jauh: SQL Connect dapat membatalkan validasi entity yang di-cache dari jarak jauh di semua perangkat yang berlangganan.
Inisialisasi aplikasi Anda
Pertama, seperti aplikasi web Firebase lainnya, lakukan inisialisasi aplikasi Anda menggunakan urutan Firebase standar.
initializeApp({...});
Menginstal paket Firebase TanStack Query
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 halnya SDK web standar, seperti yang dijelaskan sebelumnya, alat Firebase menangani pembuatan SDK otomatis berdasarkan skema dan operasi Anda.
Jika Anda baru saja menambahkan React atau Angular ke project, jalankan kembali firebase init dataconnect:sdk
untuk mengonfigurasi ulang SDK yang dihasilkan agar menyertakan binding framework tambahan.
Mengimpor library
Ada empat set impor yang diperlukan untuk melakukan inisialisasi kode klien React atau Angular Anda: impor SQL 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 '@dataconnect/generated';
// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@dataconnect/generated/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 '@dataconnect/generated';
// generated React hooks from SDK
import { injectListAllMovies, injectCreateMovie } from "@dataconnect/generated/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 useListAllMovies dengan awalan use untuk
React dan metode injectListAllMovies dengan awalan inject untuk Angular, keduanya
dari SDK yang dihasilkan.
Reaksi
Semua operasi tersebut di SDK yang dihasilkan, baik kueri maupun mutasi, memanggil binding TanStackQuery:
- Kueri memanggil dan menampilkanhook
useDataConnectQueryTanStack - Mutasi memanggil dan menampilkan hook
useDataConnectMutationTanStack
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>
}
Angular
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 agar otomatis dimuat ulang 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 SQL Connect
Secara opsional, Anda dapat terhubung ke emulator dengan memanggil
connectDataConnectEmulator, lalu meneruskan instance SQL Connect
ke hook yang dihasilkan, seperti ini:
Reaksi
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);
...
}
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, jadikan baris untuk menghubungkan ke emulator sebagai komentar.
Mengupdate SDK saat membuat prototipe
Jika Anda telah menginstal ekstensi VS Code SQL Connect, ekstensi ini akan selalu memperbarui SDK yang dihasilkan.
Jika tidak menggunakan ekstensi VS Code SQL Connect, Anda dapat menggunakan Firebase CLI untuk terus memperbarui SDK yang dihasilkan.
firebase dataconnect:sdk:generate --watchMembuat SDK di pipeline build
Anda dapat menggunakan Firebase CLI untuk membuat SDK SQL Connect dalam proses build CI/CD.
firebase dataconnect:sdk:generate