本頁面由 Cloud Translation API 翻譯而成。

使用系統產生的 iOS SDK

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

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

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

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

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

如果您按照入門指南操作，就會瞭解 Data Connect 的整體開發流程。本指南將進一步說明如何從結構定義產生 Swift SDK，以及如何使用用戶端查詢和變異。

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

將 Firebase 新增至 iOS 應用程式。
如要使用產生的 SDK，請在 Xcode 中將其設為依附元件。

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

接著：

開發應用程式結構定義。
設定 SDK 產生作業：
- 使用 Data Connect VS Code 擴充功能中的「Add SDK to app」按鈕
- 更新 connector.yaml
初始化用戶端程式碼並匯入程式庫。
實作對查詢和突變的呼叫。
設定及使用 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 模擬器進行互動式原型設計，SDK 來源檔案會在您修改定義結構定義、查詢和突變的 .gql 檔案時自動產生及更新。這項功能在熱門 (重新) 載入工作流程中相當實用。

在其他情況下，如果您使用 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 時所用的資訊 (所有資訊皆可在 Firebase 控制台的 Data Connect 分頁中找到)，初始化 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 中會以以下方式表示：

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