Użyj wygenerowanych pakietów SDK na iOS

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 w logikę klienta.

Jak już wspomnieliśmy, ważne jest, aby pamiętać, że zapytania i mutacje Data Connectnie są przesyłane przez kod klienta i 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 pozwalają tworzyć prototypy schematów, zapytań i mutacji wdrażanych przez serwer. 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

connectorId: "movies"
generate:
  swiftSdk:
    outputDir: "../movies-generated"
    package: "Movies"

outputDir określa, gdzie ma być zapisany wygenerowany pakiet SDK. Jeśli nie zostanie podany, folderem domyślnym na dane wyjściowe będzie 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 (opcjonalny) określa wydawcę Observable, który ma być używany w zapytaniach. 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.

Aktualizuj pakiety SDK podczas prototypowania

Jeśli prototypowanie odbywa się interaktywnie za pomocą rozszerzenia Data Connect w VS Code i jego emulatora Data Connect, podczas modyfikowania plików .gql definiujących schematy, zapytania i mutacje pliki źródłowe pakietu SDK są automatycznie generowane i aktualizowane. Może to być przydatna funkcja w przypadku procesów (ponownego) wczytywania na gorąco.

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 należy użyć 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 wybierz File > Add Package Dependencies > Add Local (Plik > Dodaj zależności pakietu > Dodaj lokalnie) i 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 połączenia danych (wszystkie są dostępne na karcie Połączenie danych w konsoli Firebase).

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

Uruchomione zapytania i mutacje

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 Observable. W zależności od skonfigurowanego wydawcy (patrz connector.yaml), obsługuje on makro @Observable (iOS w wersji 17 i nowszych)) lub korzysta z protokołu 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 do korzystania z 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 Data Connect pakietach SDK

Serwer Data Connect reprezentuje typowe i niestandardowe typy danych GraphQL. W pakiecie SDK są one reprezentowane w ten sposób: