使用產生的 Android SDK

Firebase SQL Connect 用戶端 SDK 可讓您直接從 Firebase 應用程式呼叫伺服器端查詢和變異。在設計要部署至 SQL Connect 服務的結構定義、查詢和變異時，您會同時產生自訂用戶端 SDK。接著，將這個 SDK 的方法整合至用戶端邏輯。

如先前所述，請務必注意，SQL Connect查詢和變動並非由用戶端程式碼提交，而是在伺服器上執行。相反地，部署時，SQL Connect 作業會儲存在伺服器上，例如 Cloud Functions。這表示您需要部署相應的用戶端變更，以免影響現有使用者 (例如使用舊版應用程式的使用者)。

因此，SQL Connect 提供開發環境和工具，讓您為伺服器部署的結構定義、查詢和變動建立原型。此外，在您設計原型時，系統也會自動產生用戶端 SDK。

反覆更新服務和用戶端應用程式後，即可部署伺服器端和用戶端更新。

用戶端開發工作流程為何？

如果您已按照「入門指南」操作，應該已瞭解 SQL Connect 的整體開發流程。本指南將詳細說明如何從結構定義產生 Android SDK，以及如何處理用戶端查詢和變動。

總而言之，如要在用戶端應用程式中使用產生的 Android SDK，請按照下列必要步驟操作：

1. 將 Firebase 新增至 Android 應用程式。
2. 在 Gradle 中將 SQL Connect 設為依附元件。
3. 新增 Kotlin Serialization Gradle 外掛程式和 Gradle 依附元件。

接著：

1. 開發應用程式結構定義。

2. 設定 SDK 生成：

   • 在 SQL Connect VS Code 擴充功能中，使用「Add SDK to app」按鈕
   • 更新 connector.yaml

3. 初始化用戶端程式碼並匯入程式庫。

4. 實作查詢和異動呼叫。

5. 設定及使用 SQL Connect 模擬器，並反覆測試。

產生 Kotlin SDK

使用 Firebase CLI 在應用程式中設定 SQL Connect 生成的 SDK。init 指令應會偵測目前資料夾中的所有應用程式，並自動安裝產生的 SDK。

firebase init dataconnect:sdk

在原型設計階段更新 SDK

如果已安裝 SQL Connect VS Code 擴充功能，系統會持續更新生成的 SDK。

如果不使用 SQL Connect VS Code 擴充功能，可以使用 Firebase CLI，讓產生的 SDK 保持最新狀態。

firebase dataconnect:sdk:generate --watch

在建構管道中產生 SDK

您可以使用 Firebase CLI，在 CI/CD 建構程序中生成 SQL Connect SDK。

firebase dataconnect:sdk:generate

設定用戶端程式碼

將 SQL Connect 納入用戶端程式碼

如要設定用戶端程式碼，以便使用 SQL 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: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

初始化 SQL Connect Android SDK

使用設定 SQL Connect 時所用的資訊，初始化 SQL Connect 例項。如要查看這項資訊，請前往 Firebase 控制台的「Databases & Storage」(資料庫與儲存空間) >「SQL Connect」(SQL 連線) 頁面。

ConnectorConfig 物件

SDK 需要連接器設定物件。

這個物件是根據 dataconnect.yaml 中的 serviceId 和 location，以及 connector.yaml 中的 connectorId 自動產生。

取得連接器執行個體

設定物件後，請取得 SQL Connect 連接器執行個體。SQL 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

訂閱即時變更

請參閱「接收 SQL Connect 的即時更新」。

處理列舉欄位的變更

應用程式的結構定義可以包含列舉，並可透過 GraphQL 查詢存取。

隨著應用程式設計變更，您可能會新增列舉支援的值。舉例來說，假設您在應用程式生命週期的後續階段，決定在 AspectRatio 列舉中加入 FULLSCREEN 值。

在 SQL 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()
)

啟用用戶端快取

SQL Connect 具有選用的用戶端快取功能，您可以編輯 connector.yaml 檔案來啟用這項功能。啟用這項功能後，產生的用戶端 SDK 會在本機快取查詢回應，這可減少應用程式發出的資料庫要求數量，並在網路可用性中斷時，讓應用程式中依賴資料庫的部分正常運作。

如要啟用用戶端快取，請在連接器設定中新增用戶端快取設定：

generate:
  kotlinSdk:
    outputDir: "../android"
    package: "com.google.firebase.dataconnect.generated"
    clientCache:
      maxAge: 5s
      storage: persistent

這項設定有兩個參數，皆為選用：

• maxAge：快取回應的最長保留時間，超過這個時間後，用戶端 SDK 就會擷取新值。範例：「0」、「30s」、「1h30m」。

  maxAge 的預設值為 0，表示系統會快取回應，但用戶端 SDK 一律會擷取最新值。只有在 CACHE_ONLY 指定為 execute() 時，系統才會使用快取值。

• storage：用戶端 SDK 可設為將回應快取至 persistent 儲存空間或 memory。快取在 persistent 儲存空間中的結果，在應用程式重新啟動後仍會保留。在 Android SDK 中，預設值為 persistent。

更新連接器的快取設定後，請重新產生用戶端 SDK 並重新建構應用程式。完成後，execute() 會快取回應，並根據您設定的政策使用快取值。這通常會自動發生，您不需要採取任何額外步驟，但請注意下列事項：

• execute() 的預設行為如上所述：如果查詢結果已快取，且快取值不早於 maxAge，則使用快取值。這項預設行為稱為 PREFER_CACHE 政策。

  您也可以指定 execute() 的個別叫用，只提供快取值 (CACHE_ONLY)，或無條件從伺服器擷取最新值 (SERVER_ONLY)。

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

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

  建立 Android 應用程式原型並進行測試

  檢測用戶端以使用本機模擬器

  無論是透過 SQL Connect VS Code 擴充功能或 CLI，您都可以使用 SQL Connect 模擬器。

  無論是哪種情況，檢測應用程式以連線至模擬器的方式都相同。

  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
  
  

  如要切換至正式環境資源，請將連線至模擬器的程式碼行註解排除。

  SQL Connect SDK 中的 SQL 類型

  SQL Connect 伺服器代表常見和自訂的 GraphQL 資料類型。在 SDK 中，這些狀態會以下列方式表示。

  SQL Connect 類型	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	Long
  不限	com.google.firebase.dataconnect.AnyValue