مزامنة البيانات

يتوافق هذا الدليل مع الإصدار 1.1.0-alpha12 من Health Connect.

تتضمّن معظم التطبيقات التي تتكامل مع Health Connect مخزن بيانات خاصًا بها يعمل كمصدر موثوق. يوفّر Health Connect طرقًا لمزامنة تطبيقك.

استنادًا إلى بنية تطبيقك، قد تتضمّن عملية المزامنة بعض الإجراءات التالية أو جميعها:

• إدخال بيانات جديدة أو معدَّلة من مستودع بيانات تطبيقك إلى Health Connect
• استرداد تغييرات البيانات من Health Connect إلى مستودع بيانات تطبيقك
• حذف البيانات من Health Connect عند حذفها من مستودع بيانات تطبيقك

في كلتا الحالتين، تأكَّد من أنّ عملية المزامنة تحافظ على توافق Health Connect مع مستودع بيانات تطبيقك.

إرسال البيانات إلى Health Connect

الجزء الأول من عملية المزامنة هو نقل البيانات من مستودع بيانات تطبيقك إلى مستودع بيانات Health Connect.

إعداد بياناتك

عادةً ما تتضمّن السجلات في مستودع بيانات تطبيقك التفاصيل التالية:

• مفتاح فريد، مثل UUID
• إصدار أو طابع زمني

عند مزامنة البيانات مع Health Connect، يجب تحديد البيانات التي تم إدراجها أو تعديلها أو حذفها منذ آخر عملية مزامنة وتوفيرها فقط.

كتابة البيانات في Health Connect

لإدخال البيانات في Health Connect، اتّبِع الخطوات التالية:

1. الحصول على قائمة بالإدخالات الجديدة أو المعدَّلة أو المحذوفة من مستودع بيانات تطبيقك
2. لكل إدخال، أنشئ عنصر Record مناسبًا لنوع البيانات هذا. على سبيل المثال، أنشئ عنصر WeightRecord للبيانات المتعلقة بالوزن.

3. حدِّد عنصر Metadata مع كل Record. ويشمل ذلك clientRecordId، وهو معرّف من مستودع بيانات تطبيقك يمكنك استخدامه لتحديد السجلّ بشكل فريد. يمكنك استخدام مفتاحك الفريد الحالي لهذا الغرض. إذا كانت بياناتك تتضمّن إصدارات، يجب أيضًا تقديم clientRecordVersion يتوافق مع نظام تحديد الإصدارات المستخدَم في بياناتك. إذا لم يكن الإصدار متاحًا، يمكنك استخدام القيمة Long للطابع الزمني الحالي كبديل.

   val recordVersion = 0L
   // Specify as needed
   // The clientRecordId is an ID that you choose for your record. This
   // is often the same ID you use in your app's datastore.
   val clientRecordId = "<your-record-id>"
   
   val record = WeightRecord(
       metadata = Metadata.activelyRecorded(
           clientRecordId = clientRecordId,
           clientRecordVersion = recordVersion,
           device = Device(type = Device.TYPE_SCALE)
       ),
       weight = Mass.kilograms(62.0),
       time = Instant.now(),
       zoneOffset = ZoneOffset.UTC,
   )
   healthConnectClient.insertRecords(listOf()(record))
   
   

4. إضافة/تعديل البيانات في Health Connect باستخدام insertRecords تعني عملية إدراج البيانات وتعديلها أنّه سيتم استبدال أي بيانات حالية في Health Connect طالما أنّ قيم clientRecordId متوفّرة في مستودع بيانات Health Connect، وأنّ قيمة clientRecordVersion أعلى من القيمة الحالية. وفي حال عدم توفّرها، تتم كتابة البيانات التي تم إدراجها أو تعديلها كبيانات جديدة.

   healthConnectClient.insertRecords(arrayListOf(record))
   

للتعرّف على الاعتبارات العملية المتعلقة بتوفير البيانات، يمكنك الاطّلاع على أفضل الممارسات المتعلّقة بكتابة البيانات.

تخزين أرقام تعريف Health Connect

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

تعرض الدالة insertRecords InsertRecordsResponse يحتوي على قائمة بقيم id. استخدِم الردّ للحصول على معرّفات السجلات وتخزينها.

val response = healthConnectClient.insertRecords(arrayListOf(record))

for (recordId in response.recordIdsList) {
    // Store recordId to your app's datastore
}

سحب البيانات من Health Connect

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

الحصول على رمز مميّز للتغييرات

للحصول على قائمة بالتغييرات التي يجب استردادها من Health Connect، يجب أن يحتفظ تطبيقك برموز التغييرات المميزة. يمكنك استخدامها عند طلب التغييرات لعرض قائمة بالتغييرات التي تم إجراؤها على البيانات ورمز مميّز جديد للتغييرات لاستخدامه في المرة التالية.

للحصول على رمز مميّز للتغييرات، اتّصِل بالدالة getChangesToken وقدِّم أنواع البيانات المطلوبة.

val changesToken = healthConnectClient.getChangesToken(
    ChangesTokenRequest(recordTypes = setOf(WeightRecord::class))
)

التحقّق من التغييرات في البيانات

بعد الحصول على رمز مميّز للتغييرات، استخدِمه للحصول على جميع التغييرات. ننصحك بإنشاء حلقة لتصفّح جميع التغييرات والتحقّق مما إذا كانت هناك تغييرات متاحة في البيانات. في ما يلي الخطوات التي يجب اتّباعها:

1. اتّصِل بـ getChanges باستخدام الرمز المميز للحصول على قائمة بالتغييرات.
2. تحقَّق من نوع التغيير، سواء كان UpsertionChange أو DeletionChange، ونفِّذ العمليات اللازمة.
   • بالنسبة إلى UpsertionChange، يجب أخذ التغييرات التي لم يتم إجراؤها من تطبيق الاتصال فقط للتأكّد من عدم إعادة استيراد البيانات.
3. عيِّن الرمز المميّز التالي للتغييرات كرمز مميّز جديد.
4. كرِّر الخطوات من 1 إلى 3 إلى أن لا يتبقى أي تغييرات.
5. تخزين الرمز المميز التالي وحجزه لعملية استيراد مستقبلية

suspend fun processChanges(token: String): String {
    var nextChangesToken = token
    do {
        val response = healthConnectClient.getChanges(nextChangesToken)
        response.changes.forEach { change ->
            when (change) {
                is UpsertionChange ->
                    if (change.record.metadata.dataOrigin.packageName != context.packageName) {
                        processUpsertionChange(change)
                    }
                is DeletionChange -> processDeletionChange(change)
            }
        }
        nextChangesToken = response.nextChangesToken
    } while (response.hasMore)
    // Return and store the changes token for use next time.
    return nextChangesToken
}

للتعرّف على الاعتبارات العملية المتعلقة باسترداد البيانات، اطّلِع على أفضل الممارسات المتعلّقة بمزامنة البيانات.

معالجة تغييرات البيانات

عليك تطبيق التغييرات على مستودع بيانات تطبيقك. بالنسبة إلى UpsertionChange، استخدِم id وlastModifiedTime من metadata إلى upsert السجلّ. بالنسبة إلى DeletionChange، استخدِم id المقدَّم لحذف السجلّ. يتطلّب ذلك أن تكون قد خزّنت السجلّ id كما هو موضّح في تخزين معرّفات Health Connect.

حذف البيانات من Health Connect

عندما يحذف المستخدم بياناته من تطبيقك، تأكَّد من إزالتها أيضًا من Health Connect. استخدِم deleteRecords لإجراء ذلك. يأخذ هذا النوع نوع سجل وقائمة بقيم id وclientRecordId، ما يجعله مناسبًا لحذف عدة بيانات دفعة واحدة. يتوفّر أيضًا deleteRecords بديل يأخذ timeRangeFilter.

أفضل الممارسات لمزامنة البيانات

تؤثر العوامل التالية في عملية المزامنة.

انتهاء صلاحية الرمز المميز

بما أنّ رمز التغييرات غير المستخدَم تنتهي صلاحيته خلال 30 يومًا، عليك استخدام استراتيجية مزامنة تتجنّب فقدان المعلومات في مثل هذه الحالة. يمكن أن تتضمّن استراتيجيتك الأساليب التالية:

