قراءة البيانات الأولية

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

يوضّح لك المثال التالي كيفية قراءة البيانات الأوّلية كجزء من الخطوات المشترَكة في سير العمل.

قراءة البيانات

يسمح Health Connect للتطبيقات بقراءة البيانات من قاعدة البيانات عندما يكون التطبيق في المقدّمة والخلفية:

• عمليات القراءة في المقدّمة: يمكنك عادةً قراءة البيانات من Health Connect عندما يكون تطبيقك في المقدّمة. في هذه الحالات، يمكنك استخدام خدمة تعمل في المقدّمة لتنفيذ هذه العملية في حال وضع المستخدم أو النظام تطبيقك في الخلفية أثناء عملية القراءة.

• عمليات القراءة في الخلفية: من خلال طلب إذن إضافي من المستخدم، يمكنك قراءة البيانات بعد أن يضع المستخدم أو النظام تطبيقك في الخلفية. اطّلِع على مثال القراءة في الخلفية الكامل.

يُسجِّل نوع بيانات "الخطوات" في Health Connect عدد الخطوات التي قطعها المستخدِم بين القراءات. يُعدّ عدد الخطوات قياسًا شائعًا على منصّات الصحة واللياقة البدنية والعافية. يسهِّل تطبيق Health Connect قراءة بيانات عدد الخطوات وتعديلها.

لقراءة السجلات، أنشئ ReadRecordsRequest وقدِّمه عند الاتصال بـ readRecords.

يوضّح المثال التالي كيفية قراءة بيانات عدد الخطوات لمستخدم خلال وقت معيّن. للحصول على مثال مفصّل يتضمّن SensorManager، يُرجى الاطّلاع على دليل بيانات عدد الخطوات.

suspend fun readStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.readRecords(
            ReadRecordsRequest(
                StepsRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        for (stepRecord in response.records) {
            // Process each step record
        }
    } catch (e: Exception) {
        // Run error handling here
    }
}

مثال على القراءة في الخلفية

لقراءة البيانات في الخلفية، يجب إدراج الإذن التالي فيملف البيان:

<application>
  <uses-permission android:name="android.permission.health.READ_HEALTH_DATA_IN_BACKGROUND" />
...
</application>

يوضّح المثال التالي كيفية قراءة بيانات عدد الخطوات في الخلفية لمستخدم معيّن في غضون فترة زمنية معيّنة باستخدام WorkManager:

class ScheduleWorker(private val appContext: Context, workerParams: WorkerParameters):
    CoroutineWorker(appContext, workerParams) {

    override suspend fun doWork(): Result {
        // Read data and process it.
        ...

        // Return success indicating successful data retrieval
        return Result.success()
    }
}

if (healthConnectClient
    .features
    .getFeatureStatus(
    HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
    ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

    // Check if necessary permission is granted
    val grantedPermissions = healthConnectClient.permissionController.getGrantedPermissions()

    if (PERMISSION_READ_HEALTH_DATA_IN_BACKGROUND !in grantedPermissions) {
        // Perform read in foreground
        ...
    } else {
        // Schedule the periodic work request in background
        val periodicWorkRequest = PeriodicWorkRequestBuilder<ScheduleWorker>(1, TimeUnit.HOURS)
            .build()

        WorkManager.getInstance(context).enqueueUniquePeriodicWork(
            "read_health_connect",
            ExistingPeriodicWorkPolicy.KEEP,
            periodicWorkRequest
        )
    }
} else {
  // Background reading is not available, perform read in foreground
  ...
}

تحتوي المَعلمة ReadRecordsRequest على قيمة pageSize تلقائية تبلغ 1000. إذا كان عدد السجلات في readResponse واحد يتجاوز pageSize الطلب، عليك تكرار الانتقال إلى جميع صفحات الاستجابة لاسترداد جميع السجلات باستخدام pageToken. ومع ذلك، يجب توخّي الحذر لتجنّب أي مشاكل متعلّقة بتقييد معدّل الإرسال.

مثال على قراءة pageToken

ننصحك باستخدام pageToken لقراءة السجلّات لاسترداد كل البيانات المتاحة من الفترة الزمنية المطلوبة.

يوضّح المثال التالي كيفية قراءة جميع السجلّات إلى أن يتم استخدام كل الرموز المميّزة للصفحات:

val type = HeartRateRecord::class
val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofDays(7))

try {
    var pageToken: String? = null
    do {
        val readResponse =
            healthConnectClient.readRecords(
                ReadRecordsRequest(
                    recordType = type,
                    timeRangeFilter = TimeRangeFilter.between(
                        startTime,
                        endTime
                    ),
                    pageToken = pageToken
                )
            )
        val records = readResponse.records
        // Do something with records
        pageToken = readResponse.pageToken
    } while (pageToken != null)
} catch (quotaError: IllegalStateException) {
    // Backoff
}

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

قراءة البيانات التي تم كتابتها سابقًا

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

تنطبق بعض القيود على القراءة:

• لأجهزة Android التي تعمل بالإصدار 14 والإصدارات الأحدث

  • ما مِن حدّ أقصى سابق على التطبيق لقراءة بياناته الخاصة.
  • حدّ أقصى لمدة 30 يومًا على تطبيق يقرأ بيانات أخرى

• على نظام التشغيل Android 13 والإصدارات الأقدم

  • حدّ أقصى لمدة 30 يومًا على قراءة التطبيق لأي بيانات

يمكن إزالة القيود من خلال طلب إذن القراءة.

لقراءة البيانات السابقة، عليك الإشارة إلى اسم الحزمة كعنصر DataOrigin في مَعلمة dataOriginFilter في ReadRecordsRequest.

يوضّح المثال التالي كيفية الإشارة إلى اسم حزمة عند قراءة سجلّات Steps:

try {
    val response =  healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = StepsRecord::class,
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
            dataOriginFilter = setOf(DataOrigin("com.my.package.name"))
        )
    )
    for (record in response.records) {
        // Process each record
    }
} catch (e: Exception) {
    // Run error handling here
}

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

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

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

سجلّ الأذونات لتطبيق تم حذفه

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

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