تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

يتوافق هذا الدليل مع الإصدار 1.1.0-alpha12 من Health Connect.

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

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

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

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

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

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

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(15))

val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = ZoneOffset.UTC,
    endZoneOffset = ZoneOffset.UTC,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)

السجلات التي تحتوي على وحدات قياس

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

في هذا النوع من البيانات، يتم تمثيل جميع المغذّيات بوحدات Mass، في حين يتم تمثيل energy بوحدة Energy.

يوضّح المثال التالي كيفية ضبط بيانات التغذية لمستخدم تناول موزًا:

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(1))

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 = startTime,
    endTime = endTime,
    startZoneOffset = ZoneOffset.UTC,
    endZoneOffset = ZoneOffset.UTC,
    metadata = Metadata.manualEntry(
        device = Device(type = Device.TYPE_PHONE)
    )
)

السجلات التي تحتوي على بيانات السلسلة

يمكن لتطبيق Health Connect تخزين قائمة ببيانات السلاسل. ومن الأمثلة على ذلك نوع البيانات معدّل نبضات القلب الذي يسجّل سلسلة من عيّنات نبضات القلب التي يتم رصدها بين القراءات.

في هذا النوع من البيانات، يتم تمثيل المَعلمة samples بقائمة من عيّنات معدّل نبضات القلب. تحتوي كل عيّنة على قيمة beatsPerMinute وقيمة time.

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

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(5))

val heartRateRecord = HeartRateRecord(
    startTime = startTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = endTime,
    endZoneOffset = ZoneOffset.UTC,
    // records 10 arbitrary data, to replace with actual data
    samples = List(10) { index ->
        HeartRateRecord.Sample(
            time = startTime + Duration.ofSeconds(index.toLong()),
            beatsPerMinute = 100 + index.toLong(),
        )
    },
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    ))

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

من العمليات الشائعة في Health Connect هي كتابة البيانات. لإضافة سجلّات، استخدِم insertRecords.

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

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    val endTime = Instant.now()
    val startTime = endTime.minus(Duration.ofMinutes(5))
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = startTime,
            endTime = endTime,
            startZoneOffset = ZoneOffset.UTC,
            endZoneOffset = ZoneOffset.UTC,
            metadata = Metadata.autoRecorded(
                device = Device(type = Device.TYPE_WATCH)
            )
        )
        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 لإجراء التغييرات.

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

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

        healthConnectClient.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(
        metadata = Metadata.autoRecorded(
            clientRecordId = "Your client record ID",
            device = Device(type = Device.TYPE_WATCH)
        ),
        // Assign more parameters for this record
    )
    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 endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(15))

val stepsRecord = StepsRecord(
    count = 100L,
    startTime = startTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = endTime,
    endZoneOffset = ZoneOffset.UTC,
    metadata = Metadata.manualEntry(
        clientRecordId = "Your supplied record ID",
        clientRecordVersion = 0L, // Your supplied record version
        device = Device(type = Device.TYPE_WATCH)
    )
)

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

أفضل الممارسات لكتابة البيانات

يجب أن تكتب التطبيقات في Health Connect البيانات المستمدة من مصادرها الخاصة فقط.

إذا تم استيراد البيانات في تطبيقك من تطبيق آخر، تقع المسؤولية على التطبيق الآخر لكتابة بياناته الخاصة في Health Connect.

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

عند تتبُّع البيانات، هناك بعض الاقتراحات التي يمكنك اتّباعها استنادًا إلى الطريقة التي يكتب بها تطبيقك البيانات.

التتبُّع السلبي

ويشمل ذلك التطبيقات التي تُجري عمليات تتبُّع سلبيّة للّياقة البدنية أو الصحة، مثل تسجيل الخطوات أو معدّل نبضات القلب باستمرار في الخلفية.

يجب أن يُجري تطبيقك عمليات كتابة للبيانات بشكل دوري في Health Connect بالطريقة التالية:

في كل عملية مزامنة، لا تُسجِّل سوى البيانات الجديدة والبيانات المعدَّلة التي تم تعديلها منذ آخر عملية مزامنة.
يجب تقسيم الطلبات إلى 1,000 سجلّ كحدّ أقصى لكل طلب كتابة.
استخدِم 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، استخدِم الدقة المناسبة. يساعد استخدام الدقة المناسبة في تقليل عبء التخزين، مع الحفاظ على اتساق البيانات ودقتها. تشمل درجة دقة البيانات شيئَين:

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

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

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

