داده ها را بنویسید

این راهنما فرآیند نوشتن یا به‌روزرسانی داده‌ها در Health Connect را پوشش می‌دهد.

تنظیم ساختار داده

قبل از نوشتن داده، ابتدا باید رکوردها را تنظیم کنیم. برای بیش از 50 نوع داده، هر کدام ساختار مربوط به خود را دارند. برای جزئیات بیشتر در مورد انواع داده های موجود به مرجع Jetpack مراجعه کنید.

سوابق پایه

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

مثال زیر نحوه تنظیم داده های شمارش مراحل را نشان می دهد:

val stepsRecord = StepsRecord(
    count = 120,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET
)

ثبت با واحدهای اندازه گیری

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

در این نوع داده، همه مواد مغذی در واحد Mass نشان داده می شوند، در حالی که energy در یک واحد Energy نمایش داده می شود.

مثال زیر نحوه تنظیم داده های تغذیه برای کاربری که موز خورده را نشان می دهد:

val banana = NutritionRecord(
    name = "banana",
    energy = 105.0.kilocalories,
    dietaryFiber = 3.1.grams,
    potassium = 0.422.grams,
    totalCarbohydrate = 27.0.grams,
    totalFat = 0.4.grams,
    saturatedFat = 0.1.grams,
    sodium = 0.001.grams,
    sugar = 14.0.grams,
    vitaminB6 = 0.0005.grams,
    vitaminC = 0.0103.grams,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET
)

سوابق با داده های سری

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

در این نوع داده، samples پارامتر با فهرستی از نمونه‌های ضربان قلب نشان داده می‌شوند. هر نمونه حاوی یک مقدار beatsPerMinute و یک مقدار time است.

مثال زیر نحوه تنظیم داده های سری ضربان قلب را نشان می دهد:

val heartRateRecord = HeartRateRecord(
    startTime = START_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endTime = END_TIME,
    endZoneOffset = END_ZONE_OFFSET,
    // records 10 arbitrary data, to replace with actual data
    samples = List(10) { index ->
        HeartRateRecord.Sample(
            time = START_TIME + Duration.ofSeconds(index.toLong()),
            beatsPerMinute = 100 + index.toLong(),
        )
    }
)

داده ها را بنویسید

یکی از گردش های کاری رایج در Health Connect نوشتن داده است. برای افزودن رکوردها، از insertRecords استفاده کنید.

مثال زیر نحوه نوشتن تعداد مراحل درج داده را نشان می دهد:

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = START_TIME,
            endTime = END_TIME,
            startZoneOffset = START_ZONE_OFFSET,
            endZoneOffset = END_ZONE_OFFSET
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

به روز رسانی داده ها

اگر نیاز به تغییر یک یا چند رکورد دارید، به‌ویژه زمانی که باید فروشگاه داده برنامه خود را با داده‌های Health Connect همگام‌سازی کنید ، می‌توانید داده‌های خود را به‌روزرسانی کنید. دو راه برای به روز رسانی داده های موجود وجود دارد که به شناسه مورد استفاده برای یافتن رکوردها بستگی دارد.

فراداده

ارزش آن را دارد که ابتدا کلاس Metadata را بررسی کنید زیرا این کار هنگام به روز رسانی داده ها ضروری است. هنگام ایجاد، هر Record در Health Connect دارای یک فیلد metadata است. ویژگی های زیر به همگام سازی مربوط می شود:

از طریق Record ID به روز رسانی کنید

برای به روز رسانی داده ها، ابتدا رکوردهای مورد نیاز را آماده کنید. در صورت لزوم هر گونه تغییر در سوابق انجام دهید. سپس برای ایجاد تغییرات با updateRecords تماس بگیرید.

مثال زیر نحوه به روز رسانی داده ها را نشان می دهد. برای این منظور، هر رکورد دارای مقادیر افست ناحیه خود در PST است.

