קריאה של נתונים נצברים

צבירת נתונים ב-Health Connect כוללת צבירות בסיסיות או צבירת נתונים בקטגוריות. בתהליכי העבודה הבאים מוסבר איך לעשות את שניהם.

צבירת נתונים בסיסית

כדי להשתמש בצבירה בסיסית של הנתונים, משתמשים בפונקציה aggregate באובייקט HealthConnectClient. הפונקציה מקבלת אובייקט AggregateRequest שבו מוסיפים את סוגי המדדים ואת טווח הזמן כפרמטרים. הקריאה לצבירות בסיסיות תלויה בסוגים של המדדים שבהם נעשה שימוש.

צבירת נתונים מצטברת

צבירה מצטברת מחשבת את הערך הכולל.

בדוגמה הבאה מוסבר איך לצבור נתונים לפי סוג נתונים:

suspend fun aggregateDistance(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(DistanceRecord.DISTANCE_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        // The result may be null if no data is available in the time range
        val distanceTotalInMeters = response[DistanceRecord.DISTANCE_TOTAL]?.inMeters ?: 0L
    } catch (e: Exception) {
        // Run error handling here
    }
}

צבירת נתונים סטטיסטית

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

בדוגמה הבאה מוסבר איך משתמשים בצבירה סטטיסטית:

suspend fun aggregateHeartRate(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response =
            healthConnectClient.aggregate(
                AggregateRequest(
                    setOf(HeartRateRecord.BPM_MAX, HeartRateRecord.BPM_MIN),
                    timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
                )
            )
        // The result may be null if no data is available in the time range
        val minimumHeartRate = response[HeartRateRecord.BPM_MIN]
        val maximumHeartRate = response[HeartRateRecord.BPM_MAX]
    } catch (e: Exception) {
        // Run error handling here
    }
}

קטגוריות

אפליקציית Health Connect מאפשרת גם לצבור נתונים בקטגוריות. שני הסוגים של קטגוריות שאפשר להשתמש בהן הם duration ו-period.

לאחר הקריאה, הן מחזירות רשימה של קטגוריות. חשוב לזכור שהרשימה יכולה להיות דלילה, ולכן קטגוריה לא תופיע ברשימה אם היא לא מכילה נתונים.

משך הזמן

במקרה כזה, הנתונים המצטברים מחולקים לקטגוריות (buckets) בתוך פרק זמן קבוע, כמו דקה או שעה. כדי לצבור נתונים בקטגוריות, משתמשים ב-aggregateGroupByDuration. הפונקציה מקבלת אובייקט AggregateGroupByDurationRequest שבו מוסיפים את סוגי המדדים, טווח הזמן ו-Duration כפרמטרים.

בדוגמה הבאה מוצג צבירה של שלבים לקטגוריות של דקות:

suspend fun aggregateStepsIntoMinutes(
    healthConnectClient: HealthConnectClient,
    startTime: LocalDateTime,
    endTime: LocalDateTime
) {
    try {
        val response =
            healthConnectClient.aggregateGroupByDuration(
                AggregateGroupByDurationRequest(
                    metrics = setOf(StepsRecord.COUNT_TOTAL),
                    timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
                    timeRangeSlicer = Duration.ofMinutes(1L)
                )
            )
        for (durationResult in response) {
            // The result may be null if no data is available in the time range
            val totalSteps = durationResult.result[StepsRecord.COUNT_TOTAL]
        }
    } catch (e: Exception) {
        // Run error handling here
    }
}

נקודה

במקרה כזה, הנתונים המצטברים מחולקים לקטגוריות לפי פרק זמן שמבוסס על תאריך, כמו שבוע או חודש. כדי לצבור נתונים בקטגוריות, משתמשים ב-aggregateGroupByPeriod. הפונקציה מקבלת אובייקט AggregateGroupByPeriodRequest שבו מוסיפים את סוגי המדדים, את טווח הזמן ואת Period כפרמטרים.

בדוגמה הבאה מוצג צבירה של שלבים לקטגוריות חודשיות:

suspend fun aggregateStepsIntoMonths(
    healthConnectClient: HealthConnectClient,
    startTime: LocalDateTime,
    endTime: LocalDateTime
) {
    try {
        val response =
            healthConnectClient.aggregateGroupByPeriod(
                AggregateGroupByPeriodRequest(
                    metrics = setOf(StepsRecord.COUNT_TOTAL),
                    timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
                    timeRangeSlicer = Period.ofMonths(1)
                )
            )
        for (monthlyResult in response) {
            // The result may be null if no data is available in the time range
            val totalSteps = monthlyResult.result[StepsRecord.COUNT_TOTAL]
        }
    } catch (e: Exception) {
        // Run error handling here
    }
}

הגבלות קריאה

כברירת מחדל, האפליקציה יכולה לקרוא נתונים עד 30 יום באמצעות כל ההרשאות שהוקצו לה. ההרשאה PERMISSION_READ_HEALTH_DATA_HISTORY מאפשרת לאפליקציה לקרוא נתונים מלפני יותר מ-30 יום.

הגבלה ל-30 יום

אפליקציות יכולות לקרוא נתונים מ-Health Connect עד 30 יום לפני שהתקבלה ההרשאה הראשונה.

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

דוגמה ל-30 יום

אם משתמש העניק לאפליקציה הרשאת קריאה בפעם הראשונה ב-30 במרץ 2023, הנתונים המוקדם ביותר שהאפליקציה תוכל לקרוא חזרה יהיו מ-28 בפברואר 2023 ואילך.

לאחר מכן, המשתמש מחק את האפליקציה ב-10 במאי 2023. המשתמש מחליט להתקין מחדש את האפליקציה ב-15 במאי 2023 ולהעניק הרשאת קריאה. התאריך המוקדם ביותר שהאפליקציה יכולה לקרוא ממנו נתונים הוא 15 באפריל 2023.

קריאת נתונים מלפני יותר מ-30 יום

אם רוצים לקרוא נתונים מלפני יותר מ-30 יום, צריך להשתמש בהרשאה PERMISSION_READ_HEALTH_DATA_HISTORY. ללא ההרשאה הזו, ניסיון לקרוא רשומה אחת שחלפו עליה יותר מ-30 ימים יוביל לשגיאה. בנוסף, אי אפשר לקרוא נתונים מלפני יותר מ-30 יום באמצעות אחת מהבקשות של טווח הזמן.