Firebase Data Connect 用戶端 SDK 可讓您直接從 Firebase 應用程式呼叫伺服器端查詢和變動。設計要部署至 Data Connect 服務的結構定義、查詢和變動時,您可以平行產生自訂用戶端 SDK。然後將這個 SDK 的方法整合至用戶端邏輯。
如我們在其他地方所述,請務必注意,Data Connect 查詢和突變不會由用戶端程式碼提交,而是在伺服器上執行。而是部署後,Data Connect 作業會儲存在伺服器上,例如 Cloud Functions。也就是說,您需要部署對應的用戶端變更,避免現有使用者 (例如使用舊版應用程式的使用者) 發生問題。
因此 Data Connect 提供開發人員環境和工具,方便您製作伺服器部署的結構定義、查詢和變動原型。此外,在您製作原型時,系統也會自動產生用戶端 SDK。
完成服務和用戶端應用程式的更新疊代後,即可部署伺服器端和用戶端更新。
什麼是客戶開發工作流程?
如果您已按照「開始使用」一文的說明操作,應該已瞭解 Data Connect 的整體開發流程。本指南會詳細說明如何從結構定義產生 Android SDK,以及如何處理用戶端查詢和變異。
總而言之,如要在用戶端應用程式中使用產生的 Android SDK,請先完成下列必要步驟:
- 將 Firebase 新增至 Android 應用程式。
- 在 Gradle 中將 Data Connect 設定為依附元件。
- 新增 Kotlin 序列化 Gradle 外掛程式和 Gradle 依附元件。
接著:
- 開發應用程式結構定義。
設定 SDK 產生作業:
- 使用 Data Connect VS Code 擴充功能的「Add SDK to app」(將 SDK 新增至應用程式) 按鈕
- 更新
connector.yaml
設定及使用 Data Connect 模擬器,並進行疊代。
產生 Kotlin SDK
使用 Firebase CLI 在應用程式中設定產生的 SDK。Data Connectinit
指令應會偵測目前資料夾中的所有應用程式,並自動安裝產生的 SDK。
firebase init dataconnect:sdk
在原型設計期間更新 SDK
如果您已安裝 Data Connect VS Code 擴充功能,系統一律會將產生的 SDK 維持在最新狀態。
如果您未使用 Data Connect VS Code 擴充功能,可以透過 Firebase CLI 讓產生的 SDK 維持最新狀態。
firebase dataconnect:sdk:generate --watch
在建構管道中產生 SDK
您可以在 CI/CD 建構程序中使用 Firebase CLI,產生 Data Connect SDK。
firebase dataconnect:sdk:generate
設定用戶端程式碼
在用戶端程式碼中加入 Data Connect
如要設定用戶端程式碼以使用 Data Connect 和產生的 SDK,請先按照標準 Firebase 設定操作說明操作。
接著,在 app/build.gradle.kts
的 plugins
區段中新增下列內容:
// 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
接著,在 app/build.gradle.kts
的 dependencies
區段中新增下列內容:
implementation(platform("com.google.firebase:firebase-bom:34.2.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
初始化 Data Connect Android SDK
使用您設定 Data Connect 時所用的資訊,初始化 Data Connect 執行個體 (所有資訊都可在 Firebase 控制台的「Data Connect」分頁中找到)。
ConnectorConfig 物件
SDK 需要連接器設定物件。
這個物件會從 dataconnect.yaml
中的 serviceId
和 location
,以及 connector.yaml
中的 connectorId
自動產生。
取得連接器執行個體
設定設定物件後,請取得 Data Connect 連接器執行個體。連接器的程式碼會由 Data Connect模擬器產生。如果連接器名稱為 movies
,且 Kotlin 套件為 com.myapplication
(如 connector.yaml
中所指定),請呼叫下列項目來擷取連接器物件:
val connector = com.myapplication.MoviesConnector.instance
使用 Android SDK 中的查詢和突變
使用連結器物件,您可以執行 GraphQL 原始碼中定義的查詢和異動。假設您的連接器已定義下列作業:
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
}
}
接著,您可以建立及擷取電影,如下所示:
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}")
您也可以擷取多部電影:
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)
您也可以收集 Flow
,只有在透過呼叫查詢的 execute()
方法擷取新的查詢結果時,才會產生結果。
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
處理列舉欄位的變更
應用程式的結構定義可以包含列舉,可供 GraphQL 查詢存取。
隨著應用程式設計變更,您可能會新增支援的列舉值。舉例來說,假設您在應用程式生命週期的稍後階段,決定將 FULLSCREEN 值新增至 AspectRatio
列舉。
在 Data Connect 工作流程中,您可以使用本機開發工具更新查詢和 SDK。
不過,在您發布用戶端更新版本之前,舊版已部署的用戶端可能會中斷。
具備復原機制的導入範例
產生的 SDK 會強制處理不明值,因為客戶的程式碼必須解除包裝 EnumValue
物件,該物件是已知列舉值的 EnumValue.Known
,或不明值的 EnumValue.Unknown
。
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()
)
製作原型並測試 Android 應用程式
設定用戶端,使用本機模擬器
您可以透過 Data Connect 模擬器,從 Data Connect VS Code 擴充功能或 CLI 進行操作。
無論是哪種情境,將應用程式連線至模擬器的做法都相同。
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
如要切換至正式版資源,請註解連線至模擬器的程式碼行。
Data Connect SDK 中的資料類型
Data Connect 伺服器代表常見和自訂的 GraphQL 資料型別。SDK 中的表示方式如下。
資料連結類型 | Kotlin |
---|---|
字串 | 字串 |
整數值 | Int (32 位元整數) |
浮點值 | Double (64 位元浮點數) |
布林值 | 布林值 |
UUID | java.util.UUID |
日期 | com.google.firebase.dataconnect.LocalDate (16.0.0-beta03 版之前為 java.util.Date) |
時間戳記 | com.google.firebase.Timestamp |
Int64 | 長 |
不限 | com.google.firebase.dataconnect.AnyValue |