Ler dados brutos

O exemplo abaixo mostra como ler dados brutos do fluxo de trabalho comum.

Dica: para mais orientações sobre a leitura de dados brutos, assista ao vídeo para desenvolvedores Android sobre leitura e gravação de dados (em inglês) na plataforma Conexão Saúde.

Ler dados

A Conexão Saúde permite que os apps leiam dados do repositório quando estão em primeiro plano e em segundo plano:

• Leituras em primeiro plano: normalmente, você pode ler dados da Conexão Saúde quando o app está em primeiro plano. Nesses casos, considere usar um serviço em primeiro plano para executar essa operação caso o usuário ou o sistema coloque seu app em segundo plano durante uma operação de leitura.

• Leituras em segundo plano: ao solicitar uma permissão extra do usuário, você pode ler dados depois que o usuário ou o sistema coloca o app em segundo plano. Confira o exemplo completo de leitura em segundo plano.

O tipo de dados "passos" no Conexão Saúde captura o número de passos que um usuário deu entre as leituras. A contagem de passos representa uma medida comum nas plataformas de saúde, condicionamento físico e bem-estar. A Conexão Saúde simplifica a leitura e a gravação de dados de contagem de passos.

Para ler registros, crie uma ReadRecordsRequest e forneça quando você chamar readRecords.

Observação: para tipos cumulativos, como StepsRecord, use aggregate() em vez de readRecords() para evitar contagem dupla de várias fontes e melhorar a precisão. Consulte Ler dados agregados para mais informações.

O exemplo abaixo mostra como ler dados de contagem de passos de um usuário em um determinado período. Para um exemplo mais detalhado com SensorManager, consulte o guia de dados de contagem de passos.

suspend fun readHeartRateByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.readRecords(
            ReadRecordsRequest(
                HeartRateRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        for (record in response.records) {
            // Process each record
        }
    } catch (e: Exception) {
        // Run error handling here
    }
}

Também é possível ler seus dados de maneira agregada usando aggregate.

suspend fun readStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        // The result may be null if no data is available in the time range
        val stepCount = response[StepsRecord.COUNT_TOTAL]
    } catch (e: Exception) {
        // Run error handling here
    }
}

Observação: se você quiser obter dados calculados, como médias e totais, recomendamos usar a agregação. É possível definir frações menores de tempo sempre que houver agregação. A API de agregação também contém lógica para processar registros duplicados e reduz as chances de limitação de taxa.

Exemplo de leitura em segundo plano

Para ler dados em segundo plano, declare a seguinte permissão no arquivo de manifesto:

<application>
  <uses-permission android:name="android.permission.health.READ_HEALTH_DATA_IN_BACKGROUND" />
...
</application>

O exemplo abaixo mostra como ler dados de contagem de passos em segundo plano para um usuário em um determinado período usando WorkManager:

class ScheduleWorker(private val appContext: Context, workerParams: WorkerParameters):
    CoroutineWorker(appContext, workerParams) {

    override suspend fun doWork(): Result {
        // Read data and process it.
        ...

        // Return success indicating successful data retrieval
        return Result.success()
    }
}

if (healthConnectClient
    .features
    .getFeatureStatus(
    HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
    ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

    // Check if necessary permission is granted
    val grantedPermissions = healthConnectClient.permissionController.getGrantedPermissions()

    if (PERMISSION_READ_HEALTH_DATA_IN_BACKGROUND !in grantedPermissions) {
        // Perform read in foreground
        ...
    } else {
        // Schedule the periodic work request in background
        val periodicWorkRequest = PeriodicWorkRequestBuilder<ScheduleWorker>(1, TimeUnit.HOURS)
            .build()

        WorkManager.getInstance(context).enqueueUniquePeriodicWork(
            "read_health_connect",
            ExistingPeriodicWorkPolicy.KEEP,
            periodicWorkRequest
        )
    }
} else {
  // Background reading is not available, perform read in foreground
  ...
}

Observação: se o usuário não conceder todas as permissões necessárias para leituras em segundo plano, o app ainda será executado e vai realizar o máximo de tarefas possível com as permissões concedidas pelo usuário.

O parâmetro ReadRecordsRequest tem um valor padrão pageSize de 1.000. Se o número de registros em um único readResponse exceder o pageSize da solicitação, será necessário iterar todas as páginas da resposta para recuperar todos os registros usando pageToken. No entanto, tome cuidado para evitar problemas de limitação de taxa.

Exemplo de leitura de pageToken

Recomendamos usar pageToken para ler registros e recuperar todos os dados disponíveis do período solicitado.

O exemplo a seguir mostra como ler todos os registros até que todos os tokens de página tenham sido usados:

val type = HeartRateRecord::class
val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofDays(7))

try {
    var pageToken: String? = null
    do {
        val readResponse =
            healthConnectClient.readRecords(
                ReadRecordsRequest(
                    recordType = type,
                    timeRangeFilter = TimeRangeFilter.between(
                        startTime,
                        endTime
                    ),
                    pageToken = pageToken
                )
            )
        val records = readResponse.records
        // Do something with records
        pageToken = readResponse.pageToken
    } while (pageToken != null)
} catch (quotaError: IllegalStateException) {
    // Backoff
}

Para informações sobre práticas recomendadas ao ler grandes conjuntos de dados, consulte Planejar para evitar a limitação de taxa.

Ler dados gravados anteriormente

Se um app tiver gravado registros na Conexão Saúde antes, ele poderá ler dados históricos. Isso se aplica a cenários em que o app precisa ser sincronizado novamente com a Conexão Saúde depois que o usuário o reinstala.

Algumas restrições de leitura se aplicam:

• Para Android 14 e versões mais recentes

  • Não há limite histórico para um app ler os próprios dados.
  • Limite de 30 dias para um app ler outros dados.

• Para Android 13 e versões anteriores

  • Limite de 30 dias para leitura de dados por apps.

Para remover as restrições, peça uma permissão de leitura.

Para ler dados históricos, é necessário indicar o nome do pacote como um objeto DataOrigin no parâmetro dataOriginFilter da ReadRecordsRequest.

O exemplo abaixo mostra como indicar o nome de um pacote ao ler os registros de frequência cardíaca:

try {
    val response =  healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = HeartRateRecord::class,
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
            dataOriginFilter = setOf(DataOrigin("com.my.package.name"))
        )
    )
    for (record in response.records) {
        // Process each record
    }
} catch (e: Exception) {
    // Run error handling here
}

Ler dados com mais de 30 dias

Por padrão, todos os aplicativos podem ler dados da Conexão Saúde registrados até 30 dias antes da permissão ser concedida.

Se você precisar estender as permissões de leitura além de qualquer uma das restrições padrão, solicite o PERMISSION_READ_HEALTH_DATA_HISTORY. Caso contrário, sem essa permissão, uma tentativa de ler registros com mais de 30 dias resulta em um erro.

Histórico de permissões de um app excluído

Se um usuário excluir seu app, todas as permissões, incluindo a de histórico, serão revogadas. Se o usuário reinstalar o app e conceder a permissão novamente, as mesmas restrições padrão serão aplicadas, e o app poderá ler dados da Conexão Saúde registrados até 30 dias antes dessa nova data.

Por exemplo, suponha que o usuário exclua seu app em 10 de maio de 2023 e o reinstale em 15 de maio de 2023, concedendo permissões de leitura. A data mais antiga de que o app poderá ler dados por padrão é 15 de abril de 2023.