Os SDKs de cliente Firebase SQL Connect permitem chamar consultas e mutações do lado do servidor diretamente de um app do Firebase. Você gera um SDK de cliente personalizado em paralelo ao projetar os esquemas, consultas e mutações que implanta no seu SQL Connect serviço. Em seguida, você integra métodos desse SDK à lógica do cliente.
Como já mencionamos em outros lugares, é importante observar que SQL 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 SQL Connect operações são armazenadas no servidor, como as Cloud Functions. Isso significa que você precisa implantar as mudanças correspondentes do lado do cliente para evitar quebrar os usuários atuais (por exemplo, em versões mais antigas do app).
É por isso que SQL Connect oferece um ambiente de desenvolvedor e ferramentas que permitem criar protótipos de esquemas, consultas e mutações implantados no servidor. Ele também gera SDKs do lado do cliente automaticamente durante a criação do protótipo.
Quando você itera atualizações nos apps de serviço e cliente, as atualizações do servidor e do lado do cliente ficam prontas para implantação.
Qual é o fluxo de trabalho de desenvolvimento do cliente?
Se você seguiu o guia de introdução, já conhece o fluxo de desenvolvimento geral do SQL Connect. Neste guia, você encontrará informações mais detalhadas sobre como gerar SDKs do Android a partir do esquema e trabalhar com consultas e mutações do cliente.
Para resumir, para usar os SDKs do Android gerados nos apps do cliente, siga estas etapas de pré-requisito:
- Adicione o Firebase ao seu Android app.
- Configure SQL Connect como uma dependência no Gradle.
- Adicione o plug-in de serialização do Kotlin e a dependência do Gradle.
Em seguida:
- Desenvolva o esquema do app.
Configure a geração do SDK:
- Com o botão Adicionar SDK ao app na extensão do SQL Connect para VS Code
- Ao atualizar seu
connector.yaml
Configure e use o emulador SQL Connect e faça iterações.
Gerar o SDK do Kotlin
Use a CLI para configurar os SDKs gerados nos seus apps.FirebaseSQL Connect
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 do SQL Connect para VS Code instalada, ela sempre manterá os SDKs gerados atualizados.
Se você não usa a extensão do SQL Connect para VS Code, pode usar a CLI do Firebase para manter os SDKs gerados atualizados.
firebase dataconnect:sdk:generate --watchGerar SDKs em pipelines de build
Você pode usar a CLI do Firebase para gerar SQL Connect SDKs em processos de build de CI/CD.
firebase dataconnect:sdk:generateConfigurar o código do cliente
Incorporar SQL Connect ao código do cliente
Para configurar o código do cliente para usar SQL Connect e o SDK gerado, primeiro siga 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.12.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 SQL Connect
Inicialize a instância do SQL Connect usando as informações que você usou para configurar o SQL Connect (tudo disponível na guia "SQL Connect" do console do 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 receber uma instância do conector
Agora que você configurou um objeto de configuração, receba uma instância do SQL Connect
conector. O código do conector será gerado pelo
SQL Connect emulador. Se o nome do conector for movies e o pacote do 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 do conector, é possível executar consultas e mutações conforme definido no código-fonte do GraphQL. Suponha que o conector tenha essas 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
}
}
Em seguida, 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}")
Também é possível 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 nos campos de enumeração
O esquema de um app pode conter enumerações, que podem ser acessadas pelas suas consultas do 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 SQL Connect, é possível usar ferramentas de desenvolvimento local para atualizar consultas e SDKs.
No entanto, antes de lançar uma versão atualizada dos clientes, os clientes implantados mais antigos podem ser interrompidos.
Exemplo de implementação resiliente
O SDK gerado força o processamento de valores desconhecidos, já que o código do cliente precisa
desembrulhar o EnumValue objeto, 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 do lado do cliente
SQL Connect tem um recurso opcional de armazenamento em cache do lado do cliente, que você
pode ativar 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 permite que as partes dependentes do banco de dados do app funcionem quando a disponibilidade da rede é interrompida.
Para ativar o armazenamento em cache do lado do cliente, adicione uma configuração de armazenamento em 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, ambos opcionais:
maxAge: a idade máxima que uma resposta armazenada em cache pode ter antes que o SDK do cliente busque novos valores. 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 novos valores. Os valores armazenados em cache só serão usados quandoCACHE_ONLYfor especificado paraexecute().storage: o SDK do cliente pode ser configurado para armazenar respostas em cache no armazenamentopersistentou namemory. Os resultados armazenados em cache no armazenamentopersistentvão persistir nas reinicializações do app. Nos SDKs do Android, o padrão épersistent.
Depois de atualizar a configuração de armazenamento em cache do conector, regenere os SDKs do cliente
e recrie o app. Depois disso, execute()
vai armazenar
respostas em cache e usar valores armazenados em cache de acordo com a política configurada. Isso geralmente acontece automaticamente, sem etapas adicionais da sua parte. No entanto, observe o seguinte:
O comportamento padrão de
execute()é 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íticaPREFER_CACHE.Também é possível especificar invocações individuais de
execute()para exibir apenas valores armazenados em cache (CACHE_ONLY) ou para buscar incondicionalmente novos valores 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 o app Android
Instrumentar clientes para usar um emulador local
Você pode usar o SQL Connect emulador, seja na extensão do SQL Connect para VS Code ou na CLI.
A instrumentação do app para se conectar ao emulador é a mesma para os 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, comente as linhas de conexão com o emulador.
Tipos de SQL nos SDKs SQL Connect
O servidor SQL Connect representa tipos de dados comuns e personalizados do GraphQL. Eles são representados no SDK da seguinte maneira.
Tipo de SQL Connect Kotlin String String Int Int (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