Cómo leer datos sin procesar

En el siguiente ejemplo, se muestra cómo leer datos sin procesar como parte de un flujo de trabajo común.

Lee datos

Health Connect permite que las apps lean datos del almacén de datos cuando la app está en primer plano y en segundo plano:

• Lecturas en primer plano: Normalmente, puedes leer datos de Health Connect cuando tu app está en primer plano. En estos casos, puedes considerar usar un servicio en primer plano para ejecutar esta operación en caso de que el usuario o el sistema pongan tu app en segundo plano durante una operación de lectura.

• Lecturas en segundo plano: Si solicitas un permiso adicional al usuario, puedes leer datos después de que el usuario o el sistema coloquen tu app en segundo plano. Consulta el ejemplo de lectura en segundo plano completo.

El tipo de datos de Pasos en Health Connect captura la cantidad de pasos que dio un usuario entre cada medición. El recuento de pasos representa una medición común en todas las plataformas de salud, actividad física y bienestar. Health Connect facilita la lectura y la escritura de los datos del recuento de pasos.

Para leer registros, crea un ReadRecordsRequest e infórmalo cuando llames a readRecords.

En el siguiente ejemplo, se muestra cómo leer los datos del recuento de pasos para un usuario en un período determinado. Para ver un ejemplo extendido con SensorManager, consulta la guía de datos de recuento de pasos.

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

También puedes leer tus datos de forma agregada con 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
    }
}

Ejemplo de lectura en segundo plano

Para leer datos en segundo plano, declara el siguiente permiso en tu archivo de manifiesto:

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

En el siguiente ejemplo, se muestra cómo leer los datos del recuento de pasos en segundo plano para un usuario en un período determinado con 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
  ...
}

El parámetro ReadRecordsRequest tiene un valor predeterminado pageSize de 1,000. Si la cantidad de registros en un solo readResponse supera el pageSize de la solicitud, debes iterar todas las páginas de la respuesta para recuperar todos los registros con pageToken. Sin embargo, ten cuidado para evitar problemas relacionados con la limitación de frecuencia.

Ejemplo de lectura de pageToken

Se recomienda usar pageToken para leer registros y recuperar todos los datos disponibles del período solicitado.

En el siguiente ejemplo, se muestra cómo leer todos los registros hasta que se agoten todos los tokens de página:

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 obtener información sobre las prácticas recomendadas cuando se leen conjuntos de datos grandes, consulta Planifica para evitar la limitación de frecuencia.

Lectura de datos pasados

Si una app escribió registros en Health Connect anteriormente, es posible que la app lea datos históricos. Esto se aplica a situaciones en las que la app necesita volver a sincronizarse con Health Connect cuando el usuario la reinstala.

Se aplican algunas restricciones de lectura:

• Para Android 14 y versiones posteriores

  • No hay límite histórico para que una app lea sus propios datos.
  • Límite de 30 días para que una app lea otros datos

• Para Android 13 y versiones anteriores

  • Límite de 30 días para que la app lea cualquier dato

Las restricciones se pueden quitar solicitando un permiso de lectura.

Para leer los datos históricos, debes indicar el nombre del paquete como un objeto DataOrigin en el parámetro dataOriginFilter de tu ReadRecordsRequest.

En el siguiente ejemplo, se muestra cómo indicar un nombre de paquete cuando se leen los registros de frecuencia 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
}

Leer datos con más de 30 días de antigüedad

De forma predeterminada, todas las aplicaciones pueden leer datos de Health Connect hasta 30 días antes del otorgamiento de cualquier permiso.

Si necesitas extender los permisos de lectura más allá de cualquiera de las restricciones predeterminadas, solicita el PERMISSION_READ_HEALTH_DATA_HISTORY. De lo contrario, sin este permiso, cualquier intento de leer registros con una antigüedad superior a 30 días generará un error.

Historial de permisos de una app borrada

Si un usuario borra tu app, se revocarán todos los permisos, incluido el permiso de historial. Si el usuario vuelve a instalar tu app y le otorga permiso de nuevo, se aplicarán las mismas restricciones predeterminadas, y tu app podrá leer datos de Health Connect hasta 30 días antes de esa fecha nueva.

Por ejemplo, supongamos que el usuario borra tu app el 10 de mayo de 2023 y, luego, la reinstala el 15 de mayo de 2023 y otorga permisos de lectura. Ahora, la fecha más antigua de la que tu app puede leer datos de forma predeterminada es el 15 de abril de 2023.

Cómo controlar excepciones

Health Connect genera excepciones estándar para las operaciones de CRUD cuando se produce un problema. Tu app debe detectar y controlar cada una de estas excepciones según corresponda.

Cada método de HealthConnectClient enumera las excepciones que se pueden generar. En general, tu app debe controlar las siguientes excepciones: