همگام سازی داده ها

اکثر برنامه‌هایی که با 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. برای هر Record یک شیء Metadata مشخص کنید. این شامل clientRecordId می‌شود که یک شناسه از پایگاه داده برنامه شماست و می‌توانید از آن برای شناسایی منحصر به فرد رکورد استفاده کنید. می‌توانید از کلید منحصر به فرد موجود خود برای این کار استفاده کنید. اگر داده‌های شما نسخه‌بندی شده‌اند، یک clientRecordVersion نیز ارائه دهید که با نسخه‌بندی استفاده شده در داده‌های شما همسو باشد. اگر نسخه‌بندی نشده است، می‌توانید از مقدار Long مربوط به timestamp فعلی به عنوان جایگزین استفاده کنید.

   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. با استفاده از insertRecords داده‌ها را به Health Connect اضافه کنید . اضافه کردن داده‌ها به این معنی است که هر داده موجود در Health Connect تا زمانی که مقادیر clientRecordId در datastore Health Connect وجود داشته باشد و clientRecordVersion بالاتر از مقدار موجود باشد، رونویسی می‌شود. در غیر این صورت، داده‌های اضافه شده به عنوان داده جدید نوشته می‌شوند.

   healthConnectClient.insertRecords(arrayListOf(record))
   

برای آشنایی با ملاحظات عملی برای تغذیه داده‌ها، بهترین شیوه‌ها برای نوشتن داده‌ها را بررسی کنید.

شناسه‌های فروشگاه Health Connect

اگر برنامه شما داده‌ها را از Health Connect نیز می‌خواند، id Health Connect را برای رکوردها پس از درج آنها ذخیره کنید. برای پردازش حذف‌ها هنگام دریافت تغییرات داده‌ها از Health Connect به این id نیاز دارید.

تابع 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، برنامه شما باید توکن‌های Changes را پیگیری کند. می‌توانید هنگام درخواست Changes از آنها برای بازگرداندن لیستی از تغییرات داده‌ها و یک توکن Changes جدید که دفعه بعد استفاده خواهد شد، استفاده کنید.

برای دریافت توکن تغییرات ، getChangesToken را فراخوانی کنید و انواع داده‌های مورد نیاز را ارائه دهید.

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

بررسی تغییرات داده‌ها

اکنون که توکن تغییرات را دریافت کرده‌اید، از آن برای دریافت همه تغییرات استفاده کنید. توصیه می‌کنیم یک حلقه ایجاد کنید تا همه تغییرات را بررسی کند و بررسی کند که آیا تغییرات داده‌ای موجود است یا خیر. مراحل زیر را دنبال کنید:

1. برای دریافت لیستی از تغییرات، getChanges با استفاده از توکن فراخوانی کنید.
2. هر تغییر را بررسی کنید که آیا نوع آن UpsertionChange است یا DeletionChange ، و عملیات لازم را انجام دهید.
   • برای UpsertionChange ، فقط تغییراتی را اعمال کنید که از برنامه فراخوانی کننده نیامده باشند تا مطمئن شوید که داده‌ها را دوباره وارد نمی‌کنید.
3. توکن تغییرات بعدی را به عنوان توکن جدید خود اختصاص دهید.
4. مراحل ۱ تا ۳ را تا زمانی که هیچ تغییری باقی نمانده باشد، تکرار کنید.
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 رکورد را همانطور که در Store Health Connect IDs ذکر شده است، ذخیره کرده باشید.

حذف داده‌ها از Health Connect

وقتی کاربری داده‌های خود را از برنامه شما حذف می‌کند، مطمئن شوید که داده‌ها از Health Connect نیز حذف می‌شوند . برای انجام این کار deleteRecords استفاده کنید. این تابع یک نوع رکورد و لیستی از مقادیر id و clientRecordId را دریافت می‌کند که حذف دسته‌ای چندین داده را آسان می‌کند. یک deleteRecords جایگزین که یک timeRangeFilter را دریافت می‌کند نیز موجود است.

بهترین روش‌ها برای همگام‌سازی داده‌ها

عوامل زیر بر روند همگام‌سازی تأثیر می‌گذارند.

انقضای توکن

از آنجایی که یک توکن Changes استفاده نشده ظرف 30 روز منقضی می‌شود، شما باید از یک استراتژی همگام‌سازی استفاده کنید که از دست رفتن اطلاعات در چنین مواردی جلوگیری کند. استراتژی شما می‌تواند شامل رویکردهای زیر باشد:

