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

تحتوي معظم التطبيقات التي تتكامل مع 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. استخدِم Upsert لنقل البيانات إلى 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، ما يسهِّل تجميع بيانات متعددة لحذفها. ويتوفّر أيضًا خيار deleteRecords بديل يستخدم timeRangeFilter.

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

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

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

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

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

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

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

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

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

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

القراءات التي تظهر في المقدمة

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

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

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

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