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

يتناول هذا الدليل عملية كتابة البيانات أو تعديلها في 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 تخزين القيم مع وحدات القياس التابعة لها لضمان الدقة. ومن الأمثلة على ذلك نوع بيانات 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. الخصائص التالية ذات صلة بالمزامنة:

الخصائص الوصف
id لكل Record في Health Connect قيمة id فريدة.
يملأ تطبيق Health Connect هذه البيانات تلقائيًا عند إدراج سجلّ جديد.
lastModifiedTime ويتتبّع كل Record أيضًا آخر مرة تم فيها تعديل السجلّ.
يملأ تطبيق Health Connect هذه البيانات تلقائيًا.
clientRecordId يمكن أن يكون لكل Record رقم تعريف فريد مرتبط به ليكون بمثابة مرجع في مخزن بيانات التطبيق.
يوفّر تطبيقك هذه القيمة.
clientRecordVersion عندما يحتوي السجل على clientRecordId، يمكن استخدام clientRecordVersion للسماح ببقاء البيانات متزامنة مع الإصدار في مخزن بيانات التطبيق.
يوفّر تطبيقك هذه القيمة.

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

لتعديل البيانات، يُرجى إعداد السجلّات المطلوبة أولاً. نفِّذ أي تغييرات على السجلات إذا لزم الأمر. يمكنك بعد ذلك الاتصال بـ 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
    }
}

التحديث من خلال معرِّف سجل العميل

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

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

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

لا تؤدي الإضافات إلى زيادة version تلقائيًا عند إجراء تغييرات، ما يمنع حدوث أي حالات غير متوقعة من استبدال البيانات. بذلك، يجب عليك تقديمه يدويًا بقيمة أعلى.

أفضل الممارسات

بعد وضع المنطق، ننصحك باتّباع أفضل الممارسات عند كتابة البيانات أو تعديلها.