Управление данными в Google Health API

Работа с данными в Google Health API – это, по сути, цикл синхронизации данных между хранилищем Google Health API в облаке и вашим приложением или серверным хранилищем данных. Однако этот цикл может принимать разные формы в зависимости от множества факторов:

  • Вы записываете данные в Google Health API? Только чтение? Или и то, и другое?
  • Хранилище данных находится в приложении или на устройстве? или в собственном облаке?
  • Нужно ли синхронизировать данные Google Health API между приложением пользователя и носимым устройством? Как часто вы синхронизируете устройства?
  • С какими типами данных вы работаете? Базовые показатели? Единицы измерения? Серии с разной частотой выборки?
  • Планируете ли вы считывать данные, когда приложение работает в фоновом режиме?
  • Планируете ли вы работать со статистикой, записанной до того, как приложение получило разрешения пользователя?

Чтобы понять, как все это работает, ознакомьтесь с жизненным циклом синхронизации Google Health API. Существует две версии этого жизненного цикла: стандартная (чтение и запись) и только чтение.

Стандартный жизненный цикл синхронизации

Стандартный жизненный цикл синхронизации в Google Health API
Рисунок 1. Жизненный цикл стандартной синхронизации в Google Health API

Интеграция с Google Health API подразумевает копирование данных в приложение или внутреннее хранилище. Для простоты в этой документации мы будем называть это хранилище хранилищем данных разработчика.

Под копированием здесь понимается любое действие, например чтение из Google Health API (копирование в хранилище данных разработчика) или запись в Google Health API (копирование в Google Health API). Повторяющееся выполнение этих действий в определенном порядке называется жизненным циклом синхронизации.

На рисунке 1 показан стандартный жизненный цикл синхронизации, включающий операции чтения и записи, без учета каких-либо ранее упомянутых факторов.

Запись

  1. Подготовка новых данных для записи. Перенесите данные с внешнего устройства или из приложения и отформатируйте элементы в представления JSON, совместимые с типами данных Google Health API. Обратите внимание, что в настоящее время Health API не поддерживает пользовательские идентификаторы, назначаемые клиентом для записи. Такие идентификаторы могут быть указаны в POST, но они игнорируются.
  2. Добавление и обновление записей. Отправка элементов данных в Google Health API с помощью конечных точек REST. Используйте POST для создания записей, а PATCH – для вставки и обновления существующих записей. Идентификаторы, необходимые для операции PATCH, будут получены в результате предыдущей операции POST (следующий шаг в предыдущем цикле).
  3. Обработка возвращенных идентификаторов ресурсов. Если вы используете идентификаторы, созданные сервером, извлеките и сохраните возвращенный сервером ресурс name или идентификатор в хранилище данных разработчика, чтобы в будущем можно было обновлять (PATCH) или удалять (DELETE) данные. Подробнее о стратегиях идентификации…

Чтение

  1. Чтение записей. Получайте новые данные и изменения существующих данных из Google Health API с помощью конечных точек REST (GET с параметрами запроса filter и разбиением на страницы pageToken или конечных точек агрегирования, таких как rollUp и dailyRollUp) или получайте уведомления с помощью подписок на вебхуки (projects.subscribers). Уведомление указывает только на то, что доступны новые данные, а не на то, что это за данные.
  2. Сверка хранилища данных разработчика. Сверьте новые и обновленные данные с хранилищем данных разработчика. Подключенные устройства могут создавать перекрывающиеся интервалы во время синхронизации. Чтобы узнать, как Google Health API решает эти проблемы, прочитайте статью Временные метки интервалов и синхронизация подключенных устройств.

Затем этот цикл повторяется с интервалами, которые зависят от потребностей внешних устройств или приложений. Обычно мы рекомендуем синхронизировать данные между вашим хранилищем и Google Health API в таком порядке.

Стратегии идентификации

Если вы планируете записывать данные в Google Health API, то перед интеграцией с Google Health API вам нужно выбрать стратегию идентификации ресурсов при создании элементов данных (базовых единиц данных).

В настоящее время Health API не поддерживает идентификаторы, назначенные клиентом для записи. Такие идентификаторы могут быть указаны в POST, но они игнорируются. Информация об этом варианте приведена здесь в ознакомительных целях.

  1. Идентификаторы, созданные сервером (вариант по умолчанию). Клиент отправляет данные без идентификатора, а серверная часть Google Health API создает и возвращает уникальный системный идентификатор.
  2. Пользовательские идентификаторы, назначенные клиентом (согласно 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 букв в нижнем регистре, цифр и дефисов).
Когда выбирать

Выбирайте идентификаторы, созданные сервером, если:

  • Приложение работает только в режиме записи или добавления (например, отправляет данные телеметрии или количество шагов, которые не обновляются и не удаляются).
  • Приложение не поддерживает локальную постоянную базу данных отдельных элементов.
  • Вам не нужно управлять ограничениями на проверку строк (например, 4-63 символов).

