مدیریت داده‌ها در 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 به‌معنای کپی کردن داده‌ها در برنامه یا پایگاه داده‌های پسین است. برای سهولت استفاده در این سند، این پایگاه داده را پایگاه داده توسعه‌دهنده می‌نامیم.

«کپی کردن» در اینجا می‌تواند جایگزین هر فعالیت مجزایی شود، مثلاً خواندن از Google Health API (کپی کردن در پایگاه داده توسعه‌دهنده) یا نوشتن در Google Health API (کپی کردن در Google Health API). انجام مکرر این کنش‌ها به ترتیبی خاص، چرخه حیات همگام‌سازی است.

شکل ۱ چرخه حیات همگام‌سازی استاندارد را نشان می‌دهد که شامل عملیات خواندن و نوشتن است، بدون درنظر گرفتن هیچ‌یک از عواملی که قبلاً ذکر شد.

نوشتن

  1. آماده‌سازی داده‌های جدید برای نوشتن — انتقال داده‌ها از دستگاه یا برنامه خارجی و قالب‌بندی نقاط داده به نمایش‌های JSON سازگار با انواع داده‌های Google Health API. توجه داشته باشید که درحال‌حاضر شناسه‌های سفارشی اختصاص‌داده‌شده به کارخواه برای نوشتن در Health API پشتیبانی نمی‌شود. چنین شناسه‌هایی ممکن است در POST ارائه شوند، اما نادیده گرفته می‌شوند.
  2. سوابق Upsert — ارسال نقاط داده به Google Health API بااستفاده از نقاط پایانی REST. از POST برای ایجاد سوابق و از PATCH برای درج و به‌روزرسانی سوابق موجود استفاده کنید. شناسه‌های موردنیاز برای عملیات PATCH از عملیات POST قبلی (مرحله بعدی در چرخه قبلی) به‌دست می‌آید.
  3. پردازش شناسه‌های منبع برگردانده‌شده — هنگام استفاده از شناسه‌های تولیدشده توسط سرور، منبع name یا شناسه برگردانده‌شده توسط سرور را استخراج و در پایگاه داده توسعه‌دهنده خود ذخیره کنید تا به‌روزرسانی‌های آینده (PATCH) یا حذف‌ها (DELETE) امکان‌پذیر شود. برای اطلاعات بیشتر درباره این دو نوع، به استراتژی‌های شناسایی مراجعه کنید.

خواندن

  1. خواندن سوابق — واکشی داده‌های جدید و تغییرات داده‌های موجود در Google Health API بااستفاده از نقاط پایانی REST (GET با پارامترهای پُرسمان filter و صفحه‌بندی pageToken، یا نقاط پایانی تجمیع مانند rollUp و dailyRollUp)، یا دریافت اعلان‌ها بااستفاده از «اشتراک‌های Webhook» (projects.subscribers). اعلان فقط نشان می‌دهد که داده‌های جدید دردسترس است، نه اینکه داده‌های واقعی چیست.
  2. تطبیق دادن پایگاه داده توسعه‌دهنده — داده‌های جدید و به‌روزشده را با پایگاه داده توسعه‌دهنده خود تطبیق دهید. دستگاه‌های متصل‌شده می‌توانند درطول همگام‌سازی‌ها، فاصله‌های زمانی هم‌پوشان ایجاد کنند. برای آشنایی با نحوه حل این موارد توسط Google Health API، مُهرهای زمان فاصله و همگام‌سازی دستگاه متصل را ببینید.

سپس این چرخه در فواصل زمانی مناسب براساس نیازهای خاص دستگاه‌ها یا برنامه‌های خارجی تکرار می‌شود. این معمولاً ترتیبی است که برای همگام‌سازی داده‌ها بین پایگاه داده خودتان و Google Health API توصیه می‌کنیم.

راهبردهای شناسایی

