Administración de datos en la API de Google Health

En esencia, trabajar con datos en la API de Google Health es un ciclo de sincronización de datos entre el almacén de datos de la API de Google Health en la nube y tu propia app o almacén de datos de backend. Sin embargo, este ciclo puede adoptar diferentes formas según una variedad de factores:

• ¿Escribes datos en la API de Google Health? ¿Solo lees? ¿O haces ambas cosas?
• ¿Tu almacén de datos es local en la app o el dispositivo? ¿O en tu propia nube?
• ¿Necesitas sincronizar datos de la API de Google Health entre la app del usuario y un dispositivo wearable? ¿Con qué frecuencia sincronizas los dispositivos?
• ¿Con qué tipos de datos trabajas? ¿Recuentos básicos? ¿Unidades de medida? ¿Series con diferentes tasas de muestreo?
• ¿Planeas leer datos mientras la app se ejecuta en segundo plano?
• ¿Planeas trabajar con datos históricos registrados antes de que tu app reciba permisos del usuario?

Para comprender cómo se relaciona todo, consulta el ciclo de vida de sincronización de la API de Google Health. Existen dos versiones de este ciclo de vida: estándar (lectura y escritura) y de solo lectura.

El ciclo de vida de sincronización estándar

Figura 1: Ciclo de vida de sincronización estándar en la API de Google Health

La integración con la API de Google Health implica copiar datos en un almacén de datos de backend o de la app. Para facilitar el uso en esta documentación, llamaremos a este almacén de datos el almacén de datos del desarrollador.

Aquí, "copiar" puede reemplazar cualquier actividad discreta, como leer desde la API de Google Health (copiar al almacén de datos del desarrollador) o escribir en la API de Google Health (copiar a la API de Google Health). Realizar estas acciones de forma repetida en un orden específico es el ciclo de vida de sincronización.

En la figura 1, se ilustra el ciclo de vida de sincronización estándar que incluye operaciones de lectura y escritura, sin importar ninguno de los factores mencionados anteriormente.

Escritura

1. Prepara datos nuevos para la escritura : Transfiere datos desde un dispositivo o una app externos, y da formato a los puntos de datos en representaciones JSON compatibles con los tipos de datos de la API de Google Health. Ten en cuenta que, por el momento, no se admiten IDs personalizados asignados por el cliente para las escrituras en la API de Health. Es posible que se proporcionen esos IDs en un POST, pero se ignoran.
2. Registros de upsert : Envía puntos de datos a la API de Google Health con extremos REST. Usa POST para crear registros y PATCH para insertar y actualizar registros existentes. Los IDs necesarios para la operación PATCH provendrán de una operación POST anterior (próximo paso en un ciclo anterior).
3. Procesa los IDs de recursos devueltos : Cuando uses IDs generados por el servidor, extrae y conserva el ID o el name del recurso que devuelve el servidor en tu almacén de datos del desarrollador para habilitar futuras actualizaciones (PATCH) o eliminaciones (DELETE). Consulta Estrategias de identificación para obtener más información sobre los dos tipos.

Leer

1. Leer registros : Recupera datos nuevos y cambios en los datos existentes en la API de Google Health con extremos REST (GET con parámetros de consulta filter y paginación pageToken, o extremos de agregación como rollUp y dailyRollUp), o recibe notificaciones en tiempo real con suscripciones de webhook (projects.subscribers). Una notificación solo indica que hay datos nuevos disponibles, no cuáles son los datos reales.
2. Concilia el almacén de datos del desarrollador : Concilia los datos nuevos y actualizados con tu almacén de datos del desarrollador.

Luego, este ciclo se repite en intervalos adecuados según las necesidades específicas de los dispositivos o las apps externos. En general, este es el orden que recomendamos para sincronizar datos entre tu propio almacén de datos y la API de Google Health.

Estrategias de identificación

