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

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

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

يسمح 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 بعد أن يُعيد المستخدم تثبيته.

لقراءة البيانات في هذا السيناريو، عليك الإشارة إلى اسم الحزمة كعنصر 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 يومًا تلقائيًا باستخدام أي أذونات تم منحها. باستخدام إذن 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 يومًا باستخدام أحد طلبات النطاق الزمني.