اگر قصد دارید داده‌ها را در Google Health API بنویسید، قبل‌از ایجاد ادغام با Google Health API، باید هنگام ایجاد نقاط داده (واحد اصلی داده) یک استراتژی شناسایی منبع انتخاب کنید.

درحال‌حاضر شناسه‌های اختصاص‌داده‌شده توسط کارخواه برای نوشتن در Health API پشتیبانی نمی‌شود. این شناسه‌ها ممکن است در POST ارائه شوند، اما نادیده گرفته می‌شوند. جزئیات مربوط به این گزینه در اینجا برای اهداف اطلاعاتی ارائه شده است.

  1. شناسه‌های تولیدشده توسط سرور (گزینه پیش‌فرض): مشتری داده‌ها را بدون شناسه ارسال می‌کند و پسای Google Health API شناسه سیستم منحصربه‌فردی را تولید و برمی‌گرداند.
  2. شناسه‌های سفارشی اختصاص‌داده‌شده به کارخواه (طبق AIP-133، هنوز پشتیبانی نمی‌شود): برنامه کارخواه یک شناسه یکتا (برای مثال، UUID یا کلید اصلی پایگاه داده محلی) تولید می‌کند و آن را هنگام ایجاد در مسیر منبع ارائه می‌دهد.

جدول زیر هر دو استراتژی شناسایی را مقایسه می‌کند تا به شما کمک کند رویکرد مناسب را برای ادغام خود انتخاب کنید:

ویژگی شناسه‌های تولیدشده توسط سرور شناسه‌های سفارشی اختصاص‌داده‌شده به کارخواه
تولید شناسه سرور درطول اجرای POST شناسه سیستم تصادفی تولید می‌کند. کارخواه شناسه پایداری را به‌صورت محلی (UUID v4 / PK داخلی) پیش‌از نوشتن تولید می‌کند.
مسیر منبع .../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 را برمی‌گرداند).
پشتیبانی همگام‌سازی آفلاین محدود. Must wait for server response to obtain official resource IDs before referencing them. پر است. نهادها را می‌توان به‌صورت آفلاین با شناسه‌های پایدار ایجاد و تغییر داد، سپس هنگام اتصال مجدد به‌طور یکپارچه همگام‌سازی کرد.
محدودیت‌های قالب کاملاً توسط سرور مدیریت می‌شود. باید از ^[a-z0-9-]{4,63}$ (۴ تا ۶۳ نویسه الفباعددی کوچک و خط تیره) پیروی کند.
زمان انتخاب

شناسه‌های تولیدشده توسط سرور را انتخاب کنید اگر:

  • برنامه شما فقط نوشتنی / فقط افزودنی است (مثلاً ارسال دورسنجی یا تعداد قدم‌ها که هرگز به‌روزرسانی یا بعداً حذف نمی‌شود).
  • برنامه شما پایگاه داده محلی پایداری از نقاط داده فردی را حفظ نمی‌کند.
  • سادگی را ترجیح می‌دهید و نمی‌خواهید محدودیت‌های اعتبارسنجی رشته (مثل نویسه‌های 4-63) را مدیریت کنید.

شناسه‌های سفارشی را انتخاب کنید اگر:

  • برنامه همگام‌سازی دوطرفه‌ای را اجرا می‌کنید که سوابق سلامتی را در دستگاه‌های مختلف می‌خواند، می‌نویسد، و به‌روز می‌کند.
  • برنامه شما پایگاه داده محلی (مانند Room یا SQLite) دارد که سوابق را با کلیدهای اصلی محلی ذخیره می‌کند.
  • کاربرانتان داده‌ها را به‌صورت آفلاین یا ازطریق اتصال‌های تلفن همراه متناوب ضبط می‌کنند که در این شرایط، تکرار امن ضروری است.
  • می‌خواهید جدول‌های نگاشت شناسه را بین پایگاه داده باکت‌اند و میانای برنامه‌سازی کاربردی حذف کنید.

