Клиентские SDK Firebase Data Connect позволяют вызывать серверные запросы и мутации непосредственно из приложения Firebase. Вы генерируете собственный клиентский SDK параллельно с разработкой схем, запросов и мутаций, которые вы разворачиваете в сервисе Data Connect . Затем вы интегрируете методы из этого SDK в клиентскую логику.
Как мы уже упоминали ранее, важно отметить, что запросы и мутации Data Connect не отправляются клиентским кодом и не выполняются на сервере. Вместо этого при развёртывании операции Data Connect хранятся на сервере, как облачные функции. Это означает, что вам необходимо развернуть соответствующие изменения на стороне клиента, чтобы избежать нарушения работы существующих пользователей (например, в старых версиях приложения).
Именно поэтому Data Connect предоставляет вам среду разработки и инструменты, позволяющие создавать прототипы схем, запросов и мутаций, развёртываемых на сервере. Кроме того, Data Connect автоматически генерирует клиентские SDK во время создания прототипа.
После итеративного обновления сервисных и клиентских приложений обновления как на стороне сервера, так и на стороне клиента готовы к развертыванию.
Каков рабочий процесс разработки клиента?
Если вы следовали руководству «Начало работы» , то вы уже ознакомились с общим процессом разработки Data Connect . В этом руководстве вы найдете более подробную информацию о создании Android SDK на основе вашей схемы и работе с клиентскими запросами и мутациями.
Подводя итог, чтобы использовать сгенерированные Android SDK в клиентских приложениях, вам необходимо выполнить следующие предварительные действия:
- Добавьте Firebase в ваше приложение Android .
- Настройте Data Connect как зависимость в Gradle.
- Добавьте плагин Gradle для сериализации Kotlin и зависимость Gradle.
Затем:
- Разработайте схему своего приложения.
Настройте генерацию SDK:
- С кнопкой «Добавить SDK в приложение» в нашем расширении Data Connect VS Code
- Обновив ваш
connector.yaml
Настройте и используйте эмулятор Data Connect и повторите попытку.
Создайте свой Kotlin SDK
Как и в большинстве проектов Firebase, работа над клиентским кодом Firebase Data Connect осуществляется в локальном каталоге проекта. Расширение Data Connect VS Code и Firebase CLI — важные локальные инструменты для генерации и управления клиентским кодом.
Параметры генерации SDK привязаны к нескольким записям в файле dataconnect.yaml
, созданном при инициализации проекта.
Инициализировать генерацию SDK
В файлеconnector.yaml
добавьте outputDir
, package
и (для веб-SDK) packageJsonDir
. connectorId: movies
generate:
kotlinSdk:
outputDir: ../../../src/main/java/com/myapplication
package: com.myapplication
Замените outputDir
на путь к каталогу, в который будет помещен сгенерированный код; этот путь указывается относительно каталога, содержащего сам файл connector.yaml
. Замените package
на оператор пакета Kotlin, который будет использоваться в сгенерированных файлах, или опустите package
, чтобы использовать пакет по умолчанию.
Обновляйте SDK во время создания прототипа
При интерактивном прототипировании с помощью расширения Data Connect VS Code и его эмулятора Data Connect исходные файлы SDK автоматически генерируются и обновляются при изменении файлов .gql
определяющих схемы, запросы и мутации. Это может быть полезной функцией в рабочих процессах горячей (пере)загрузки.
.gql
, а также автоматическое обновление исходных кодов SDK.Кроме того, вы можете использовать CLI для повторной генерации SDK при каждом изменении файлов .gql:
firebase dataconnect:sdk:generate --watch
Создание SDK для интеграции и выпуска продуктов
В некоторых сценариях, например при подготовке исходных кодов проекта для отправки на CI-тесты, вы можете вызвать Firebase CLI для пакетного обновления.
В этих случаях используйте firebase dataconnect:sdk:generate
.
Настроить клиентский код
Интегрируйте Data Connect в свой клиентский код
Чтобы настроить клиентский код для использования Data Connect и сгенерированного вами SDK, сначала следуйте стандартным инструкциям по настройке Firebase .
Затем добавьте следующее в раздел plugins
в 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
Затем добавьте следующее в раздел dependencies
в app/build.gradle.kts
:
implementation(platform("com.google.firebase:firebase-bom:33.16.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
Инициализируйте Data Connect Android SDK
Инициализируйте свой экземпляр Data Connect используя информацию, которую вы использовали для настройки Data Connect (все доступно на вкладке Data Connect консоли Firebase ).
Объект ConnectorConfig
Для SDK требуется объект конфигурации коннектора.
Этот объект автоматически генерируется из serviceId
и location
в dataconnect.yaml
и connectorId
в connector.yaml
.
Получение экземпляра коннектора
Теперь, когда вы настроили объект конфигурации, получите экземпляр коннектора Data Connect . Код для вашего коннектора будет сгенерирован эмулятором Data Connect . Если имя вашего коннектора — movies
, а пакет Kotlin — com.myapplication
, как указано в connector.yaml
, то получите объект коннектора, вызвав:
val connector = com.myapplication.MoviesConnector.instance
Используйте запросы и мутации из вашего Android SDK
С помощью объекта-коннектора вы можете выполнять запросы и мутации, как определено в исходном коде GraphQL. Предположим, что для вашего коннектора определены следующие операции:
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
}
}
то вы можете создать и получить фильм следующим образом:
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}")
Вы также можете получить несколько фильмов:
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)
Вы также можете собрать Flow
, который будет выдавать результат только при получении нового результата запроса с помощью вызова метода execute()
запроса.
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
Создайте прототип и протестируйте свое приложение для Android
Клиенты инструмента используют локальный эмулятор
Вы можете использовать эмулятор Data Connect как из расширения Data Connect VS Code, так и из CLI.
Настройка приложения для подключения к эмулятору одинакова для обоих сценариев.
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 app
Для переключения на производственные ресурсы закомментируйте строки подключения к эмулятору.
Типы данных в SDK Data Connect
Сервер Data Connect поддерживает стандартные и пользовательские типы данных GraphQL. В SDK они представлены следующим образом.
Тип подключения данных | Котлин |
---|---|
Нить | Нить |
Инт | Int (32-битное целое число) |
Плавать | Double (64-битное число с плавающей точкой) |
Булевое значение | Булевое значение |
UUID | java.util.UUID |
Дата | com.google.firebase.dataconnect.LocalDate (был java.util.Date до версии 16.0.0-beta03) |
Метка времени | com.google.firebase.Timestamp |
Int64 | Длинный |
Любой | com.google.firebase.dataconnect.AnyValue |
Клиентские SDK Firebase Data Connect позволяют вызывать серверные запросы и мутации непосредственно из приложения Firebase. Вы генерируете собственный клиентский SDK параллельно с разработкой схем, запросов и мутаций, которые вы разворачиваете в сервисе Data Connect . Затем вы интегрируете методы из этого SDK в клиентскую логику.
Как мы уже упоминали ранее, важно отметить, что запросы и мутации Data Connect не отправляются клиентским кодом и не выполняются на сервере. Вместо этого при развёртывании операции Data Connect хранятся на сервере, как облачные функции. Это означает, что вам необходимо развернуть соответствующие изменения на стороне клиента, чтобы избежать нарушения работы существующих пользователей (например, в старых версиях приложения).
Именно поэтому Data Connect предоставляет вам среду разработки и инструменты, позволяющие создавать прототипы схем, запросов и мутаций, развёртываемых на сервере. Кроме того, Data Connect автоматически генерирует клиентские SDK во время создания прототипа.
После итеративного обновления сервисных и клиентских приложений обновления как на стороне сервера, так и на стороне клиента готовы к развертыванию.
Каков рабочий процесс разработки клиента?
Если вы следовали руководству «Начало работы» , то вы уже ознакомились с общим процессом разработки Data Connect . В этом руководстве вы найдете более подробную информацию о создании Android SDK на основе вашей схемы и работе с клиентскими запросами и мутациями.
Подводя итог, чтобы использовать сгенерированные Android SDK в клиентских приложениях, вам необходимо выполнить следующие предварительные действия:
- Добавьте Firebase в ваше приложение Android .
- Настройте Data Connect как зависимость в Gradle.
- Добавьте плагин Gradle для сериализации Kotlin и зависимость Gradle.
Затем:
- Разработайте схему своего приложения.
Настройте генерацию SDK:
- С кнопкой «Добавить SDK в приложение» в нашем расширении Data Connect VS Code
- Обновив ваш
connector.yaml
Настройте и используйте эмулятор Data Connect и повторите попытку.
Создайте свой Kotlin SDK
Как и в большинстве проектов Firebase, работа над клиентским кодом Firebase Data Connect осуществляется в локальном каталоге проекта. Расширение Data Connect VS Code и Firebase CLI — важные локальные инструменты для генерации и управления клиентским кодом.
Параметры генерации SDK привязаны к нескольким записям в файле dataconnect.yaml
, созданном при инициализации проекта.
Инициализировать генерацию SDK
В файлеconnector.yaml
добавьте outputDir
, package
и (для веб-SDK) packageJsonDir
. connectorId: movies
generate:
kotlinSdk:
outputDir: ../../../src/main/java/com/myapplication
package: com.myapplication
Замените outputDir
на путь к каталогу, в который будет помещен сгенерированный код; этот путь указывается относительно каталога, содержащего сам файл connector.yaml
. Замените package
на оператор пакета Kotlin, который будет использоваться в сгенерированных файлах, или опустите package
, чтобы использовать пакет по умолчанию.
Обновляйте SDK во время создания прототипа
При интерактивном прототипировании с помощью расширения Data Connect VS Code и его эмулятора Data Connect исходные файлы SDK автоматически генерируются и обновляются при изменении файлов .gql
определяющих схемы, запросы и мутации. Это может быть полезной функцией в рабочих процессах горячей (пере)загрузки.
.gql
, а также автоматическое обновление исходных кодов SDK.Кроме того, вы можете использовать CLI для повторной генерации SDK при каждом изменении файлов .gql:
firebase dataconnect:sdk:generate --watch
Создание SDK для интеграции и выпуска продуктов
В некоторых сценариях, например при подготовке исходных кодов проекта для отправки на CI-тесты, вы можете вызвать Firebase CLI для пакетного обновления.
В этих случаях используйте firebase dataconnect:sdk:generate
.
Настроить клиентский код
Интегрируйте Data Connect в свой клиентский код
Чтобы настроить клиентский код для использования Data Connect и сгенерированного вами SDK, сначала следуйте стандартным инструкциям по настройке Firebase .
Затем добавьте следующее в раздел plugins
в 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
Затем добавьте следующее в раздел dependencies
в app/build.gradle.kts
:
implementation(platform("com.google.firebase:firebase-bom:33.16.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
Инициализируйте Data Connect Android SDK
Инициализируйте свой экземпляр Data Connect используя информацию, которую вы использовали для настройки Data Connect (все доступно на вкладке Data Connect консоли Firebase ).
Объект ConnectorConfig
Для SDK требуется объект конфигурации коннектора.
Этот объект автоматически генерируется из serviceId
и location
в dataconnect.yaml
и connectorId
в connector.yaml
.
Получение экземпляра коннектора
Теперь, когда вы настроили объект конфигурации, получите экземпляр коннектора Data Connect . Код для вашего коннектора будет сгенерирован эмулятором Data Connect . Если имя вашего коннектора — movies
, а пакет Kotlin — com.myapplication
, как указано в connector.yaml
, то получите объект коннектора, вызвав:
val connector = com.myapplication.MoviesConnector.instance
Используйте запросы и мутации из вашего Android SDK
С помощью объекта-коннектора вы можете выполнять запросы и мутации, как определено в исходном коде GraphQL. Предположим, что для вашего коннектора определены следующие операции:
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
}
}
то вы можете создать и получить фильм следующим образом:
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}")
Вы также можете получить несколько фильмов:
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)
Вы также можете собрать Flow
, который будет выдавать результат только при получении нового результата запроса с помощью вызова метода execute()
запроса.
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
Создайте прототип и протестируйте свое приложение для Android
Клиенты инструмента используют локальный эмулятор
Вы можете использовать эмулятор Data Connect как из расширения Data Connect VS Code, так и из CLI.
Настройка приложения для подключения к эмулятору одинакова для обоих сценариев.
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 app
Для переключения на производственные ресурсы закомментируйте строки подключения к эмулятору.
Типы данных в SDK Data Connect
Сервер Data Connect поддерживает стандартные и пользовательские типы данных GraphQL. В SDK они представлены следующим образом.
Тип подключения данных | Котлин |
---|---|
Нить | Нить |
Инт | Int (32-битное целое число) |
Плавать | Double (64-битное число с плавающей точкой) |
Булевое значение | Булевое значение |
UUID | java.util.UUID |
Дата | com.google.firebase.dataconnect.LocalDate (был java.util.Date до версии 16.0.0-beta03) |
Метка времени | com.google.firebase.Timestamp |
Int64 | Длинный |
Любой | com.google.firebase.dataconnect.AnyValue |