أنواع بيانات Google Health API

يتضمّن الجدول التالي القائمة الكاملة لأنواع البيانات، مع عدّة أعمدة لمساعدتك في فهم طريقة عرض كل نوع في Google Health API، بالإضافة إلى النطاق الذي يتوفّر فيه كل نوع.

ملاحظة مهمة: يختلف تنسيق معرّفات أنواع البيانات عندما يتضمّن نوع البيانات أكثر من كلمة واحدة. في نقطة نهاية، يجب أن يكون اسم نوع البيانات بتنسيق kebab-case، مثل body-fat. في مَعلمة فلتر، يجب أن يكون اسم نوع البيانات بتنسيق snake case، مثل body_fat.

الجدول: أنواع بيانات Google Health API

نوع البيانات   dataType   filter المَعلمة	نوع السجلّ	العمليات المتاحة	النطاق	إتاحة استخدام ويب هوك	إتاحة استخدام أصفار حقيقية
السعرات الحرارية المحروقة   active-energy-burned   active_energy_burned	الفاصل الزمني	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
دقائق النشاط   active-minutes   active_minutes	الفاصل الزمني	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
دقائق قسم النشاط   active-zone-minutes   active_zone_minutes	الفاصل الزمني	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
مستوى النشاط   activity-level   activity_level	الفاصل الزمني	قائمة، تسوية	.activity_and_fitness.readonly .activity_and_fitness.writeonly
الارتفاع   altitude   altitude	الفاصل الزمني	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
الغلوكوز في الدم   blood-glucose   blood_glucose	عيّنة	list, get, reconcile, rollup, dailyRollup	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
نسبة الدهون في الجسم   body-fat   body_fat	عيّنة	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
السعرات الحرارية المحروقة في منطقة معدل ضربات القلب   calories-in-heart-rate-zone   calories_in_heart_rate_zone	الفاصل الزمني	rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
درجة حرارة الجسم الأساسية   core-body-temperature   core_body_temperature	عيّنة	list, get, reconcile, rollup, dailyRollup	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
تغيُّر معدّل نبضات القلب اليومي   daily-heart-rate-variability   daily_heart_rate_variability	يوميًا	قائمة، تسوية	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
مناطق معدّل نبضات القلب اليومية   daily-heart-rate-zones   daily_heart_rate_zones	يوميًا	قائمة، تسوية	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
تشبّع الأكسجين اليومي   daily-oxygen-saturation   daily_oxygen_saturation	يوميًا	قائمة، تسوية	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
معدّل التنفس اليومي   daily-respiratory-rate   daily_respiratory_rate	يوميًا	قائمة، تسوية	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
معدّل النبض أثناء الراحة اليومي   daily-resting-heart-rate   daily_resting_heart_rate	يوميًا	قائمة، تسوية	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
القيم المشتقة لدرجة حرارة الجسم أثناء النوم   daily-sleep-temperature-derivations   daily_sleep_temperature_derivations	يوميًا	قائمة، تسوية	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
الحد الأقصى اليومي لاستهلاك الأكسجين   daily-vo2-max   daily_vo2_max	يوميًا	قائمة، تسوية	.activity_and_fitness.readonly .activity_and_fitness.writeonly
المسافة   distance   distance	الفاصل الزمني	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
تخطيط القلب الكهربائي (ECG)   electrocardiogram   electrocardiogram	الجلسة	قائمة	.ecg.readonly
التمرين   exercise   exercise	الجلسة	list, get, reconcile, create, update, batchDelete	.activity_and_fitness.readonly .activity_and_fitness.writeonly
الطوابق   floors   floors	الفاصل الزمني	reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
الطعام   food   food	طعام	قائمة، الحصول على	.nutrition.readonly .nutrition.writeonly
وحدة قياس الطعام   food-measurement-unit   food_measurement_unit	طعام	قائمة، الحصول على	.nutrition.readonly .nutrition.writeonly
معدّل نبضات القلب   heart-rate   heart_rate	عيّنة	list, reconcile, rollup, dailyRollup	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
تغيُّر معدّل نبضات القلب   heart-rate-variability   heart_rate_variability	عيّنة	قائمة، تسوية	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
الارتفاع   height   height	عيّنة	list, get, reconcile, create, update, batchDelete	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
سجلّ الترطيب   hydration-log   hydration_log	الجلسة	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.nutrition.readonly .nutrition.writeonly
إشعار اضطراب نظم القلب   irregular-rhythm-notification   irregular_rhythm_notification	الجلسة	قائمة	.irn.readonly
فترة الدورة الشهرية   menstrual-period   menstrual_period	الفاصل الزمني	create, update, batchDelete	.reproductive_health.writeonly
الحالات المزاجية   moods   moods	عيّنة	create, update, batchDelete	.mindfulness.writeonly
سجلّ التغذية   nutrition-log   nutrition_log	عيّنة	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.nutrition.readonly .nutrition.writeonly
اختبار التبويض   ovulation-test   ovulation_test	عيّنة	create, update, batchDelete	.reproductive_health.writeonly
تشبّع الأكسجين   oxygen-saturation   oxygen_saturation	عيّنة	قائمة، تسوية	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
ملخّص معدّل التنفس أثناء النوم   respiratory-rate-sleep-summary   respiratory_rate_sleep_summary	عيّنة	قائمة، تسوية	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
الحد الأقصى لاستهلاك الأكسجين أثناء الجري   run-vo2-max   run_vo2_max	عيّنة	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
فترات الخمول   sedentary-period   sedentary_period	الفاصل الزمني	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
النوم   sleep   sleep	الجلسة	list, get, reconcile, create, update, batchDelete	.sleep.readonly .sleep.writeonly
الخطوات   steps   steps	الفاصل الزمني	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
بيانات طول مسافات السباحة   swim-lengths-data   swim_lengths_data	الفاصل الزمني	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
الأعراض   symptoms   symptoms	عيّنة	create, update, batchDelete	.logged_symptoms.writeonly
الوقت المستغرق في منطقة معدل ضربات القلب   time-in-heart-rate-zone   time_in_heart_rate_zone	الفاصل الزمني	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
إجمالي السعرات الحرارية   total-calories   total_calories	الفاصل الزمني	rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
السعة القصوى للأكسجين   vo2-max   vo2_max	عيّنة	قائمة، تسوية	.activity_and_fitness.readonly .activity_and_fitness.writeonly
الوزن   weight   weight	عيّنة	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly

