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

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

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