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

צבירת נתונים ב-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
    }
}

סינון לפי מקור הנתונים

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

בדוגמה הבאה אפשר לראות איך משתמשים ב-dataOriginFilter וב-AggregateRequest כדי לצבור נתונים של צעדים מאפליקציה ספציפית:

suspend fun aggregateStepsFromSpecificApp(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant,
    appPackageName: String
) {
    try {
        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
                dataOriginFilter = setOf(DataOrigin(appPackageName))
            )
        )
        // The result may be null if no data is available in the time range
        val totalSteps = response[StepsRecord.COUNT_TOTAL] ?: 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] ?: 0L
        val maximumHeartRate = response[HeartRateRecord.BPM_MAX] ?: 0L
    } catch (e: Exception) {
        // Run error handling here
    }
}

קטגוריות

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

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

משך הזמן

במקרה הזה, הנתונים המצטברים מחולקים לקבוצות בתוך פרק זמן קבוע, כמו דקה או שעה. כדי לצבור נתונים לדליים, משתמשים ב-aggregateGroupByDuration. היא מקבלת אובייקט AggregateGroupByDurationRequest שבו מוסיפים את סוגי המדדים, את טווח הזמן ואת Duration כפרמטרים. אפשר להשתמש בזוגות של אובייקטים Instant או LocalDateTime בשביל startTime ו-endTime ב-TimeRangeFilter.

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

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] ?: 0L
        }
    } 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] ?: 0L
        }
    } catch (e: Exception) {
        // Run error handling here
    }
}

הגבלות קריאה

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

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

היסטוריית ההרשאות של אפליקציה שנמחקה

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

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

נתונים מצטברים שמושפעים מסדרי העדיפויות של האפליקציות שנבחרו על ידי המשתמש

משתמשי קצה יכולים להגדיר עדיפות לאפליקציות השינה והפעילות שהם שילבו עם Health Connect. רק משתמשי קצה יכולים לשנות את רשימות העדיפות האלה. כשמבצעים קריאה מצטברת, Aggregate API מתחשב בכל נתון כפול ושומר רק את הנתונים מהאפליקציה עם העדיפות הכי גבוהה. יכול להיות שיהיו נתונים כפולים אם המשתמש מפעיל כמה אפליקציות שכותבות את אותו סוג של נתונים – למשל מספר הצעדים שבוצעו או המרחק שעבר – באותו זמן.

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

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

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

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

קריאה ברקע

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

סוגי נתונים מצטברים נתמכים לפי רשומה

בטבלה הזו מפורטים כל סוגי הנתונים המצטברים שנתמכים על ידי רשומות Health Connect.