Firebase Data Connect pakiety SDK klienta umożliwiają wywoływanie zapytań i mutacji po stronie serwera bezpośrednio z aplikacji w 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 zintegruj metody z tego pakietu SDK z logiką klienta.
Jak już wspominaliśmy, warto pamiętać, że Data Connect zapytania i mutacje nie są przesyłane przez kod klienta i wykonywane na serwerze. Zamiast tego po wdrożeniu operacje Data Connect są przechowywane na serwerze, tak jak Cloud Functions. Oznacza to, że musisz wdrożyć odpowiednie zmiany po stronie klienta, aby uniknąć problemów 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 wdrażanych na serwerze. Podczas tworzenia prototypu automatycznie generuje też pakiety SDK po stronie klienta.
Gdy wprowadzisz aktualizacje usługi i aplikacji klienckich, zarówno aktualizacje po stronie serwera, jak i po stronie klienta będą gotowe do wdrożenia.
Jak wygląda proces tworzenia aplikacji klienckiej?
Jeśli postępujesz zgodnie z instrukcjami w sekcji Pierwsze kroki, poznasz ogólny proces tworzenia aplikacji Data Connect. W tym przewodniku znajdziesz bardziej szczegółowe informacje o generowaniu pakietów SDK na Androida na podstawie schematu oraz o pracy z zapytaniami i mutacjami klienta.
Podsumowując, aby używać wygenerowanych pakietów Android SDK w aplikacjach klienckich, musisz wykonać te czynności wstępne:
- Dodaj Firebase do aplikacji na Androida.
- Skonfiguruj Data Connect jako zależność w Gradle.
- Dodaj wtyczkę Gradle do serializacji w języku Kotlin i zależność Gradle.
Następnie:
- Opracuj schemat aplikacji.
Skonfiguruj generowanie pakietu SDK:
- Za pomocą przycisku Dodaj pakiet SDK do aplikacji w naszym rozszerzeniu Data Connect do VS Code
- aktualizując
connector.yaml,
Skonfiguruj i używaj Data Connect emulatora oraz iteruj.
Generowanie pakietu SDK w języku Kotlin
Użyj interfejsu wiersza poleceń Firebase, aby skonfigurować w aplikacjach wygenerowane pakiety SDK Data Connect.
Polecenie init powinno wykryć wszystkie aplikacje w bieżącym folderze i automatycznie zainstalować wygenerowane pakiety SDK.
firebase init dataconnect:sdk
Aktualizowanie pakietów SDK podczas tworzenia prototypu
Jeśli masz zainstalowane rozszerzenie Data Connect VS Code, będzie ono zawsze aktualizować wygenerowane pakiety SDK.
Jeśli nie używasz rozszerzenia Data Connect VS Code, możesz użyć wiersza poleceń Firebase, aby aktualizować wygenerowane pakiety SDK.
firebase dataconnect:sdk:generate --watchGenerowanie pakietów SDK w potokach kompilacji
Za pomocą wiersza poleceń Firebase możesz generować Data Connect pakiety SDK w procesach kompilacji CI/CD.
firebase dataconnect:sdk:generateKonfigurowanie kodu klienta
Wprowadź Data Connect do kodu klienta.
Aby skonfigurować kod klienta do korzystania z Data Connect i wygenerowanego pakietu SDK, najpierw wykonaj standardowe instrukcje konfiguracji Firebase.
Następnie dodaj ten kod do sekcji plugins w pliku app/build.gradle.kts:
// The Firebase team tests with version 1.8.22; however, other 1.8 versions,
// and all newer versions are expected work too.
kotlin("plugin.serialization") version "1.8.22" // MUST match the version of the Kotlin compiler
Następnie dodaj ten kod do sekcji dependencies w pliku app/build.gradle.kts:
implementation(platform("com.google.firebase:firebase-bom:34.11.0"))
implementation("com.google.firebase:firebase-dataconnect")
implementation("com.google.firebase:firebase-auth") // Optional
implementation("com.google.firebase:firebase-appcheck") // Optional
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3") // Newer versions should work too
implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1") // Newer versions should work too
Zainicjuj pakiet Data Connect Android SDK.
Zainicjuj instancję Data Connect, używając informacji, których użyto do skonfigurowania Data Connect (wszystkie są dostępne na karcie Firebase konsoliData Connect).
Obiekt ConnectorConfig
Pakiet SDK wymaga obiektu konfiguracji oprogramowania sprzęgającego.
Ten obiekt jest generowany automatycznie na podstawie serviceId i location w dataconnect.yaml oraz connectorId w connector.yaml.
Pobieranie instancji oprogramowania sprzęgającego
Po skonfigurowaniu obiektu konfiguracji uzyskaj instancję Data Connect
łącznika. Kod złącza zostanie wygenerowany przez emulator Data Connect. Jeśli nazwa łącznika to movies, a pakiet Kotlin to com.myapplication, zgodnie z opisem w connector.yaml, pobierz obiekt łącznika, wywołując:
val connector = com.myapplication.MoviesConnector.instance
Używanie zapytań i mutacji z pakietu Android SDK
Za pomocą obiektu łącznika możesz uruchamiać zapytania i mutacje zdefiniowane w kodzie źródłowym GraphQL. Załóżmy, że oprogramowanie sprzęgające ma zdefiniowane 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
}
}
Możesz wtedy utworzyć i pobrać film w ten sposób:
val connector = MoviesConnector.instance
val addMovieResult1 = connector.createMovie.execute(
title = "Empire Strikes Back",
releaseYear = 1980,
genre = "Sci-Fi",
rating = 5
)
val movie1 = connector.getMovieByKey.execute(addMovieResult1.data.key)
println("Empire Strikes Back: ${movie1.data.movie}")
Możesz też pobrać wiele filmów:
val connector = MoviesConnector.instance
val addMovieResult2 = connector.createMovie.execute(
title="Attack of the Clones",
releaseYear = 2002,
genre = "Sci-Fi",
rating = 5
)
val listMoviesResult = connector.listMoviesByGenre.execute(genre = "Sci-Fi")
println(listMoviesResult.data.movies)
Możesz też zebrać Flow, który będzie generować wynik tylko wtedy, gdy nowe wyniki zapytania zostaną pobrane za pomocą wywołania metody execute() zapytania.
val connector = MoviesConnector.instance
connector.listMoviesByGenre.flow(genre = "Sci-Fi").collect { data ->
println(data.movies)
}
connector.createMovie.execute(
title="A New Hope",
releaseYear = 1977,
genre = "Sci-Fi",
rating = 5
)
connector.listMoviesByGenre.execute(genre = "Sci-Fi") // will cause the Flow to get notified
Obsługa zmian w polach wyliczeniowych
Schemat aplikacji może zawierać wyliczenia, do których można uzyskać dostęp za pomocą zapytań GraphQL.
W miarę zmian w projekcie aplikacji możesz dodawać nowe obsługiwane wartości wyliczeniowe. Załóżmy na przykład, że w późniejszym okresie cyklu życia aplikacji zdecydujesz się dodać wartość FULLSCREEN do wyliczenia AspectRatio.
W przypadku Data Connect możesz używać lokalnych narzędzi programistycznych do aktualizowania zapytań i pakietów SDK.
Zanim jednak udostępnisz zaktualizowaną wersję klientów, starsi wdrożeni klienci mogą przestać działać.
Przykład odpornej implementacji
Wygenerowany pakiet SDK wymusza obsługę nieznanych wartości, ponieważ kod klienta musi rozpakować obiekt EnumValue, który w przypadku znanych wartości wyliczenia ma postać EnumValue.Known, a w przypadku nieznanych wartości – EnumValue.Unknown.
val result = connector.listMoviesByAspectRatio.execute(AspectRatio.WIDESCREEN)
val encounteredAspectRatios = mutableSetOf<String>()
result.data.movies
.mapNotNull { it.otherAspectRatios }
.forEach { otherAspectRatios ->
otherAspectRatios
.filterNot { it.value == AspectRatio.WIDESCREEN }
.forEach {
when (it) {
is EnumValue.Known -> encounteredAspectRatios.add(it.value.name)
is EnumValue.Unknown ->
encounteredAspectRatios.add("[unknown ratio: ${it.stringValue}]")
}
}
}
println(
"Widescreen movies also include additional aspect ratios: " +
encounteredAspectRatios.sorted().joinToString()
)
Włączanie zapisywania w pamięci podręcznej po stronie klienta
Data Connect ma opcjonalną funkcję buforowania po stronie klienta, którą możesz włączyć, edytując plik connector.yaml. Gdy ta funkcja jest włączona, wygenerowane pakiety SDK do klienta lokalnie buforują odpowiedzi na zapytania, co może zmniejszyć liczbę żądań bazy danych wysyłanych przez aplikację i umożliwić działanie części aplikacji zależnych od bazy danych w przypadku przerw w dostępie do sieci.
Aby włączyć buforowanie po stronie klienta, dodaj konfigurację buforowania po stronie klienta do konfiguracji łącznika:
generate:
kotlinSdk:
outputDir: "../android"
package: "com.google.firebase.dataconnect.generated"
clientCache:
maxAge: 5s
storage: persistent
Ta konfiguracja ma 2 parametry, które są opcjonalne:
maxAge: maksymalny wiek buforowanej odpowiedzi, po którym pakiet SDK klienta pobiera nowe wartości. Przykłady: „0”, „30s”, „1h30m”.Domyślna wartość parametru
maxAgeto0, co oznacza, że odpowiedzi są buforowane, ale pakiet SDK klienta zawsze pobiera nowe wartości. Wartości buforowane będą używane tylko wtedy, gdy parametrCACHE_ONLYma wartośćexecute().storage: Pakiet SDK klienta można skonfigurować tak, aby buforował odpowiedzi w pamięcipersistentlub wmemory. Wyniki zapisane w pamięci podręcznejpersistentbędą dostępne po ponownym uruchomieniu aplikacji. W pakietach SDK na Androida domyślna wartość topersistent.
Po zaktualizowaniu konfiguracji buforowania oprogramowania sprzęgającego wygeneruj ponownie pakiety SDK klienta i przebuduj aplikację. Gdy to zrobisz, execute()
będzie buforować odpowiedzi i używać wartości z pamięci podręcznej zgodnie ze skonfigurowanymi zasadami. Zwykle odbywa się to automatycznie, bez żadnych dodatkowych działań z Twojej strony. Pamiętaj jednak o tych kwestiach:
Domyślne działanie funkcji
execute()jest opisane powyżej: jeśli wynik jest zapisany w pamięci podręcznej dla zapytania, a wartość w pamięci podręcznej nie jest starsza niżmaxAge, użyj wartości z pamięci podręcznej. To domyślne działanie jest nazywane zasadąPREFER_CACHE.Możesz też określić, że poszczególne wywołania funkcji
execute()mają zwracać tylko wartości z pamięci podręcznej (CACHE_ONLY) lub bezwarunkowo pobierać nowe wartości z serwera (SERVER_ONLY).val queryResult = queryRef.execute(QueryRef.FetchPolicy.CACHE_ONLY)val queryResult = queryRef.execute(QueryRef.FetchPolicy.SERVER_ONLY)Tworzenie prototypu i testowanie aplikacji na Androida
Instrumentowanie klientów do korzystania z lokalnego emulatora
Możesz użyć emulatora Data Connect w rozszerzeniu Data Connect do VS Code lub w interfejsie CLI.
Instrumentowanie aplikacji w celu połączenia z emulatorem jest takie samo w obu scenariuszach.
val connector = MoviesConnector.instance // Connect to the emulator on "10.0.2.2:9399" connector.dataConnect.useEmulator() // (alternatively) if you're running your emulator on non-default port: connector.dataConnect.useEmulator(port = 9999) // Make calls from your appAby przełączyć się na zasoby produkcyjne, zakomentuj wiersze służące do łączenia się z emulatorem.
Typy danych w pakietach SDK Data Connect
Data Connect serwer reprezentuje standardowe i niestandardowe typy danych GraphQL. W pakiecie SDK są one reprezentowane w ten sposób:
Data Connect Typ Kotlin Ciąg znaków Ciąg znaków Liczba całkowita Liczba całkowita (32-bitowa) Liczba zmiennoprzecinkowa Double (liczba zmiennoprzecinkowa 64-bitowa) Wartość logiczna Wartość logiczna UUID java.util.UUID Data com.google.firebase.dataconnect.LocalDate (do wersji 16.0.0-beta03 był to java.util.Date) Sygnatura czasowa com.google.firebase.Timestamp Int64 Długi Dowolna com.google.firebase.dataconnect.AnyValue