إنّ العمل مع البيانات في 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.
معرّفات الكتابة التي يحدّدها العميل غير متاحة في 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 دورة الحياة للقراءة فقط.