Gerenciamento de dados na API Google Health

Trabalhar com dados na API Google Health é, essencialmente, um ciclo de sincronização de dados entre o armazenamento de dados da API Google Health na nuvem e o armazenamento de dados do seu app ou back-end. No entanto, esse ciclo pode assumir formas diferentes, dependendo de vários fatores:

• Você está gravando dados na API Google Health? Apenas lendo? Ou fazendo os dois?
• O armazenamento de dados é local no app ou dispositivo? Ou na sua própria nuvem?
• Você precisa sincronizar os dados da API Google Health entre o app do usuário e um dispositivo wearable? Com que frequência você sincroniza os dispositivos?
• Com que tipos de dados você está trabalhando? Contagens básicas? Unidades de medida? Séries com diferentes taxas de amostragem?
• Você planeja ler dados enquanto o app está em segundo plano?
• Você planeja trabalhar com dados históricos registrados antes que o app receba permissões do usuário?

Para entender como tudo isso se encaixa, confira o ciclo de vida de sincronização da API Google Health. Há duas versões desse ciclo de vida: padrão (leitura e gravação) e somente leitura.

O ciclo de vida de sincronização padrão

Figura 1: ciclo de vida de sincronização padrão na API Google Health

A integração com a API Google Health significa copiar dados para um armazenamento de dados de app ou back-end. Para facilitar o uso nesta documentação, vamos chamar esse armazenamento de dados de armazenamento de dados do desenvolvedor.

"Copiar" aqui pode substituir qualquer atividade discreta, como ler na API Google Health (copiar para o armazenamento de dados do desenvolvedor) ou gravar na API Google Health (copiar para a API Google Health). Realizar essas ações repetidamente em uma ordem específica é o ciclo de vida de sincronização.

A Figura 1 ilustra o ciclo de vida de sincronização padrão que envolve operações de leitura e gravação, sem considerar nenhum dos fatores mencionados anteriormente.

Gravação

1. Preparar novos dados para gravação : transfira dados de um dispositivo ou app externo e formate os pontos de dados em representações JSON compatíveis com os tipos de dados da API Google Health. No momento, não há suporte para IDs personalizados atribuídos pelo cliente para gravações na API Health. Esses IDs podem ser fornecidos em um POST, mas são ignorados.
2. Inserir ou atualizar registros : envie pontos de dados para a API Google Health usando endpoints REST. Use POST para criar registros e PATCH para inserir e atualizar registros atuais. Os IDs necessários para a operação PATCH terão vindo de uma operação POST anterior (próxima etapa em um ciclo anterior).
3. Processar IDs de recursos retornados : ao usar IDs gerados pelo servidor, extraia e mantenha o recurso retornado pelo servidor name ou ID no armazenamento de dados do desenvolvedor para permitir atualizações futuras (PATCH) ou exclusões (DELETE). Consulte Estratégias de identificação para mais informações sobre os dois tipos.

Lidos

1. Ler registros : busque novos dados e mudanças nos dados atuais na API Google Health usando endpoints REST (GET com parâmetros de consulta filter e paginação pageToken ou endpoints de agregação como rollUp e dailyRollUp) ou receba notificações em tempo real usando assinaturas de webhook (projects.subscribers). Uma notificação indica apenas que novos dados estão disponíveis, não quais são os dados reais.
2. Reconciliar o armazenamento de dados do desenvolvedor : reconcilie os dados novos e atualizados com o armazenamento de dados do desenvolvedor.

Esse ciclo se repete em intervalos adequados de acordo com as necessidades específicas de dispositivos ou apps externos. Essa é geralmente a ordem recomendada para sincronizar dados entre seu próprio armazenamento de dados e a API Google Health.

Estratégias de identificação

Se você pretende gravar dados na API Google Health, antes de criar a integração com as APIs Google Health, escolha uma estratégia de identificação de recursos ao criar pontos de dados (a unidade básica de dados).

No momento, não há suporte para IDs atribuídos pelo cliente para gravações na API Health. Esses IDs podem ser fornecidos em um POST, mas são ignorados. Os detalhes dessa opção são fornecidos aqui para fins informativos.

1. IDs gerados pelo servidor (opção padrão): o cliente envia dados sem um ID, e o back-end da API Google Health gera e retorna um identificador de sistema exclusivo.
2. IDs personalizados atribuídos pelo cliente (por AIP-133, ainda não compatível): o app cliente gera um identificador exclusivo (por exemplo, um UUID ou uma chave primária de banco de dados local) e o fornece no caminho do recurso após a criação.

A tabela a seguir compara as duas estratégias de identificação para ajudar você a escolher a abordagem certa para sua integração:

Recurso	IDs gerados pelo servidor	IDs personalizados atribuídos pelo cliente
Geração de ID	O servidor gera um ID de sistema aleatório durante POST execução.	O cliente gera um ID estável localmente (UUID v4 / PK interno) antes da gravação.
Caminho do recurso	.../dataPoints/{server_id} (retornado na resposta)	.../dataPoints/{custom_id}
Etapa local pós-gravação	Obrigatório. É necessário armazenar o server_id retornado no banco de dados local para permitir atualizações/exclusões futuras.	Nenhum. O app já tem o ID.
Tabela de mapeamento de ID	Obrigatório. O cliente precisa manter um mapeamento bidirecional (local_id ↔ server_id).	Não é necessário. O cliente usa a própria chave primária diretamente.
Comportamento de repetição (rede fraca)	Risco de duplicados. Repetir um POST com tempo limite cria um registro duplicado com um novo ID do servidor.	Seguro e idempotente. Repetir POST com o mesmo custom_id impede a criação de duplicados (retorna 409 ALREADY_EXISTS).
Suporte à sincronização off-line	Limitado. É necessário aguardar a resposta do servidor para receber IDs de recursos oficiais antes de fazer referência a eles.	Completo. As entidades podem ser criadas e modificadas off-line com IDs estáveis e, em seguida, sincronizadas perfeitamente quando reconectadas.
Restrições de formato	Gerenciado totalmente pelo servidor.	Precisa seguir ^[a-z0-9-]{4,63}$ (4 a 63 caracteres alfanuméricos e hifens em letras minúsculas).
Quando escolher	Escolha IDs gerados pelo servidor se: O app é somente gravação / somente anexação (por exemplo, envio de telemetria ou contagens de etapas que nunca são atualizadas ou excluídas posteriormente). O app não mantém um banco de dados persistente local de pontos de dados individuais. Você prefere a simplicidade sem gerenciar restrições de validação de string (como caracteres 4-63).	Escolha IDs personalizados se: Você opera um app de sincronização bidirecional que lê, grava e atualiza registros de saúde em dispositivos. O app tem um banco de dados local (como Room ou SQLite) que armazena registros com chaves primárias locais. Os usuários registram dados off-line ou em conexões móveis intermitentes em que são necessárias novas tentativas seguras. Você quer eliminar tabelas de mapeamento de ID entre o banco de dados de back-end e a API.

O ciclo de vida de sincronização somente leitura

Figura 2: ciclo de vida de sincronização somente leitura na API Google Health

Um app que pretende apenas ler na API Google Health precisa copiar dados para o armazenamento de dados do desenvolvedor e processar a parte de reconciliação do ciclo de vida.

As mesmas tarefas abordadas na seção "Ler" se aplicam aqui.

A Figura 2 ilustra o ciclo de vida somente leitura.