كتابة البيانات

يتناول هذا الدليل عملية كتابة البيانات أو تعديلها في Health Connect.

إعداد بنية البيانات

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

السجلّات الأساسية

يلتقط نوع بيانات الخطوات في Health Connect عدد الخطوات التي اتخذها المستخدم بين القراءات. يمثّل عدد الخطوات قياسًا شائعًا عبر منصات الصحة واللياقة البدنية والعافية.

يوضّح المثال التالي كيفية ضبط بيانات عدد الخطوات:

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

سجلات بوحدات قياس

يمكن لتطبيق Health Connect تخزين القيم مع وحدات القياس لتوفير ودقتها. أحد الأمثلة على ذلك هو نوع بيانات التغذية الذي يكون واسعًا وشاملة. وتشمل مجموعة واسعة من الحقول الغذائية الاختيارية التي تتراوح بين من إجمالي الكربوهيدرات إلى الفيتامينات. تمثل كل نقطة بيانات العناصر الغذائية التي من المحتمل أن يتم استهلاكها كجزء من وجبة أو عنصر غذائي.

في هذا النوع من البيانات، يتم تمثيل جميع العناصر الغذائية بوحدات 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. السمات التالية ذات صلة بـ المزامنة:

التعديل من خلال رقم تعريف السجلّ

لتحديث البيانات، قم بإعداد السجلات المطلوبة أولاً. أجرِ أي تغييرات على السجلات إذا لزم الأمر. بعد ذلك، يمكنك الاتصال بالرقم updateRecords لإجراء التغييرات.

يوضّح المثال التالي كيفية تعديل البيانات. لهذا الغرض، يجب تخصيص كل سجل تم تعديل قيم إزاحة المنطقة الخاصة بها إلى توقيت المحيط الهادئ.

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
    }
}

الترقية من خلال معرِّف سجلّ العميل

إذا كنت تستخدم القيمتين الاختياريتين لمعرّف سجل العميل وإصدار سجل العميل، نقترح استخدام insertRecords بدلاً من updateRecords.

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

يوضح المثال التالي كيفية إجراء عملية بحث أعلى على البيانات التي تم سحبها من مخزن بيانات التطبيق:

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

لتضمين الإصدارات في بياناتك، تحتاج إلى توفير Metadata.clientRecordVersion بقيمة Long استنادًا إلى عمليات تحديد الإصدارات المنطق.

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

لا تعمل عمليات التحسين على زيادة 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، استخدِم درجة الدقة المناسبة. استخدام تساعد الدقة المناسبة في تقليل حِمل التخزين، مع الحفاظ على بيانات متسقة ودقيقة. تشمل درجة دقة البيانات أمرين:

1. معدل تكرار عمليات الكتابة: عدد المرات التي يرسل فيها تطبيقك أي بيانات جديدة إلى Health Connect. على سبيل المثال، اكتب بيانات جديدة كل 15 دقيقة.
2. دقة البيانات المكتوبة: عدد المرات التي تم فيها دفع البيانات أخذ عينة. على سبيل المثال، اكتب عينات لمعدل ضربات القلب كل 5 ثوانٍ. ليس كل أنواع البيانات نفس معدل العينة. تعديل عدد الخطوات بفائدة بسيطة البيانات كل ثانية، على عكس وتيرة أقل تكرارًا مثل كل 60 ثوانٍ. ومع ذلك، قد تمنح معدلات العينات الأعلى للمستخدمين معلومات دقيقة في بيانات الصحة واللياقة البدنية الخاصة بهم. تكرارات معدلات العينات يجب أن يحقق توازنًا بين التفاصيل والأداء.

كتابة البيانات التي تتم مراقبتها على مدار اليوم

بالنسبة إلى البيانات التي يتم جمعها بشكلٍ مستمرّ، مثل الخطوات، يجب أن يستوفي طلبك إرسال رسالة إلى Health Connect كل 15 دقيقة على الأقل خلال اليوم.

كتابة الجلسات

يجب كتابة البيانات في Health Connect في نهاية التمرين أو النوم. جلسة المراجعة.

كأفضل ممارسة، يجب كتابة أي جلسة نوم أو جلسة تمرين مع جهاز التسجيل وبيانات التعريف المناسبة، بما في ذلك RecordingMethod

على الأقل، يجب أن يتّبع تطبيقك الإرشادات الواردة في قسم "المتوقَّع". العمود أدناه. أين اتبع "أفضل" التوجيه.

البيانات التي تم تتبعها أثناء التمرين

البيانات التي يتم تتبُّعها أثناء النوم