Scrittura di dati

Questa guida illustra il processo di scrittura o aggiornamento dei dati in Connessione Salute.

Configura la struttura dei dati

Prima di scrivere i dati, dobbiamo configurare i record. Per più di 50 dati tipo, ognuno con le proprie strutture. Consulta la documentazione di riferimento di Jetpack per ulteriori dettagli sui dati tipi disponibili.

Record di base

Il tipo di dati Passi in Connessione Salute registra il numero di passi che un l'utente tra una lettura e l'altra. Il numero di passi rappresenta una misurazione comune su piattaforme di salute, fitness e benessere.

L'esempio seguente mostra come impostare i dati per il conteggio dei passi:

val stepsRecord = StepsRecord(
    count = 120,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET
)

Registrazione con unità di misura

Connessione Salute può archiviare i valori insieme alle relative unità di misura per fornire la precisione. Un esempio è il tipo di dati Alimentazione che è vasto e esaustive. Include una vasta gamma di campi nutritivi facoltativi, dai carboidrati totali alle vitamine. Ogni punto dati rappresenta le sostanze nutritive potenzialmente consumati come parte di un pasto o di un alimento.

In questo tipo di dati, tutti i nutrienti sono rappresentati in unità di Mass, mentre energy è rappresentato in un'unità di Energy.

L'esempio seguente mostra come impostare i dati nutrizionali per un utente che ha mangiato una banana:

val banana = NutritionRecord(
    name = "banana",
    energy = 105.0.kilocalories,
    dietaryFiber = 3.1.grams,
    potassium = 0.422.grams,
    totalCarbohydrate = 27.0.grams,
    totalFat = 0.4.grams,
    saturatedFat = 0.1.grams,
    sodium = 0.001.grams,
    sugar = 14.0.grams,
    vitaminB6 = 0.0005.grams,
    vitaminC = 0.0103.grams,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET
)

Record con dati della serie

Connessione Salute può archiviare un elenco di dati delle serie. Un esempio è la Tipo di dati Battito cardiaco che acquisisce una serie di campioni di battito cardiaco rilevato tra una lettura e l'altra.

In questo tipo di dati, il parametro samples è rappresentato da un elenco di Campioni di battito cardiaco. Ogni campione contiene un valore beatsPerMinute e un valore time.

L'esempio seguente mostra come impostare i dati delle serie del battito cardiaco:

val heartRateRecord = HeartRateRecord(
    startTime = START_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endTime = END_TIME,
    endZoneOffset = END_ZONE_OFFSET,
    // records 10 arbitrary data, to replace with actual data
    samples = List(10) { index ->
        HeartRateRecord.Sample(
            time = START_TIME + Duration.ofSeconds(index.toLong()),
            beatsPerMinute = 100 + index.toLong(),
        )
    }
)

Scrittura di dati

Uno dei flussi di lavoro comuni in Connessione Salute è la scrittura di dati. Per aggiungere record, utilizza insertRecords.

L'esempio seguente mostra come scrivere i conteggi di passaggi per l'inserimento di dati:

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = START_TIME,
            endTime = END_TIME,
            startZoneOffset = START_ZONE_OFFSET,
            endZoneOffset = END_ZONE_OFFSET
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

Aggiorna dati

Se hai bisogno di modificare uno o più record, soprattutto sincronizza il datastore dell'app con i dati di Connessione Salute, puoi aggiornare i tuoi dati. Esistono due modi per aggiornare i dati esistenti, che dipendono identificatore utilizzato per trovare i record.

Metadati

Ti consigliamo di esaminare prima il corso Metadata in quanto è necessario quando aggiornare i dati. Al momento della creazione, ogni Record in Connessione Salute ha un metadata. Le seguenti proprietà sono pertinenti per dell'audiodescrizione:

Aggiorna tramite Record ID

Per aggiornare i dati, prepara prima i record necessari. Apporta eventuali modifiche record, se necessario. Quindi, chiama updateRecords per effettuare le modifiche.

L'esempio seguente mostra come aggiornare i dati. A questo scopo, ogni record i valori di offset di zona vengono regolati in PST.