چرخه حیات همگام‌سازی فقط خواندنی

چرخه حیات همگام‌سازی فقط‌خواندنی در Google Health API
شکل ۲: چرخه حیات همگام‌سازی فقط خواندنی در Google Health API

برنامه‌ای که قصد دارد فقط از Google Health API بخواند باید داده‌ها را در ذخیره‌گاه داده توسعه‌دهنده خود کپی کند و بخش تطبیق چرخه حیات را مدیریت کند.

همان تکالیفی که در بخش خواندن پوشش داده شده است در اینجا نیز اعمال می‌شود.

شکل ۲ چرخه حیات فقط خواندنی را نشان می‌دهد.

مُهرهای زمان بازه و همگام‌سازی دستگاه متصل‌شده

داده‌های فاصله‌ای نشان‌دهنده اندازه‌گیری‌های جمع‌آوری‌شده درطول یک دوره زمانی است، مانند تعداد قدم‌ها، ضربان قلب، یا جلسه‌های تمرین. درمقابل، اندازه‌گیری‌های نقطه‌ای شامل ورودی‌های دستی مانند گزارش غذا یا خواندن ترازو است. داده‌های فاصله‌ای معمولاً از همگام‌سازی دستگاه‌های متصل، مانند ساعت‌های هوشمند و ردیاب‌های تناسب اندام، به‌دست می‌آید.

مُهرهای زمان بازه (startTime و endTime در بارهای JSON REST، یا start_time و end_time در عبارت‌های فیلتر و gRPC) رفتارهای منحصربه‌فردی را هنگام کار با داده‌های بازه معرفی می‌کنند. این بخش توضیح می‌دهد که چرا فاصله‌های هم‌پوشان رخ می‌دهد و نقاط پایانی list و reconcile را مقایسه می‌کند.

فاصله‌های زمانی هم‌پوشان از دستگاه‌های متصل‌شده

دستگاه‌های متصل‌شده مثل ردیاب‌های Fitbit و Google Pixel Watch به‌طور مداوم خوانش‌های زیست‌سنجشی با فرکانس بالا را هنگام پوشیده شدن جمع‌آوری می‌کنند. پس‌از اینکه دستگاهی نقاط داده را با Google Health همگام‌سازی می‌کند، آن سوابق موجود را به‌طور عطف‌به‌ماسبق تغییر نمی‌دهد. مُهرهای زمان فاصله ذخیره‌شده آن‌ها بدون تغییر باقی می‌ماند.

بااین‌حال، قبل‌از چرخه‌های همگام‌سازی بعدی، الگوریتم‌های درون‌دستگاهی اغلب دورسنجی حسگر خام را دوباره تفسیر می‌کنند. دستگاه خوانش‌های جمع‌آوری‌شده در ساعت‌های قبلی را دوباره دسته‌بندی می‌کند. وقتی دستگاه دوباره همگام‌سازی شود، نقاط داده جدید را بارگذاری می‌کند. مرزهای شروع و پایان آن‌ها می‌تواند با فاصله‌های زمانی ذخیره‌شده قبلی هم‌پوشانی داشته باشد.

برای مثال، کاربری را درنظر بگیرید که ساعت هوشمند دارد و داده‌های فعالیت او در دو دسته متوالی همگام‌سازی می‌شود:

  1. درطول اولین همگام‌سازی، دستگاه نقطه داده‌ای را بارگذاری می‌کند که 10:00:00Z تا 10:14:59Z را پوشش می‌دهد.
  2. پس‌از محاسبه مجدد در دستگاه، همگام‌سازی دوم نقطه داده دیگری را بارگذاری می‌کند که 10:14:00Z تا 10:28:59Z را پوشش می‌دهد.

هر دو سابقه به‌طور مستقل در پسای Google Health ذخیره می‌شوند. درنتیجه، هر دو نقطه داده بازه زمانی 10:14:00Z تا 10:14:59Z را پوشش می‌دهند. این کار باعث ایجاد هم‌پوشانی ۵۹ ثانیه‌ای هنگام پُرسمان سوابق خام می‌شود.

