Ham verileri okuma

Aşağıdaki örnekte, yaygın iş akışının bir parçası olarak ham verilerin nasıl okunacağı gösterilmektedir.

Verileri okuma

Health Connect, uygulamaların ön planda ve arka planda çalışırken veri deposundaki verileri okumasına olanak tanır:

• Ön planda okuma: Uygulamanız ön plandayken Health Connect'teki verileri normalde okuyabilirsiniz. Bu gibi durumlarda, kullanıcı veya sistem okuma işlemi sırasında uygulamanızı arka plana yerleştirirse bu işlemi çalıştırmak için ön plan hizmeti kullanmayı düşünebilirsiniz.

• Arka planda okuma: Kullanıcıdan ek izin isteyerek, kullanıcı veya sistem uygulamanızı arka plana yerleştirdikten sonra verileri okuyabilirsiniz. Tam arka planda okuma örneğini inceleyin.

Health Connect'teki Adımlar veri türü, bir kullanıcının okumalar arasında attığı adım sayısını yakalar. Adım sayısı, sağlık, fitness ve sağlıklı yaşam platformlarında ortak bir ölçümü temsil eder. Health Connect, adım sayısı verilerini okumanıza ve yazmanıza olanak tanır.

Kayıtları okumak için bir ReadRecordsRequest oluşturun ve readRecords'ı aradığınızda bunu sağlayın.

Aşağıdaki örnekte, belirli bir süre içinde bir kullanıcının adım sayısı verilerinin nasıl okunacağı gösterilmektedir. SensorManager ile ilgili daha ayrıntılı bir örnek için adım sayısı veri kılavuzuna bakın.

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
    }
}

Ayrıca, aggregate kullanarak verilerinizi toplu şekilde okuyabilirsiniz.

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
    }
}

Mobil adımları okuma

Android 14 (API düzeyi 34) ve SDK Uzantısı sürüm 20 veya sonraki sürümlerde Health Connect, cihaz üzerinde adım sayma özelliği sunar. Herhangi bir uygulamaya READ_STEPS izni verildiyse Health Connect, Android destekli cihazdaki adımları kaydetmeye başlar ve kullanıcılar, Health Connect Adımlar girişlerine otomatik olarak eklenen adım verilerini görür.

Cihazda adım sayma özelliğinin kullanılabilir olup olmadığını kontrol etmek için cihazda Android 14 (API düzeyi 34) sürümünün yüklü olduğunu ve SDK uzantısı sürümünün en az 20 olduğunu doğrulamanız gerekir. Aşağıdaki kodu kullanabilirsiniz:

val isStepTrackingAvailable =
    Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE &&
        SdkExtensions.getExtensionVersion(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) >= 20

Health Connect tarafından kaydedilen mobil adımların DataOrigin değeri, paket adı olarak ayarlanır android. Uygulamanız yalnızca aggregate kullanarak toplanmış adım sayılarını okuyorsa ve DataOrigin ile filtreleme yapmıyorsa cihazdaki adımlar otomatik olarak toplama dahil edilir.

Uygulamanızın cihazdaki adımları okuması gerekiyorsa veya adım verilerini kaynak uygulamaya ya da cihaza göre ayrılmış şekilde gösteriyorsa DataOrigin değerinin android olduğu kayıtlar için sorgu oluşturabilirsiniz. Uygulamanız adım verileri için ilişkilendirme gösteriyorsa android paketindeki verileri mevcut cihaza atfetmeniz gerekir. Bunu yapmak için "Telefonunuz" gibi bir etiket kullanabilir, Settings.Global.getString(resolver, Settings.Global.DEVICE_NAME) ile cihaz adını alabilir veya kaydın meta verilerindeki Device alanını inceleyebilirsiniz.

Aşağıdaki örnekte, android veri kaynağına göre filtreleme yaparak birleştirilmiş mobil adım sayısı verilerinin nasıl okunacağı gösterilmektedir:

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),
                dataOriginFilter = setOf(DataOrigin("android"))
            )
        )
        // 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
    }
}

Cihaz Üzerinde Adım Sayma

Cihaz üzerinde adım sayma özelliği hakkında daha fazla bilgi:

