SDK ứng dụng Firebase Data Connect cho phép bạn gọi các truy vấn và biến đổi phía máy chủ ngay từ ứng dụng Firebase. Bạn tạo một SDK ứng dụng tuỳ chỉnh song song khi thiết kế giản đồ, truy vấn và biến đổi mà bạn triển khai cho dịch vụ Data Connect. Sau đó, bạn tích hợp các phương thức từ SDK này vào logic ứng dụng.
Như đã đề cập ở nơi khác, điều quan trọng cần lưu ý là các truy vấn và đột biến Data Connect không được mã ứng dụng gửi và thực thi trên máy chủ. Thay vào đó, khi được triển khai, các thao tác Data Connect sẽ được lưu trữ trên máy chủ như Chức năng trên đám mây. Điều này có nghĩa là bạn cần triển khai các thay đổi tương ứng ở phía máy khách để tránh làm gián đoạn người dùng hiện tại (ví dụ: trên các phiên bản ứng dụng cũ).
Đó là lý do Data Connect cung cấp cho bạn một môi trường và công cụ dành cho nhà phát triển, cho phép bạn tạo nguyên mẫu cho các giản đồ, truy vấn và đột biến được triển khai trên máy chủ. Công cụ này cũng tự động tạo SDK phía máy khách trong khi bạn tạo nguyên mẫu.
Khi bạn lặp lại các bản cập nhật cho dịch vụ và ứng dụng khách, cả bản cập nhật phía máy chủ và phía ứng dụng khách đều sẵn sàng để triển khai.
Tạo SDK Swift
Giống như hầu hết các dự án Firebase, công việc trên mã ứng dụng Firebase Data Connect diễn ra trong thư mục dự án cục bộ. Cả tiện ích Data Connect VS Code và CLI Firebase đều là các công cụ cục bộ quan trọng để tạo và quản lý mã ứng dụng.
Các tuỳ chọn tạo SDK được liên kết với một số mục trong tệp dataconnect.yaml được tạo khi bạn khởi chạy dự án.
Khởi chạy quá trình tạo SDK
Trongconnector.yaml, hãy thêm outputDir, package và (đối với SDK web) packageJsonDir.
connectorId: "movies"
generate:
swiftSdk:
outputDir: "../movies-generated"
package: "Movies"
outputDir chỉ định vị trí xuất SDK đã tạo. Nếu không được chỉ định, thư mục trình kết nối sẽ được dùng làm thư mục đầu ra mặc định.
package chỉ định tên của gói sẽ được tạo. Trình tạo sẽ tạo một thư mục có tên của gói, chứa Package.swift và mã được tạo.
observablePublisher (không bắt buộc) chỉ định nhà xuất bản Observable để sử dụng trong tham chiếu truy vấn. Các giá trị có thể là observableMacro (iOS 17 trở lên) và observableObject (trước iOS 17). Giá trị mặc định, nếu không có giá trị nào được chỉ định, là observableMacro.
Cập nhật SDK trong khi tạo bản nguyên mẫu
Nếu bạn đang tạo bản minh hoạ tương tác bằng tiện ích Data Connect VS Code và trình mô phỏng Data Connect, thì các tệp nguồn SDK sẽ tự động được tạo và cập nhật trong khi bạn sửa đổi các tệp .gql xác định giản đồ, truy vấn và đột biến. Đây có thể là một tính năng hữu ích trong quy trình tải lại (nóng).
.gql và cũng tự động cập nhật các nguồn SDK.
Ngoài ra, bạn có thể sử dụng CLI để tạo lại SDK bất cứ khi nào tệp .gql thay đổi:
firebase dataconnect:sdk:generate --watchTạo SDK để tích hợp và phát hành chính thức
Trong một số trường hợp, chẳng hạn như chuẩn bị nguồn dự án để gửi cho các bài kiểm thử CI, bạn có thể gọi CLI Firebase để cập nhật hàng loạt.
Trong những trường hợp này, hãy sử dụng firebase dataconnect:sdk:generate.
Thiết lập mã ứng dụng
Để thiết lập mã ứng dụng của bạn nhằm sử dụng Data Connect và SDK đã tạo, trước tiên, hãy làm theo hướng dẫn thiết lập Firebase tiêu chuẩn.
Sau đó, hãy mở không gian làm việc của ứng dụng bằng Xcode.
Trong thanh điều hướng trên cùng, hãy chọn File (Tệp) > Add Package Dependencies (Thêm phần phụ thuộc gói) > Add Local (Thêm cục bộ) rồi chọn thư mục chứa tệp nguồn Package.swift đã tạo.
Khởi chạy SDK iOS Data Connect
Khởi chạy thực thể Data Connect bằng thông tin bạn đã sử dụng để thiết lập Data Connect (tất cả đều có trong thẻ Data Connect của bảng điều khiển Firebase).
Lấy một thực thể trình kết nối
Trình mô phỏng Data Connect sẽ tạo mã cho trình kết nối. Nếu tên trình kết nối là movies và gói là movies, như được chỉ định trong connector.yaml, thì hãy truy xuất đối tượng trình kết nối bằng cách gọi:
let connector = DataConnect.moviesConnector
Chạy truy vấn và đột biến
Với đối tượng trình kết nối, bạn có thể chạy các truy vấn và đột biến như được xác định trong mã nguồn GraphQL. Giả sử trình kết nối của bạn có các thao tác sau:
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
}
}
Sau đó, bạn có thể tạo một phim như sau:
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)")
Để truy xuất một bộ phim, bạn sẽ sử dụng tham chiếu truy vấn. Tất cả tệp tham chiếu truy vấn đều là nhà xuất bản có thể quan sát. Tuỳ thuộc vào nhà xuất bản được định cấu hình (xem connector.yaml), các nhà xuất bản này sẽ hỗ trợ macro @Observable (iOS 17 trở lên) hoặc triển khai giao thức ObservableObject. Giá trị mặc định (nếu không có giá trị nào được chỉ định) là macro @Observable được hỗ trợ trên iOS 17 trở lên.
Trong thành phần hiển thị SwiftUI, bạn có thể liên kết kết quả truy vấn bằng cách sử dụng biến data đã xuất bản của tham chiếu truy vấn và gọi phương thức execute() của truy vấn để cập nhật dữ liệu. Biến data sẽ khớp với hình dạng của dữ liệu đã được xác định trong định nghĩa truy vấn GQL.
Tất cả kết quả được truy xuất đều tuân thủ giao thức Decodable. Nếu bạn đưa khoá chính của đối tượng vào lệnh tìm nạp GQL, thì các đối tượng đó cũng là Identifiable, cho phép bạn sử dụng các đối tượng đó trong trình lặp.
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()
}
}
Truy vấn cũng hỗ trợ thực thi một lần.
let resultData = try await DataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre: "Sci-Fi")
Tạo nguyên mẫu và kiểm thử ứng dụng iOS
Đo lường ứng dụng để sử dụng trình mô phỏng cục bộ
Bạn có thể sử dụng trình mô phỏng Data Connect, cho dù là từ tiện ích Data Connect VS Code hay từ CLI.
Việc đo lường ứng dụng để kết nối với trình mô phỏng cũng giống nhau đối với cả hai trường hợp.
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
Loại dữ liệu trong SDK Data Connect
Máy chủ Data Connect đại diện cho các loại dữ liệu GraphQL phổ biến và tuỳ chỉnh. Các giá trị này được biểu thị trong SDK như sau.
| Loại kết nối dữ liệu | Swift |
|---|---|
| Chuỗi | Chuỗi |
| Int | Int |
| Nổi | Giường đôi |
| Boolean | Bool |
| mã nhận dạng duy nhất (UUID) | mã nhận dạng duy nhất (UUID) |
| Ngày | FirebaseDataConnect.LocalDate |
| Dấu thời gian | FirebaseCore.Timestamp |
| Int64 | Int64 |
| Bất kỳ | FirebaseDataConnect.AnyValue |