Pakiety SDK klienta Firebase Data Connect umożliwiają wywoływanie zapytań i mutacji po stronie serwera bezpośrednio z aplikacji Firebase. Niestandardowy pakiet SDK klienta generujesz równolegle z projektowaniem schematów, zapytań i mutacji, które wdrażasz w usłudze Data Connect. Następnie integrujesz metody z tego pakietu SDK z logiką klienta.
Jak już wspomnieliśmy, Data Connectzapytania i mutacje nie są przesyłane przez kod klienta ani wykonywane na serwerze. Zamiast tego po wdrożeniu operacje Data Connect są przechowywane na serwerze, podobnie jak w przypadku Cloud Functions. Oznacza to, że musisz wdrożyć odpowiednie zmiany po stronie klienta, aby nie zakłócać działania aplikacji u dotychczasowych użytkowników (np. w starszych wersjach aplikacji).
Dlatego Data Connect udostępnia środowisko programistyczne i narzędzia, które umożliwiają tworzenie prototypów schematów, zapytań i mutacji wdrożonych na serwerze. Podczas tworzenia prototypu automatycznie generuje też zestawy SDK po stronie klienta.
Gdy wprowadzisz aktualizacje w aplikacjach usługi i klienta, będzie można wdrożyć aktualizacje zarówno po stronie serwera, jak i po stronie klienta.
Generowanie pakietu SDK Swift
Podobnie jak w przypadku większości projektów Firebase, praca nad kodem klienta Firebase Data Connect odbywa się w lokalnym katalogu projektu. Zarówno rozszerzenie Data Connect w VS Code, jak i narzędzie wiersza poleceń Firebase są ważnymi narzędziami lokalnymi do generowania kodu klienta i zarządzania nim.
Opcje generowania pakietu SDK są powiązane z kilkoma wpisami w pliku dataconnect.yaml, który został wygenerowany podczas inicjowania projektu.
Inicjowanie generowania pakietu SDK
W konfiguracjiconnector.yaml dodaj swoje outputDir, package i (w przypadku pakietu SDK na potrzeby internetu) packageJsonDir.
connectorId: "movies"
generate:
swiftSdk:
outputDir: "../movies-generated"
package: "Movies"
outputDir określa, gdzie ma zostać wygenerowany pakiet SDK. Jeśli nie zostanie podany, jako domyślny katalog wyjściowy używany jest folder usługi łącznika.
package określa nazwę pakietu, który zostanie wygenerowany. Generator utworzy folder o nazwie pakietu, który będzie zawierać plik Package.swift i wygenerowany kod.
observablePublisher (opcjonalnie) określa wydawcę Observable, którego należy użyć w odniesieniach zapytania. Możliwe wartości to observableMacro (iOS 17 lub nowszy) i observableObject (starsza wersja iOS 17). Jeśli nie podasz żadnej wartości, domyślną wartością będzie observableMacro.
Aktualizowanie pakietów SDK podczas prototypowania
Jeśli prototypowanie odbywa się interaktywnie za pomocą rozszerzenia Data Connect w VS Code i jego emulatora Data Connect, pliki źródłowe pakietu SDK są automatycznie generowane i aktualizowane podczas modyfikowania plików .gql definiujących schematy, zapytania i mutacje. Może to być przydatna funkcja w przypadku procesów (ponownego) wczytywania na gorąco.
.gql, a także automatycznie aktualizować źródła pakietu SDK.
Możesz też użyć interfejsu wiersza poleceń, aby wygenerować pakiety SDK za każdym razem, gdy zmienisz pliki .gql:
firebase dataconnect:sdk:generate --watch
Generowanie pakietów SDK na potrzeby integracji i wersji produkcyjnych
W niektórych przypadkach, np. podczas przygotowywania źródeł projektu do przesłania na potrzeby testów CI, możesz wywołać interfejs wiersza poleceń Firebase w celu aktualizacji zbiorczej.
W takich przypadkach użyj firebase dataconnect:sdk:generate.
Konfigurowanie kodu klienta
Aby skonfigurować kod klienta pod kątem korzystania z Data Connect i wygenerowanego pakietu SDK, najpierw wykonaj standardowe instrukcje konfiguracji Firebase.
Następnie otwórz obszar roboczy aplikacji w Xcode.
Na górnym pasku nawigacyjnym kliknij Plik > Dodaj zależności pakietu > Dodaj lokalny, a następnie wybierz folder zawierający wygenerowany plik źródłowy Package.swift.
Inicjowanie pakietu Data Connect iOS SDK
Zainicjuj instancję Data Connect, korzystając z informacji użytych do skonfigurowania usługi Data Connect (wszystkie dostępne w konsoli Firebase na karcie Data Connect).
Pobieranie instancji oprogramowania sprzęgającego
Kod dla Twojego łącznika zostanie wygenerowany przez emulator Data Connect. Jeśli nazwa łącznika to movies, a pakiet to movies, zgodnie z definicją w pliku connector.yaml, pobierz obiekt łącznika, wywołując:
let connector = DataConnect.moviesConnector
Wykonywanie zapytań i mutacji
Za pomocą obiektu łącznika możesz wykonywać zapytania i mutacje zgodnie z definicją w kodzie źródłowym GraphQL. Załóżmy, że w Twoim oprogramowaniu sprzęgającym zdefiniowano te operacje:
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
}
}
Następnie możesz utworzyć film w ten sposób:
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)")
Aby pobrać film, użyj odwołania do zapytania. Wszystkie odwołania do zapytań to wydawcy w Observable. W zależności od skonfigurowanego wydawcy (patrz: connector.yaml)) obsługują one makro @Observable (iOS 17 lub nowszy) lub implementują protokół ObservableObject. Jeśli nie określisz żadnej wartości, domyślnie zostanie użyte makro @Observable obsługiwane w iOS 17 i nowszych.
W widoku SwiftUI możesz powiązać wyniki zapytania za pomocą opublikowanej zmiennej data odwołania do zapytania i wywołania metody execute() zapytania w celu zaktualizowania danych. Zmienna data będzie odpowiadać kształtowi danych zdefiniowanych w definicji zapytania GQL.
Wszystkie pobrane wyniki są zgodne z protokołem Decodable. Jeśli w wywołaniu GQL uwzględnisz klucz podstawowy obiektu, obiekty będą też Identifiable, co pozwoli Ci używać ich w iteracjach.
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()
}
}
Zapytania obsługują też wykonanie jednorazowe.
let resultData = try await DataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre: "Sci-Fi")
Tworzenie prototypu i testowanie aplikacji na iOS
Użyj klienta, aby użyć lokalnego emulatora
Możesz użyć emulatora Data Connect, korzystając z rozszerzenia Data Connect w VS Code lub z poziomu wiersza poleceń.
W obu przypadkach instrumentowanie aplikacji w celu połączenia z emulatorem jest takie samo.
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
Typy danych w pakietach SDK Data Connect
Serwer Data Connect reprezentuje typowe i niestandardowe typy danych GraphQL. W pakiecie SDK są one reprezentowane w ten sposób:
| Typ Data Connect | Swift |
|---|---|
| Ciąg znaków | Ciąg znaków |
| Liczba całkowita | Liczba całkowita |
| Liczba zmiennoprzecinkowa | Podwójne |
| Wartość logiczna | Wartość logiczna |
| UUID | UUID |
| Data | FirebaseDataConnect.LocalDate |
| Sygnatura czasowa | FirebaseCore.Timestamp |
| Int64 | Int64 |
| Dowolna | FirebaseDataConnect.AnyValue |