Si deseas escribir datos en la API de Google Health, antes de compilar tu integración con las APIs de Google Health, debes elegir una estrategia de identificación de recursos cuando crees puntos de datos (la unidad básica de datos).

Por el momento, no se admiten IDs personalizados asignados por el cliente para las escrituras en la API de Health. Es posible que se proporcionen esos IDs en un POST, pero se ignoran. Los detalles sobre esta opción se proporcionan aquí con fines informativos.

1. IDs generados por el servidor (opción predeterminada): El cliente envía datos sin un ID, y el backend de la API de Google Health genera y devuelve un identificador único del sistema.
2. IDs personalizados asignados por el cliente (según AIP-133, aún no compatibles): La app cliente genera un identificador único (por ejemplo, un UUID o una clave principal de la base de datos local) y lo proporciona en la ruta de recursos cuando se crea.

En la siguiente tabla, se comparan ambas estrategias de identificación para ayudarte a elegir el enfoque adecuado para tu integración:

Función	IDs generados por el servidor	IDs personalizados asignados por el cliente
Generación de IDs	El servidor genera un ID del sistema aleatorio durante POST ejecución.	El cliente genera un ID estable de forma local (UUID v4 / PK interna) antes de la escritura.
Ruta de recursos	.../dataPoints/{server_id} (devuelto en la respuesta)	.../dataPoints/{custom_id}
Paso local posterior a la escritura	Obligatorio. Debe almacenar el server_id devuelto en la base de datos local para habilitar futuras actualizaciones o eliminaciones.	Ninguno. La app ya posee el ID.
Tabla de asignación de IDs	Obligatorio. El cliente debe mantener una asignación bidireccional (local_id ↔ server_id).	No es necesario. El cliente usa su propia clave principal directamente.
Comportamiento de reintento (red débil)	Riesgo de duplicados. Si se reintenta un POST con tiempo de espera agotado, se crea un registro duplicado con un ID de servidor nuevo.	Seguro e idempotente. Si se reintenta POST con el mismo custom_id se evita la creación de duplicados (devuelve 409 ALREADY_EXISTS).
Compatibilidad con la sincronización sin conexión	Limitado. Debes esperar la respuesta del servidor para obtener los IDs de recursos oficiales antes de hacer referencia a ellos.	Full. Las entidades se pueden crear y mutar sin conexión con IDs estables y, luego, sincronizar sin problemas cuando se restablece la conexión.
Restricciones de formato	El servidor se encarga de todo.	Debe seguir ^[a-z0-9-]{4,63}$ (4–63 caracteres alfanuméricos en minúscula y guiones).
Cuándo elegir	Elige IDs generados por el servidor si se cumplen las siguientes condiciones: Tu app es de solo escritura o de solo anexión (p.ej., envía datos de telemetría o recuentos de pasos que nunca se actualizan ni se borran más adelante). Tu app no mantiene una base de datos persistente local de puntos de datos individuales. Prefieres la simplicidad sin administrar restricciones de validación de cadenas (como 4-63 caracteres).	Elige IDs personalizados si se cumplen las siguientes condiciones: Operas una app de sincronización bidireccional que lee, escribe y actualiza registros de salud en todos los dispositivos. Tu app tiene una base de datos local (como Room o SQLite) que almacena registros con claves principales locales. Tus usuarios registran datos sin conexión o a través de conexiones móviles intermitentes en las que son necesarios reintentos seguros. Deseas eliminar las tablas de asignación de IDs entre tu base de datos de backend y la API.

El ciclo de vida de sincronización de solo lectura

Figura 2: Ciclo de vida de sincronización de solo lectura en la API de Google Health

Una app que solo desea leer desde la API de Google Health debe copiar datos a su almacén de datos del desarrollador y controlar la parte de conciliación del ciclo de vida.

Aquí se aplican las mismas tareas que se describen en la sección Leer.

En la figura 2, se ilustra el ciclo de vida de solo lectura.