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

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