قيود طلب البحث

عند طلب نقاط البيانات أو عمليات التجميع أو عمليات التجميع اليومية من واجهة برمجة التطبيقات، يجب مراعاة القيود التالية:

• متطلبات الفلتر: تتطلّب بعض أنواع البيانات المشتقة للقراءة فقط، مثل total-calories، فلترًا يحدّد وقت بدء الفترة (باستخدام الوقت الفعلي أو الوقت المدني).
• حدود نطاق طلب البحث: الحد الأقصى لنطاق طلب البحث في calories-in-heart-rate-zone وheart-rate وactive-minutes وtotal-calories هو 14 يومًا. الحد الأقصى لنطاق طلب البحث لجميع أنواع البيانات الأخرى هو 90 يومًا.

مدى توفّر البيانات

لا تتوفّر تعديلات على بيانات المستخدم إلا بعد مزامنة جهاز تتبُّع النشاط أو إدخال بيانات جديدة يدويًا في تطبيق Fitbit للأجهزة الجوّالة أو تطبيق الويب. ويمكن لجهاز Fitbit وتطبيق Fitbit للأجهزة الجوّالة إجراء المزامنة تلقائيًا كل 15 دقيقة عندما يكون تطبيق Fitbit مفتوحًا على الجهاز الجوّال ويكون الجهازان متصلَين بشبكة بيانات نشطة وضمن نطاق Bluetooth. إذا كان المستخدم يتتبّع النشاط باستخدام MobileTrack، تتم مزامنة البيانات كل ساعة طالما أنّ التطبيق مفتوح.

الاستعلام عن البيانات السابقة

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

ومع ذلك، تظل طلبات البحث عن البيانات السابقة خاضعة لحدود المعدّل العادية. لتقليل عدد طلبات البيانات من واجهة برمجة التطبيقات مقارنةً بهذه الحدود، تتيح Google Health API طلب البحث عن البيانات خلال نطاق زمني. يُرجى ملاحظة حدود التقسيم على صفحات والطلبات التالية:

• يعرض كل نقطة نهاية الحد الأقصى لحجم الصفحة وهو 10,000 نقطة بيانات لكل صفحة.
• تقتصر النطاقات الزمنية لطلبات البحث على ما بين 14 و90 يومًا لكل طلب.

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

لضمان الأداء الأمثل وتجنُّب أخطاء واجهة برمجة التطبيقات، اتّبِع الإرشادات التالية عند طلب بيانات سابقة:

مزامنة البيانات على مراحل (التحميل السريع مقابل التحميل البطيء)

• التحميل الأوّلي "السريع": يتم جلب وعرض بيانات آخر 7 إلى 14 يومًا فقط خلال تسلسل التحميل الأساسي. يضمن ذلك أن يرى المستخدمون البيانات على الفور بدون انتظار الاستعلامات التي تستغرق وقتًا طويلاً.
• التحميل "البارد" في الخلفية: تفويض عملية استرداد البيانات السابقة إلى قائمة انتظار غير متزامنة ذات أولوية أقل أو إلى عملية في الخلفية بعد عرض واجهة المستخدم الأساسية.

