خواندن داده‌های تجمیعی

تجمیع داده‌ها در Health Connect شامل تجمیع‌های پایه یا تجمیع داده‌ها در دسته‌ها می‌شود. جریان‌های کار زیر نحوه انجام هر دو را به شما نشان می‌دهد.

انبوهش پایه

برای استفاده از تجمیع پایه روی داده‌هایتان، از تابع aggregate روی شیء HealthConnectClient استفاده کنید. این تابع شیء AggregateRequest را می‌پذیرد که در آن انواع معیار و محدوده زمانی را به‌عنوان پارامترهای آن اضافه می‌کنید. نحوه نام‌گذاری تجمیع‌های پایه به نوع سنجه‌های استفاده‌شده بستگی دارد.

تجمیع تجمعی

تجمع تجمعی مقدار کل را محاسبه می‌کند.

مثال زیر نحوه انبوهش داده‌ها برای یک نوع داده را نشان می‌دهد:

suspend fun readDistanceAggregate(startTime: Instant, endTime: Instant): Number {
    val response = healthConnectClient.aggregate(
        AggregateRequest(
            metrics = setOf(DistanceRecord.DISTANCE_TOTAL),
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )
    return response[DistanceRecord.DISTANCE_TOTAL]?.inMeters ?: 0L
}
HealthConnectManager.kt

فیلتر کردن براساس منشأ داده

همچنین می‌توانید داده‌های انبوهشی را براساس منشأ آن فیلتر کنید. برای مثال، فقط شامل داده‌های نوشته‌شده توسط یک برنامه خاص.

مثال زیر نشان می‌دهد که چگونه از 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
    }
}
HealthConnectManager.kt

انبوهش آماری

تراکم آماری مقادیر کمینه، بیشینه، یا میانگین گزارش‌ها را با نمونه‌ها محاسبه می‌کند.

مثال زیر نحوه استفاده از انبوهش آماری را نشان می‌دهد:

suspend fun readHeartRateAggregate(startTime: Instant, endTime: Instant): Pair<Long, Long> {
    val response = healthConnectClient.aggregate(
        AggregateRequest(
            metrics = setOf(HeartRateRecord.BPM_MAX, HeartRateRecord.BPM_MIN),
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )
    val minimumHeartRate = response[HeartRateRecord.BPM_MIN] ?: 0L
    val maximumHeartRate = response[HeartRateRecord.BPM_MAX] ?: 0L

    return maximumHeartRate to minimumHeartRate
}
HealthConnectManager.kt

سطل‌ها

‫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
    }
}
HealthConnectManager.kt

نقطه

در این مورد، داده‌های تجمیعی در بازه‌های زمانی مبتنی بر تاریخ، مانند یک هفته یا یک ماه، به دسته‌های مختلف تقسیم می‌شوند. برای تجمیع داده‌ها در دسته‌ها، از 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
    }
}
HealthConnectManager.kt

محدودیت‌های خواندن

به‌طور پیش‌فرض، همه برنامه‌ها می‌توانند داده‌های Health Connect را تا ۳۰ روز قبل‌از زمانی که اولین اجازه اعطا شده است بخوانند.

اگر نیاز دارید اجازه‌های خواندن را فراتر از هریک از محدودیت‌های پیش‌فرض گسترش دهید، PERMISSION_READ_HEALTH_DATA_HISTORY را درخواست کنید. درغیراین‌صورت، بدون این اجازه، تلاش برای خواندن سوابق قدیمی‌تر از ۳۰ روز منجر به خطا می‌شود.

سابقه اجازه‌های برنامه حذف‌شده

اگر کاربری برنامه شما را حذف کند، همه اجازه‌ها، ازجمله اجازه سابقه، لغو می‌شود. اگر کاربر برنامه‌تان را دوباره نصب کند و اجازه را دوباره اعطا کند، همان محدودیت‌های پیش‌فرض اعمال می‌شود و برنامه شما می‌تواند داده‌های Health Connect را تا ۳۰ روز قبل‌از آن تاریخ جدید بخواند.

برای مثال، فرض کنید کاربر برنامه شما را در ۱۰ مه ۲۰۲۳ حذف کند و سپس برنامه را در ۱۵ مه ۲۰۲۳ بازنصب کند و اجازه‌های خواندن را اعطا کند. از این پس، اولین تاریخی که برنامه‌تان می‌تواند به‌طور پیش‌فرض داده‌ها را از آن بخواند ۱۵ آوریل ۲۰۲۳ است.

داده‌های تجمیعی تحت‌تأثیر اولویت‌های برنامه‌های انتخابی کاربر

کاربران نهایی می‌توانند برای برنامه‌های «خواب» و «فعالیت» که با Health Connect ادغام کرده‌اند اولویت تعیین کنند. فقط کاربران نهایی می‌توانند این فهرست‌های اولویت‌دار را تغییر دهند. وقتی خواندن تجمیعی انجام می‌دهید، «میانای برنامه‌سازی کاربردی تجمیعی» هرگونه داده تکراری را درنظر می‌گیرد و فقط داده‌های برنامه با بالاترین اولویت را نگه می‌دارد. اگر کاربر چند برنامه داشته باشد که نوع یکسانی از داده‌ها را (مثل تعداد قدم‌ها یا مسافت طی‌شده) در یک زمان می‌نویسند، ممکن است داده‌های تکراری وجود داشته باشد.

برای کسب اطلاعات درباره اینکه کاربران نهایی چگونه می‌توانند برنامه‌هایشان را اولویت‌بندی کنند، به مدیریت داده‌های Health Connect مراجعه کنید.

کاربر می‌تواند برنامه‌ها را اضافه یا حذف کند و همچنین اولویت آن‌ها را تغییر دهد. کاربر ممکن است بخواهد برنامه‌ای را که داده‌های تکراری می‌نویسد بردارد تا مجموع داده‌ها در صفحه Health Connect با برنامه دارای بالاترین اولویت یکسان باشد. مجموع داده‌ها به‌صورت هم‌زمان به‌روزرسانی می‌شود.

اگرچه Aggregate API داده‌های برنامه‌های «فعالیت» و «خواب» را با حذف داده‌های تکراری براساس نحوه تنظیم اولویت‌های کاربر محاسبه می‌کند، شما همچنان می‌توانید منطق خودتان را برای محاسبه جداگانه داده‌های هر برنامه که این داده‌ها را می‌نویسد بسازید.

فقط انواع داده «فعالیت» و «خواب» توسط Health Connect تکرارزدایی می‌شوند و مجموع داده‌های نشان‌داده‌شده مقادیر پس‌از انجام تکرارزدایی توسط «میانای برنامه‌سازی کاربردی تجمیع» است. این مجموع‌ها جدیدترین روز کاملی را نشان می‌دهد که داده‌های مربوط به گام‌ها و مسافت در آن وجود دارد. برای انواع دیگر داده‌ها، نتایج تجمیعی همه داده‌های نوع موردنظر را در Health Connect از همه برنامه‌هایی که داده‌ها را نوشته‌اند ترکیب می‌کند.

خواندن در پس‌زمینه

می‌توانید درخواست کنید برنامه‌تان در پس‌زمینه اجرا شود و داده‌ها را از Health Connect بخواند. اگر اجازه خواندن پس‌زمینه‌ای را درخواست کنید، کاربرتان می‌تواند به برنامه شما اجازه دهد داده‌ها را در پس‌زمینه بخواند.

انواع داده‌های تجمیعی پشتیبانی‌شده براساس سوابق

این جدول همه انواع داده‌های تجمیعی پشتیبانی‌شده توسط Health Connect را براساس سابقه فهرست می‌کند.