Menggunakan Android SDK yang dihasilkan

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 alur pengembangan keseluruhan untuk SQL Connect. Dalam panduan ini, Anda akan menemukan informasi yang lebih mendetail tentang cara membuat Android SDK dari skema dan menggunakan kueri serta mutasi klien.

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

  1. Tambahkan Firebase ke aplikasi Android Anda.
  2. Konfigurasikan SQL Connect sebagai dependensi di Gradle.
  3. Tambahkan plugin Kotlin Serialization Gradle dan dependensi Gradle.

Kemudian:

  1. Mengembangkan skema aplikasi Anda.

  2. Siapkan pembuatan SDK:

  3. Lakukan inisialisasi kode klien dan impor library.

  4. Menerapkan panggilan ke kueri dan mutasi.

  5. Siapkan dan gunakan emulator SQL Connect, lalu lakukan iterasi.

Membuat SDK Kotlin

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

Mengupdate SDK saat membuat prototipe

Jika Anda telah menginstal ekstensi SQL Connect VS Code, 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 --watch

Membuat SDK di pipeline build

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

firebase dataconnect:sdk:generate

Menyiapkan kode klien

Menggabungkan SQL Connect ke dalam kode klien Anda

Untuk menyiapkan kode klien agar menggunakan SQL Connect dan SDK yang Anda buat, pertama-tama ikuti petunjuk penyiapan Firebase standar.

Kemudian, tambahkan kode berikut ke bagian plugins di app/build.gradle.kts:

// The Firebase team tests with version 1.8.22; however, other 1.8 versions,
// and all newer versions are expected work too.
kotlin("plugin.serialization") version "1.8.22" // MUST match the version of the Kotlin compiler

Kemudian, tambahkan kode berikut ke bagian dependencies di app/build.gradle.kts:

implementation(platform("com.google.firebase:firebase-bom:35.0.1"))
implementation("com.google.firebase:firebase-dataconnect")
implementation("com.google.firebase:firebase-auth") // Optional
implementation("com.google.firebase:firebase-appcheck") // Optional
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3") // Newer versions should work too
implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1") // Newer versions should work too

Melakukan inisialisasi SQL Connect Android SDK

Lakukan inisialisasi instance SQL Connect menggunakan informasi yang Anda gunakan untuk menyiapkan SQL Connect. Temukan informasi ini di halaman Databases & Storage > SQL Connect di Firebase console.

Objek ConnectorConfig

SDK memerlukan objek konfigurasi konektor.

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

Mendapatkan instance konektor

Setelah menyiapkan objek konfigurasi, dapatkan instance konektor SQL Connect. Kode untuk konektor Anda akan dibuat oleh emulator SQL Connect. Jika nama konektor Anda adalah movies dan paket Kotlin adalah com.myapplication, seperti yang ditentukan dalam connector.yaml, ambil objek konektor dengan memanggil:

val connector = com.myapplication.MoviesConnector.instance

Menggunakan kueri dan mutasi dari Android SDK Anda

Dengan objek konektor, Anda dapat menjalankan kueri dan mutasi seperti yang ditentukan dalam kode sumber GraphQL. Misalnya, konektor Anda memiliki operasi berikut yang ditentukan:

mutation createMovie($title: String!, $releaseYear: Int!, $genre: String!, $rating: Int!) {
  movie_insert(data: {
    title: $title
    releaseYear: $releaseYear
    genre: $genre
    rating: $rating
  })
}

query getMovieByKey($key: Movie_Key!) {
  movie(key: $key) { id title }
}

query listMoviesByGenre($genre: String!) {
  movies(where: {genre: {eq: $genre}}) {
    id
    title
  }
}

maka Anda dapat membuat dan mengambil film sebagai berikut:

val connector = MoviesConnector.instance

val addMovieResult1 = connector.createMovie.execute(
  title = "Empire Strikes Back",
  releaseYear = 1980,
  genre = "Sci-Fi",
  rating = 5
)

val movie1 = connector.getMovieByKey.execute(addMovieResult1.data.key)

println("Empire Strikes Back: ${movie1.data.movie}")

Anda juga dapat mengambil beberapa film:

val connector = MoviesConnector.instance

val addMovieResult2 = connector.createMovie.execute(
  title="Attack of the Clones",
  releaseYear = 2002,
  genre = "Sci-Fi",
  rating = 5
)

