داده های جمع شده را بخوانید

تجمیع داده‌ها در 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 همچنین می‌تواند به شما امکان دهد داده‌ها را در قالب سطل‌هایی (buckets) جمع‌آوری کنید. دو نوع سطلی که می‌توانید استفاده کنید شامل مدت زمان (duration ) و دوره (period) است.

پس از فراخوانی، آنها لیستی از سطل‌ها را برمی‌گردانند. توجه داشته باشید که این لیست می‌تواند پراکنده باشد، بنابراین اگر سطلی حاوی هیچ داده‌ای نباشد، در لیست گنجانده نمی‌شود.

مدت زمان

در این حالت، داده‌های تجمیع‌شده در یک بازه زمانی ثابت، مانند یک دقیقه یا یک ساعت، به بخش‌هایی تقسیم می‌شوند. برای تجمیع داده‌ها در بخش‌های مختلف، 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 ادغام کرده‌اند، اولویت تعیین کنند. فقط کاربران نهایی می‌توانند این لیست‌های اولویت را تغییر دهند. هنگامی که شما یک خواندن کلی انجام می‌دهید، API کلی هرگونه داده تکراری را در نظر می‌گیرد و فقط داده‌های برنامه‌ای را که بالاترین اولویت را دارد، نگه می‌دارد. اگر کاربر چندین برنامه داشته باشد که همزمان داده‌های یکسانی - مانند تعداد گام‌های برداشته شده یا مسافت طی شده - را می‌نویسند، داده‌های تکراری می‌توانند وجود داشته باشند.

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

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

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

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

پیشینه خوانده شده

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

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

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