Este guia aborda o processo para gravar ou atualizar dados na plataforma Conexão Saúde.
Configurar a estrutura de dados
Antes de gravar dados, precisamos configurar os registros. Há mais de 50 tipos de dados e cada um tem as respectivas estruturas. Consulte a referência do Jetpack para detalhes sobre os tipos de dados disponíveis.
Registros básicos
O tipo de dado de Passos na plataforma Conexão Saúde captura o número de passos de um usuário entre as leituras. A contagem de passos é uma medida comum nas plataformas de saúde, condicionamento físico e bem-estar.
O exemplo abaixo mostra como definir dados de contagem de passos:
val stepsRecord = StepsRecord(
count = 120,
startTime = START_TIME,
endTime = END_TIME,
startZoneOffset = START_ZONE_OFFSET,
endZoneOffset = END_ZONE_OFFSET
)
Registros com unidades de medida
A plataforma Conexão Saúde pode armazenar valores com as unidades de medida deles para maior precisão. Um exemplo é o tipo de dados de Nutrição, que é amplo e abrangente. Ele inclui uma grande variedade de campos nutricionais opcionais, desde o total de carboidratos até quantidades de vitaminas. Cada ponto de dados representa os nutrientes possivelmente consumidos como parte de uma refeição ou de um alimento.
Nesse tipo de dados, todos os nutrientes são representados em unidades de
Mass, enquanto a energy é representada em uma unidade de Energy.
O exemplo abaixo mostra como definir dados nutricionais para um usuário que comeu uma 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
)
Registros com dados de série
A Conexão Saúde pode armazenar uma lista de dados de série. Um exemplo é o tipo de dados Frequência cardíaca, que captura uma série de amostras de batimentos cardíacos detectados entre as leituras.
Nesse tipo de dados, o parâmetro samples é representado por uma lista de
amostras de frequência cardíaca. Cada amostra contém um valor beatsPerMinute
e um time.
O exemplo abaixo mostra como definir dados da série para frequência cardíaca:
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(),
)
}
)
Gravar dados
Um dos fluxos de trabalho comuns na plataforma Conexão Saúde é a gravação de dados. Para adicionar registros,
use insertRecords.
O exemplo abaixo mostra como gravar dados inserindo contagens de passos:
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
}
}
Atualizar dados
Se você precisar mudar um ou mais registros, especialmente quando precisar sincronizar o repositório de dados do seu app com os dados da Conexão Saúde, é possível atualizar seus dados. Há duas maneiras de atualizar os dados atuais, dependendo do identificador usado para encontrar os registros.
Metadados
Primeiro, examine a classe Metadata, porque ela é necessária ao
atualizar dados. Na criação, cada Record da Conexão Saúde tem um
campo metadata. As propriedades abaixo são relevantes para a
sincronização:
| Propriedades | Descrição |
|---|---|
id
|
Cada Record no app Conexão Saúde tem um valor de id
exclusivo.A plataforma Conexão Saúde preenche automaticamente esse registro ao inserir um novo. |
lastModifiedTime
|
Cada Record também grava a última vez em que o
registro foi modificado.A plataforma Conexão Saúde preenche esse registro automaticamente. |
clientRecordId
|
Cada Record pode ter um ID exclusivo associado
a ele para servir como referência no repositório de dados do app.
Seu app fornece esse valor. |
clientRecordVersion
|
Quando um registro tem um clientRecordId, a
clientRecordVersion pode ser usada para permitir que os dados
sejam sincronizados com a versão no repositório de dados
do app.Seu app fornece esse valor. |
Atualizar pelo ID do registro
Para atualizar os dados, primeiro prepare os registros necessários. Faça as mudanças nos
registros, se necessário. Em seguida, chame updateRecords para fazer
as mudanças.
O exemplo abaixo mostra como atualizar os dados. Para essa finalidade, cada registro tem os valores de zona ajustados para 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
}
}
Inserir e atualizar usando o ID do registro do cliente
Se você estiver usando os valores opcionais de ID e de versão de registro do cliente,
recomendamos usar insertRecords em vez de updateRecords.
A função insertRecords pode inserir e atualizar dados.
Se os dados já existirem na Conexão Saúde com base no conjunto de IDs do
registro do cliente, eles serão substituídos. Caso contrário, serão gravados como novos.
Esse cenário é útil sempre que você precisa sincronizar dados do
repositório de dados do seu app com a plataforma Conexão Saúde.
O exemplo abaixo mostra como executar uma inserção em dados extraídos do repositório de dados do 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
}
}
Depois disso, você pode chamar essas funções na linha de execução principal.
upsertSteps(healthConnectClient, pullStepsFromDatastore())
Verificação de valor na versão do registro do cliente
Se o processo de inserção e atualização de dados incluir a versão do registro do cliente, a Conexão
Saúde vai realizar verificações de comparação nos valores de
clientRecordVersion. Se a versão dos dados inseridos for mais recente que a
atual versão dos dados, eles serão atualizados. Caso contrário, o processo
vai ignorar a mudança e o valor permanecerá o mesmo.
Para incluir o controle de versão nos seus dados, é necessário fornecer à
Metadata.clientRecordVersion um valor Long com base na lógica do controle de
versão.
val sr = StepsRecord(
count = count,
startTime = startTime,
startZoneOffset = startZoneOffset,
endTime = endTime,
endZoneOffset = endZoneOffset,
metadata = Metadata(
clientRecordId = cid,
clientRecordVersion = version
)
)
As inserções não incrementam automaticamente a version sempre que há mudanças,
evitando instâncias inesperadas de substituição de dados. É necessário fornecê-las manualmente com
um valor mais alto.
Práticas recomendadas
Depois de criar a lógica, siga as práticas recomendadas ao gravar ou atualizar dados.