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

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

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

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

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

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

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

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

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

Писать

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

Читать

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

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

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

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

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

1. Идентификаторы, генерируемые сервером (вариант по умолчанию) : клиент отправляет данные без идентификатора, и бэкэнд API Google Health генерирует и возвращает уникальный системный идентификатор.
2. Пользовательские идентификаторы, назначаемые клиентом (согласно AIP-133 , пока не поддерживаются) : клиентское приложение генерирует уникальный идентификатор (например, UUID или первичный ключ локальной базы данных) и предоставляет его в пути к ресурсу при создании.

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

Особенность	Идентификаторы, сгенерированные сервером	Пользовательские идентификаторы, присвоенные клиентом
Генерация идентификаторов	В процессе выполнения POST сервер генерирует случайный идентификатор системы.	Перед записью клиент генерирует стабильный идентификатор локально (UUID v4 / внутренний первичный ключ).
Путь к ресурсу	.../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.

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

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

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

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

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