suspend fun updateSteps(
    healthConnectClient: HealthConnectClient,
    prevRecordStartTime: Instant,
    prevRecordEndTime: Instant
) {
    try {
        val request = healthConnectClient.readRecords(
            ReadRecordsRequest(
                recordType = StepsRecord::class,
                timeRangeFilter = TimeRangeFilter.between(
                    prevRecordStartTime,
                    prevRecordEndTime
                )
            )
        )

        val newStepsRecords = arrayListOf<StepsRecord>()
        for (record in request.records) {
            // Adjusted both offset values to reflect changes
            val sr = StepsRecord(
                count = record.count,
                startTime = record.startTime,
                startZoneOffset = record.startTime.atZone(ZoneId.of("PST")).offset,
                endTime = record.endTime,
                endZoneOffset = record.endTime.atZone(ZoneId.of("PST")).offset,
                metadata = record.metadata
            )
            newStepsRecords.add(sr)
        }

        client.updateRecords(newStepsRecords)
    } catch (e: Exception) {
        // Run error handling here
    }
}

Esegui upsert tramite ID record client

Se utilizzi i valori facoltativi ID record client e Versione record client, consigliamo di utilizzare insertRecords anziché updateRecords.

La funzione insertRecords è in grado di eseguire l'upsert dei dati. Se i dati esistono in Connessione Salute in base all'insieme di dati specificato con gli ID record client, vengono sovrascritti. In caso contrario, vengono scritti come nuovi dati. Questo scenario è utile ogni volta che devi sincronizzare i dati da del tuo datastore dell'app a Connessione Salute.

L'esempio seguente mostra come eseguire un upsert sui dati estratti il datastore dell'app:

suspend fun pullStepsFromDatastore() : ArrayList<StepsRecord> {
    val appStepsRecords = arrayListOf<StepsRecord>()
    // Pull data from app datastore
    // ...
    // Make changes to data if necessary
    // ...
    // Store data in appStepsRecords
    // ...
    var sr = StepsRecord(
        // Assign parameters for this record
        metadata = Metadata(
            clientRecordId = cid
        )
    )
    appStepsRecords.add(sr)
    // ...
    return appStepsRecords
}

suspend fun upsertSteps(
    healthConnectClient: HealthConnectClient,
    newStepsRecords: ArrayList<StepsRecord>
) {
    try {
        healthConnectClient.insertRecords(newStepsRecords)
    } catch (e: Exception) {
        // Run error handling here
    }
}

Dopodiché, puoi chiamare queste funzioni nel thread principale.

upsertSteps(healthConnectClient, pullStepsFromDatastore())

Controllo del valore nella versione del record client

Se il processo di upserting dei dati include la versione del record del client, Health Connect esegue controlli di confronto in clientRecordVersion e i relativi valori. Se la versione dei dati inseriti è superiore a ai dati esistenti, viene eseguito l'upsert. In caso contrario, la procedura ignora la modifica e il valore rimane lo stesso.

Per includere il controllo delle versioni nei dati, devi fornire Metadata.clientRecordVersion con un valore Long basato sul controllo delle versioni logica.

val sr = StepsRecord(
    count = count,
    startTime = startTime,
    startZoneOffset = startZoneOffset,
    endTime = endTime,
    endZoneOffset = endZoneOffset,
    metadata = Metadata(
        clientRecordId = cid,
        clientRecordVersion = version
    )
)

Gli upsert non aumentano automaticamente di version in caso di modifiche, per evitare istanze impreviste di sovrascrittura dei dati. Detto ciò, assegnale manualmente un valore più alto.

Best practice per la scrittura dei dati

Le app devono scrivere in Connessione Salute solo dati provenienti dalla tua proprietà.

Se i dati nella tua app sono stati importati da un'altra app, la responsabilità ricade sull'altra app per scrivere i propri dati in Connessione Salute.

