Gestione dei dati nell'API Google Health

Lavorare con i dati nell'API Google Health è essenzialmente un ciclo di sincronizzazione dei dati tra il datastore dell'API Google Health nel cloud e il datastore della tua app o del tuo backend. Tuttavia, questo ciclo può assumere forme diverse a seconda di una serie di fattori:

• Stai scrivendo dati nell'API Google Health? Solo lettura? O entrambe le cose?
• Il datastore è locale sull'app o sul dispositivo? O nel tuo cloud?
• Devi sincronizzare i dati dell'API Google Health tra l'app dell'utente e un dispositivo indossabile? Con quale frequenza sincronizzi i dispositivi?
• Con quali tipi di dati stai lavorando? Conteggi di base? Unità di misura? Serie con diverse frequenze di campionamento?
• Hai intenzione di leggere i dati mentre l'app è in background?
• Hai intenzione di lavorare con i dati storici registrati prima che la tua app ricevesse le autorizzazioni dell'utente?

Per capire come si inserisce tutto questo, dai un'occhiata al ciclo di vita della sincronizzazione dell'API Google Health. Esistono due versioni di questo ciclo di vita: standard (lettura e scrittura) e di sola lettura.

Il ciclo di vita della sincronizzazione standard

Figura 1: ciclo di vita della sincronizzazione standard nell'API Google Health

L'integrazione con l'API Google Health comporta la copia dei dati in un'app o in un datastore di backend. Per facilità d'uso in questa documentazione, chiameremo questo datastore datastore dello sviluppatore.

