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

تحتوي معظم التطبيقات التي يتم دمجها مع Health Connect على قاعدة بيانات خاصة بها تُعدّ مصدر المعلومات. يوفّر Health Connect طرقًا لمزامنة التطبيقات.

تأكَّد من أنّ تطبيقك ينفّذ ما يلي:

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

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

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

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

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

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

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

يمكنك تصميم قاعدة بيانات تطبيقك لتتبُّع البيانات التي سبق أن تم إرسالها إلى Health Connect. لتحقيق ذلك، طبِّق المنطق التالي:

• قدِّم قائمة بالتغييرات ورمزًا مميزًا يمكن استخدامه لاسترداد السجلّات التي تم تعديلها منذ إصدار الرمز المميّز الأخير.
• تتبُّع آخر مرة تم فيها تعديل البيانات المُصدَّرة

هذه الخطوات ضرورية لضمان عدم إدخال سوى البيانات الجديدة أو المعدَّلة إلى Health Connect.

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

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

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

3. حدِّد عنصر Metadata مع كل Record باستخدام المفتاح الفريد و تفاصيل الإصدار من قاعدة بيانات تطبيقك. إذا لم تكن بياناتك مُحدَّدة الإصدار، يمكنك استخدام القيمة Long للطابع الزمني الحالي كخيار بديل.

   val record = WeightRecord(
       metadata = Metadata(
           clientRecordId = "<Your record's Client ID>",
           clientRecordVersion = <Your record's version>
       ),
       weight = weight,
       time = time,
       zoneOffset = zoneOffset
   )
   

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

   healthConnectClient.insertRecords(arrayListOf(record))
   

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

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

بعد تعديل سجلاتك وإضافتها إلى 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 لإدراج السجلّ. بالنسبة إلى DeletionChange، استخدِم id المقدَّمة لحذف السجلّ.

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

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

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

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

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

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

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

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

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

• قراءة جميع البيانات وإزالة تكرارها هذه هي الاستراتيجية الأكثر مثالية.
  • تخزين الطابع الزمني لآخر مرة قرأ فيها التطبيق البيانات من Health Connect
  • عند انتهاء صلاحية الرمز المميّز، تتم إعادة قراءة جميع البيانات من آخر طابع زمني أو لآخر 30 يومًا. بعد ذلك، عليك إزالة تكراراتها مقارنةً بالبيانات التي تم قراءتها سابقًا باستخدام المعرّفات.
  • من الأفضل استخدام أرقام تعريف العملاء لأنّها مطلوبة لتعديل البيانات.
• قراءة البيانات منذ آخر طابع زمني للقراءة فقط ويؤدي ذلك إلى بعض الاختلافات في البيانات في وقت انتهاء صلاحية رمز Changes، ولكن الفترة الزمنية أقصر وقد تستغرق بضعة ساعات إلى يومَين.
  • تخزين الطابع الزمني لآخر مرة قرأ فيها التطبيق البيانات من 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، يمكن للمستخدم منح تطبيقك إذن قراءة البيانات في الخلفية.

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

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

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