使用系統產生的 iOS SDK

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

如我們在其他地方所述，請務必注意，Data Connect 查詢和突變不會由用戶端程式碼提交，而是在伺服器上執行。而是部署後，Data Connect 作業會儲存在伺服器上，例如 Cloud Functions。也就是說，您需要部署對應的用戶端變更，避免現有使用者 (例如使用舊版應用程式) 無法正常運作。

因此 Data Connect 提供開發人員環境和工具，方便您製作伺服器部署的結構定義、查詢和變動原型。此外，在您製作原型時，系統也會自動產生用戶端 SDK。

完成服務和用戶端應用程式的更新疊代後，即可部署伺服器端和用戶端更新。

什麼是用戶端開發工作流程？

如果您已按照「開始使用」一文的說明操作，應該已瞭解 Data Connect 的整體開發流程。本指南將詳細說明如何從架構產生 Swift SDK，以及如何處理用戶端查詢和變動。

總而言之，如要在用戶端應用程式中使用產生的 Swift SDK，請先完成下列必要步驟：

  1. 將 Firebase 新增至 iOS 應用程式。

  2. 如要使用產生的 SDK，請在 Xcode 中將其設為依附元件。

    在 Xcode 頂端導覽列中，依序選取「File」>「Add Package Dependencies」>「Add Local」，然後選擇包含所產生 Package.swift 的資料夾。

接著：

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

  2. 設定 SDK 產生作業：

    • 使用 Data Connect VS Code 擴充功能的「Add SDK to app」(將 SDK 新增至應用程式) 按鈕
    • 更新connector.yaml

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

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

  5. 設定及使用 Data Connect 模擬器，然後疊代。

產生 Swift SDK

與大多數 Firebase 專案一樣，您會在專案的本機目錄中處理Firebase Data Connect用戶端程式碼。Data Connect VS Code 擴充功能和 Firebase CLI 都是重要的本機工具，可產生及管理用戶端程式碼。

SDK 生成選項會對應到您初始化專案時生成的 dataconnect.yaml 檔案中的多個項目。

初始化 SDK 生成作業

在 connector.yaml 中，加入 outputDir、package 和 (適用於網頁 SDK) packageJsonDir。 
connectorId: "movies"
generate:
  swiftSdk:
    outputDir: "../movies-generated"
    package: "Movies"

outputDir 指定產生的 SDK 輸出位置。如未指定，系統會使用連接器資料夾做為預設輸出目錄。

package 指定要產生的套件名稱。產生器會建立以套件名稱命名的資料夾，內含 Package.swift 和產生的程式碼。

observablePublisher (選用) 指定要在查詢參照中使用的 Observable 發布者。可能的值為 observableMacro (iOS 17 以上版本) 和 observableObject (iOS 17 以前版本)。如未指定值，預設值為 observableMacro。

在原型設計期間更新 SDK

如果您使用 Data Connect VS Code 擴充功能及其 Data Connect 模擬器，以互動方式製作原型，系統會在您修改定義結構定義、查詢和變異的 .gql 檔案時，自動產生及更新 SDK 來源檔案。在熱重載工作流程中，這項功能相當實用。

在其他情況下，如果您使用 Firebase CLI 的 Data Connect 模擬器，可以監控 .gql 更新，並自動更新 SDK 來源。

或者，您也可以在 .gql 檔案變更時，使用 CLI 重新產生 SDK：

firebase dataconnect:sdk:generate --watch

產生 SDK，用於整合及發布正式版

在某些情況下 (例如準備專案來源以提交 CI 測試時)，您可以呼叫 Firebase CLI 進行批次更新。

在這些情況下，請使用 firebase dataconnect:sdk:generate。

初始化 Data Connect iOS SDK

使用您設定 Data Connect 時所用的資訊，初始化 Data Connect 執行個體 (所有資訊都可在 Firebase 控制台的「Data Connect」分頁中找到)。

取得連接器執行個體

連接器的代碼會由 Data Connect模擬器產生。如果連接器名稱為 movies，且套件為 movies (如 connector.yaml 中所指定)，請呼叫下列項目來擷取連接器物件：

let connector = DataConnect.moviesConnector

實作查詢和異動

使用連結器物件，您可以執行 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
  }
}

接著，您可以按照下列步驟製作電影：

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)")

如要擷取電影，請使用查詢參照。所有查詢參照都是 Observable 發布商。視設定的發布商而定 (請參閱 connector.yaml))，他們會支援 @Observable 巨集 (iOS 17 以上版本) 或實作 ObservableObject 通訊協定。如未指定，預設值為 iOS 17 以上版本支援的 @Observable 巨集。

在 SwiftUI 檢視區塊中，您可以繫結查詢結果，方法是使用查詢參照的已發布 data 變數，並呼叫查詢的 execute() 方法來更新資料。data 變數會與 GQL 查詢定義中定義的資料形狀相符。

所有擷取的結果都符合 Decodable 通訊協定。如果您在 GQL 擷取中加入物件的主鍵，物件也會是 Identifiable，方便您在疊代器中使用。

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

查詢也支援單次執行。

let resultData = try await DataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre: "Sci-Fi")

製作原型並測試 iOS 應用程式

設定用戶端，使用本機模擬器

您可以透過 Data Connect 模擬器，從 Data Connect VS Code 擴充功能或 CLI 進行操作。

無論是哪種情境，將應用程式連線至模擬器的做法都相同。

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 app

Data Connect SDK 中的資料類型

Data Connect 伺服器代表常見和自訂的 GraphQL 資料型別。SDK 中的表示方式如下。

資料連結類型 Swift
字串 字串
整數值 整數值
浮點值 雙人床
布林值 布林值
UUID UUID
日期 FirebaseDataConnect.LocalDate
時間戳記 FirebaseCore.Timestamp
Int64 Int64
不限 FirebaseDataConnect.AnyValue