Menggunakan Android SDK 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 harus men-deploy perubahan sisi klien yang sesuai untuk menghindari gangguan pada pengguna yang ada (misalnya, pada versi aplikasi lama).

Itulah sebabnya SQL Connect menyediakan lingkungan dan alat developer yang memungkinkan Anda membuat prototipe skema, kueri, dan mutasi yang di-deploy server. SQL Connect juga membuat SDK sisi klien 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 Android SDK dari skema dan penggunaan kueri dan mutasi klien.

Singkatnya, untuk menggunakan Android SDK yang dibuat 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 Gradle Serialisasi Kotlin dan dependensi Gradle.

Kemudian:

  1. Kembangkan skema aplikasi Anda.

  2. Siapkan pembuatan SDK:

  3. Lakukan inisialisasi kode klien dan impor library.

  4. Terapkan panggilan ke kueri dan mutasi.

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

Buat SDK Kotlin

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

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

Menyiapkan kode klien

Menggabungkan SQL Connect ke dalam kode klien

Untuk menyiapkan kode klien agar menggunakan SQL Connect dan SDK yang dibuat, ikuti terlebih dahulu 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:34.12.0"))
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 (semua tersedia di tab SQL Connect konsol Firebase).

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 SQL Connect konektor. Kode untuk konektor Anda akan dibuat oleh the SQL Connect emulator. 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

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

Kemudian, 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

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

Contoh penerapan yang tangguh

SDK yang dibuat akan memaksa penanganan nilai yang tidak diketahui karena kode pelanggan harus meng-unwrap 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 cache sisi klien

SQL Connect memiliki fitur cache sisi klien opsional, yang Anda dapat aktifkan dengan mengedit file connector.yaml. Jika fitur ini diaktifkan, SDK klien yang dibuat akan menyimpan respons kueri dalam cache 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 cache sisi klien, tambahkan konfigurasi cache 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 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 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 Android SDK, nilai defaultnya adalah persistent.

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

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

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

    Membuat prototipe dan menguji aplikasi Android

    Menginstrumentasi klien untuk menggunakan emulator lokal

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

    Menginstrumentasi 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, beri komentar pada baris untuk menghubungkan ke emulator.

    Jenis SQL di SQL Connect SDK

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

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