Memulai Firebase Data Connect

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

1. Jika belum melakukannya, buat project Firebase.
   1. Di Firebase console, klik Add project, lalu ikuti petunjuk di layar.

2. Upgrade project Anda ke paket Blaze. Ini memungkinkan Anda membuat instance Cloud SQL untuk PostgreSQL.

3. Buka bagian Data Connect di Firebase console dan ikuti alur kerja penyiapan produk.

4. Pilih lokasi bagi database CloudSQL untuk PostgreSQL Anda.

5. Catat nama serta ID project, layanan, dan database untuk mengonfirmasi nanti.

6. 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.

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.

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:

1. Buka direktori project Firebase di VS Code jika Anda belum melakukannya.
2. 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 Samping Utama

• 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:

Panel Bawah

• 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.

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").

Email

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.

1. Anda dapat menggunakan ekstensi Firebase VS Code untuk melakukan deployment.
   • Di UI ekstensi, pada panel Firebase Data Connect, klik Deploy.

2. Atau, Anda dapat menggunakan Firebase CLI.

   firebase deploy
   

3. 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.

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.

1. Temukan sumber yang dihasilkan otomatis di lokasi yang Anda tentukan sebelumnya dalam file connector.yaml.

2. 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.

3. Jika tidak menggunakan IDX, Anda dapat menyiapkan klien yang dapat dipanggil dari command line.

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 = {
  //...
};

initializeApp(firebaseConfig);

// Remove the following line to connect directly to production
connectDataConnectEmulator(
  getDataConnect(connectorConfig),
  "localhost",
  9399
);

listEmails().then(res => {
  console.log(res.data.emails);
  process.exit(0);
});
    

    node clientTest.js
    

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

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:

1. Di VS Code, di panel sebelah kiri, klik ikon Firebase untuk membuka UI ekstensi Firebase VS Code.
2. Klik tombol Connect to Local PostgreSQL.

Langkah berikutnya