إنّ العمل مع البيانات في Google Health API هو في الأساس دورة مزامنة البيانات بين مستودع بيانات Google Health API على السحابة الإلكترونية ومستودع بيانات تطبيقك أو الخلفية. ومع ذلك، يمكن أن تتخذ هذه الدورة أشكالاً مختلفة حسب مجموعة متنوعة من العوامل:
- هل تكتب البيانات في Google Health API؟ هل تريد القراءة فقط؟ أم كلاهما؟
- هل مخزن البيانات محلي على التطبيق أو الجهاز؟ أو في السحابة الإلكترونية الخاصة بك؟
- هل تحتاج إلى مزامنة بيانات Google Health API بين تطبيق المستخدم وجهاز قابل للارتداء؟ كم مرة تتم مزامنة الأجهزة؟
- ما هي أنواع البيانات التي تتعامل معها؟ هل تقصد الأعداد الأساسية؟ وحدات القياس؟ سلاسل بمعدلات مختلفة لاختيار العيّنات؟
- هل تخطّط لقراءة البيانات عندما يكون تطبيقك يعمل في الخلفية؟
- هل تخطّط للعمل مع البيانات السابقة التي تم تسجيلها قبل أن يحصل تطبيقك على أذونات المستخدم؟
لفهم كيفية عمل كل ذلك معًا، اطّلِع على دورة مزامنة واجهة برمجة التطبيقات Google Health API. يتوفّر إصداران من دورة الحياة هذه: الإصدار العادي (القراءة والكتابة) والإصدار المتاح للقراءة فقط.
دورة حياة المزامنة العادية
يعني الدمج مع Google Health API نسخ البيانات إلى تطبيق أو مستودع بيانات خلفي. لتسهيل الاستخدام في هذه المستندات، سنشير إلى مخزن البيانات هذا باسم مخزن بيانات المطوّرين.
يمكن أن يحلّ مصطلح "نسخ" هنا محل أي نشاط منفصل، مثل القراءة من Google Health API (النسخ إلى مخزن بيانات المطوّر) أو الكتابة إلى Google Health API (النسخ إلى Google Health API). ويُطلق على تنفيذ هذه الإجراءات بشكل متكرّر بترتيب محدّد اسم دورة حياة المزامنة.
يوضّح الشكل 1 دورة حياة المزامنة العادية التي تتضمّن عمليات القراءة والكتابة، بغض النظر عن أي من العوامل المذكورة سابقًا.
كتابة
- إعداد بيانات جديدة للكتابة: يمكنك نقل البيانات من جهاز أو تطبيق خارجيين وتنسيق نقاط البيانات في تمثيلات JSON متوافقة مع أنواع بيانات Google Health API. يُرجى العلم أنّ المعرّفات المخصّصة التي يحدّدها العميل للكتابة غير متاحة في Health API في الوقت الحالي. يمكن تقديم هذه المعرّفات في
POST، ولكن سيتم تجاهلها. - إدراج السجلات أو تعديلها: إرسال نقاط البيانات إلى Google Health API باستخدام نقاط نهاية REST استخدِم
POSTلإنشاء السجلات، وPATCHلإدراج السجلات الحالية وتعديلها. ستكون أرقام التعريف المطلوبة لعمليةPATCHقد تم الحصول عليها من عمليةPOSTسابقة (الخطوة التالية في دورة سابقة). - معالجة معرّفات الموارد التي تم إرجاعها: عند استخدام المعرّفات التي تم إنشاؤها على الخادم، استخرِج معرّف المورد
nameأو المعرّف الذي تم إرجاعه من الخادم واحتفظ به في مخزن بيانات المطوّرين لتفعيل التعديلات (PATCH) أو عمليات الحذف (DELETE) المستقبلية. اطّلِع على استراتيجيات التعريف للحصول على مزيد من المعلومات حول النوعَين.
قراءة
- قراءة السجلات: يمكنك استرداد بيانات جديدة وتغييرات على البيانات الحالية من Google Health API باستخدام نقاط نهاية REST (
GETمع مَعلمات طلب البحثfilterوالتصفّح على عدّة صفحاتpageToken، أو نقاط نهاية التجميع مثلrollUpوdailyRollUp)، أو تلقّي إشعارات في الوقت الفعلي باستخدام اشتراكات Webhook (projects.subscribers). يشير الإشعار فقط إلى توفّر بيانات جديدة، وليس إلى نوع البيانات الفعلية. - تسوية مستودع بيانات المطوّر: سوِّ البيانات الجديدة والمعدَّلة مع مستودع بيانات المطوّر. يمكن أن تنتج الأجهزة المرتبطة فواصل زمنية متداخلة أثناء عمليات المزامنة. للتعرّف على كيفية حلّ Google Health API لهذه المشاكل، يمكنك الاطّلاع على الطوابع الزمنية للفاصل الزمني ومزامنة الأجهزة المرتبطة.
وتتكرّر هذه الدورة بعد ذلك على فترات مناسبة وفقًا للاحتياجات المحدّدة للأجهزة أو التطبيقات الخارجية. وهذا هو الترتيب الذي ننصح به بشكل عام لمزامنة البيانات بين مستودع البيانات الخاص بك وGoogle Health API.
استراتيجيات تحديد المشاكل
إذا كنت تنوي كتابة بيانات إلى Google Health API، عليك اختيار استراتيجية تعريف الموارد عند إنشاء نقاط البيانات (وحدة البيانات الأساسية) قبل إنشاء عملية الدمج مع واجهات Google Health API.
معرّفات الكتابة التي يحدّدها العميل غير متاحة في Health API في الوقت الحالي.
يمكن تقديم معرّفات من هذا النوع في POST، ولكن سيتم تجاهلها. يتم تقديم تفاصيل حول هذا الخيار هنا لأغراض إعلامية.
- المعرّفات التي ينشئها الخادم (الخيار التلقائي): يرسل العميل البيانات بدون معرّف، وينشئ الخلفية البرمجية لواجهة Google Health API معرّف نظام فريدًا وتعرضه.
- المعرّفات المخصّصة التي يحدّدها العميل (وفقًا AIP-133، غير متاحة بعد): ينشئ تطبيق العميل معرّفًا فريدًا (على سبيل المثال، معرّف فريد عالميًا أو مفتاح أساسي لقاعدة بيانات محلية) ويقدّمه في مسار المورد عند الإنشاء.
يقارن الجدول التالي بين استراتيجيتَي التعريف لمساعدتك في اختيار النهج المناسب لعملية الدمج:
| الميزة | أرقام التعريف التي ينشئها الخادم | المعرّفات المخصّصة التي يحدّدها العميل |
|---|---|---|
| إنشاء المعرّف | ينشئ الخادم معرّف نظام عشوائيًا أثناء POST
التنفيذ. |
ينشئ العميل معرّفًا ثابتًا محليًا (UUID الإصدار 4 / المفتاح الأساسي الداخلي) قبل الكتابة. |
| مسار المرجع | .../dataPoints/{server_id} (تم إرجاعها في الردّ) |
.../dataPoints/{custom_id} |
| خطوة "الكتابة المحلية" بعد النشر | هذا العنصر مطلوب. يجب تخزين قيمة server_id التي تم إرجاعها في قاعدة البيانات المحلية لتفعيل عمليات التعديل/الحذف المستقبلية. |
لا شيء. يمتلك التطبيق المعرّف حاليًا. |
| جدول ربط المعرّفات | هذا العنصر مطلوب. يجب أن يحتفظ العميل بعملية ربط ثنائية الاتجاه
(local_id ↔ server_id). |
غير مطلوب. يستخدم العميل مفتاحه الأساسي مباشرةً. |
| سلوك إعادة المحاولة (شبكة ضعيفة) | خطر تكرار البيانات: تؤدي إعادة محاولة POST
انتهت مهلتها إلى إنشاء سجل مكرّر بمعرّف خادم جديد. |
آمنة وغير متكررة: إعادة محاولة POST باستخدام
custom_id يمنع إنشاء نسخة مكررة (يعرض 409
ALREADY_EXISTS). |
| إتاحة المزامنة بلا إنترنت | محدودة يجب انتظار استجابة الخادم للحصول على معرّفات الموارد الرسمية قبل الإشارة إليها. | كاملة: يمكن إنشاء الكيانات وتعديلها بلا إنترنت باستخدام معرّفات ثابتة، ثم تتم مزامنتها بسلاسة عند إعادة الاتصال بالإنترنت. |
| قيود التنسيق | يتم التعامل معها بالكامل من خلال الخادم. | يجب أن يتّبع التنسيق ^[a-z0-9-]{4,63}$ (من 4 إلى 63 حرفًا أبجديًا رقميًا صغيرًا وواصلات). |
| حالات الاختيار |
اختَر المعرّفات التي ينشئها الخادم في الحالات التالية:
|
اختَر المعرّفات المخصّصة في الحالات التالية:
|
دورة حياة المزامنة للقراءة فقط
يجب أن ينسخ التطبيق الذي يريد القراءة فقط من Google Health API البيانات إلى مخزن بيانات المطوّر وأن يتعامل مع جزء التسوية من دورة الحياة.
تنطبق هنا المهام نفسها الواردة في قسم القراءة.
يوضّح الشكل 2 دورة الحياة للقراءة فقط.
الطوابع الزمنية الفاصلة ومزامنة الأجهزة المتصلة
تمثّل بيانات الفواصل الزمنية القياسات التي يتم جمعها على مدار فترة زمنية، مثل الخطوات أو معدّل نبضات القلب أو جلسات التمارين الرياضية. في المقابل، تشمل القياسات في نقطة زمنية معيّنة إدخالات يدوية، مثل سجلّ الطعام أو قراءة الميزان. تنشأ بيانات الفترات الزمنية عادةً من مزامنة الأجهزة المتصلة، مثل الساعات الذكية وأجهزة تتبُّع اللياقة البدنية.
تتضمّن الطوابع الزمنية للفاصل الزمني (startTime وendTime في حمولات JSON الخاصة بـ REST، أو start_time وend_time في عبارات الفلتر وgRPC) سلوكيات فريدة عند التعامل مع بيانات الفاصل الزمني. يوضّح هذا القسم سبب حدوث فترات متداخلة ويقارن بين نقطتَي النهاية list وreconcile.
الفواصل الزمنية المتداخلة من الأجهزة المتصلة
تجمع الأجهزة المتصلة، مثل أجهزة تتبُّع Fitbit وساعة Google Pixel Watch، باستمرار قراءات بيومترية عالية التردد أثناء ارتدائها. بعد أن يزامن الجهاز نقاط البيانات مع Google Health، لن يعدّل السجلات الحالية بأثر رجعي. وتبقى الطوابع الزمنية للفواصل الزمنية المخزّنة بدون تغيير.
ومع ذلك، قبل دورات المزامنة اللاحقة، غالبًا ما تعيد الخوارزميات على الجهاز فقط تفسير بيانات القياس عن بُعد الأولية من المستشعر. يعيد الجهاز تصنيف القراءات التي تم جمعها على مدار الساعات السابقة. وعندما تتم مزامنة الجهاز مرة أخرى، يتم تحميل نقاط البيانات الجديدة. ويمكن أن تتداخل حدود البداية والنهاية مع الفواصل الزمنية المخزّنة سابقًا.
على سبيل المثال، لنفترض أنّ مستخدمًا يرتدي ساعة ذكية تتم مزامنة بيانات نشاط المستخدم الخاصة به في دفعتَين متتاليتَين:
- أثناء المزامنة الأولى، يحمّل الجهاز نقطة بيانات تغطي الفترة من
10:00:00Zإلى10:14:59Z. - بعد إعادة الحساب على الجهاز فقط، تتم مزامنة ثانية لتحميل نقطة بيانات أخرى تغطي الفترة من
10:14:00Zإلى10:28:59Z.
يتم تخزين كلا السجلّين بشكل مستقل في الخلفية في Google Health. نتيجةً لذلك، تغطّي نقطتا البيانات الفاصل الزمني من 10:14:00Z إلى 10:14:59Z.
ينتج عن ذلك تداخل لمدة 59 ثانية عند طلب البحث عن السجلات الأولية.
مقارنة القائمة وتسوية نقاط النهاية
يمكنك التعامل مع هذه الفواصل الزمنية المتداخلة باستخدام نقطة النهاية list أو reconcile. اختَر نقطة النهاية التي تتوافق مع متطلبات تطبيقك:
| الميزة | نقطة نهاية list |
نقطة نهاية reconcile |
|---|---|---|
| طريقة HTTP | GET https://health.googleapis.com/v4/users/me/dataTypes/dataType/dataPoints |
GET https://health.googleapis.com/v4/users/me/dataTypes/dataType/dataPoints:reconcile |
| سلوك التداخل | تعرِض هذه السمة جميع السجلات المخزَّنة كما تم تحميلها بدون إزالة التكرار. عندما تتداخل الفواصل الزمنية، يتم عرض كلا السجلّين. | يحلّ التعارضات ويزيل البيانات المكرّرة من السجلات المتداخلة على الأجهزة وجلسات المزامنة في بث واحد متواصل. |
| المزايا | تقدّم هذه السمة سجلّ تدقيق كاملاً وغير معدَّل لكل سجلّ تم تحميله من كل جهاز ودُفعة مزامنة. | تبسّط هذه السمة عرض المخطط الزمني واحتساب المدة من خلال التعامل تلقائيًا مع الفواصل الزمنية المتداخلة وحالات التعارض بين الأجهزة المتعددة. |
| العيوب | يتحمّل تطبيقك مسؤولية رصد الفترات المتداخلة وحلّها، وحالات التعارض بين الأجهزة المتعدّدة، وفترات عدم ارتداء الساعة. | يتم حذف السجلات المتداخلة التابعة من الرد، وبالتالي لا يمكن تدقيق دفعات مزامنة الأجهزة الفردية بشكل منفصل. |
تم تصميم نقطة النهاية reconcile لرسم واجهات المستخدمين وعرض المخططات الزمنية للنشاط واحتساب إجمالي المدد غير المتداخلة. ويحلّ
الفواصل الزمنية المتعارضة من جلسات المزامنة التي تم إعادة تقسيمها إلى مجموعات. ويوفّق أيضًا بين الأنشطة التي يتم تسجيلها في الوقت نفسه على أجهزة متعددة، مثل ساعة وهاتف.
تعمل التسوية على حلّ الجلسات المتعارضة من خلال اختيار السجلّ الموثوق به بدلاً من إنشاء اتحاد زمني اصطناعي. على سبيل المثال، لا يتم دمج 11:00:00Z مع 11:30:00Z و11:20:00Z مع 11:50:00Z في 11:00:00Z مع 11:50:00Z. يعرض الردّ الذي تمّت تسويته نقطة البيانات الفائزة مع الفاصل الزمني الأصلي الذي تمّ تسجيله. ويحافظ ذلك على سلامة بيانات القياس عن بُعد والمقاييس التي تم قياسها خلال هذه الجلسة.
يوضّح الشكل 3 كيف تعالج نقطة النهاية reconcile الجلسات المتداخلة.
يختار هذا الإعداد السجل الموثوق به بدلاً من إنشاء اتحاد زمني اصطناعي.
يقدّم دليل نقاط النهاية أمثلة كاملة على الطلبات والردود. لمقارنة سجلّات list الأولية مع ناتج reconcile، اطّلِع على الحصول على عرض متوافق لبيانات الفترات.
تم تصميم نقطة النهاية list لتشخيص الأجهزة وعمليات تدقيق البيانات. استخدِم هذا الخيار عندما يتطلّب سير عملك فحص السجلات غير المعدَّلة كما تم تحميلها من كل جهاز. عند إجراء طلب بحث باستخدام list، يجب أن تعالج منطق العميل أي تداخلات في الفواصل الزمنية في البيانات الأولية.
قابلية تعديل الطابع الزمني وتعديلات المالك
لا تعدّل الأجهزة المتصلة بشكل رجعي الطوابع الزمنية المخزّنة خلال دورات المزامنة العادية. ومع ذلك، فإنّ الطوابع الزمنية للفاصل الزمني (startTime وendTime في حمولات REST JSON، أو start_time وend_time في عبارات الفلتر وgRPC) ليست غير قابلة للتغيير على مستوى جميع مصادر البيانات. يمكن للمالك الأساسي أو من أنشأ السجلّ فقط تعديل حقوله. لا يمكن للتطبيقات الأخرى تعديل نقاط البيانات التي لم تنشئها.
يمكن لتطبيق المالك استخدام نقطة النهاية patch لتعديل السجلات الحالية. ويشمل ذلك تعديل الطوابع الزمنية الخاصة بالبدء أو الانتهاء،
ما يؤدي إلى تعديل حقلَي التوقيت العالمي المتفق عليه (startTime وendTime) والتوقيت المدني
(civilStartTime وcivilEndTime) على الخادم. للاطّلاع على مثال حول تعديل الطوابع الزمنية باستخدام PATCH، راجِع تعديل الطوابع الزمنية للفاصل الزمني للبيانات الحالية في دليل نقاط النهاية.
وبالمثل، فإنّ نقاط البيانات التي تتم مزامنتها من منصات خارجية، مثل Health Connect أو تطبيقات الشركاء، تستفيد من التعديلات التي يتم إجراؤها على المصدر الأصلي. إذا تلقّى تطبيق Health Connect لاحقًا تعديلاً لسجلّ تمت مزامنته من تطبيق تابع لجهة خارجية، سيتم نشر هذه التغييرات واستبدال السجلّ الحالي.