• Sensör Kullanımı: Health Connect, SensorManager uygulamasındaki TYPE_STEP_COUNTER sensörünü kullanır. Bu sensör, düşük güç tüketimi için optimize edilmiştir. Bu nedenle, arka planda sürekli adım takibi için idealdir.
• Veri Ayrıntı Düzeyi: Pil ömrünü korumak için adım verileri genellikle gruplandırılır ve Health Connect veritabanına dakikada en fazla bir kez yazılır.
• İlişkilendirme: Daha önce belirtildiği gibi, bu cihaz üzerinde özellik tarafından kaydedilen tüm adımlar, DataOrigin içindeki android paket adıyla ilişkilendirilir.
• Etkinleştirme: Cihazdaki adım sayma mekanizması yalnızca cihazda en az bir uygulamaya Health Connect'te READ_STEPS izni verildiğinde etkin olur.

Arka planda okuma örneği

Verileri arka planda okumak için manifest dosyanızda aşağıdaki izni bildirin:

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

Aşağıdaki örnekte, WorkManager kullanılarak belirli bir süre içinde bir kullanıcının adım sayısı verilerinin arka planda nasıl okunacağı gösterilmektedir:

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
  ...
}

ReadRecordsRequest parametresinin varsayılan pageSize değeri 1.000'dir. Tek bir readResponse içindeki kayıt sayısı, isteğin pageSize değerini aşıyorsa pageToken kullanarak tüm kayıtları almak için yanıtın tüm sayfalarını yinelemeniz gerekir. Ancak sıklık sınırlamasıyla ilgili sorun yaşamamak için dikkatli olun.

pageToken okuma örneği

İstenen dönemdeki tüm verileri almak için kayıtları okumak üzere pageToken kullanılması önerilir.

Aşağıdaki örnekte, tüm sayfa jetonları tükenene kadar tüm kayıtların nasıl okunacağı gösterilmektedir:

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
}

Büyük veri kümelerini okurken yararlanabileceğiniz en iyi uygulamalar hakkında bilgi edinmek için Hız sınırlamasıyla karşılaşmamayı planlama başlıklı makaleyi inceleyin.

Daha önce yazılan verileri okuma

Daha önce Health Connect'e kayıt yazmış olan uygulamalar, geçmiş verileri okuyabilir. Bu, uygulamanın kullanıcı tarafından yeniden yüklendikten sonra Health Connect ile yeniden senkronize edilmesi gerektiği senaryolar için geçerlidir.

Okumayla ilgili bazı kısıtlamalar vardır:

• Android 14 ve sonraki sürümler için

  • Bir uygulamanın kendi verilerini okumasıyla ilgili geçmiş sınırlama yoktur.
  • Bir uygulamanın diğer verileri okumasıyla ilgili 30 günlük sınır.

• Android 13 ve önceki sürümler için

  • Uygulamaların herhangi bir veriyi okumasıyla ilgili 30 günlük sınır.

Kısıtlamalar, okuma izni isteğinde bulunarak kaldırılabilir.

Geçmiş verileri okumak için paket adını ReadRecordsRequest parametresinin dataOriginFilter parametresinde DataOrigin nesnesi olarak belirtmeniz gerekir.

Aşağıdaki örnekte, kalp atış hızı kayıtları okunurken paket adının nasıl belirtileceği gösterilmektedir:

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
}

30 günden eski verileri okuma

Varsayılan olarak tüm uygulamalar, herhangi bir izin ilk kez verilmeden önceki 30 güne kadar olan Health Connect verilerini okuyabilir.

Okuma izinlerini varsayılan kısıtlamaların ötesine genişletmeniz gerekiyorsa PERMISSION_READ_HEALTH_DATA_HISTORY isteğinde bulunun. Aksi takdirde, bu izin olmadan 30 günden eski kayıtları okuma girişimi hatayla sonuçlanır.

Silinen bir uygulamanın izin geçmişi

Bir kullanıcı uygulamanızı silerse geçmiş izni de dahil olmak üzere tüm izinler iptal edilir. Kullanıcı uygulamanızı yeniden yükleyip tekrar izin verirse aynı varsayılan kısıtlamalar geçerli olur ve uygulamanız, bu yeni tarihten önceki 30 güne kadar olan Health Connect verilerini okuyabilir.

Örneğin, kullanıcının uygulamanızı 10 Mayıs 2023'te sildiğini, 15 Mayıs 2023'te yeniden yüklediğini ve okuma izni verdiğini varsayalım. Uygulamanızın artık varsayılan olarak veri okuyabileceği en erken tarih 15 Nisan 2023'tür.

İstisnaları işleme

Health Connect, bir sorunla karşılaşıldığında CRUD işlemleri için standart istisnalar oluşturur. Uygulamanız bu istisnaların her birini uygun şekilde yakalayıp işlemelidir.

HealthConnectClient üzerindeki her yöntemde oluşturulabilecek istisnalar listelenir. Genel olarak uygulamanız aşağıdaki istisnaları işlemelidir: