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

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

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

يسمح 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
  ...
}

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

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