อ่านข้อมูลดิบ

ตัวอย่างต่อไปนี้แสดงวิธีอ่านข้อมูลดิบซึ่งเป็นส่วนหนึ่งของเวิร์กโฟลว์ทั่วไป

อ่านข้อมูล

Health Connect อนุญาตให้แอปอ่านข้อมูลจากที่เก็บข้อมูลเมื่อแอป ทำงานในเบื้องหน้าและเบื้องหลัง

  • การอ่านในเบื้องหน้า: โดยปกติแล้ว คุณจะอ่านข้อมูลจาก Health Connect ได้เมื่อ แอปของคุณอยู่ในเบื้องหน้า ในกรณีเหล่านี้ คุณอาจพิจารณาใช้ บริการเบื้องหน้าเพื่อเรียกใช้การดำเนินการนี้ในกรณีที่ผู้ใช้หรือระบบวางแอป ของคุณไว้ในเบื้องหลังระหว่างการดำเนินการอ่าน

  • การอ่านในเบื้องหลัง: การขอสิทธิ์เพิ่มเติมจากผู้ใช้จะช่วยให้คุณอ่านข้อมูลได้หลังจากที่ผู้ใช้หรือระบบวางแอปของคุณไว้ในเบื้องหลัง ดูตัวอย่างการอ่านพื้นหลังฉบับสมบูรณ์

ประเภทข้อมูลจำนวนก้าวใน Health Connect จะบันทึกจำนวนก้าวที่ผู้ใช้เดิน ระหว่างการอ่าน จำนวนก้าวเป็นหน่วยวัดทั่วไปในแพลตฟอร์มด้านสุขภาพ การออกกำลังกาย และสุขภาวะ Health Connect ช่วยให้การอ่าน และการเขียนข้อมูลจำนวนก้าวเป็นเรื่องง่าย

หากต้องการอ่านระเบียน ให้สร้าง ReadRecordsRequest และระบุ เมื่อเรียกใช้ readRecords

ตัวอย่างต่อไปนี้แสดงวิธีอ่านข้อมูลจำนวนก้าวของผู้ใช้ภายใน ช่วงเวลาหนึ่ง ดูตัวอย่างเพิ่มเติมที่มี SensorManager ได้ในคำแนะนำเกี่ยวกับข้อมูลจำนวนก้าว

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

นอกจากนี้ คุณยังอ่านข้อมูลในลักษณะที่รวบรวมได้โดยใช้ 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
    }
}

ตัวอย่างการอ่านในเบื้องหลัง

หากต้องการอ่านข้อมูลในเบื้องหลัง ให้ประกาศสิทธิ์ต่อไปนี้ในไฟล์ Manifest

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

ตัวอย่างต่อไปนี้แสดงวิธีอ่านข้อมูลจำนวนก้าวในเบื้องหลังสำหรับ ผู้ใช้ภายในช่วงเวลาหนึ่งโดยใช้ 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
  ...
}

พารามิเตอร์ ReadRecordsRequest มีค่าเริ่มต้น pageSize เป็น 1000 หากจำนวนระเบียนใน readResponse เดียวเกินpageSizeของคำขอ คุณต้องทำซ้ำ ในทุกหน้าของคำตอบเพื่อดึงข้อมูลระเบียนทั้งหมดโดยใช้ pageToken อย่างไรก็ตาม โปรดระมัดระวังเพื่อหลีกเลี่ยงปัญหาการจำกัดอัตรา

ตัวอย่างการอ่าน pageToken

ขอแนะนำให้ใช้ pageToken เพื่ออ่านบันทึกเพื่อดึงข้อมูลทั้งหมด ที่มีจากระยะเวลาที่ขอ

ตัวอย่างต่อไปนี้แสดงวิธีอ่านระเบียนทั้งหมดจนกว่าจะใช้โทเค็นหน้าเว็บทั้งหมด จนหมด

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
}

ดูข้อมูลเกี่ยวกับแนวทางปฏิบัติแนะนำเมื่ออ่านชุดข้อมูลขนาดใหญ่ได้ที่ วางแผนเพื่อหลีกเลี่ยงการจำกัดอัตรา

อ่านข้อมูลที่เขียนไว้ก่อนหน้านี้

หากแอปเคยเขียนบันทึกลงใน Health Connect มาก่อน แอปนั้นจะอ่านข้อมูลย้อนหลังได้ ซึ่งใช้ได้กับสถานการณ์ที่แอปต้องซิงค์กับ Health Connect อีกครั้งหลังจากที่ผู้ใช้ติดตั้งแอปใหม่

โดยมีข้อจำกัดในการอ่านบางประการดังนี้

  • สำหรับ Android 14 ขึ้นไป

    • ไม่มีขีดจํากัดย้อนหลังสําหรับแอปที่อ่านข้อมูลของตัวเอง
    • จำกัด 30 วันสำหรับแอปที่อ่านข้อมูลอื่นๆ

  • สำหรับ Android 13 และต่ำกว่า

    • จำกัด 30 วันในการอ่านข้อมูลของแอป

คุณนำข้อจำกัดออกได้โดยขอสิทธิ์อ่าน

หากต้องการอ่านข้อมูลย้อนหลัง คุณต้องระบุชื่อแพ็กเกจเป็นออบเจ็กต์ DataOrigin ในพารามิเตอร์ dataOriginFilter ของ ReadRecordsRequest

