Dengan SDK klien Firebase Data Connect, Anda dapat memanggil kueri dan mutasi sisi server secara langsung dari aplikasi Firebase. Anda membuat SDK klien kustom secara paralel saat mendesain skema, kueri, dan mutasi yang di-deploy ke layanan Data Connect. Kemudian, Anda mengintegrasikan metode dari SDK ini ke dalam logika klien Anda.
Seperti yang telah kami sebutkan di tempat lain, penting untuk diperhatikan bahwa kueri dan mutasi tidak dikirimkan oleh kode klien dan dieksekusi di server.Data Connect Sebagai gantinya, saat di-deploy, operasi Data Connect disimpan di server seperti Cloud Functions. Artinya, Anda perlu men-deploy perubahan sisi klien yang sesuai untuk menghindari gangguan pada pengguna yang sudah ada (misalnya, di versi aplikasi yang lebih lama).
Itulah sebabnya Data Connect menyediakan lingkungan dan alat developer yang memungkinkan Anda membuat prototipe skema, kueri, dan mutasi yang di-deploy server. Selain itu, SDK sisi klien juga dibuat 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 alur kerja pengembangan klien?
Jika Anda mengikuti Mulai, Anda telah diperkenalkan dengan alur pengembangan keseluruhan untuk Data Connect. Dalam panduan ini, Anda akan menemukan informasi yang lebih mendetail tentang cara membuat Swift SDK dari skema Anda dan cara menggunakan kueri dan mutasi klien.
Singkatnya, untuk menggunakan SDK Swift yang dihasilkan di aplikasi klien, Anda harus mengikuti langkah-langkah prasyarat berikut:
- Tambahkan Firebase ke aplikasi iOS Anda.
Untuk menggunakan SDK yang dihasilkan, konfigurasikan sebagai dependensi di Xcode.
Di panel navigasi atas Xcode, pilih File > Add Package Dependencies > Add Local, lalu pilih folder yang berisi
Package.swiftyang dihasilkan.
Kemudian:
- Kembangkan skema aplikasi Anda.
Menyiapkan pembuatan SDK:
- Dengan tombol Tambahkan SDK ke aplikasi di ekstensi VS Code Data Connect kami
- Dengan memperbarui
connector.yaml
Siapkan dan gunakan emulator Data Connect dan lakukan iterasi.
Membuat Swift SDK
Gunakan CLI Firebase untuk menyiapkan SDK yang dihasilkan Data 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
Memperbarui SDK saat membuat prototipe
Jika Anda telah menginstal ekstensi Data Connect VS Code, ekstensi ini akan selalu memperbarui SDK yang dihasilkan.
Jika tidak menggunakan ekstensi Data Connect VS Code, 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 Data Connect dalam proses build CI/CD.
firebase dataconnect:sdk:generateMenginisialisasi Data Connect iOS SDK
Lakukan inisialisasi instance Data Connect menggunakan informasi yang Anda gunakan untuk menyiapkan Data Connect (semua tersedia di tab Data Connect konsol Firebase).
Mendapatkan instance konektor
Kode untuk konektor Anda akan dibuat oleh emulator
Data Connect. Jika nama konektor Anda adalah movies dan
paketnya adalah movies, seperti yang ditentukan dalam connector.yaml, maka
ambil objek konektor dengan memanggil:
let connector = DataConnect.moviesConnector
Menerapkan kueri dan mutasi
Dengan objek konektor, Anda dapat menjalankan kueri dan mutasi seperti yang ditentukan dalam kode sumber GraphQL. Misalkan 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 film sebagai berikut:
let mutationResult = try await connector.createMovieMutation.execute(
title: "Empire Strikes Back",
releaseYear: 1980,
genre: "Sci-Fi",
rating: 5)
print("Movie ID: \(mutationResult.data.movie_insert.id)")
Untuk mengambil film, Anda akan menggunakan referensi kueri. Semua referensi kueri adalah
penayang yang dapat diamati. Bergantung pada penayang yang dikonfigurasi (lihat connector.yaml)),
mereka mendukung makro @Observable (iOS 17+) atau menerapkan
protokol ObservableObject. Defaultnya, jika tidak ada yang ditentukan, adalah makro
@Observable yang didukung di iOS 17+.
Dalam tampilan SwiftUI, Anda dapat mengikat hasil kueri menggunakan variabel data
yang dipublikasikan dari ref kueri dan memanggil metode execute() kueri untuk memperbarui
data. Variabel data akan cocok dengan bentuk data yang ditentukan
dalam definisi kueri GQL Anda.
Semua hasil yang diambil mematuhi protokol Decodable. Jika Anda menyertakan
kunci utama objek dalam pengambilan GQL, objek juga akan Identifiable,
sehingga Anda dapat menggunakannya dalam iterator.
struct ListMovieView: View {
@StateObject private var queryRef = connector.listMoviesByGenreQuery.ref(genre: "Sci-Fi")
var body: some View {
VStack {
Button {
Task {
do {
try await refresh()
} catch {
print("Failed to refresh: \(error)")
}
}
} label: {
Text("Refresh")
}
// use the query results in a view
ForEach(queryRef.data?.movies ?? [], id: \.self.id) { movie in
Text(movie.title)
}
}
}
@MainActor
func refresh() async throws {
_ = try await queryRef.execute()
}
}
Kueri juga mendukung eksekusi sekali jalan.
let resultData = try await DataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre: "Sci-Fi")
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 di kemudian hari dalam siklus proses aplikasi, Anda memutuskan untuk menambahkan
nilai LAYAR PENUH ke enum AspectRatio.
Dalam alur kerja Data Connect, Anda dapat menggunakan alat pengembangan lokal untuk memperbarui kueri dan SDK.
Namun, sebelum Anda merilis versi klien yang diupdate, klien lama yang di-deploy mungkin rusak.
Contoh penerapan yang tangguh
SDK yang dihasilkan memaksa penanganan nilai yang tidak diketahui karena enum yang dihasilkan berisi nilai _UNKNOWN, dan Swift menerapkan pernyataan switch yang lengkap.
do {
let result = try await DataConnect.moviesConnector.listMovies.execute()
if let data = result.data {
for movie in data.movies {
switch movie.aspectratio {
case .ACADEMY: print("academy")
case .WIDESCREEN: print("widescreen")
case .ANAMORPHIC: print("anamorphic")
case ._UNKNOWN(let unknownAspect): print(unknownAspect)
}
}
}
} catch {
// handle error
}
Mengaktifkan penyimpanan ke dalam cache sisi klien
Data 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 menyimpan respons kueri secara lokal dalam cache, yang dapat mengurangi jumlah permintaan database yang dibuat aplikasi Anda dan memungkinkan bagian aplikasi Anda yang bergantung pada database berfungsi saat ketersediaan jaringan terganggu.
Untuk mengaktifkan penayangan cache sisi klien, tambahkan konfigurasi penayangan cache klien ke konfigurasi konektor Anda:
generate:
swiftSdk:
outputDir: "../ios"
package: "FirebaseDataConnectGenerated"
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
maxAgeadalah0, yang berarti respons di-cache, tetapi SDK klien akan selalu mengambil nilai baru. Nilai yang di-cache hanya akan digunakan jikaCACHE_ONLYditentukan keexecute().storage: Client SDK dapat dikonfigurasi untuk menyimpan respons dalam cache di penyimpananpersistentatau dimemory. Hasil yang di-cache di penyimpananpersistentakan tetap ada saat aplikasi dimulai ulang. Di iOS SDK, nilai defaultnya adalahpersistent.
Setelah memperbarui konfigurasi caching konektor, buat ulang SDK klien dan bangun ulang aplikasi. Setelah melakukannya, execute() akan menyimpan respons dalam cache dan menggunakan nilai yang di-cache sesuai dengan kebijakan yang Anda konfigurasi. Hal ini
biasanya 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 darimaxAge, maka gunakan nilai yang di-cache. Perilaku default ini disebut kebijakanPREFER_CACHE.Anda juga dapat menentukan untuk setiap pemanggilan
execute()agar hanya menayangkan nilai yang di-cache (CACHE_ONLY) atau mengambil nilai baru dari server tanpa syarat (SERVER_ONLY).try await execute(fetchPolicy: .cacheOnly)try await execute(fetchPolicy: .serverOnly)Membuat prototipe dan menguji aplikasi iOS
Menginstrumentasikan klien untuk menggunakan emulator lokal
Anda dapat menggunakan emulator Data Connect, baik dari ekstensi VS Code Data Connect maupun dari CLI.
Pengukuran aplikasi untuk terhubung ke emulator sama untuk kedua skenario.
let connector = DataConnect.moviesConnector // Connect to the emulator on "127.0.0.1:9399" connector.useEmulator() // (alternatively) if you're running your emulator on non-default port: connector.useEmulator(port: 9999) // Make calls from your appJenis data di SDK Data Connect
Server Data Connect menampilkan jenis data GraphQL umum dan kustom. Hal ini ditampilkan di SDK sebagai berikut.
Jenis Data Connect Swift String String Int Int Float Ganda Boolean Bool UUID UUID Tanggal FirebaseDataConnect.LocalDate Stempel waktu FirebaseCore.Timestamp Int64 Int64 Semua FirebaseDataConnect.AnyValue