تقسيم طلب البحث المستند إلى الوقت

• لا تطلب نطاقات متعددة السنوات أو متعددة الأشهر في طلب واحد من واجهة برمجة التطبيقات. قسِّم طلبات البحث الكبيرة السابقة إلى فواصل زمنية أصغر ومتسلسلة (على سبيل المثال، أسبوع واحد لكل طلب).
• يمكنك معالجة الطلبات الفرعية هذه على شكل دفعات أو تسلسل بأمان للالتزام بحدود التزامن والحفاظ على مؤشرات التقدّم الثابتة في واجهة المستخدم.

الاستفادة من عمليات التجميع المُسبقة

إعادة هيكلة لوحات البيانات الخاصة بالنظرة العامة ومخططات المؤشرات لاستخدام نقاط نهاية مجمّعة مسبقًا وملخّصة (مثل DailyRollUpDataPoints)، ما سيؤدي إلى تقليل الحمل الزائد للحوسبة بشكل كبير في الخلفية ووقت نقل البيانات إلى العميل عبر الشبكة

معالجة الأخطاء بشكل مرن (إعادة المحاولة بذكاء)

• يجب تنفيذ معالجة صارمة للتراجع الأسي عند مواجهة حدود المعدّل (429 Too Many Requests) ومهلات بوابة الخادم (504 Gateway Timeout)، وعدم إعادة محاولة إرسال الحِزم الكبيرة التي تعذّر إرسالها على الفور. تؤدي عمليات إعادة المحاولة الفورية إلى زيادة الازدحام في الخلفية وتفاقم تدهور أداء النظام.
• إذا انتهت مهلة طلب بحث بشكل متكرّر، يمكنك تلقائيًا الرجوع إلى فترة زمنية أصغر (على سبيل المثال، تقليل مدة أسبوع إلى 3 أيام).

تحذير: قد يؤدي عدم اتّباع هذه الإرشادات إلى حدوث سلوك غير متوقّع وأخطاء.

إمكانية وصول الجهات الخارجية

لا يمكن لأجهزة Fitbit التواصل مباشرةً مع التطبيقات أو الخدمات التابعة لجهات خارجية. تم تصميم هذه الأجهزة للتواصل والمزامنة حصريًا مع تطبيق Fitbit للأجهزة الجوّالة.

تتم مزامنة البيانات تلقائيًا على مدار اليوم عندما يكون تطبيق Fitbit مفتوحًا، أو كل 15 دقيقة إذا كان البلوتوث نشطًا وكان التطبيق يعمل في الخلفية. بعد اكتمال عملية المزامنة هذه، تصبح البيانات متاحة للخدمات التابعة لجهات خارجية من خلال Google Health API.

معايير المسافة

يتم قياس مسافات التمارين، مثل elevationGainMillimeters، بالملليمترات كوحدة قياس معيارية للأسباب التالية:

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

اختلاف طول النهار

تعطي Health API الأولوية للوقت الذي يحدّده المستخدم من أجل احتساب مدد الأيام المتغيرة الناتجة عن التوقيت الصيفي أو السفر. يتم تخزين كل نقطة بيانات مع طابع زمني فعلي بالتوقيت العالمي المنسَّق (UTC) وإزاحة التوقيت العالمي المنسَّق النشطة في وقت وقوع الحدث. يتيح ذلك للنظام ما يلي:

• ربط الحدث بلحظة زمنية محددة.
• تصحيح الوقت حسب السياق المحلي للمستخدم من أجل التجميع

نظام التوقيت الصيفي

عندما يتم تطبيق التوقيت الصيفي، يؤدي "الرجوع إلى التوقيت العادي" إلى يوم مدني مدته 25 ساعة، وسيتضمّن التجميع الخاص بهذا التاريخ بيانات لمدة 25 ساعة. يؤدي "التقديم" إلى يوم مدني مدته 23 ساعة حيث يتم إعادة ضبط الوقت إلى التوقيت العادي.

سفر

ويمكن أن يؤدي السفر عبر المناطق الزمنية إلى اختلافات أكبر في المدة الفعلية ليوم مدني واحد.

استخدِم نقطة النهاية dailyRollUp لتسوية اختلافات المناطق الزمنية. ويتم تلقائيًا ربط البيانات بيوم التقويم الذي تم تسجيلها فيه وفقًا للتوقيت المحلي للمستخدم، ما يؤدي إلى "تجميع" اليوم معًا على الرغم من تغيُّر المنطقة الزمنية.