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 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

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

outputDir określa, gdzie ma zostać wygenerowany pakiet SDK. Jeśli nie zostanie podany, folder z połączem jest używany jako domyślny katalog wyjściowy.

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 zapytań. Możliwe wartości to observableMacro (iOS 17 lub nowszy) i observableObject (starsza wersja iOS 17). Jeśli nie podasz żadnej opcji, 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, 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 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.

Zainicjuj pakiet SDK Data Connect na iOS

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: