Работа с данными в Google Health API – это, по сути, цикл синхронизации данных между хранилищем Google Health API в облаке и вашим приложением или серверным хранилищем данных. Однако этот цикл может принимать разные формы в зависимости от множества факторов:
- Вы записываете данные в Google Health API? Только чтение? Или и то, и другое?
- Хранилище данных находится в приложении или на устройстве? или в собственном облаке?
- Нужно ли синхронизировать данные Google Health API между приложением пользователя и носимым устройством? Как часто вы синхронизируете устройства?
- С какими типами данных вы работаете? Базовые показатели? Единицы измерения? Серии с разной частотой выборки?
- Планируете ли вы считывать данные, когда приложение работает в фоновом режиме?
- Планируете ли вы работать со статистикой, записанной до того, как приложение получило разрешения пользователя?
Чтобы понять, как все это работает, ознакомьтесь с жизненным циклом синхронизации Google Health API. Существует две версии этого жизненного цикла: стандартная (чтение и запись) и только чтение.
Стандартный жизненный цикл синхронизации
Интеграция с Google Health API подразумевает копирование данных в приложение или внутреннее хранилище. Для простоты в этой документации мы будем называть это хранилище хранилищем данных разработчика.
Под копированием здесь понимается любое действие, например чтение из Google Health API (копирование в хранилище данных разработчика) или запись в Google Health API (копирование в Google Health API). Повторяющееся выполнение этих действий в определенном порядке называется жизненным циклом синхронизации.
На рисунке 1 показан стандартный жизненный цикл синхронизации, включающий операции чтения и записи, без учета каких-либо ранее упомянутых факторов.
Запись
- Подготовка новых данных для записи. Перенесите данные с внешнего устройства или из приложения и отформатируйте элементы в представления JSON, совместимые с типами данных Google Health API. Обратите внимание, что в настоящее время Health API не поддерживает пользовательские идентификаторы, назначаемые клиентом для записи. Такие идентификаторы могут быть указаны в
POST, но они игнорируются. - Добавление и обновление записей. Отправка элементов данных в Google Health API с помощью конечных точек REST. Используйте
POSTдля создания записей, аPATCH– для вставки и обновления существующих записей. Идентификаторы, необходимые для операцииPATCH, будут получены в результате предыдущей операцииPOST(следующий шаг в предыдущем цикле). - Обработка возвращенных идентификаторов ресурсов. Если вы используете идентификаторы, созданные сервером, извлеките и сохраните возвращенный сервером ресурс
nameили идентификатор в хранилище данных разработчика, чтобы в будущем можно было обновлять (PATCH) или удалять (DELETE) данные. Подробнее о стратегиях идентификации…
Чтение
- Чтение записей. Получайте новые данные и изменения существующих данных из Google Health API с помощью конечных точек REST (
GETс параметрами запросаfilterи разбиением на страницыpageTokenили конечных точек агрегирования, таких какrollUpиdailyRollUp) или получайте уведомления с помощью подписок на вебхуки (projects.subscribers). Уведомление указывает только на то, что доступны новые данные, а не на то, что это за данные. - Сверка хранилища данных разработчика. Сверьте новые и обновленные данные с хранилищем данных разработчика. Подключенные устройства могут создавать перекрывающиеся интервалы во время синхронизации. Чтобы узнать, как Google Health API решает эти проблемы, прочитайте статью Временные метки интервалов и синхронизация подключенных устройств.
Затем этот цикл повторяется с интервалами, которые зависят от потребностей внешних устройств или приложений. Обычно мы рекомендуем синхронизировать данные между вашим хранилищем и Google Health API в таком порядке.
Стратегии идентификации
Если вы планируете записывать данные в Google Health API, то перед интеграцией с Google Health API вам нужно выбрать стратегию идентификации ресурсов при создании элементов данных (базовых единиц данных).
В настоящее время Health API не поддерживает идентификаторы, назначенные клиентом для записи.
Такие идентификаторы могут быть указаны в POST, но они игнорируются. Информация об этом варианте приведена здесь в ознакомительных целях.
- Идентификаторы, созданные сервером (вариант по умолчанию). Клиент отправляет данные без идентификатора, а серверная часть Google Health API создает и возвращает уникальный системный идентификатор.
- Пользовательские идентификаторы, назначенные клиентом (согласно AIP-133, пока не поддерживаются). Клиентское приложение генерирует уникальный идентификатор (например, UUID или первичный ключ локальной базы данных) и предоставляет его в пути к ресурсу при создании.
В таблице ниже сравниваются обе стратегии идентификации, чтобы помочь вам выбрать правильный подход для вашей интеграции:
| Функция | Идентификаторы, созданные сервером | Пользовательские идентификаторы, назначенные клиентом |
|---|---|---|
| Генерация идентификаторов | Сервер генерирует случайный идентификатор системы во время выполнения POST. |
Клиент генерирует стабильный идентификатор локально (UUID v4/внутренний PK) перед записью. |
| Путь к ресурсу | .../dataPoints/{server_id} (возвращается в ответе) |
.../dataPoints/{custom_id} |
| Локальный шаг после записи | Обязательно. Возвращенный идентификатор server_id необходимо сохранить в локальной базе данных, чтобы в будущем можно было обновлять и удалять данные. |
Нет. Идентификатор уже принадлежит приложению. |
| Таблица сопоставления идентификаторов | Обязательно. Клиент должен поддерживать двустороннее сопоставление (local_id ↔ server_id). |
Нет. Клиент использует собственный первичный ключ напрямую. |
| Поведение при повторных попытках (слабая сеть) | Риск дублирования. Повторная попытка выполнить операцию POST, время ожидания которой истекло, приведет к созданию дублирующейся записи с новым идентификатором сервера. |
Безопасный и идемпотентный. Повторная попытка POST с тем же custom_id предотвращает создание дубликатов (возвращает 409
ALREADY_EXISTS). |
| Поддержка офлайн-синхронизации | Ограниченный доступ. Прежде чем ссылаться на идентификаторы ресурсов, необходимо дождаться ответа сервера. | Полный. Объекты можно создавать и изменять в офлайн-режиме, используя стабильные идентификаторы, а затем синхронизировать при подключении к интернету. |
| Ограничения по формату | Полностью обрабатывается сервером. | Должно соответствовать регулярному выражению ^[a-z0-9-]{4,63}$ (от 4 до 63 букв в нижнем регистре, цифр и дефисов). |
| Когда выбирать |
Выбирайте идентификаторы, созданные сервером, если:
|
Выбирайте пользовательские идентификаторы, если:
|
Жизненный цикл синхронизации только для чтения
Приложение, которое должно только считывать данные из Google Health API, должно копировать их в хранилище данных разработчика и обрабатывать часть жизненного цикла, связанную со сверкой.
Здесь применимы те же задачи, что и в разделе Чтение.
На рисунке 2 показан жизненный цикл только для чтения.
Временные метки интервалов и синхронизация подключенных устройств
Интервальные данные представляют собой измерения, собранные за определенный период времени, например количество шагов, частоту сердечных сокращений или тренировки. В отличие от них, измерения в определенный момент времени включают записи, сделанные вручную, например журнал питания или показания весов. Обычно интервальные данные поступают при синхронизации подключенных устройств, таких как умные часы и фитнес-трекеры.
Временные метки интервалов (startTime и endTime в полезных нагрузках REST JSON или start_time и end_time в выражениях фильтров и gRPC) привносят уникальные особенности при работе с данными интервалов. В этом разделе объясняется, почему возникают перекрывающиеся интервалы, и сравниваются конечные точки list и reconcile.
Перекрывающиеся интервалы на подключенных устройствах
Подключенные устройства, такие как трекеры Fitbit и Google Pixel Watch, непрерывно собирают высокочастотные биометрические данные, пока вы их носите. После того как устройство синхронизирует данные с Google Health, оно не изменяет существующие записи задним числом. Временные метки интервалов остаются без изменений.
Однако перед последующими циклами синхронизации алгоритмы на устройстве часто заново интерпретируют необработанные данные телеметрии датчиков. Устройство перераспределяет показания, собранные за предыдущие часы. При следующей синхронизации устройство загрузит новые элементы данных. Их границы начала и конца могут перекрываться с ранее сохраненными интервалами.
Например, пользователь носит умные часы, данные о его активности синхронизируются двумя последовательными пакетами:
- Во время первой синхронизации устройство загружает данные за период с
10:00:00Zпо10:14:59Z. - После пересчета на устройстве вторая синхронизация загружает ещё один элемент данных, охватывающий период с
10:14:00Zдо10:28:59Z.
Обе записи хранятся независимо друг от друга в серверной части Google Health. В результате оба элемента данных охватывают интервал с 10:14:00Z по 10:14:59Z.
Это приводит к 59-секундному перекрытию при запросе необработанных записей.
Сравните списки и сопоставьте конечные точки
Вы можете обрабатывать эти перекрывающиеся интервалы, используя конечную точку list или reconcile. Выберите конечную точку, которая соответствует требованиям вашего приложения:
| Функция | list конечная точка |
reconcile конечная точка |
|---|---|---|
| Метод HTTP | GET https://health.googleapis.com/v4/users/me/dataTypes/dataType/dataPoints |
GET https://health.googleapis.com/v4/users/me/dataTypes/dataType/dataPoints:reconcile |
| Поведение при пересечении | Возвращает все сохраненные записи в том виде, в котором они были загружены, без дедупликации. Если интервалы пересекаются, возвращаются обе записи. | Разрешает конфликты и удаляет дублирующиеся записи на разных устройствах и в разных сеансах синхронизации, объединяя их в один непрерывный поток. |
| Преимущества | Предоставляет полный, неизмененный журнал аудита каждой записи, загруженной каждым устройством и пакетом синхронизации. | Упрощает отрисовку хронологии и расчет продолжительности за счет автоматической обработки перекрывающихся интервалов и конфликтов между несколькими устройствами. |
| Недостатки | Ваше приложение должно обнаруживать и устранять перекрывающиеся интервалы, конфликты между несколькими устройствами и периоды, когда устройство не надето на запястье. | Подчиненные перекрывающиеся записи не включаются в ответ, поэтому отдельные пакеты синхронизации устройств нельзя проверить по отдельности. |
Конечная точка reconcile предназначена для отрисовки пользовательских интерфейсов, визуализации хронологии действий и вычисления неперекрывающихся суммарных длительностей. Она разрешает конфликтующие интервалы из повторно сегментированных сеансов синхронизации. Кроме того, оно сопоставляет данные журнала активности, которые одновременно регистрируются на нескольких устройствах, например на часах и телефоне.
При согласовании конфликтующих сеансов выбирается авторитетная запись, а не синтезируется искусственное объединение времени. Например, диапазоны 11:00:00Z–11:30:00Z и 11:20:00Z–11:50:00Z не будут объединены в диапазон 11:00:00Z–11:50:00Z. В согласованном ответе возвращается элемент данных, который выиграл, с исходным записанным интервалом. Это позволяет сохранить целостность телеметрии и показателей, полученных в ходе сеанса.
На рисунке 3 показано, как конечная точка reconcile обрабатывает перекрывающиеся сеансы.
Вместо того чтобы создавать искусственное объединение времени, система выбирает авторитетную запись.
Полные примеры запросов и ответов приведены в руководстве по конечным точкам. Чтобы сравнить необработанные записи list с выходными данными reconcile, ознакомьтесь со статьей Как получить согласованное представление данных за интервал.
Конечная точка list предназначена для диагностики устройств и аудита данных. Используйте его, если вам нужно проверять неизмененные записи, загруженные с каждого устройства. При запросе с list логика клиента должна обрабатывать любые перекрытия интервалов в первичных данных.
Изменяемость временных меток и обновление владельцев
Подключенные устройства не изменяют временные метки задним числом во время обычных циклов синхронизации. Однако временные метки интервалов (startTime и endTime в полезных нагрузках REST JSON или start_time и end_time в выражениях фильтров и gRPC) не являются неизменяемыми для всех источников данных. Изменять поля записи может только ее создатель или владелец. Другие приложения не могут изменять элементы данных, которые они не создавали.
Приложение-владелец может использовать конечную точку patch, чтобы обновлять существующие записи. В частности, можно изменить временные метки начала и окончания, что приведет к обновлению полей UTC (startTime и endTime) и гражданского времени (civilStartTime и civilEndTime) на сервере. Пример обновления временных меток с помощью PATCH приведен в разделе Обновление временных меток интервалов для существующих данных руководства по конечным точкам.
Аналогично, элементы данных, синхронизированные с внешних платформ, таких как "Здоровье и спорт" или партнерские приложения, наследуют обновления из исходного источника. Если впоследствии Здоровье и спорт получит обновление для синхронизированной записи из исходного стороннего приложения, эти изменения будут распространены и перезапишут существующую запись.