Com os SDKs do cliente do Firebase Data Connect, é possível chamar consultas e mutações do lado do servidor diretamente de um app do Firebase. Você gera um SDK do cliente personalizado em paralelo ao projetar os esquemas, as consultas e as mutações que implanta no seu serviço Data Connect. Em seguida, integre os métodos desse SDK à lógica do cliente.
Como já mencionamos, é importante observar que Data Connect consultas e mutações não são enviadas pelo código do cliente e executadas no servidor. Em vez disso, quando implantadas, as operações Data Connect são armazenadas no servidor, como o Cloud Functions. Isso significa que você precisa implantar as mudanças correspondentes do lado do cliente para evitar falhas nos usuários atuais (por exemplo, em versões mais antigas do app).
Por isso, o Data Connect oferece um ambiente de desenvolvimento e ferramentas que permitem prototipar seus esquemas, consultas e mutações implantados no servidor. Ele também gera SDKs do lado do cliente automaticamente enquanto você cria protótipos.
Depois de iterar as atualizações nos apps de serviço e cliente, as atualizações do lado do servidor e do cliente estarão prontas para implantação.
Qual é o fluxo de trabalho de desenvolvimento do cliente?
Se você seguiu os Primeiros passos, conheceu o fluxo geral de desenvolvimento para Data Connect. Neste guia, você encontra informações mais detalhadas sobre como gerar SDKs do Android com base no seu esquema e trabalhar com consultas e mutações do cliente.
Resumindo, para usar os SDKs do Android gerados nos apps cliente, siga estas etapas de pré-requisito:
- Adicione o Firebase ao seu app Android.
- Configure Data Connect como uma dependência no Gradle.
- Adicione o plug-in Gradle do Kotlin Serialization e a dependência do Gradle.
Depois, siga estas instruções:
- Desenvolva o esquema do app.
Configure a geração de SDKs:
- Com o botão Adicionar SDK ao app na extensão Data Connect do VS Code
- Atualizando seu
connector.yaml
Configure e use o emulador Data Connect e faça iterações.
Gerar seu SDK Kotlin
Use a CLI Firebase para configurar os SDKs gerados pelo Data Connect nos seus apps.
O comando init detecta todos os apps na pasta atual e instala os SDKs gerados automaticamente.
firebase init dataconnect:sdk
Atualizar SDKs durante a criação de protótipos
Se você tiver a extensão Data Connect do VS Code instalada, ela sempre manterá os SDKs gerados atualizados.
Se você não usa a extensão Data Connect do VS Code, pode usar a CLI do Firebase para manter os SDKs gerados atualizados.
firebase dataconnect:sdk:generate --watchGerar SDKs em pipelines de build
Use a CLI do Firebase para gerar SDKs Data Connect em processos de build de CI/CD.
firebase dataconnect:sdk:generateConfigurar o código do cliente
Incorpore Data Connect ao código do cliente
Para configurar seu código do cliente para usar Data Connect e o SDK gerado, siga primeiro as instruções de configuração padrão do Firebase.
Em seguida, adicione o seguinte à seção plugins em 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
Em seguida, adicione o seguinte à seção dependencies em
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
Inicializar o SDK do Android Data Connect
Inicialize a instância Data Connect usando as informações que você usou para configurar o Data Connect (tudo disponível na guia Data Connect do console Firebase).
O objeto ConnectorConfig
O SDK exige um objeto de configuração do conector.
Esse objeto é gerado automaticamente de serviceId e location em
dataconnect.yaml, e connectorId em connector.yaml.
Como conseguir uma instância de conector
Agora que você configurou um objeto de configuração, receba uma instância de conector Data Connect. O código do conector será gerado pelo emulador
Data Connect. Se o nome do conector for movies e o
pacote Kotlin for com.myapplication, conforme especificado em connector.yaml, recupere o objeto do conector chamando:
val connector = com.myapplication.MoviesConnector.instance
Usar consultas e mutações do SDK do Android
Com o objeto conector, é possível executar consultas e mutações conforme definido no código-fonte GraphQL. Suponha que seu conector tenha estas operações definidas:
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
}
}
então você pode criar e recuperar um filme da seguinte maneira:
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}")
Você também pode recuperar vários filmes:
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)
Também é possível coletar um Flow que só produzirá um resultado quando um novo resultado de consulta
for recuperado usando uma chamada para o método execute() da consulta.
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
Processar mudanças em campos de enumeração
O esquema de um app pode conter enumerações, que podem ser acessadas pelas suas consultas GraphQL.
À medida que o design de um app muda, você pode adicionar novos valores compatíveis com enumeração. Por exemplo, imagine que, mais tarde no ciclo de vida do aplicativo, você decida adicionar um valor
FULLSCREEN à enumeração AspectRatio.
No fluxo de trabalho do Data Connect, você pode usar ferramentas de desenvolvimento local para atualizar suas consultas e SDKs.
No entanto, antes de lançar uma versão atualizada dos clientes, os clientes implantados mais antigos podem falhar.
Exemplo de implementação resiliente
O SDK gerado força o processamento de valores desconhecidos, já que o código do cliente precisa
desencapsular o objeto EnumValue, que é EnumValue.Known para valores de enumeração conhecidos
ou EnumValue.Unknown para valores desconhecidos.
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()
)
Ativar o armazenamento em cache no lado do cliente
O Data Connect tem um recurso opcional de cache do lado do cliente, que pode ser ativado editando o arquivo connector.yaml. Quando esse recurso está ativado, os SDKs de cliente gerados armazenam em cache localmente as respostas de consulta, o que pode reduzir o número de solicitações de banco de dados feitas pelo app e permitir que as partes dependentes do banco de dados funcionem quando a disponibilidade da rede é interrompida.
Para ativar o cache do lado do cliente, adicione uma configuração de cache do cliente à configuração do conector:
generate:
kotlinSdk:
outputDir: "../android"
package: "com.google.firebase.dataconnect.generated"
clientCache:
maxAge: 5s
storage: persistent
Essa configuração tem dois parâmetros opcionais:
maxAge: a idade máxima que uma resposta em cache pode ter antes que o SDK do cliente busque valores atualizados. Exemplos: "0", "30s", "1h30m".O valor padrão de
maxAgeé0, o que significa que as respostas são armazenadas em cache, mas o SDK do cliente sempre vai buscar valores atualizados. Os valores armazenados em cache só serão usados quandoCACHE_ONLYfor especificado comoexecute().storage: o SDK do cliente pode ser configurado para armazenar respostas em cache no armazenamentopersistentou emmemory. Os resultados armazenados em cache no armazenamentopersistentserão mantidos entre as reinicializações do app. Nos SDKs do Android, o padrão épersistent.
Depois de atualizar a configuração de cache do conector, gere novamente os SDKs do cliente
e reconstrua o app. Depois disso, o execute()
armazenará em cache
respostas e usará valores armazenados em cache de acordo com a política configurada. Isso geralmente acontece de forma automática, sem que você precise seguir etapas adicionais. No entanto, observe o seguinte:
O comportamento padrão de
execute()é o descrito acima: se um resultado for armazenado em cache para uma consulta e o valor armazenado em cache não for mais antigo quemaxAge, use o valor armazenado em cache. Esse comportamento padrão é chamado de política dePREFER_CACHE.Também é possível especificar invocações individuais de
execute()para disponibilizar apenas valores em cache (CACHE_ONLY) ou buscar incondicionalmente valores atualizados do servidor (SERVER_ONLY).val queryResult = queryRef.execute(QueryRef.FetchPolicy.CACHE_ONLY)val queryResult = queryRef.execute(QueryRef.FetchPolicy.SERVER_ONLY)Criar protótipos e testar seu app Android
Instrumentar clientes para usar um emulador local
É possível usar o emulador Data Connect, seja na extensão do Data Connect para VS Code ou na CLI.
A instrumentação do app para se conectar ao emulador é a mesma nos dois cenários.
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 appPara mudar para recursos de produção, adicione um comentário às linhas de conexão com o emulador.
Tipos de dados nos SDKs Data Connect
O servidor Data Connect representa tipos de dados GraphQL comuns e personalizados. Elas são representadas no SDK da seguinte maneira.
Tipo Data Connect Kotlin String String Int Int (número inteiro de 32 bits) Ponto flutuante Double (ponto flutuante de 64 bits) Booleano Booleano UUID java.util.UUID Data com.google.firebase.dataconnect.LocalDate (era java.util.Date até a versão 16.0.0-beta03) Carimbo de data/hora com.google.firebase.Timestamp Int64 Longo Qualquer com.google.firebase.dataconnect.AnyValue