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

בדוגמה הבאה מוסבר איך לקרוא נתונים גולמיים כחלק מתהליך העבודה הנפוץ.

קריאת נתונים

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 (stepRecord in response.records) {
            // Process each step record
        }
    } 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
  ...
}

ערך ברירת המחדל של pageSize של הפרמטר ReadRecordsRequest הוא 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.

הדוגמה הבאה מראה איך לציין את שם החבילה בזמן קריאת רשומות של Steps:

try {
    val response =  healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = StepsRecord::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.