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

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

تشمل عملية تجميع البيانات في 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
    }
}

قيود القراءة

يمكن لتطبيقك قراءة البيانات لمدة تصل إلى 30 يومًا تلقائيًا باستخدام أي أذونات تم منحها. باستخدام إذن PERMISSION_READ_HEALTH_DATA_HISTORY، يمكن لتطبيقك قراءة البيانات التي مرّ عليها أكثر من 30 يومًا.

الحظر لمدة 30 يومًا

يمكن للتطبيقات قراءة البيانات من Health Connect لمدة تصل إلى 30 يومًا قبل منح أي إذن لأول مرة.

ومع ذلك، إذا حذف أحد المستخدمين تطبيقك، سيتم فقدان سجل الأذونات. إذا أعاد المستخدم تثبيت تطبيقك ومنح الإذن مرة أخرى، يمكن لتطبيقك قراءة البيانات من Health Connect لمدة تصل إلى 30 يومًا قبل هذا التاريخ الجديد.

مثال على فترة 30 يومًا

إذا منح مستخدم إذن القراءة لتطبيقك لأول مرة في 30 آذار (مارس) 2023، سيكون أقدم تاريخ يمكن لتطبيقك قراءة البيانات فيه هو 28 شباط (فبراير) 2023 وما بعد.

بعد ذلك، يحذف المستخدم تطبيقك في 10 أيار (مايو) 2023. قرّر المستخدم إعادة تثبيت التطبيق في 15 أيار (مايو) 2023 ومنحه إذن القراءة. أقرب تاريخ يمكن لتطبيقك الآن قراءة البيانات منه هو 15 نيسان (أبريل) 2023.

قراءة البيانات الأقدم من 30 يومًا

إذا أردت قراءة بيانات أقدم من 30 يومًا، عليك استخدام إذن PERMISSION_READ_HEALTH_DATA_HISTORY. بدون هذا الإذن، يؤدي محاولة قراءة سجلّ واحد أقدم من 30 يومًا إلى حدوث خطأ. لا يمكنك أيضًا قراءة أي بيانات أقدم من 30 يومًا باستخدام أحد طلبات ملف تعريف الارتباط المتعلّقة بالنطاق الزمني.

البيانات المجمّعة المتأثرة بأولويات التطبيقات التي يختارها المستخدم

يمكن للمستخدمين النهائيين ضبط الأولوية لتطبيقَي "النوم" و"النشاط" اللذَين دمجتهما مع Health Connect. يمكن للمستخدمين النهائيين فقط تغيير هذه القوائم ذات الأولوية. عند إجراء عملية قراءة مجمّعة، تأخذ واجهة برمجة التطبيقات Aggregate API في الاعتبار أي بيانات مكرّرة ولا تحتفظ إلا بالبيانات من التطبيق الذي يمتلك أعلى أولوية. يمكن أن تظهر بيانات مكرّرة إذا كان لدى المستخدم تطبيقات متعدّدة تكتب النوع نفسه من البيانات، مثل عدد الخطوات التي تمّ اتخاذها أو المسافة التي تم قطعها، في الوقت نفسه.

للحصول على معلومات عن كيفية منح المستخدمين النهائيين الأولوية لتطبيقاتهم، يُرجى الاطّلاع على مقالة إدارة بيانات Health Connect.

يمكن للمستخدم إضافة التطبيقات أو إزالتها، بالإضافة إلى تغيير أولوياتها. قد يريد المستخدم إزالة تطبيق يكتب بيانات مكرّرة حتى تكون إجماليات البيانات على شاشة Health Connect مطابقة للتطبيق الذي منحوه الأولوية القصوى. يتم تعديل إجماليات البيانات في الوقت الفعلي.

على الرغم من أنّ واجهة Aggregate API تحسب بيانات تطبيقَي "النشاط" و"النوم" من خلال إزالة تكرار البيانات وفقًا لكيفية تحديد المستخدِم للأولويات، لا يزال بإمكانك إنشاء منطقك الخاص لحساب البيانات بشكل منفصل لكل تطبيق يكتب هذه البيانات.

لا تزيل Health Connect تكرارًا إلا في نوعَي البيانات "النشاط" و"النوم"، وتشكل عناوين الجدول التي تظهر في قسم "إجمالي البيانات" القيم التي تمّت إزالتها من تكرارها من خلال واجهة برمجة التطبيقات Aggregate API. تعرِض هذه القيم الإجمالية أحدث يوم كامل تتوفّر فيه بيانات الخطوات والمسافة. بالنسبة إلى الأنواع الأخرى من التطبيقات، يتم عرض إجمالي أعداد جميع هذه التطبيقات مجتمعة في إجمالي البيانات في Health Connect.

مواد القراءة في الخلفية

يمكنك طلب تشغيل تطبيقك في الخلفية وقراءة البيانات من Health Connect. إذا طلبت إذن قراءة البيانات في الخلفية، يمكن للمستخدم منح تطبيقك إذن الوصول إلى البيانات في الخلفية.