قراءة البيانات المجمّعة

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

تتضمّن عملية تجميع البيانات في 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 أيضًا تجميع البيانات في مجموعات. يتضمّن نوعا الحزم التي يمكنك استخدامهما المدة والفترة.

بعد استدعائها، تُرجع قائمة بالحِزم. يُرجى العِلم أنّ القائمة قد تكون متفرقّة، لذلك لا يتم تضمين حزمة في القائمة إذا لم تحتوي على أي بيانات.

المدة

في هذه الحالة، يتم تقسيم البيانات المجمّعة إلى مجموعات ضمن مدة زمنية ثابتة، مثل دقيقة أو ساعة. لتجميع البيانات في حِزم، استخدِم 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
    }
}

قيود القراءة

يمكن لجميع التطبيقات تلقائيًا قراءة البيانات من 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.