È inoltre consigliabile implementare una logica che gestisca le eccezioni di scrittura come i dati non rientrano nei limiti o si tratta di un errore di sistema interno. Puoi applicare strategie di backoff e di ripetizione di un job su un meccanismo di pianificazione dei job. Se scrivi a Connessione Salute non riesce. Assicurati che la tua app possa andare oltre quel punto di esportazione. Non dimenticare di registrare e segnalare gli errori per facilitare la diagnosi.

Ecco un paio di suggerimenti utili per il monitoraggio dei dati da seguire a seconda del modo in cui l'app scrive i dati.

Monitoraggio passivo

Sono incluse le app che eseguono il monitoraggio passivo o di salute dell'attività, come registrando passi o battito cardiaco in background.

La tua app deve scrivere periodicamente i dati in Connessione Salute nel nei seguenti modi:

• A ogni sincronizzazione, scrivi solo i nuovi dati e quelli aggiornati che sono stati modificati dal giorno durante l'ultima sincronizzazione.
• Richieste di chunk a un massimo di 1000 record per richiesta di scrittura.
• Utilizza WorkManager per pianificare attività periodiche in background, con per un periodo di almeno 15 minuti.

• Limita l'esecuzione delle attività solo quando il dispositivo è inattivo e non è in esaurimento batteria.

  val constraints = Constraints.Builder()
      .requiresBatteryNotLow()
      .requiresDeviceIdle(true)
      .build()
  
  val writeDataWork = PeriodicWorkRequestBuilder<WriteDataToHealthConnectWorker>(
          15,
          TimeUnit.MINUTES,
          5,
          TimeUnit.MINUTES
      )
      .setConstraints(constraints)
      .build()
  

Monitoraggio attivo

Sono incluse le app che eseguono il monitoraggio basato sugli eventi come l'allenamento e il sonno, o input manuali dell'utente come l'alimentazione. Questi record vengono creati quando l'app è in primo piano o in rari eventi quando viene utilizzato più volte in un giorno.

Assicurati che la tua app non mantenga Connessione Salute per l'intera durata durata dell'evento.

I dati devono essere scritti in Connessione Salute in uno dei due modi seguenti:

• Sincronizza i dati in Connessione Salute al termine dell'evento. Ad esempio, sincronizza dati quando l'utente termina una sessione di allenamento rilevata.
• Pianificare un'attività una tantum utilizzando WorkManager per sincronizzare i dati in un secondo momento.

Best practice per granularità e frequenza delle scritture

Quando scrivi dati in Connessione Salute, usa la risoluzione appropriata. L'utilizzo del una risoluzione adeguata aiuta a ridurre il carico di archiviazione, mantenendo al contempo coerenti e accurati. La risoluzione dei dati include due aspetti:

1. Frequenza di scritture: la frequenza con cui l'applicazione esegue il push dei nuovi dati in Connessione Salute. Ad esempio, scrivi nuovi dati ogni 15 minuti.
2. Granularità dei dati scritti: la frequenza con cui i dati inviati sono stati campionato. Ad esempio, scrivi campioni del battito cardiaco ogni 5 secondi. Non tutti i tipi di dati richiede la stessa frequenza di campionamento. L'aggiornamento del conteggio dei passi presenta un vantaggio minimo ogni secondo, al contrario di una cadenza meno frequente come secondi. Tuttavia, frequenze di campionamento più elevate possono offrire agli utenti una cronologia esaminare in modo dettagliato i propri dati relativi a salute e fitness. Frequenze di frequenza di campionamento devono trovare un equilibrio tra dettaglio e rendimento.

Scrivere dati monitorati durante il giorno

Per i dati raccolti regolarmente, come i passaggi, la tua applicazione deve scrivere a Connessione Salute almeno ogni 15 minuti durante la giornata.

Scrittura delle sessioni

I dati devono essere scritti in Connessione Salute alla fine dell'esercizio o del sonno durante la sessione.

Come best practice, qualsiasi sessione di sonno o allenamento deve essere scritta con il dispositivo di registrazione e i metadati appropriati, tra cui RecordingMethod.

Come minimo, la tua richiesta deve seguire le indicazioni della sezione colonna sottostante. Dove possibili, segui le "migliori" guida.

Dati rilevati durante un allenamento

Dati rilevati durante il sonno