• در پایگاه داده برنامه خود، جدیدترین رکورد مصرف‌شده که دارای id Health Connect نیز هست را جستجو کنید.
• از Health Connect رکوردهایی را درخواست کنید که با یک مهر زمانی خاص شروع می‌شوند و سپس آنها را در مخزن داده برنامه خود وارد یا به‌روزرسانی کنید.
• برای رزرو توکن تغییرات (Changes token) برای دفعه‌ی بعدی که به آن نیاز دارید، درخواست دهید.

استراتژی‌های پیشنهادی مدیریت تغییرات

در صورتی که توکن‌های تغییرات برنامه شما نامعتبر یا منقضی شده باشند، بسته به کاربرد آن در منطق شما، استراتژی‌های مدیریتی زیر را توصیه می‌کنیم:

• تمام داده‌ها را بخوانید و حذف کنید . این ایده‌آل‌ترین استراتژی است.
  • مهر زمانی آخرین باری که آنها داده ها را از Health Connect می خوانند، ذخیره کنید.
  • در زمان انقضای توکن، تمام داده‌ها را از آخرین برچسب زمانی یا برای ۳۰ روز گذشته دوباره بخوانید. سپس، آن را با استفاده از شناسه‌ها در برابر داده‌های خوانده شده قبلی dedupe کنید.
  • در حالت ایده‌آل، شناسه‌های کلاینت را پیاده‌سازی کنید زیرا برای به‌روزرسانی داده‌ها مورد نیاز هستند.
• فقط داده‌های بعد از آخرین برچسب زمانی خوانده شده را بخوانید . این منجر به برخی اختلافات داده‌ای در حدود زمان انقضای توکن Changes می‌شود، اما دوره زمانی کوتاه‌تر است و می‌تواند از چند ساعت تا چند روز طول بکشد.
  • مهر زمانی آخرین باری که آنها داده ها را از Health Connect می خوانند، ذخیره کنید.
  • در زمان انقضای توکن، تمام داده‌ها از این برچسب زمانی به بعد خوانده می‌شوند.
• داده‌های ۳۰ روز گذشته را حذف و سپس بخوانید . این روش با آنچه در اولین ادغام اتفاق می‌افتد، همسوتر است.
  • تمام داده‌های خوانده شده توسط برنامه از Health Connect را در 30 روز گذشته حذف کنید.
  • پس از حذف، تمام این داده‌ها را دوباره بخوانید.
• خواندن داده‌های ۳۰ روز گذشته بدون حذف داده‌های تکراری . این استراتژی ایده‌آل نیست و منجر به نمایش داده‌های تکراری به کاربران می‌شود.
  • تمام داده‌های خوانده شده توسط برنامه از Health Connect را در 30 روز گذشته حذف کنید.
  • اجازه ورود ورودی‌های تکراری.

نوع داده، توکن‌ها را تغییر می‌دهد

اگر برنامه شما بیش از یک نوع داده را به طور مستقل مصرف می‌کند، برای هر نوع داده از توکن‌های تغییر جداگانه استفاده کنید. فقط در صورتی از لیستی از چندین نوع داده با API همگام‌سازی تغییرات استفاده کنید که این انواع داده یا با هم مصرف می‌شوند یا اصلاً مصرف نمی‌شوند.

پیش‌زمینه خوانده می‌شود

برنامه‌ها فقط می‌توانند داده‌های Health Connect را در حالی که در پیش‌زمینه هستند بخوانند. هنگام همگام‌سازی داده‌ها از Health Connect، دسترسی به Health Connect ممکن است در هر نقطه‌ای قطع شود. به عنوان مثال، برنامه شما باید هنگام خواندن حجم زیادی از داده‌ها از Health Connect، وقفه‌ها را در اواسط همگام‌سازی مدیریت کند و دفعه بعد که برنامه باز می‌شود، ادامه دهد.

پیشینه خوانده شده

شما می‌توانید درخواست کنید که برنامه شما در پس‌زمینه اجرا شود و داده‌ها را از Health Connect بخواند. اگر مجوز Background Read درخواست کنید، کاربر شما می‌تواند به برنامه شما اجازه دهد تا در پس‌زمینه داده‌ها را بخواند.

زمان‌بندی‌های واردات

از آنجایی که برنامه شما نمی‌تواند از داده‌های جدید مطلع شود، داده‌های جدید را در دو مرحله بررسی کنید:

• هر بار که برنامه شما در پیش‌زمینه فعال می‌شود. در این حالت، از رویدادهای چرخه عمر استفاده کنید.
• به صورت دوره‌ای، در حالی که برنامه شما در پیش‌زمینه است. هنگامی که داده‌های جدید در دسترس قرار گرفت، به کاربران اطلاع دهید و به آنها اجازه دهید صفحه نمایش خود را به‌روزرسانی کنند تا تغییرات را منعکس کنند.