val listMoviesResult = connector.listMoviesByGenre.execute(genre = "Sci-Fi")

println(listMoviesResult.data.movies)

Anda juga dapat mengumpulkan Flow yang hanya akan menghasilkan hasil saat hasil kueri baru diambil menggunakan panggilan ke metode execute() kueri.

val connector = MoviesConnector.instance

connector.listMoviesByGenre.flow(genre = "Sci-Fi").collect { data ->
  println(data.movies)
}

connector.createMovie.execute(
  title="A New Hope",
  releaseYear = 1977,
  genre = "Sci-Fi",
  rating = 5
)

connector.listMoviesByGenre.execute(genre = "Sci-Fi") // will cause the Flow to get notified

Berlangganan perubahan real-time

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.

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 terbaru klien, klien lama yang di-deploy mungkin akan rusak.

Contoh implementasi yang tangguh

SDK yang dihasilkan memaksa penanganan nilai yang tidak diketahui karena kode pelanggan harus membuka objek EnumValue, yang berupa EnumValue.Known untuk nilai enum yang diketahui atau EnumValue.Unknown untuk nilai yang tidak diketahui.

val result = connector.listMoviesByAspectRatio.execute(AspectRatio.WIDESCREEN)
val encounteredAspectRatios = mutableSetOf<String>()

result.data.movies
  .mapNotNull { it.otherAspectRatios }
  .forEach { otherAspectRatios ->
    otherAspectRatios
      .filterNot { it.value == AspectRatio.WIDESCREEN }
      .forEach {
        when (it) {
          is EnumValue.Known -> encounteredAspectRatios.add(it.value.name)
          is EnumValue.Unknown ->
            encounteredAspectRatios.add("[unknown ratio: ${it.stringValue}]")
        }
      }
  }

println(
  "Widescreen movies also include additional aspect ratios: " +
    encounteredAspectRatios.sorted().joinToString()
)

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:
  kotlinSdk:
    outputDir: "../android"
    package: "com.google.firebase.dataconnect.generated"
    clientCache:
      maxAge: 5s
      storage: persistent

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 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 execute().

  • storage: SDK klien dapat dikonfigurasi untuk meng-cache respons di penyimpanan persistent atau di memory. Hasil yang di-cache di penyimpanan persistent akan tetap ada setiap kali aplikasi dimulai ulang. Di Android SDK, defaultnya adalah persistent.

Setelah memperbarui konfigurasi caching konektor, buat ulang SDK klien dan bangun ulang aplikasi Anda. Setelah Anda melakukannya, execute() 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 execute() 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 pemanggilan execute() satu per satu untuk hanya menyajikan nilai yang di-cache (CACHE_ONLY) atau untuk mengambil nilai baru tanpa syarat dari server (SERVER_ONLY).

    val queryResult = queryRef.execute(QueryRef.FetchPolicy.CACHE_ONLY)

    val queryResult = queryRef.execute(QueryRef.FetchPolicy.SERVER_ONLY)

    Membuat prototipe dan menguji aplikasi Android Anda

    Menginstrumentasikan klien untuk menggunakan emulator lokal

    Anda dapat menggunakan emulator SQL Connect, baik dari ekstensi VS Code SQL Connect maupun dari CLI.

    Melakukan instrumentasi aplikasi untuk terhubung ke emulator sama untuk kedua skenario.

    val connector = MoviesConnector.instance

// Connect to the emulator on "10.0.2.2:9399"
connector.dataConnect.useEmulator()

// (alternatively) if you're running your emulator on non-default port:
connector.dataConnect.useEmulator(port = 9999)

// Make calls from your app

    Untuk beralih ke resource produksi, jadikan baris untuk menghubungkan ke emulator sebagai komentar.

    Jenis SQL di SQL Connect SDK

    Server SQL Connect mewakili jenis data GraphQL umum dan kustom. Hal ini direpresentasikan dalam SDK sebagai berikut.

    Jenis SQL Connect Kotlin
    String String
    Int Int (bilangan bulat 32-bit)
    Float Double (float 64-bit)
    Boolean Boolean
    UUID java.util.UUID
    Tanggal com.google.firebase.dataconnect.LocalDate (sebelumnya java.util.Date hingga 16.0.0-beta03)
    Stempel waktu com.google.firebase.Timestamp
    Int64 Long
    Semua com.google.firebase.dataconnect.AnyValue