suspend fun updateSteps(
    healthConnectClient: HealthConnectClient,
    prevRecordStartTime: Instant,
    prevRecordEndTime: Instant
) {
    try {
        val request = healthConnectClient.readRecords(
            ReadRecordsRequest(
                recordType = StepsRecord::class,
                timeRangeFilter = TimeRangeFilter.between(
                    prevRecordStartTime,
                    prevRecordEndTime
                )
            )
        )

        val newStepsRecords = arrayListOf<StepsRecord>()
        for (record in request.records) {
            // Adjusted both offset values to reflect changes
            val sr = StepsRecord(
                count = record.count,
                startTime = record.startTime,
                startZoneOffset = record.startTime.atZone(ZoneId.of("PST")).offset,
                endTime = record.endTime,
                endZoneOffset = record.endTime.atZone(ZoneId.of("PST")).offset,
                metadata = record.metadata
            )
            newStepsRecords.add(sr)
        }

        client.updateRecords(newStepsRecords)
    } catch (e: Exception) {
        // Run error handling here
    }
}

از طریق شناسه سابقه مشتری آپلود کنید

اگر از مقادیر اختیاری Client Record ID و Client Record Version استفاده می کنید، توصیه می کنیم از insertRecords به جای updateRecords استفاده کنید.

تابع insertRecords قابلیت اضافه کردن داده ها را دارد. اگر داده‌ها در Health Connect بر اساس مجموعه شناسه‌های سوابق مشتری وجود داشته باشد، بازنویسی می‌شود. در غیر این صورت به عنوان داده جدید نوشته می شود. این سناریو زمانی مفید است که نیاز به همگام سازی داده ها از فروشگاه داده برنامه خود با Health Connect داشته باشید.

مثال زیر نشان می‌دهد که چگونه می‌توان یک upsert را روی داده‌های استخراج‌شده از فروشگاه داده برنامه انجام داد:

suspend fun pullStepsFromDatastore() : ArrayList<StepsRecord> {
    val appStepsRecords = arrayListOf<StepsRecord>()
    // Pull data from app datastore
    // ...
    // Make changes to data if necessary
    // ...
    // Store data in appStepsRecords
    // ...
    var sr = StepsRecord(
        // Assign parameters for this record
        metadata = Metadata(
            clientRecordId = cid
        )
    )
    appStepsRecords.add(sr)
    // ...
    return appStepsRecords
}

suspend fun upsertSteps(
    healthConnectClient: HealthConnectClient,
    newStepsRecords: ArrayList<StepsRecord>
) {
    try {
        healthConnectClient.insertRecords(newStepsRecords)
    } catch (e: Exception) {
        // Run error handling here
    }
}

پس از آن، می توانید این توابع را در موضوع اصلی خود فراخوانی کنید.

upsertSteps(healthConnectClient, pullStepsFromDatastore())

بررسی ارزش در نسخه ثبت مشتری

اگر فرآیند درج اطلاعات شما شامل نسخه ثبت مشتری باشد، Health Connect بررسی های مقایسه را در مقادیر clientRecordVersion انجام می دهد. اگر نسخه از داده های درج شده بالاتر از نسخه داده های موجود باشد، upsert اتفاق می افتد. در غیر این صورت، فرآیند تغییر را نادیده می گیرد و مقدار ثابت می ماند.

برای گنجاندن نسخه‌سازی در داده‌های خود، باید Metadata.clientRecordVersion با مقدار Long بر اساس منطق نسخه‌سازی خود ارائه دهید.

val sr = StepsRecord(
    count = count,
    startTime = startTime,
    startZoneOffset = startZoneOffset,
    endTime = endTime,
    endZoneOffset = endZoneOffset,
    metadata = Metadata(
        clientRecordId = cid,
        clientRecordVersion = version
    )
)

هر زمان که تغییراتی وجود داشته باشد، Upsert ها به طور خودکار version افزایش نمی دهند و از هر گونه نمونه غیرمنتظره ای از رونویسی داده ها جلوگیری می کنند. با آن، شما باید به صورت دستی آن را با مقدار بالاتری عرضه کنید.

بهترین روش ها برای نوشتن داده ها

برنامه‌ها فقط باید داده‌های منبع خود را در Health Connect بنویسند.

اگر داده های برنامه شما از برنامه دیگری وارد شده باشد، مسئولیت نوشتن داده های خود در Health Connect بر عهده برنامه دیگر است.

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

هنگام ردیابی داده ها، بسته به روشی که برنامه شما داده ها را می نویسد، می توانید چند پیشنهاد را دنبال کنید.

ردیابی غیرفعال

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

برنامه شما باید به صورت دوره‌ای داده‌ها را به روش‌های زیر در Health Connect بنویسد :

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

• کارها را محدود کنید تا فقط زمانی که دستگاه بیکار است و باتری آن کم نیست اجرا شود.

  val constraints = Constraints.Builder()
      .requiresBatteryNotLow()
      .requiresDeviceIdle(true)
      .build()
  
  val writeDataWork = PeriodicWorkRequestBuilder<WriteDataToHealthConnectWorker>(
          15,
          TimeUnit.MINUTES,
          5,
          TimeUnit.MINUTES
      )
      .setConstraints(constraints)
      .build()
  

ردیابی فعال

این شامل برنامه‌هایی می‌شود که ردیابی مبتنی بر رویداد مانند ورزش و خواب، یا ورودی دستی کاربر مانند تغذیه را انجام می‌دهند. این رکوردها زمانی ایجاد می‌شوند که برنامه در پیش‌زمینه باشد یا در رویدادهای نادری که چند بار در روز از آن استفاده می‌شود.

مطمئن شوید که برنامه شما Health Connect را در تمام مدت رویداد اجرا نمی‌کند.

داده ها باید به یکی از دو روش در Health Connect نوشته شوند:

• پس از اتمام رویداد، داده ها را در Health Connect همگام کنید. به عنوان مثال، زمانی که کاربر یک جلسه تمرین ردیابی شده را پایان می دهد، داده ها را همگام سازی کنید.
• با استفاده از WorkManager برای همگام سازی داده ها بعداً یک کار یکباره را برنامه ریزی کنید.

بهترین روش ها برای دانه بندی و فراوانی نوشته ها

هنگام نوشتن داده ها در Health Connect، از وضوح مناسب استفاده کنید. استفاده از وضوح مناسب به کاهش بار ذخیره سازی کمک می کند، در حالی که همچنان داده های ثابت و دقیق را حفظ می کند. وضوح داده ها شامل 2 چیز است:

1. فرکانس نوشتن : هر چند وقت یکبار برنامه شما هر داده جدیدی را به Health Connect فشار می دهد. به عنوان مثال، هر 15 دقیقه یک داده جدید بنویسید.
2. دانه بندی داده های نوشته شده : هر چند وقت یکبار از داده هایی که وارد می شوند نمونه برداری شده است. به عنوان مثال، نمونه ضربان قلب را هر 5 ثانیه بنویسید. هر نوع داده ای به نرخ نمونه یکسانی نیاز ندارد. به‌روزرسانی داده‌های شمارش گام‌ها در هر ثانیه، در مقایسه با سرعت کمتر مانند هر 60 ثانیه، سود کمی دارد. با این حال، نرخ نمونه بالاتر ممکن است به کاربران نگاه دقیق‌تری به داده‌های سلامت و تناسب اندامشان بدهد. فرکانس های نرخ نمونه باید تعادلی بین جزئیات و عملکرد ایجاد کنند.

داده های نظارت شده در طول روز را بنویسید

برای داده‌هایی که به صورت مداوم جمع‌آوری می‌شوند، مانند مراحل، برنامه شما باید حداقل هر ۱۵ دقیقه در روز به Health Connect بنویسد.

جلسات را بنویسید

داده ها باید در پایان جلسه تمرین یا خواب در Health Connect نوشته شوند.

به عنوان بهترین روش، هر جلسه خواب یا جلسه تمرین باید با دستگاه ضبط و ابرداده مناسب، از جمله RecordingMethod نوشته شود.

حداقل، درخواست شما باید از راهنمای ستون "مورد انتظار" زیر پیروی کند. در صورت امکان، "بهترین" راهنمایی را دنبال کنید.

داده های ردیابی شده در طول تمرین

داده های ردیابی شده در هنگام خواب