• ابحث في مستودع بيانات تطبيقك عن السجلّ الذي تم استخدامه مؤخرًا والذي يتضمّن أيضًا id من Health Connect.
• يمكنك طلب سجلّات من Health Connect تبدأ بطابع زمني محدّد، ثم إدراجها أو تعديلها في مستودع بيانات تطبيقك.
• اطلب رمزًا مميزًا للتغييرات لحجزه لاستخدامه في المرة القادمة التي تحتاج فيها إليه.

استراتيجيات إدارة "التغييرات المقترَحة"

في حال كان تطبيقك يتلقّى رموز تغييرات غير صالحة أو منتهية الصلاحية، ننصحك باتّباع استراتيجيات الإدارة التالية حسب طريقة تطبيقها في منطقك:

• قراءة جميع البيانات وإزالة التكرار هذه هي الاستراتيجية الأنسب.
  • تخزين الطابع الزمني لآخر مرة قرأ فيها البيانات من Health Connect
  • عند انتهاء صلاحية الرمز المميّز، أعِد قراءة جميع البيانات من الطابع الزمني الأحدث أو لآخر 30 يومًا. بعد ذلك، أزِل التكرار من البيانات التي تمت قراءتها سابقًا باستخدام المعرّفات.
  • يُفضَّل تنفيذ أرقام تعريف العملاء لأنّها مطلوبة لتعديل البيانات.
• قراءة البيانات فقط منذ الطابع الزمني لآخر قراءة: ويؤدي ذلك إلى بعض التناقضات في البيانات في وقت انتهاء صلاحية رمز التغييرات المميّز، ولكن الفترة الزمنية أقصر وقد تستغرق بضع ساعات إلى يومين.
  • تخزين الطابع الزمني لآخر مرة قرأ فيها البيانات من Health Connect
  • عند انتهاء صلاحية الرمز المميز، اقرأ جميع البيانات من هذا الطابع الزمني فصاعدًا.
• حذف البيانات ثم قراءتها لآخر 30 يومًا يتوافق ذلك بشكل أكبر مع ما يحدث عند إجراء عملية الدمج الأولى.
  • حذف جميع البيانات التي قرأها التطبيق من Health Connect خلال آخر 30 يومًا
  • بعد حذفها، عليك قراءة كل هذه البيانات مرة أخرى.
• قراءة البيانات لآخر 30 يومًا بدون إزالة التكرار هذه هي الاستراتيجية الأقل ملاءمة، وتؤدي إلى عرض بيانات مكرّرة للمستخدمين.
  • حذف جميع البيانات التي قرأها التطبيق من Health Connect خلال آخر 30 يومًا
  • السماح بإدخالات مكرّرة

رموز تغيير نوع البيانات

إذا كان تطبيقك يستهلك أكثر من نوع بيانات واحد بشكل مستقل، استخدِم رموز Changes Tokens منفصلة لكل نوع بيانات. لا تستخدِم قائمة بأنواع بيانات متعدّدة مع واجهة برمجة التطبيقات Changes Sync API إلا إذا كان يتم استخدام أنواع البيانات هذه معًا أو لا يتم استخدامها على الإطلاق.

القراءات في المقدّمة

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

القراءة في الخلفية

يمكنك طلب تشغيل تطبيقك في الخلفية وقراءة البيانات من Health Connect. إذا طلبت الإذن Background Read، يمكن للمستخدم منح تطبيقك إذن الوصول إلى البيانات وقراءتها في الخلفية.

توقيتات الاستيراد

بما أنّه لا يمكن إرسال إشعارات إلى تطبيقك بشأن البيانات الجديدة، عليك التحقّق من توفّر بيانات جديدة في نقطتَين:

• في كل مرة يصبح تطبيقك نشطًا في المقدّمة. في هذه الحالة، استخدِم أحداث مراحل النشاط.
• بشكل دوري، أثناء بقاء تطبيقك في المقدّمة إبلاغ المستخدمين عند توفّر بيانات جديدة، ما يتيح لهم تعديل شاشتهم لعرض التغييرات