إنّ العمل مع البيانات في 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.
لا تتيح Health API حاليًا استخدام المعرّفات التي يحدّدها العميل لعمليات الكتابة.
يمكن تقديم هذه المعرّفات في POST، ولكن يتم تجاهلها. يتم توفير تفاصيل حول هذا الخيار هنا لأغراض إعلامية.
- المعرّفات التي ينشئها الخادم (الخيار التلقائي): يرسل العميل البيانات بدون معرّف، وتنشئ الخلفية في Google Health API معرّفًا فريدًا للنظام وتعرضه.
- المعرّفات المخصّصة التي يحدّدها العميل (وفقًا لـ AIP-133، غير متوافقة بعد): ينشئ تطبيق العميل معرّفًا فريدًا (على سبيل المثال، معرّف UUID أو مفتاح أساسي لقاعدة بيانات محلية) ويوفّره في مسار المورد عند الإنشاء.
يقارن الجدول التالي بين استراتيجيتَي تحديد الهوية لمساعدتك في اختيار النهج المناسب لعملية الدمج:
| الميزة | أرقام التعريف التي ينشئها الخادم | المعرّفات المخصّصة التي يحدّدها العميل |
|---|---|---|
| إنشاء المعرّفات | ينشئ الخادم معرّف نظام عشوائيًا أثناء تنفيذ POST. |
ينشئ العميل معرّفًا ثابتًا على الجهاز (UUID v4 / مفتاح أساسي داخلي) قبل الكتابة. |
| مسار المرجع | .../dataPoints/{server_id} (يتم عرضها في الردّ) |
.../dataPoints/{custom_id} |
| خطوة محلية بعد الكتابة | هذا العنصر مطلوب. Must store returned server_id in local
DB to enable future updates/deletions. |
ما مِن صورة فائزة: يملك التطبيق المعرّف حاليًا. |
| جدول ربط أرقام التعريف | هذا العنصر مطلوب. يجب أن يحافظ العميل على عملية ربط ثنائية الاتجاه
(local_id ↔ server_id). |
غير مطلوب يستخدم العميل مفتاحه الأساسي مباشرةً. |
| سلوك إعادة المحاولة (شبكة ضعيفة) | خطر تكرار المحتوى: تؤدي إعادة محاولة تنفيذ POST انتهت مهلته إلى إنشاء سجلّ مكرّر بمعرّف خادم جديد. |
آمنة وغير قابلة للتغيير: تؤدي إعادة محاولة تنفيذ POST باستخدام custom_id نفسه إلى منع إنشاء نسخة مكرّرة (يتم عرض 409
ALREADY_EXISTS). |
| دعم المزامنة بلا إنترنت | محدودة: يجب الانتظار حتى استجابة الخادم للحصول على معرّفات الموارد الرسمية قبل الإشارة إليها. | كاملة يمكن إنشاء الكيانات وتعديلها بلا إنترنت باستخدام معرّفات ثابتة، ثم مزامنتها بسلاسة عند إعادة الاتصال. |
| قيود التنسيق | تتم معالجتها بالكامل من خلال الخادم. | يجب أن يتّبع ^[a-z0-9-]{4,63}$ (من 4 إلى 63 حرفًا أبجديًا رقميًا صغيرًا وواصلات). |
| حالات الاستخدام |
اختَر المعرّفات التي ينشئها الخادم في الحالات التالية:
|
اختَر المعرّفات المخصّصة في الحالات التالية:
|
دورة حياة المزامنة للقراءة فقط
على التطبيق الذي يهدف إلى القراءة فقط من Google Health API نسخ البيانات إلى مخزن بيانات المطوّر ومعالجة جزء التسوية من دورة الحياة.
تنطبق هنا المهام نفسها التي تم تناولها في قسم القراءة.
يوضّح الشكل 2 دورة حياة الإذن بالقراءة فقط.
الطوابع الزمنية للفواصل الزمنية ومزامنة الأجهزة المتصلة
تمثّل بيانات الفترات الزمنية القياسات التي يتم جمعها على مدار فترة زمنية، مثل الخطوات أو معدّل نبضات القلب أو جلسات التمارين الرياضية. في المقابل، تشمل القياسات في وقت محدّد الإدخالات اليدوية، مثل سجلّ الطعام أو قراءة الميزان. تنشأ بيانات التمارين المتناوبة عادةً من مزامنة الأجهزة المتصلة، مثل الساعات الذكية وأدوات تتبّع اللياقة البدنية.
تُقدّم الطوابع الزمنية للفترات (startTime وendTime في حمولات REST JSON، أو
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 بعد ذلك تعديلاً لسجلّ متزامن من التطبيق الخارجي الأصلي، يتم نشر هذه التغييرات واستبدال السجلّ الحالي.