Выбирайте пользовательские идентификаторы, если:

  • Вы управляете приложением с двунаправленной синхронизацией, которое читает, записывает и обновляет информацию о здоровье на разных устройствах.
  • В вашем приложении есть локальная база данных (например, Room или SQLite), в которой хранятся записи с локальными первичными ключами.
  • Пользователи записывают данные в автономном режиме или при нестабильном мобильном подключении, когда необходимы безопасные повторные попытки.
  • Вы хотите исключить таблицы сопоставления идентификаторов между базой данных бэкенда и API.

Жизненный цикл синхронизации только для чтения

Жизненный цикл синхронизации только для чтения в Google Health API
Рисунок 2. Жизненный цикл синхронизации только для чтения в Google Health API

Приложение, которое должно только считывать данные из Google Health API, должно копировать их в хранилище данных разработчика и обрабатывать часть жизненного цикла, связанную со сверкой.

Здесь применимы те же задачи, что и в разделе Чтение.

На рисунке 2 показан жизненный цикл только для чтения.

Временные метки интервалов и синхронизация подключенных устройств

Интервальные данные представляют собой измерения, собранные за определенный период времени, например количество шагов, частоту сердечных сокращений или тренировки. В отличие от них, измерения в определенный момент времени включают записи, сделанные вручную, например журнал питания или показания весов. Обычно интервальные данные поступают при синхронизации подключенных устройств, таких как умные часы и фитнес-трекеры.

Временные метки интервалов (startTime и endTime в полезных нагрузках REST JSON или start_time и end_time в выражениях фильтров и gRPC) привносят уникальные особенности при работе с данными интервалов. В этом разделе объясняется, почему возникают перекрывающиеся интервалы, и сравниваются конечные точки list и reconcile.

Перекрывающиеся интервалы на подключенных устройствах

Подключенные устройства, такие как трекеры Fitbit и Google Pixel Watch, непрерывно собирают высокочастотные биометрические данные, пока вы их носите. После того как устройство синхронизирует данные с Google Health, оно не изменяет существующие записи задним числом. Временные метки интервалов остаются без изменений.

Однако перед последующими циклами синхронизации алгоритмы на устройстве часто заново интерпретируют необработанные данные телеметрии датчиков. Устройство перераспределяет показания, собранные за предыдущие часы. При следующей синхронизации устройство загрузит новые элементы данных. Их границы начала и конца могут перекрываться с ранее сохраненными интервалами.

Например, пользователь носит умные часы, данные о его активности синхронизируются двумя последовательными пакетами:

  1. Во время первой синхронизации устройство загружает данные за период с 10:00:00Z по 10:14:59Z.
  2. После пересчета на устройстве вторая синхронизация загружает ещё один элемент данных, охватывающий период с 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 обрабатывает перекрывающиеся сеансы. Вместо того чтобы создавать искусственное объединение времени, система выбирает авторитетную запись.

Разрешение перекрывающихся интервалов: согласование дедупликации конечных точек и искусственного объединения времени
Рисунок 3. Согласование конфликтующих сеансов и искусственное объединение по времени

Полные примеры запросов и ответов приведены в руководстве по конечным точкам. Чтобы сравнить необработанные записи list с выходными данными reconcile, ознакомьтесь со статьей Как получить согласованное представление данных за интервал.

Конечная точка list предназначена для диагностики устройств и аудита данных. Используйте его, если вам нужно проверять неизмененные записи, загруженные с каждого устройства. При запросе с list логика клиента должна обрабатывать любые перекрытия интервалов в первичных данных.

Изменяемость временных меток и обновление владельцев

Подключенные устройства не изменяют временные метки задним числом во время обычных циклов синхронизации. Однако временные метки интервалов (startTime и endTime в полезных нагрузках REST JSON или start_time и end_time в выражениях фильтров и gRPC) не являются неизменяемыми для всех источников данных. Изменять поля записи может только ее создатель или владелец. Другие приложения не могут изменять элементы данных, которые они не создавали.

Приложение-владелец может использовать конечную точку patch, чтобы обновлять существующие записи. В частности, можно изменить временные метки начала и окончания, что приведет к обновлению полей UTC (startTime и endTime) и гражданского времени (civilStartTime и civilEndTime) на сервере. Пример обновления временных меток с помощью PATCH приведен в разделе Обновление временных меток интервалов для существующих данных руководства по конечным точкам.

Аналогично, элементы данных, синхронизированные с внешних платформ, таких как "Здоровье и спорт" или партнерские приложения, наследуют обновления из исходного источника. Если впоследствии Здоровье и спорт получит обновление для синхронизированной записи из исходного стороннего приложения, эти изменения будут распространены и перезапишут существующую запись.