使用生成的 iOS SDK

注意：Firebase Data Connect 目前处于公开预览版阶段。 Data Connect 将受 Google Cloud Platform 服务条款的服务专用条款部分中的“正式发布前产品条款”的约束。正式发布前的功能可供使用 “按原样”可能只能获得有限的支持如需了解详情，请参阅发布阶段说明。

借助 Firebase Data Connect 客户端 SDK，您可以直接从 Firebase 应用调用服务器端查询和更改。在设计要部署到 Data Connect 服务的架构、查询和更改时，您可以并行生成自定义客户端 SDK。然后，将此 SDK 中的方法集成到您的客户端逻辑中。

正如我们在其他地方提到的，需要注意的是，Data Connect 查询和变更不是由客户端代码提交， 服务器。而是在部署后，Data Connect 操作会像 Cloud Functions 函数一样存储在服务器上。这意味着，您需要部署相应的客户端更改，以免影响现有用户（例如，在旧版应用中）。

因此，Data Connect为您提供了开发者环境 一种工具，用于对服务器部署的架构、查询和变更进行原型设计。 在您进行原型设计时，它还会自动生成客户端 SDK。

在对服务和客户端应用进行迭代更新后，服务器和 即可部署客户端更新

生成 Swift SDK

与大多数 Firebase 项目一样，Firebase Data Connect 客户端代码的工作在本地项目目录中进行。Data Connect VS Code 扩展程序和 Firebase CLI 都是生成和管理客户端代码的重要本地工具。

SDK 生成选项与 dataconnect.yaml 中的多个条目相对应 文件。

初始化 SDK 生成

在 connector.yaml 中，添加 outputDir、package 和（对于 Web 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 源文件。这在热(重新)加载工作流中非常有用。

在其他情况下，如果您使用 Data Connect 模拟器 Firebase CLI，您可以在 .gql 更新时设置手表，并使用 SDK 来源已自动更新。

或者，您也可以在 .gql 文件发生更改时使用 CLI 重新生成 SDK：

firebase dataconnect:sdk:generate --watch

生成用于集成和正式版本的 SDK

在某些情况下（例如准备项目源代码以提交 CI 测试），您可以调用 Firebase CLI 进行批量更新。

在这种情况下，请使用 firebase dataconnect:sdk:generate。

设置客户端代码

如需设置客户端代码以使用 Data Connect 和您生成的 SDK，首先 按照标准 Firebase 设置说明操作。

然后，使用 Xcode 打开您的应用工作区。

在顶部导航栏中，选择 File >添加软件包依赖项 >将 Local，然后选择包含生成的 Package.swift 源文件。

初始化 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 变量将与定义的数据的形状匹配 。

所有检索到的结果均遵循 Decodable 协议。如果您在 GQL 提取中添加了对象的主键，则这些对象也是 Identifiable，您可以在迭代器中使用它们。

注意：@StateObject 不会实时更新。如果使用 @Observable 宏作为发布商，也无需提供此信息。

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 应用进行原型设计和测试

对客户端进行插桩 (instrument) 处理以使用本地模拟器

您可以使用 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