SDK máy khách Firebase Data Connect cho phép bạn gọi các truy vấn và đột biến phía máy chủ trực tiếp từ một ứng dụng Firebase. Bạn tạo một SDK máy khách tuỳ chỉnh song song khi thiết kế các lược đồ, truy vấn và đột biến mà bạn triển khai cho dịch vụ Data Connect. Sau đó, bạn tích hợp các phương thức từ SDK này vào logic máy khách.
Như chúng tôi đã đề cập ở nơi khác, điều quan trọng cần lưu ý là Data Connect các truy vấn và đột biến không được mã ứng dụng gửi và thực thi trên máy chủ. Thay vào đó, khi được triển khai, các hoạt động Data Connect sẽ được lưu trữ trên máy chủ như Cloud Functions. Điều này có nghĩa là bạn cần triển khai các thay đổi tương ứng ở phía máy khách để tránh làm gián đoạn người dùng hiện tại (ví dụ: trên các phiên bản ứng dụng cũ hơn).
Đó là lý do Data Connect cung cấp cho bạn một môi trường và công cụ dành cho nhà phát triển, cho phép bạn tạo mẫu các lược đồ, truy vấn và đột biến được triển khai trên máy chủ. Công cụ này cũng tự động tạo SDK phía máy khách trong khi bạn tạo mẫu.
Khi bạn lặp lại các bản cập nhật cho dịch vụ và ứng dụng máy khách, cả bản cập nhật phía máy chủ và phía máy khách đều sẵn sàng triển khai.
Quy trình phát triển máy khách là gì?
Nếu bạn đã làm theo phần Bắt đầu, thì bạn đã được giới thiệu về quy trình phát triển tổng thể cho Data Connect. Trong hướng dẫn này, bạn sẽ tìm thấy thông tin chi tiết hơn về việc tạo SDK Android từ giản đồ và làm việc với các truy vấn và đột biến của ứng dụng.
Tóm lại, để sử dụng SDK Android đã tạo trong các ứng dụng máy khách, bạn sẽ làm theo các bước tiên quyết sau:
- Thêm Firebase vào ứng dụng Android.
- Định cấu hình Data Connect làm phần phụ thuộc trong Gradle.
- Thêm trình bổ trợ Gradle cho quá trình chuyển đổi tuần tự Kotlin và phần phụ thuộc Gradle.
Sau đó:
- Phát triển lược đồ ứng dụng.
Thiết lập quá trình tạo SDK:
- Bằng nút Add SDK to app (Thêm SDK vào ứng dụng) trong tiện ích Data Connect VS Code
- Bằng cách cập nhật
connector.yaml
Thiết lập và sử dụng trình mô phỏng Data Connect rồi lặp lại.
Tạo SDK Kotlin
Sử dụng Firebase CLI để thiết lập SDK do Data Connect tạo trong các ứng dụng.
Lệnh init sẽ phát hiện tất cả ứng dụng trong thư mục hiện tại và tự động cài đặt SDK đã tạo.
firebase init dataconnect:sdk
Cập nhật SDK trong khi tạo mẫu
Nếu bạn đã cài đặt tiện ích Data Connect VS Code, thì tiện ích này sẽ luôn cập nhật SDK đã tạo.
Nếu không sử dụng tiện ích Data Connect VS Code, bạn có thể sử dụng Firebase CLI để cập nhật SDK đã tạo.
firebase dataconnect:sdk:generate --watchTạo SDK trong quy trình tạo bản dựng
Bạn có thể sử dụng Firebase CLI để tạo Data Connect SDK trong các quy trình tạo bản dựng CI/CD.
firebase dataconnect:sdk:generateThiết lập mã máy khách
Kết hợp Data Connect vào mã máy khách
Để thiết lập mã máy khách sử dụng Data Connect và SDK đã tạo, trước tiên, hãy làm theo hướng dẫn thiết lập Firebase tiêu chuẩn.
Sau đó, hãy thêm nội dung sau vào phần plugins trong 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
Sau đó, hãy thêm nội dung sau vào phần dependencies trong 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
Khởi chạy SDK Android Data Connect
Khởi chạy thực thể Data Connect bằng thông tin mà bạn đã dùng để thiết lập Data Connect (tất cả đều có trong thẻ Data Connect của bảng điều khiển Firebase).
Đối tượng ConnectorConfig
SDK yêu cầu một đối tượng cấu hình trình kết nối.
Đối tượng này được tự động tạo từ serviceId và location trong dataconnect.yaml, cũng như connectorId trong connector.yaml.
Lấy thực thể trình kết nối
Bây giờ, bạn đã thiết lập một đối tượng cấu hình, hãy lấy thực thể trình kết nối Data Connect. Mã cho trình kết nối của bạn sẽ do trình mô phỏng
Data Connect tạo. Nếu tên trình kết nối là movies và gói Kotlin là com.myapplication, như được chỉ định trong connector.yaml, thì hãy truy xuất đối tượng trình kết nối bằng cách gọi:
val connector = com.myapplication.MoviesConnector.instance
Sử dụng các truy vấn và đột biến từ SDK Android
Với đối tượng trình kết nối, bạn có thể chạy các truy vấn và đột biến như được xác định trong mã nguồn GraphQL. Giả sử trình kết nối của bạn có các hoạt động sau được xác định:
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
}
}
thì bạn có thể tạo và truy xuất một bộ phim như sau:
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}")
Bạn cũng có thể truy xuất nhiều bộ phim:
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)
Bạn cũng có thể thu thập một Flow sẽ chỉ tạo ra kết quả khi một kết quả truy vấn mới được truy xuất bằng cách gọi phương thức execute() của truy vấn.
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
Xử lý các thay đổi đối với trường liệt kê
Lược đồ của ứng dụng có thể chứa các giá trị liệt kê, mà truy vấn GraphQL có thể truy cập.
Khi thiết kế của ứng dụng thay đổi, bạn có thể thêm các giá trị được hỗ trợ cho enum mới. Ví dụ: hãy tưởng tượng rằng sau này trong vòng đời của ứng dụng, bạn quyết định thêm giá trị FULLSCREEN vào enum AspectRatio.
Trong quy trình Data Connect, bạn có thể sử dụng công cụ phát triển cục bộ để cập nhật các truy vấn và SDK.
Tuy nhiên, trước khi bạn phát hành phiên bản cập nhật của ứng dụng, các ứng dụng đã triển khai cũ hơn có thể gặp lỗi.
Ví dụ về cách triển khai linh hoạt
SDK đã tạo buộc phải xử lý các giá trị không xác định vì mã của khách hàng phải
giải gói đối tượng EnumValue. Đối tượng này là EnumValue.Known cho các giá trị enum
đã biết hoặc EnumValue.Unknown cho các giá trị không xác định.
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()
)
Bật tính năng lưu vào bộ nhớ đệm phía máy khách
Data Connect có một tính năng lưu vào bộ nhớ đệm phía máy khách không bắt buộc. Bạn
có thể bật tính năng này bằng cách chỉnh sửa tệp connector.yaml. Khi tính năng này được bật, các SDK máy khách đã tạo sẽ lưu vào bộ nhớ đệm cục bộ các phản hồi truy vấn. Điều này có thể làm giảm số lượng yêu cầu cơ sở dữ liệu mà ứng dụng của bạn thực hiện và cho phép các phần phụ thuộc vào cơ sở dữ liệu của ứng dụng hoạt động khi kết nối mạng bị gián đoạn.
Để bật tính năng lưu vào bộ nhớ đệm phía máy khách, hãy thêm cấu hình lưu vào bộ nhớ đệm của máy khách vào cấu hình trình kết nối:
generate:
kotlinSdk:
outputDir: "../android"
package: "com.google.firebase.dataconnect.generated"
clientCache:
maxAge: 5s
storage: persistent
Cấu hình này có 2 tham số, cả hai đều không bắt buộc:
maxAge: Tuổi tối đa mà phản hồi được lưu vào bộ nhớ đệm có thể có trước khi SDK máy khách tìm nạp các giá trị mới. Ví dụ: "0", "30s", "1h30m".Giá trị mặc định cho
maxAgelà0, có nghĩa là các phản hồi được lưu vào bộ nhớ đệm, nhưng SDK máy khách sẽ luôn tìm nạp các giá trị mới. Các giá trị được lưu vào bộ nhớ đệm sẽ chỉ được sử dụng khiCACHE_ONLYđược chỉ định choexecute().storage: Bạn có thể định cấu hình SDK máy khách để lưu vào bộ nhớ đệm các phản hồi trong bộ nhớpersistenthoặc trongmemory. Kết quả được lưu vào bộ nhớ đệm trong bộ nhớpersistentsẽ tồn tại trong các lần khởi động lại ứng dụng. Trong SDK Android, giá trị mặc định làpersistent.
Sau khi cập nhật cấu hình lưu vào bộ nhớ đệm của trình kết nối, hãy tạo lại SDK máy khách
và tạo lại ứng dụng. Sau khi bạn thực hiện xong, execute()
sẽ lưu vào bộ nhớ đệm
các phản hồi và sử dụng các giá trị được lưu vào bộ nhớ đệm theo chính sách mà bạn đã định cấu hình. Quá trình này thường diễn ra tự động mà bạn không cần thực hiện thêm bước nào; tuy nhiên, hãy lưu ý những điều sau:
Hành vi mặc định của
execute()như mô tả ở trên: nếu một kết quả được lưu vào bộ nhớ đệm cho một truy vấn và giá trị được lưu vào bộ nhớ đệm không cũ hơnmaxAge, thì hãy sử dụng giá trị được lưu vào bộ nhớ đệm. Hành vi mặc định này được gọi là chính sáchPREFER_CACHE.Bạn cũng có thể chỉ định cho từng lệnh gọi của
execute()để chỉ phân phát các giá trị được lưu vào bộ nhớ đệm (CACHE_ONLY) hoặc để tìm nạp vô điều kiện các giá trị mới từ máy chủ (SERVER_ONLY).val queryResult = queryRef.execute(QueryRef.FetchPolicy.CACHE_ONLY)val queryResult = queryRef.execute(QueryRef.FetchPolicy.SERVER_ONLY)Tạo mẫu và kiểm thử ứng dụng Android
Thiết bị máy khách để sử dụng trình mô phỏng cục bộ
Bạn có thể sử dụng trình mô phỏng Data Connect, cho dù là từ tiện ích Data Connect VS Code hay từ CLI.
Việc thiết bị ứng dụng để kết nối với trình mô phỏng là giống nhau cho cả hai trường hợp.
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Để chuyển sang tài nguyên sản xuất, hãy nhận xét các dòng để kết nối với trình mô phỏng.
Kiểu dữ liệu trong Data Connect SDK
Máy chủ Data Connect đại diện cho các kiểu dữ liệu GraphQL thông thường và tuỳ chỉnh. Các kiểu dữ liệu này được biểu thị trong SDK như sau.
Data Connect Kiểu Kotlin Chuỗi Chuỗi Int Int (số nguyên 32 bit) Nổi Double (số thực 64 bit) Boolean Boolean mã nhận dạng duy nhất (UUID) java.util.UUID Ngày com.google.firebase.dataconnect.LocalDate (was java.util.Date until 16.0.0-beta03) Dấu thời gian com.google.firebase.Timestamp Int64 Dài Bất kỳ com.google.firebase.dataconnect.AnyValue