קריאת נתונים גולמיים

בדוגמה הבאה מוצג אופן הקריאה של נתונים גולמיים כחלק מתהליך העבודה המשותף.

קריאת נתונים

‫Health Connect מאפשר לאפליקציות לקרוא נתונים ממאגר הנתונים כשהאפליקציה פועלת בחזית וברקע:

  • קריאות ברקע: בדרך כלל אפשר לקרוא נתונים מ-Health Connect כשהאפליקציה פועלת ברקע. במקרים כאלה, כדאי להשתמש בשירות פעיל כדי להריץ את הפעולה, למקרה שהמשתמש או המערכת ימקמו את האפליקציה ברקע במהלך פעולת קריאה.

  • קריאות ברקע: אם תבקשו מהמשתמש הרשאה נוספת, תוכלו לקרוא נתונים אחרי שהמשתמש או המערכת יעבירו את האפליקציה שלכם לרקע. דוגמה מלאה לקריאה ברקע

סוג הנתונים 'צעדים' ב-Health Connect מתעד את מספר הצעדים שהמשתמש עשה בין הקריאות. מספר הצעדים הוא מדד נפוץ בפלטפורמות של בריאות, כושר ורווחה. אפליקציית Health Connect מאפשרת לקרוא ולכתוב נתונים של מונה הצעדים בקלות.

כדי לקרוא רשומות, צריך ליצור ReadRecordsRequest ולספק אותו כשמתקשרים אל readRecords.

בדוגמה הבאה מוצג איך לקרוא נתונים של מספר הצעדים של משתמש בפרק זמן מסוים. דוגמה מורחבת עם SensorManager מופיעה במדריך בנושא נתונים של ספירת הצעדים.

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

אפשר גם לקרוא את הנתונים בצורה מצטברת באמצעות 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
    }
}

דוגמה לקריאה ברקע

כדי לקרוא נתונים ברקע, צריך להצהיר על ההרשאה הבאה בקובץ המניפסט:

<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 (1,000). אם מספר הרשומות בקובץ 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.