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

يتضمّن تجميع البيانات في 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.