مقایسه فهرست و تطبیق دادن نقاط پایانی

می‌توانید این فاصله‌های هم‌پوشان را بااستفاده از نقطه پایانی 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 ادغام نمی‌کند. پاسخ تطبیق‌داده‌شده، نقطه داده برنده را با فاصله زمانی ثبت‌شده اصلی آن برمی‌گرداند. این کار یکپارچگی دورسنجی و سنجه‌های اندازه‌گیری‌شده آن جلسه را حفظ می‌کند.

شکل ۳ نشان می‌دهد که نقطه پایانی reconcile چگونه جلسه‌های هم‌پوشان را مدیریت می‌کند. این الگوریتم به‌جای ایجاد یک اتحاد زمانی مصنوعی، رکورد معتبر را انتخاب می‌کند.

حل‌وفصل کردن فاصله‌های هم‌پوشان: تطبیق دادن حذف تکرار نقطه پایان درمقابل ادغام اتحاد زمان مصنوعی
شکل ۳: تطبیق جلسه متناقض درمقابل ادغام اتحاد زمان مصنوعی

راهنمای «نقاط پایانی» نمونه‌های کامل درخواست و پاسخ را ارائه می‌دهد. برای مقایسه سوابق خام list با خروجی reconcile، دریافت نمای تطبیق‌داده‌شده از داده‌های بازه را ببینید.

نقطه پایانی list برای تشخیص سلامت دستگاه و ممیزی داده‌ها طراحی شده است. زمانی از آن استفاده کنید که گردش کارتان نیاز به بازرسی سوابق اصلاح‌نشده بارگذاری‌شده توسط هر دستگاه داشته باشد. هنگام پرسمان با list، منطق کارخواه شما باید هرگونه هم‌پوشانی بازه را در داده‌های خام مدیریت کند.

تغییرپذیری مُهر زمان و به‌روزرسانی‌های مالک

دستگاه‌های متصل‌شده مُهرهای زمان ذخیره‌شده را درطول چرخه‌های همگام‌سازی عادی به‌طور عطف‌به‌ماسبق اصلاح نمی‌کنند. بااین‌حال، مُهرهای زمان بازه (startTime و endTime در بارداده‌های REST JSON، یا start_time و end_time در عبارت‌های فیلتر و gRPC) در همه منابع داده به‌طور جهانی تغییرناپذیر نیستند. فقط محتواساز یا مالک اصلی سابقه می‌تواند فیلدهای آن را اصلاح کند. برنامه‌های دیگر نمی‌توانند نقطه‌های داده‌ای را که ایجاد نکرده‌اند ویرایش کنند.

برنامه مالک می‌تواند از patch نقطه پایان برای به‌روزرسانی سوابق موجود خود استفاده کند. این شامل اصلاح مُهرهای زمان شروع یا پایان می‌شود، که هر دو فیلد ساعت هماهنگ جهانی (startTime و endTime) و زمان رسمی (civilStartTime و civilEndTime) را در سرور به‌روز می‌کند. برای نمونه‌ای از به‌روزرسانی مُهرهای زمان با PATCH، به‌روزرسانی مُهرهای زمان فاصله برای داده‌های موجود را در راهنمای «نقطه‌های پایانی» ببینید.

به‌طور مشابه، نقاط داده همگام‌سازی‌شده از پلاتفرم‌های خارجی مثل Health Connect یا برنامه‌های شریک، به‌روزرسانی‌ها را از منبع اصلی دریافت می‌کنند. اگر Health Connect متعاقباً به‌روزرسانی‌ای برای سابقه همگام‌سازی‌شده از برنامه طرف سوم اصلی دریافت کند، آن تغییرات منتشر می‌شوند و روی سابقه موجود بازنویسی می‌شوند.