SDK máy khách Firebase Data Connect cho phép bạn gọi trực tiếp các truy vấn và đột biến phía máy chủ từ một ứng dụng Firebase. Bạn tạo một SDK máy khách tuỳ chỉnh song song khi thiết kế các lược đồ, truy vấn và đột biến 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 máy khách.
Như chúng tôi đã đề cập ở nơi khác, điều quan trọng cần lưu ý là Data Connect các truy vấn và đột biến không được mã ứng dụng khách gửi và không 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ư Cloud Functions. Đ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ũ hơn).
Đó 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 mẫu các lược đồ, 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 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, cả bản cập nhật phía máy chủ và phía máy khách đều sẵn sàng triển khai.
Tạo SDK Swift
Sử dụng Firebase CLI để thiết lập các SDK do Data Connect tạo trong ứng dụng.
Lệnh init sẽ phát hiện tất cả ứng dụng trong thư mục hiện tại và tự động cài đặt các SDK được tạo.
firebase init dataconnect:sdk
Cập nhật SDK trong khi tạo mẫu
Nếu bạn đã cài đặt tiện ích Data Connect VS Code, tiện ích này sẽ luôn cập nhật các SDK được tạo.
Nếu không sử dụng tiện ích Data Connect VS Code, bạn có thể sử dụng Firebase CLI để cập nhật các SDK được tạo.
firebase dataconnect:sdk:generate --watchTạo SDK trong quy trình xây dựng
Bạn có thể sử dụng Firebase CLI để tạo Data Connect SDK trong các quy trình xây dựng CI/CD.
firebase dataconnect:sdk:generateKhởi chạy SDK iOS Data Connect
Khởi chạy thực thể Data Connect bằng thông tin mà bạn đã 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 thực thể trình kết nối
Mã cho trình kết nối sẽ do trình mô phỏng
Data Connect tạo. 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
Triển khai 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 đã xác định 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 bộ 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ả tham chiếu truy vấn đều là nhà xuất bản Observable. 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 hỗ trợ macro @Observable (iOS 17 trở lên) hoặc triển khai
ObservableObject giao thức. 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 chế độ xem SwiftUI, bạn có thể liên kết kết quả truy vấn bằ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ả 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 này trong trình vòng 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")
Xử lý các thay đổi đối với trường liệt kê
Lược đồ của ứng dụng có thể chứa các giá trị liệt kê, mà truy vấn GraphQL có thể truy cập.
Khi thiết kế ứng dụng thay đổi, bạn có thể thêm các giá trị được hỗ trợ cho enum mới. Ví dụ: hãy tưởng tượng rằng sau này trong vòng đời của ứng dụng, bạn quyết định thêm giá trị FULLSCREEN vào enum AspectRatio.
Trong quy trình làm việc của Data Connect, bạn có thể sử dụng công cụ phát triển cục bộ để cập nhật các truy vấn và SDK.
Tuy nhiên, trước khi bạn phát hành phiên bản cập nhật của ứng dụng, các ứng dụng cũ đã triển khai có thể bị gián đoạn.
Ví dụ về cách triển khai linh hoạt
SDK được tạo buộc phải xử lý các giá trị không xác định vì các enum được tạo chứa giá trị _UNKNOWN và Swift thực thi các câu lệnh chuyển đổi toàn diện.
do {
let result = try await DataConnect.moviesConnector.listMovies.execute()
if let data = result.data {
for movie in data.movies {
switch movie.aspectratio {
case .ACADEMY: print("academy")
case .WIDESCREEN: print("widescreen")
case .ANAMORPHIC: print("anamorphic")
case ._UNKNOWN(let unknownAspect): print(unknownAspect)
}
}
}
} catch {
// handle error
}
Tạo 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 là giống nhau cho 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
Các kiểu dữ liệu trong Data Connect SDK
Máy chủ Data Connect đại diện cho các kiểu dữ liệu GraphQL phổ biến và tuỳ chỉnh. Các kiểu dữ liệu này được biểu thị trong SDK như sau.
| Data Connect Kiể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 |