"Copia" può sostituire qualsiasi attività discreta, ad esempio la lettura dall'API Google Health (copia nel datastore dello sviluppatore) o la scrittura nell'API Google Health (copia nell'API Google Health). L'esecuzione ripetuta di queste azioni in un ordine specifico è il ciclo di vita della sincronizzazione.

La Figura 1 illustra il ciclo di vita della sincronizzazione standard che prevede operazioni di lettura e scrittura, indipendentemente dai fattori menzionati in precedenza.

Scrittura

1. Prepara i nuovi dati per la scrittura : trasferisci i dati da un dispositivo o un'app esterni e formatta i punti dati in rappresentazioni JSON compatibili con i tipi di dati dell'API Google Health. Tieni presente che al momento l'API Health non supporta gli ID assegnati dal client personalizzati per le scritture. Questi ID possono essere forniti in un POST, ma vengono ignorati.
2. Applicare l'upsert ai record: invia i punti dati all'API Google Health utilizzando gli endpoint REST. Utilizza POST per creare record e PATCH per inserire e aggiornare i record esistenti. Gli ID necessari per l'operazione PATCH provengono da un'operazione POST precedente (passaggio successivo in un ciclo precedente).
3. Elabora gli ID risorsa restituiti : quando utilizzi gli ID generati dal server, estrai e mantieni la risorsa restituita dal server name o l'ID nel datastore dello sviluppatore per consentire aggiornamenti (PATCH) o eliminazioni (DELETE) futuri. Per ulteriori informazioni sui due tipi, consulta Strategie di identificazione.

Lettura

1. Leggi i record : recupera i nuovi dati e le modifiche ai dati esistenti nell'API Google Health utilizzando gli endpoint REST (GET con parametri di query filter e paginazione pageToken o endpoint di aggregazione come rollUp e dailyRollUp) oppure ricevi notifiche in tempo reale utilizzando gli abbonamenti webhook (projects.subscribers). Una notifica indica solo che sono disponibili nuovi dati, non quali sono i dati effettivi.
2. Riconcilia il datastore dello sviluppatore : riconcilia i dati nuovi e aggiornati con il datastore dello sviluppatore.

Questo ciclo si ripete a intervalli appropriati in base alle esigenze specifiche dei dispositivi o delle app esterni. In genere, questo è l'ordine che consigliamo per la sincronizzazione dei dati tra il tuo datastore e l'API Google Health.

Strategie di identificazione

Se intendi scrivere dati nell'API Google Health, prima di creare l'integrazione con le API Google Health, devi scegliere una strategia di identificazione delle risorse quando crei punti dati (l'unità di dati di base).

Al momento l'API Health non supporta gli ID assegnati dal client per le scritture. Questi ID possono essere forniti in un POST, ma vengono ignorati. I dettagli su questa opzione sono forniti qui a scopo informativo.

1. ID generati dal server (opzione predefinita): il client invia i dati senza un ID e il backend dell'API Google Health genera e restituisce un identificatore di sistema univoco.
2. ID personalizzati assegnati dal client (per AIP-133, non ancora supportati): l'app client genera un identificatore univoco (ad esempio, un UUID o una chiave primaria del database locale) e lo fornisce nel percorso della risorsa al momento della creazione.

La tabella seguente confronta entrambe le strategie di identificazione per aiutarti a scegliere l'approccio giusto per la tua integrazione:

Funzionalità	ID generati dal server	ID personalizzati assegnati dal client
Generazione ID	Il server genera un ID di sistema casuale durante POST esecuzione.	Il client genera un ID stabile localmente (UUID v4 / PK interno) prima della scrittura.
Percorso risorsa	.../dataPoints/{server_id} (restituito nella risposta)	.../dataPoints/{custom_id}
Passaggio locale post-scrittura	Obbligatorio. Devi memorizzare il server_id restituito nel database locale per consentire aggiornamenti/eliminazioni futuri.	Nessuno. L'app possiede già l'ID.
Tabella di mapping degli ID	Obbligatorio. Il client deve mantenere un mapping bidirezionale (local_id ↔ server_id).	Non necessario. Il client utilizza direttamente la propria chiave primaria.
Comportamento di ripetizione (rete debole)	Rischio di duplicati. Se riprovi a eseguire un POST con timeout, viene creato un record duplicato con un nuovo ID server.	Sicuro e idempotente. Se riprovi a eseguire POST con lo stesso custom_id, viene impedita la creazione di duplicati (viene restituito 409 ALREADY_EXISTS).
Supporto della sincronizzazione offline	Limitato. Devi attendere la risposta del server per ottenere gli ID risorsa ufficiali prima di farvi riferimento.	Completo. Le entità possono essere create e modificate offline con ID stabili, quindi sincronizzate senza problemi quando viene ripristinata la connessione.
Vincoli di formato	Gestito interamente dal server.	Deve seguire ^[a-z0-9-]{4,63}$ (4-63 caratteri alfanumerici minuscoli e trattini).
Quando scegliere	Scegli gli ID generati dal server se: La tua app è di sola scrittura / aggiunta (ad es. invio di dati di telemetria o conteggi dei passi che non vengono mai aggiornati o eliminati in un secondo momento). La tua app non gestisce un database permanente locale di singoli punti dati. Preferisci la semplicità senza gestire i vincoli di convalida delle stringhe vincoli (ad esempio, 4-63 caratteri).	Scegli gli ID personalizzati se: Gestisci un'app di sincronizzazione bidirezionale che legge, scrive e aggiorna le cartelle cliniche su tutti i dispositivi. La tua app ha un database locale (ad esempio Room o SQLite) che memorizza record con chiavi primarie locali. I tuoi utenti registrano i dati offline o tramite connessioni mobili intermittenti in cui sono necessari tentativi sicuri. Vuoi eliminare le tabelle di mapping degli ID tra il database di backend e l'API.

Il ciclo di vita della sincronizzazione di sola lettura

Figura 2: ciclo di vita della sincronizzazione di sola lettura nell'API Google Health

Un'app che intende leggere solo dall'API Google Health deve copiare i dati nel proprio datastore dello sviluppatore e gestire la parte di riconciliazione del ciclo di vita.

Le stesse attività descritte nella sezione Lettura si applicano anche qui.

La Figura 2 illustra il ciclo di vita di sola lettura.