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

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

الخصائص	الوصف
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)
        }

        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 تلقائيًا عند حدوث تغييرات، ما يمنع حدوث أي حالات غير متوقعة لاستبدال البيانات. مع ذلك، عليك توفيره يدويًا بقيمة أعلى.

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

يجب أن تكتب التطبيقات البيانات الخاصة بالمصدر في 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 دقيقة على الأقل خلال اليوم.

نوع البيانات	الوحدة	المتوقعة	مثال
الخطوات	الخطوات	كل دقيقة واحدة	من 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 مساءً
عدد دفعات الكرسي المتحرك	يدفع	كل دقيقة واحدة	23:14 - 23:15 - 5 دفعات 23:16 - 23:17 - 22 دفعة 23:17 - 23:18 - 8 دفعات
العدد النشط من CaloriesBurned	السُعرات الحرارية	كل ١٥ دقيقة	من 23:15 إلى 23:30 - وحدتان حراريتان من 23:30 إلى 23:45 - 25 سعرًا حراريًا من 23:45 إلى 00:00 - 5 سعرات حرارية
إجمالي السعرات الحرارية المحروقة	سعر حراري	كل ١٥ دقيقة	من 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 كم
الارتفاع المكتسب	د	كل دقيقة واحدة	من 20:36 إلى 20:37 - 3.048 دقيقة من 20:39 إلى 20:40 - 3.048 دقيقة من 23:23 إلى 23:24 - 9.144 دقيقة
عدد الطوابق التي تم صعودها	طوابق	كل دقيقة واحدة	من 23:14 إلى 23:15 - 5 طوابق من 23:16 إلى 23:16 - 22 طابقًا من 23:17 إلى 23:18 - 8 طوابق
معدل ضربات القلب	نبضة في الدقيقة	كل دقيقة واحدة	6:11 صباحًا - 55 نبضة في الدقيقة
معدل ضربات القلب Rmssd	ميللي ثانية	كل دقيقة واحدة	6:11 صباحًا - 23 ملي ثانية
معدّل التنفس	نفَس/دقيقة	كل دقيقة واحدة	23:14 - 23:15 - 60 نفَسًا/دقيقة 23:16 - 23:16 - 62 نفَسًا/دقيقة 23:17 - 23:18 - 64 نفَسًا/دقيقة
تشبّع الأكسجين في الدم	%	كل ساعة واحدة	6:11 - 95.208%

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

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

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

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

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

نوع البيانات	الوحدة	المتوقعة	مع أطيب التحيات	مثال
الخطوات	الخطوات	كل دقيقة واحدة	كل ثانية واحدة	من 23:14 إلى 23:15 - 5 خطوات من 23:16 إلى 23:17 - 22 خطوة من 23:17 إلى 23:18 - 8 خطوات
وتيرة الخطوات	خطوة/دقيقة	كل دقيقة واحدة	كل ثانية واحدة	من 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 دفعات
سلسلة نقاط التواصل في ركوب الدرّاجة	نَفَس في الدقيقة	كل دقيقة واحدة	كل ثانية واحدة	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 كم
العدد النشط من CaloriesBurned	سعر حراري	كل دقيقة واحدة	كل ثانية واحدة	23:14-23:15 - 20 سعر حراري 23:16 - 23:17 - 20 سعر حراري 23:17 - 23:18 - 25 سعر حراري
إجمالي السعرات الحرارية المحروقة	سعر حراري	كل دقيقة واحدة	كل ثانية واحدة	23:14-23:15 - 36 سعر حراري 23:16 - 23:17 - 36 سعر حراري 23:17 - 23:18 - 41 سعر حراري
الارتفاع المكتسب	د	كل دقيقة واحدة	كل ثانية واحدة	من 20:36 إلى 20:37 - 3.048 دقيقة من 20:39 إلى 20:40 - 3.048 دقيقة من 23:23 إلى 23:24 - 9.144 دقيقة
مسارات التمارين الرياضية	خطوط الطول والعرض/النص البديل	كل 3 إلى 5 ثوانٍ	كل ثانية واحدة
معدل ضربات القلب	نبضة في الدقيقة	كل دقيقة واحدة	كل ثانية واحدة	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 - نوم عميق
معدّل نبضات القلب أثناء الراحة	نبضة في الدقيقة	قيمة يومية واحدة (أول شيء متوقع في الصباح)	6:11 صباحًا - 60 نبضة في الدقيقة
تشبّع الأكسجين في الدم	%	قيمة يومية واحدة (أول شيء متوقع في الصباح)	6:11 - 95.208%