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

این راهنما با Health Connect نسخه 1.1.0-alpha12 سازگار است.

اکثر برنامه‌هایی که با 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 مهر زمانی فعلی به عنوان جایگزین استفاده کنید.

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

    healthConnectClient.insertRecords(arrayListOf(record))

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

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

برای به دست آوردن نشانه تغییرات ، با getChangesToken تماس بگیرید و انواع داده های مورد نیاز را ارائه دهید.

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

تغییرات داده ها را بررسی کنید

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

  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 ارائه شده برای حذف رکورد استفاده کنید. این مستلزم آن است که id رکورد را همانطور که در شناسه‌های Store 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 درخواست کنید، کاربر می‌تواند به برنامه شما اجازه دهد تا داده‌ها را در پس‌زمینه بخواند.

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

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

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