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

تحتوي معظم التطبيقات التي تتكامل مع 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 يومًا
    • السماح بالإدخالات المكرّرة

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

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

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

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

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

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

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