ตัวอย่างต่อไปนี้แสดงวิธีระบุชื่อแพ็กเกจเมื่ออ่านบันทึกอัตราการเต้นของหัวใจ

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 วัน

โดยค่าเริ่มต้น แอปพลิเคชันทั้งหมดจะอ่านข้อมูลจาก Health Connect ได้นานสูงสุด 30 วัน ก่อนที่จะมีการให้สิทธิ์ครั้งแรก

หากต้องการขยายสิทธิ์การอ่านนอกเหนือจากข้อจำกัดเริ่มต้น ให้ขอPERMISSION_READ_HEALTH_DATA_HISTORY ไม่เช่นนั้น หากไม่มีสิทธิ์นี้ การพยายามอ่านบันทึกที่เก่ากว่า 30 วันจะทำให้เกิดข้อผิดพลาด

ประวัติสิทธิ์ของแอปที่ถูกลบ

หากผู้ใช้ลบแอปของคุณ ระบบจะเพิกถอนสิทธิ์ทั้งหมด รวมถึงสิทธิ์เข้าถึงประวัติ หากผู้ใช้ติดตั้งแอปของคุณอีกครั้งและให้สิทธิ์อีกครั้ง ข้อจำกัดเริ่มต้นเดียวกันจะมีผล และแอปของคุณจะอ่านข้อมูลจาก Health Connect ได้นานสูงสุด 30 วันก่อนวันที่ใหม่นั้น

เช่น สมมติว่า ผู้ใช้ลบแอปของคุณในวันที่ 10 พฤษภาคม 2023 แล้วติดตั้งแอปอีกครั้ง ในวันที่ 15 พฤษภาคม 2023 และให้สิทธิ์อ่าน วันที่ที่เร็วที่สุด ที่แอปของคุณอ่านข้อมูลได้โดยค่าเริ่มต้น คือ15 เมษายน 2023

จัดการข้อยกเว้น

Health Connect จะส่งข้อยกเว้นมาตรฐานสำหรับการดำเนินการ CRUD เมื่อพบปัญหา แอปของคุณควรตรวจจับและจัดการข้อยกเว้นแต่ละรายการเหล่านี้ตามความเหมาะสม

แต่ละเมธอดใน HealthConnectClient จะแสดงข้อยกเว้นที่อาจเกิดขึ้น โดยทั่วไปแล้ว แอปควรจัดการข้อยกเว้นต่อไปนี้

ตารางที่ 1: ข้อยกเว้นของ Health Connect และแนวทางปฏิบัติแนะนำ
ข้อยกเว้น คำอธิบาย แนวทางปฏิบัติแนะนำ
IllegalStateException เกิดสถานการณ์ใดสถานการณ์หนึ่งต่อไปนี้

  • บริการ Health Connect ไม่พร้อมใช้งาน
  • คำขอไม่ใช่โครงสร้างที่ถูกต้อง เช่น คำขอแบบรวมใน ที่เก็บข้อมูลเป็นระยะๆ ซึ่งใช้Instantออบเจ็กต์สำหรับtimeRangeFilter

จัดการปัญหาที่อาจเกิดขึ้นกับอินพุตก่อนที่จะส่งคำขอ ควรกำหนดค่าให้กับตัวแปรหรือใช้เป็นพารามิเตอร์ภายในฟังก์ชันที่กำหนดเองแทนการใช้ในคำขอโดยตรง เพื่อให้คุณใช้กลยุทธ์การจัดการข้อผิดพลาดได้
IOException มีปัญหาเกิดขึ้นเมื่ออ่านและเขียนข้อมูลจาก ดิสก์ คำแนะนำต่อไปนี้จะช่วยให้คุณหลีกเลี่ยงปัญหานี้ได้

  • สำรองข้อมูลที่ผู้ใช้ป้อน
  • สามารถจัดการปัญหาที่เกิดขึ้นระหว่างการดำเนินการเขียนแบบกลุ่ม เช่น ตรวจสอบว่ากระบวนการดำเนินการต่อจากปัญหาและดำเนินการที่เหลือ
  • ใช้กลยุทธ์การลองใหม่และการหยุดชั่วคราวเพื่อจัดการปัญหาคำขอ

RemoteException เกิดข้อผิดพลาดภายในหรือในการสื่อสาร กับบริการพื้นฐานที่ SDK เชื่อมต่อ

เช่น แอปของคุณพยายามลบระเบียนที่มี uid ที่ระบุ อย่างไรก็ตาม ระบบจะส่งข้อยกเว้น หลังจากที่แอปพบว่าไม่มีบันทึก เมื่อตรวจสอบบริการพื้นฐาน 		คำแนะนำต่อไปนี้จะช่วยให้คุณหลีกเลี่ยงปัญหานี้ได้

  • ซิงค์ที่เก็บข้อมูลของแอปกับ Health Connect เป็นประจำ
  • ใช้กลยุทธ์การลองใหม่และการหยุดชั่วคราวเพื่อจัดการปัญหาคำขอ

SecurityException มีปัญหาเกิดขึ้นเมื่อคำขอต้องใช้สิทธิ์ที่ไม่ได้ให้ไว้ หากต้องการหลีกเลี่ยงปัญหานี้ โปรดตรวจสอบว่าคุณได้ประกาศการใช้ประเภทข้อมูล Health Connect สำหรับแอปที่เผยแพร่แล้ว นอกจากนี้ คุณต้องประกาศสิทธิ์ของ Health Connect ในไฟล์ Manifest และในกิจกรรมของคุณ