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

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

อ่านข้อมูล

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

อ่านข้อมูลจำนวนก้าวในอุปกรณ์เคลื่อนที่

ใน Android 14 (API ระดับ 34) และ SDK Extension เวอร์ชัน 20 ขึ้นไป Health Connect จะนับจำนวนก้าวในอุปกรณ์ หากแอปได้รับสิทธิ์ READ_STEPS แล้ว Health Connect จะเริ่มบันทึกจำนวนก้าวจากอุปกรณ์ที่ใช้ Android และผู้ใช้จะเห็นข้อมูลจำนวนก้าวที่เพิ่มลงในรายการจำนวนก้าวของ Health Connect โดยอัตโนมัติ

หากต้องการตรวจสอบว่าการนับก้าวในอุปกรณ์พร้อมใช้งานหรือไม่ คุณต้องยืนยันว่า อุปกรณ์ใช้ Android 14 (API ระดับ 34) และมีส่วนขยาย SDK อย่างน้อย เวอร์ชัน 20 คุณใช้โค้ดต่อไปนี้ได้

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

จำนวนก้าวที่ Health Connect บันทึกไว้ในอุปกรณ์เคลื่อนที่จะมี DataOrigin ตั้งค่าเป็นชื่อแพ็กเกจ android หากแอปของคุณ เพียงแค่อ่านจำนวนก้าวที่รวบรวมไว้โดยใช้ aggregate และ ไม่ได้กรองตาม DataOrigin ระบบจะรวมจำนวนก้าวในอุปกรณ์ไว้ใน จำนวนรวมโดยอัตโนมัติ

หากแอปต้องอ่านจำนวนก้าวในอุปกรณ์ หรือหากแอปแสดงข้อมูลจำนวนก้าว ที่แบ่งตามแอปพลิเคชันหรืออุปกรณ์แหล่งที่มา คุณสามารถค้นหาบันทึก ที่ DataOrigin เป็น android ได้ หากแอปแสดงการระบุแหล่งที่มาสำหรับข้อมูลขั้นตอน คุณควรระบุแหล่งที่มาของข้อมูลจากแพ็กเกจ Android ไปยังอุปกรณ์ปัจจุบัน คุณทำได้โดยใช้ป้ายกำกับ เช่น "โทรศัพท์ของคุณ" ดึงข้อมูลชื่ออุปกรณ์ด้วย Settings.Global.getString(resolver, Settings.Global.DEVICE_NAME) หรือตรวจสอบฟิลด์ Device ในข้อมูลเมตาของระเบียน

ตัวอย่างต่อไปนี้แสดงวิธีอ่านข้อมูลจำนวนก้าวรวมในอุปกรณ์เคลื่อนที่โดย กรองต้นทางของข้อมูล android

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

การนับก้าวในอุปกรณ์

เจาะลึกรายละเอียดเพิ่มเติมเกี่ยวกับฟีเจอร์การนับก้าวบนอุปกรณ์

• การใช้เซ็นเซอร์: Health Connect ใช้เซ็นเซอร์ TYPE_STEP_COUNTER จาก SensorManager เซ็นเซอร์นี้ได้รับการเพิ่มประสิทธิภาพเพื่อการใช้พลังงานต่ำ จึงเหมาะสำหรับการติดตามจำนวนก้าวอย่างต่อเนื่องในเบื้องหลัง
• ระดับความละเอียดของข้อมูล: โดยทั่วไปแล้ว ระบบจะจัดกลุ่มข้อมูลจำนวนก้าวและเขียนลงในฐานข้อมูล Health Connect ไม่บ่อยกว่า 1 ครั้งต่อนาทีเพื่อประหยัดแบตเตอรี่
• การระบุแหล่งที่มา: ดังที่กล่าวไว้ก่อนหน้านี้ ขั้นตอนทั้งหมดที่บันทึกโดยฟีเจอร์ในอุปกรณ์นี้จะได้รับการระบุแหล่งที่มาเป็นชื่อแพ็กเกจ android ใน DataOrigin
• การเปิดใช้งาน: กลไกการนับก้าวในอุปกรณ์จะทำงานเมื่อแอปพลิเคชันอย่างน้อย 1 รายการในอุปกรณ์ได้รับREAD_STEPS สิทธิ์ภายใน Health Connect เท่านั้น

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

หากต้องการอ่านข้อมูลในเบื้องหลัง ให้ประกาศสิทธิ์ต่อไปนี้ในไฟล์ 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 จะแสดงข้อยกเว้นที่อาจเกิดขึ้น โดยทั่วไปแล้ว แอปควรจัดการข้อยกเว้นต่อไปนี้