Dalam panduan memulai ini, Anda akan mempelajari cara:
- Tambahkan Firebase Data Connect ke project Firebase Anda.
- Siapkan lingkungan pengembangan yang menyertakan ekstensi Kode Visual Studio agar berfungsi dengan instance produksi.
- Kemudian, kami akan menunjukkan cara:
- Buat skema menggunakan contoh aplikasi email.
- Tentukan kueri dan mutasi untuk skema Anda.
- Gunakan SDK yang dibuat secara otomatis untuk memanggil kueri dan mutasi ini dari klien Anda.
- Deploy prototipe akhir Anda ke tahap produksi.
Prasyarat
Untuk menggunakan panduan memulai ini, Anda akan memerlukan hal berikut.
- Linux, macOS, atau Windows
- Kode Visual Studio
Menambahkan Data Connect ke project Anda dan membuat sumber data
- Jika belum melakukannya, buat project Firebase.
- Di Firebase console, klik Add project, lalu ikuti petunjuk di layar.
Upgrade project Anda ke paket Blaze. Ini memungkinkan Anda membuat instance Cloud SQL untuk PostgreSQL.
Buka bagian Data Connect di Firebase console dan ikuti alur kerja penyiapan produk.
Pilih lokasi bagi database CloudSQL untuk PostgreSQL Anda.
Catat nama serta ID project, layanan, dan database untuk mengonfirmasi nanti.
Ikuti alur penyiapan yang tersisa, lalu klik Selesai.
Memilih dan menyiapkan lingkungan pengembangan
Anda akan memulai Data Connect dengan membuat prototipe aplikasi di Kode Visual Studio.
Secara opsional, Anda dapat menginstal database PostgreSQL lokal untuk pengembangan lokal dengan emulator Data Connect. Penyiapan ini dibahas di bagian akhir panduan memulai ini.
Data Connect mendukung dua pengalaman pengembangan untuk pembuatan prototipe:
- Jika Anda adalah developer web atau Kotlin Android, Anda dapat membuat prototipe skema dan operasi secara lokal saat terhubung ke instance Cloud SQL untuk PostgreSQL, atau (opsional) menjalankan PostgreSQL secara lokal.
Jika Anda developer web, Anda dapat menggunakan IDX untuk membuat prototipe di ruang kerja IDX menggunakan template IDX yang telah dikonfigurasi sebelumnya dengan PostgreSQL, ekstensi VS Code dengan emulator Data Connect, dan kode panduan memulai yang disiapkan untuk Anda.
Pengembangan VS Code
Jika Anda ingin mengembangkan aplikasi secara lokal, bukan menggunakan IDX, siapkan ekstensi Firebase VS Code untuk membantu Anda melakukan iterasi pengembangan secara cepat dengan pembuatan SDK untuk web, Kotlin Android, dan, yang akan segera hadir, iOS.
- Buat direktori baru untuk project lokal Anda.
- Buka VS Code di direktori baru.
- Download ekstensi, yang dipaketkan sebagai paket VSIX, dari Firebase Storage.
- Di VS Code, dari menu Lihat, pilih Ekstensi.
- Di panel judul panel Ekstensi, klik ikon menu more_horiz, lalu ikuti Instal dari VSIX....
Pengembangan IDX
IDX adalah lingkungan yang dioptimalkan untuk pengembangan aplikasi web. Jika Anda adalah developer Android Kotlin, ikuti langkah-langkah pada tab Pengembangan VS Code.
Untuk menyiapkan template IDX Data Connect:
- Akses template di situs Project IDX.
- Ikuti alur penyiapan.
Menyiapkan project lokal
Instal CLI, dengan mengikuti petunjuk biasa.
Kemudian, aktifkan eksperimen Firebase Data Connect.
firebase experiments:enable dataconnect
Untuk menyiapkan project lokal, kami akan menginisialisasi direktori project Anda dan memperbarui beberapa file konfigurasi yang diperlukan untuk pembuatan kode.
Menyiapkan direktori project
Inisialisasi direktori project Anda.
Penyiapan ekstensi Firebase
Di panel sebelah kiri VS Code, klik ikon Firebase untuk membuka UI ekstensi Firebase VS Code.
Di UI ekstensi Firebase:
- Pastikan Anda telah login.
- Di Firebase console, pastikan alur penyiapan Data Connect, termasuk penyediaan database, telah selesai.
- Klik tombol Run firebase init.
- Periksa tab Terminal di Panel bawah VS Code untuk melihat perintah.
- Pilih Data Connect sebagai fitur untuk digunakan dalam direktori ini.
- Jika diminta, berikan ID project, layanan, dan database dari project Data Connect yang Anda buat sebelumnya di konsol.
Penyiapan terminal
- Jika perlu, login menggunakan
firebase login
. - Di Firebase console, pastikan alur penyiapan Data Connect, termasuk penyediaan database, telah selesai.
- Jalankan
firebase init
untuk menginisialisasi direktori Anda sebagai project Firebase, dengan mengikuti petunjuk di layar. - Pilih Data Connect sebagai fitur untuk digunakan dalam direktori ini.
- Jika diminta, berikan ID project, layanan, dan database dari project Data Connect yang Anda buat sebelumnya di konsol.
Kedua alur tersebut akan membuat file firebase.json
dan .firebaserc
, serta subdirektori dataconnect
, termasuk file dataconnect.yaml
dan connector.yaml
penting dalam direktori kerja lokal Anda.
Mengonfigurasi tempat kode SDK dibuat
Data Connect secara otomatis menghasilkan kode SDK saat Anda mengedit skema.
Untuk menentukan tempat SDK dibuat, perbarui file untuk konektor
awal Anda, di dataconnect/connector/connector.yaml
.
connectorId: "my-connector"
authMode: "PUBLIC"
generate:
javascriptSdk:
outputDir: "../../js-email-generated"
package: "@email-manager/emails"
packageJsonDir: "../../"
kotlinSdk:
outputDir: "../kotlin-email-generated"
package: com.myemailapplication
Memahami Toolkit Data Connect
Data Connect Toolkit adalah komponen ekstensi Firebase VS Code yang membantu pengembangan skema serta pengelolaan kueri dan mutasi, langsung dari Visual Studio Code.
Untuk melihat fitur Toolkit:
- Buka direktori project Firebase di VS Code jika Anda belum melakukannya.
- Di VS Code, di panel sebelah kiri, klik ikon Firebase untuk membuka UI ekstensi Firebase VS Code.
Selama pekerjaan pengembangan, perhatikan bahwa dengan Toolkit ini, Anda dapat berinteraksi dengan lingkungan lokal serta dengan resource produksi. Dalam panduan memulai ini, Anda akan berinteraksi dengan lingkungan produksi.
UI ekstensi memberi Anda beberapa fitur yang berguna:
Pada VS Code {i>Primary Side Bar<i}:
- Panel Config, yang memungkinkan Anda login ke Google dan memilih project Firebase.
- Panel Firebase Data Connect yang memungkinkan Anda mengontrol emulator bawaan dan men-deploy resource ke produksi.
- Panel FDC Explorer, yang mencantumkan kueri dan mutasi implisit yang dihasilkan secara otomatis berdasarkan skema Anda
Pada Panel bawah VS Code:
- Tab Eksekusi Data Connect, dengan alat yang memungkinkan Anda meneruskan data dalam permintaan, meniru autentikasi, dan melihat hasil.
Sebelum kita mulai mengembangkan aplikasi, lihat beberapa fitur ekstensi.
Mencoba CodeLens kustom | Saat Anda menggunakan resource dalam file schema.gql , queries.gql , dan mutations.gql , setelah Anda menulis blok kode secara sintaksis untuk melengkapi, CodeLens kustom akan menampilkan tindakan yang dapat Anda lakukan pada tabel dan operasi yang dideklarasikan.
|
Menetapkan tingkat autentikasi untuk permintaan | Di panel bawah, panel Eksekusi Data Connect menyediakan tab Configuration tempat Anda dapat memilih tingkat autentikasi yang disimulasikan untuk operasi. |
Mengisi variabel dalam kueri dan mutasi | Di tab Configuration yang sama, Anda bisa mengisi payload operasi. |
Memeriksa histori, respons, dan error | Selain itu, di tab Configuration, Anda dapat memeriksa tab History dan Results untuk mengetahui informasi proses debug. |
Membuat skema dan kueri Data Connect
Penyiapan selesai. Sekarang kita dapat mulai mengembangkan aplikasi dengan Data Connect.
Mulai gunakan GraphQL untuk membuat model pengguna dan email. Anda akan memperbarui sumber di:
/dataconnect/schema/schema.gql
/dataconnect/connector/queries.gql
Mulai mengembangkan skema
Di direktori project Firebase, catat folder dataconnect
. Di sinilah Anda menentukan model data untuk database Cloud SQL menggunakan GraphQL.
Dalam file /dataconnect/schema/schema.gql
, mulai tentukan skema yang
menyertakan pengguna dan email.
Pengguna
Di Data Connect, kolom GraphQL dipetakan ke kolom. Pengguna memiliki uid
,
name
, dan email address
. Data Connect mengenali beberapa jenis data
primitif: String
dan Date
.
Salin cuplikan berikut atau hapus tanda komentar pada baris yang sesuai dalam file.
# File `/dataconnect/schema/schema.gql`
type User @table(key: "uid") {
uid: String!
name: String!
address: String!
}
Secara default, Firebase Data Connect akan menambahkan kunci id
UUID jika tidak ada yang disediakan. Namun, dalam hal ini Anda ingin uid
saya menjadi kunci utama, yang
dapat Anda lakukan melalui perintah @table(key: "uid")
.
Setelah memiliki pengguna, Anda dapat membuat model email. Di sini Anda dapat menambahkan kolom umum (atau kolom) untuk data email. Kali ini, kami tidak menambahkan kunci utama karena Anda dapat mengandalkan Data Connect untuk mengelolanya.
# File `/dataconnect/schema/schema.gql`
type Email @table {
subject: String!
date: Date!
text: String!
from: User!
}
Perhatikan bahwa kolom from
dipetakan ke jenis User
.
Data Connect memahami bahwa ini adalah hubungan antara Email
dan User
, dan akan mengelola hubungan ini untuk Anda.
Men-deploy skema ke produksi
Karena Anda menggunakan ekstensi Firebase VS Code untuk bekerja dengan database produksi, Anda harus men-deploy skema sebelum melanjutkan.
- Anda dapat menggunakan ekstensi Firebase VS Code untuk melakukan deployment.
- Di UI ekstensi, pada panel Firebase Data Connect, klik Deploy.
Atau, Anda dapat menggunakan Firebase CLI.
firebase deploy
Dalam alur ekstensi atau CLI, Anda mungkin perlu meninjau perubahan skema dan menyetujui perubahan yang berpotensi merusak. Anda akan diminta untuk:
- Tinjau perubahan skema menggunakan
firebase dataconnect:sql:diff
- Jika Anda sudah puas dengan perubahannya, terapkan perubahan tersebut menggunakan alur yang dimulai oleh
firebase dataconnect:sql:migrate
.
- Tinjau perubahan skema menggunakan
Melihat ekstensi skema yang dihasilkan
Saat Anda mengedit skema email, Data Connect otomatis menghasilkan ekstensi skema, kueri, mutasi, filter, dan relasi tabel. Anda dapat melihat kode yang dihasilkan ini dengan dua cara.
- Anda dapat melihat daftar kueri dan mutasi implisit yang dihasilkan di UI ekstensi Firebase, pada panel FDC Explorer.
- Anda dapat melihat semua kode lokal yang dihasilkan dalam sumber dalam direktori
.dataconnect/schema
.
Jalankan mutasi untuk menambahkan data ke tabel Anda
Anda dapat melihat tombol CodeLens muncul pada jenis GraphQL di /dataconnect/schema/schema.gql
.
Kueri dan mutasi waktu pengembangan
Operasi yang terkait dengan tombol CodeLens ini adalah tindakan cepat dan berguna, dalam hal ini, menambahkan data ke tabel. Data Connect menggunakan mutasi GraphQL untuk menjelaskan bagaimana dan siapa yang dapat beroperasi terhadap database. Dengan menggunakan tombol ini, kode ini akan membuat operasi waktu pengembangan untuk penyempitan data dengan cepat.
Setelah men-deploy skema ke produksi, Anda dapat menggunakan tombol CodeLens Jalankan (Produksi) untuk melakukan tindakan ini pada backend Anda.
Menulis kueri untuk membuat daftar email
Sekarang bagian yang menyenangkan, kueri. Sebagai developer, Anda sudah terbiasa menulis kueri SQL daripada kueri GraphQL, jadi awalnya mungkin akan terasa sedikit berbeda. Namun, GraphQL jauh lebih singkat dan aman dari jenis SQL daripada SQL mentah. Dan ekstensi VS Code kami memudahkan pengalaman pengembangan.
Mulai edit file /dataconnect/connector/queries.gql
. Jika Anda ingin mendapatkan
semua email, gunakan kueri seperti ini.
# File `/dataconnect/connector/queries.gql`
query listEmails @auth(level: PUBLIC) {
emails {
id, subject, text, date
from {
name
}
}
}
Fitur yang sangat menarik di sini adalah kemampuan untuk memperlakukan hubungan database seperti grafik. Karena Email memiliki kolom from
yang merujuk ke Pengguna, Anda dapat menyarangkan kolom tersebut dan mendapatkan kembali informasi tentang pengguna.
perintah @auth
Perintah @auth
tidak digunakan secara maksimal dalam contoh ini,
tetapi konsepnya sangat efektif. Ini adalah cara Anda memutuskan kebijakan
otorisasi untuk operasi terhadap {i>database<i}.
Kueri ini cukup sederhana. Fitur Data Connect yang sebenarnya dan menarik mulai tampak saat Anda melakukan penggabungan yang lebih kompleks dengan hubungan many-to-many. Anda akan mempelajari lebih lanjut tentang hal ini saat menjelajahi alat dan dokumentasi.
Menguji kueri Anda
Setelah kueri ini dibuat, periksa apakah kueri tersebut berfungsi sebelum mengintegrasikannya ke dalam kode klien. Salah satu bagian dari pengalaman developer untuk Data Connect adalah kemampuan untuk melakukan iterasi dan menguji hasil kueri dengan cepat menggunakan panel Eksekusi Data Connect.
Anda dapat memberikan argumen yang diperlukan kueri ini, lalu mengklik tombol CodeLens di atas nama kueri. Tindakan ini akan mengeksekusi kueri dan menampilkan hasilnya, sehingga Anda dapat melihat bahwa kueri ini berfungsi seperti yang diharapkan.
Membuat kode SDK klien dan mengkueri data dari aplikasi klien
Untuk menutup siklus pengembangan, integrasikan kueri ini ke dalam kode klien.
Anda dapat menulis klien untuk mendemonstrasikan pemanggilan kueri dan penanganan balasan dari layanan Data Connect.
- Temukan sumber yang dihasilkan otomatis di lokasi yang Anda tentukan
sebelumnya dalam file
connector.yaml
. Tambahkan Firebase ke project Anda, daftarkan aplikasi Anda, dan instal Firebase core SDK yang relevan:
- Untuk JavaScript, ikuti petunjuk ini.
- Untuk Kotlin, ikuti petunjuk ini.
Jika tidak menggunakan IDX, Anda dapat menyiapkan klien yang dapat dipanggil dari command line.
JavaScript
Buat file sumber, clientTest.js
, dan salin kode berikut.
const { initializeApp } = require("firebase/app"); const { connectDataConnectEmulator, getDataConnect, } = require("firebase/data-connect"); const { listEmails, connectorConfig } = require("@email-manager/emails"); // TODO: Replace the following with your app's Firebase project configuration const firebaseConfig = { //... }; const app = initializeApp(firebaseConfig); const dc = getDataConnect(app, connectorConfig); // Remove the following line to connect directly to production connectDataConnectEmulator(dc, "localhost", 9399); listEmails().then(res => { console.log(res.data.emails); process.exit(0); });
Dan Anda dapat menjalankan klien Anda.
node clientTest.js
Android Kotlin
Buat file sumber, clientTest.kt
, dan salin kode berikut.
class MainActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) lifecycleScope.launch { val connector = MyConnector.instance connector.dataConnect.useEmulator() // Remove to connect to production try { println(connector.listEmails.execute().data.emails) } catch (e: Throwable) { println("ERROR: $e") } } } }
Kemudian:
- Jalankan Aktivitas.
- Periksa output logcat Android.
Men-deploy prototipe yang telah selesai ke tahap produksi
Anda telah menyelesaikan iterasi pengembangan. Sekarang Anda dapat men-deploy skema, data, kueri, dan mutasi ke server dengan UI ekstensi Firebase atau Firebase CLI, seperti yang Anda lakukan dengan skema.
Setelah di-deploy, layanan Data Connect Anda akan siap untuk memproses operasi dari klien. Instance Cloud SQL untuk PostgreSQL akan diupdate dengan skema dan data akhir yang di-deploy dan dihasilkan.
(Opsional) Menginstal PostgreSQL secara lokal
Dengan menginstal PostgreSQL secara lokal dan mengintegrasikannya dengan emulator, Anda dapat membuat prototipe di lingkungan pengembangan yang sepenuhnya lokal.
Anda dapat menginstal instance baru PostgreSQL atau menggunakan instance yang sudah ada.
Menginstal PostgreSQL
Instal PostgreSQL versi 15.x dengan mengikuti petunjuk untuk platform Anda.
- macOS. Download dan instal Postgres.app.
- Windows: Gunakan penginstal EDB dari halaman download PostgreSQL.
- Docker: Tarik lalu jalankan
gambar
pgvector/pgvector:15
, yang dilengkapi dengan dukungan PostgreSQL 15.x dan vektor. - Linux: Sebaiknya gunakan Docker dengan image sebelumnya, tetapi Anda juga dapat mengikuti petunjuk alternatif untuk distribusi populer.
Catat nama host, port, nama pengguna, dan sandi, serta output parameter terkait selama urutan penginstalan.
Untuk terhubung ke instance PostgreSQL, emulator memerlukan:
- Parameter konfigurasi penyiapan ini
- Nama database dari
dataconnect.yaml
dan database dengan nama yang sesuai yang diinisialisasi dalam instance lokal.
Mengupdate .firebaserc
dengan string koneksi
Gunakan detail konfigurasi PostgreSQL lokal Anda, termasuk nama pengguna dan sandi PostgreSQL lokal Anda, untuk string koneksi yang akan ditambahkan ke kunci berikut dalam file .firebaserc
Anda.
{
"projects": {},
...,
...,
"dataconnectEmulatorConfig": {
"postgres": {
"localConnectionString": "postgresql://postgresusername:postgrespassword@localhost:5432?sslmode=disable"
}}
}
Menghubungkan ke instance PostgreSQL lokal
Setelah konfigurasi ini selesai, untuk terhubung ke database lokal Anda:
- Di VS Code, di panel sebelah kiri, klik ikon Firebase untuk membuka UI ekstensi Firebase VS Code.
- Klik tombol Connect to Local PostgreSQL.