نوع البيانات	الوحدة	القيمة المتوقّعة	مثال
الخطوات	الخطوات	كل دقيقة واحدة	23:14 - 23:15 - 5 خطوات 23:16 - 23:17 - 22 خطوة 23:17 - 23:18 - 8 خطوات
StepsCadence	خطوة/دقيقة	كل دقيقة واحدة	23:14 - 23:15 - 5 نبضات في الدقيقة 23:16 - 23:17 - 22 نبضة في الدقيقة 23:17 - 23:18 - 8 نبضة في الدقيقة
عدد دفعات الكرسي المتحرك	دفعات	كل دقيقة واحدة	23:14 - 23:15 - 5 دفعات 23:16 - 23:17 - 22 دفعة 23:17 - 23:18 - 8 دفعات
ActiveCaloriesBurned	السُعرات الحرارية	كل 15 دقيقة	23:15 - 23:30 - سعرتَان حراريتان 23:30 - 23:45 - 25 سعرة حرارية 23:45 - 00:00 - 5 سعرات حرارية
TotalCaloriesBurned	السُعرات الحرارية	كل 15 دقيقة	23:15 - 23:30 - 16 سعرة حرارية 23:30 - 23:45 - 16 سعرة حرارية 23:45 - 00:00 - 16 سعرة حرارية
المسافة	كلم/دقيقة	كل دقيقة واحدة	من 23:14 إلى 23:15 - 0.008 كلم 23:16 - 23:16 - 0.021 كلم 23:17 - 23:18 - 0.012 كلم
ElevationGained	د	كل دقيقة واحدة	20:36 - 20:37 - 3.048m 20:39 - 20:40 - 3.048m 23:23 - 23:24 - 9.144m
عدد الطوابق التي تم صعودها	طوابق	كل دقيقة واحدة	23:14 - 23:15 - 5 طوابق 23:16 - 23:16 - 22 طابقًا 23:17 - 23:18 - 8 طوابق
HeartRate	نبضة في الدقيقة	كل دقيقة واحدة	6:11 صباحًا - 55 نبضة في الدقيقة
HeartRateVariabilityRmssd	ميللي ثانية	كل دقيقة واحدة	6:11 صباحًا - 23 ملي ثانية
RespiratoryRate	نفَس في الدقيقة	كل دقيقة واحدة	23:14 - 23:15 - 60 نفسًا في الدقيقة 23:16 - 23:16 - 62 نفسًا في الدقيقة 23:17 - 23:18 - 64 نفسًا في الدقيقة
OxygenSaturation	%	كل ساعة واحدة	‫6:11 - ‏95.208%

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

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

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

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

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

نوع البيانات	الوحدة	القيمة المتوقّعة	مع أطيب التحيات	مثال
الخطوات	الخطوات	كل دقيقة واحدة	كل ثانية واحدة	23:14-23:15 - 5 خطوات 23:16 - 23:17 - 22 خطوة 23:17 - 23:18 - 8 خطوات
StepsCadence	خطوة/دقيقة	كل دقيقة واحدة	كل ثانية واحدة	من 23:14 إلى 23:15 - 35 نبضة في الدقيقة 23:16 - 23:17 - 37 نبضة في الدقيقة 23:17 - 23:18 - 40 نبضة في الدقيقة
عدد دفعات الكرسي المتحرك	دفعات	كل دقيقة واحدة	كل ثانية واحدة	من 23:14 إلى 23:15 - 5 دفعات 23:16 - 23:17 - 22 دفعة 23:17 - 23:18 - 8 دفعات
CyclingPedalingCadence	نَفَس/دقيقة	كل دقيقة واحدة	كل ثانية واحدة	‫23:14-23:15 - 65 دورة في الدقيقة 23:16 - 23:17 - 70 دورة في الدقيقة 23:17 - 23:18 - 68 دورة في الدقيقة
الطاقة	واط	كل دقيقة واحدة	كل ثانية واحدة	من 23:14 إلى 23:15 - 250 واط 23:16 - 23:17 - 255 واط 23:17 - 23:18 - 245 واط
السرعة	كلم/دقيقة	كل دقيقة واحدة	كل ثانية واحدة	من 23:14 إلى 23:15 - 0.3 كم/دقيقة 23:16 - 23:17 - 0.4 كلم/دقيقة 23:17 - 23:18 -0.4 كلم/دقيقة
المسافة	كلم/م	كل دقيقة واحدة	كل ثانية واحدة	من 23:14 إلى 23:15 - 0.008 كلم 23:16 - 23:16 - 0.021 كلم 23:17 - 23:18 - 0.012 كلم
ActiveCaloriesBurned	السُعرات الحرارية	كل دقيقة واحدة	كل ثانية واحدة	23:14-23:15 - 20 سعرة حرارية 23:16 - 23:17 - 20 سعرة حرارية 23:17 - 23:18 - 25 سعرة حرارية
TotalCaloriesBurned	السُعرات الحرارية	كل دقيقة واحدة	كل ثانية واحدة	من 23:14 إلى 23:15 - 36 سعرة حرارية 23:16 - 23:17 - 36 سعرة حرارية 23:17 - 23:18 - 41 سعرة حرارية
ElevationGained	د	كل دقيقة واحدة	كل ثانية واحدة	20:36 - 20:37 - 3.048m 20:39 - 20:40 - 3.048m 23:23 - 23:24 - 9.144m
ExerciseRoutes	lat/lng/alt	كل 3 إلى 5 ثوانٍ	كل ثانية واحدة
HeartRate	نبضة في الدقيقة	كل دقيقة واحدة	كل ثانية واحدة	‫23:14-23:15 - 150 نبضة في الدقيقة ‫23:16 - 23:17 -152 نبضة في الدقيقة 23:17 - 23:18 - 155 نبضة في الدقيقة

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

نوع البيانات	الوحدة	عيّنات البيانات المتوقّعة	مثال
مراحل النوم	المرحلة	فترة زمنية دقيقة لكل مرحلة من مراحل النوم	23:46 - 23:50 - استيقاظ 23:50 - 23:56 - نوم خفيف 23:56 - 00:16 - نوم عميق
RestingHeartRate	نبضة في الدقيقة	قيمة يومية واحدة (من المفترض أن تظهر في الصباح الباكر)	6:11 صباحًا - 60 نبضة في الدقيقة
OxygenSaturation	%	قيمة يومية واحدة (من المفترض أن تظهر في الصباح الباكر)	‫6:11 - ‏95.208%