کار با دادهها در API گوگل هلث در اصل چرخهای از همگامسازی دادهها بین مخزن داده گوگل هلث API در فضای ابری و برنامه یا مخزن داده بکاند شما است. با این حال، این چرخه بسته به عوامل مختلف میتواند اشکال مختلفی داشته باشد:
- آیا شما در حال نوشتن دادهها در API گوگل هلث هستید؟ فقط خواندن؟ یا هر دو را انجام میدهید؟
- آیا پایگاه داده شما روی برنامه یا دستگاه شما به صورت محلی ذخیره شده است؟ یا روی فضای ابری خودتان؟
- آیا نیاز دارید دادههای API گوگل هلث را بین برنامه کاربر و یک دستگاه پوشیدنی همگامسازی کنید؟ چند وقت یکبار دستگاهها را همگامسازی میکنید؟
- با چه نوع دادههایی کار میکنید؟ شمارشهای پایه؟ واحدهای اندازهگیری؟ سریهایی با نرخهای نمونهبرداری متفاوت؟
- آیا قصد دارید در حالی که برنامه شما در پسزمینه است، دادهها را بخوانید؟
- آیا قصد دارید با دادههای تاریخی ثبتشده قبل از دریافت مجوزهای کاربر توسط برنامهتان کار کنید؟
برای درک چگونگی ارتباط همه اینها با هم، نگاهی به چرخه حیات همگامسازی API گوگل هلث بیندازید. دو نسخه از این چرخه حیات وجود دارد: استاندارد (خواندنی و نوشتنی) و فقط خواندنی.
چرخه عمر همگامسازی استاندارد
ادغام با API گوگل هلث به معنای کپی کردن دادهها در یک برنامه یا مخزن داده بکاند است. برای سهولت استفاده در این مستندات، ما این مخزن داده را مخزن داده توسعهدهنده مینامیم.
«کپی» در اینجا میتواند جایگزین هر فعالیت مجزایی مانند خواندن از API گوگل هلث (کپی کردن در انبار داده توسعهدهندگان) یا نوشتن در API گوگل هلث (کپی کردن در API گوگل هلث) شود. انجام مکرر این اقدامات با ترتیبی خاص، چرخه حیات همگامسازی است.
شکل ۱ چرخه عمر همگامسازی استاندارد را که شامل عملیات خواندن و نوشتن است، بدون توجه به هیچ یک از عواملی که قبلاً ذکر شد، نشان میدهد.
بنویس
- آمادهسازی دادههای جدید برای نوشتن — دادهها را از یک دستگاه یا برنامه خارجی منتقل کنید و نقاط داده را به نمایشهای JSON سازگار با انواع داده Google Health API قالببندی کنید. توجه داشته باشید که شناسههای سفارشی اختصاص داده شده توسط کلاینت برای نوشتن در حال حاضر در Health API پشتیبانی نمیشوند. چنین شناسههایی ممکن است در یک
POSTارائه شوند، اما نادیده گرفته میشوند. - افزودن رکوردها - ارسال نقاط داده به API گوگل هلث با استفاده از نقاط انتهایی REST. از
POSTبرای ایجاد رکوردها وPATCHبرای درج و بهروزرسانی رکوردهای موجود استفاده کنید. شناسههای مورد نیاز برای عملیاتPATCHاز یک عملیاتPOSTقبلی (مرحله بعدی در یک چرخه قبلی) آمدهاند. - پردازش شناسههای منبع بازگشتی — هنگام استفاده از شناسههای تولید شده توسط سرور،
nameیا شناسه منبع بازگشتی توسط سرور را استخراج کرده و در مخزن داده توسعهدهنده خود ذخیره کنید تا بهروزرسانیها (PATCH) یا حذفها (DELETE) در آینده فعال شوند. برای اطلاعات بیشتر در مورد این دو نوع، به استراتژیهای شناسایی مراجعه کنید.
بخوانید
- خواندن رکوردها — دادههای جدید را از دادههای موجود در API گوگل هلث با استفاده از نقاط پایانی REST (
GETبا پارامترهای پرسوجویfilterو صفحهبندیpageToken، یا نقاط پایانی تجمیع مانندrollUpوdailyRollUp) دریافت کنید و تغییرات را در آنها اعمال کنید، یا با استفاده از Webhook Subscriptions (projects.subscribers) اعلانهای بلادرنگ دریافت کنید. یک اعلان فقط نشان میدهد که دادههای جدید در دسترس هستند، نه اینکه دادههای واقعی چه هستند. - تطبیق پایگاه داده توسعهدهندگان — دادههای جدید و بهروزرسانیشده را با پایگاه داده توسعهدهندگان خود تطبیق دهید. دستگاههای متصل میتوانند در طول همگامسازیها فواصل همپوشانی ایجاد کنند. برای آشنایی با نحوه حل آنها توسط API Google Health، به بخش «مُهرهای زمانی فاصلهای و همگامسازی دستگاه متصل» مراجعه کنید.
این چرخه سپس در فواصل زمانی مناسب و با توجه به نیازهای خاص دستگاهها یا برنامههای خارجی تکرار میشود. این ترتیبی است که ما معمولاً برای همگامسازی دادهها بین پایگاه داده خود و API گوگل هلث توصیه میکنیم.
استراتژیهای شناسایی
اگر قصد دارید قبل از ایجاد ادغام با APIهای Google Health، دادهها را در Google Health API بنویسید، باید هنگام ایجاد نقاط داده (واحد اصلی دادهها) یک استراتژی شناسایی منابع انتخاب کنید.
شناسههای اختصاص داده شده توسط کلاینت برای نوشتن در حال حاضر در Health API پشتیبانی نمیشوند. چنین شناسههایی ممکن است در یک POST ارائه شوند، اما نادیده گرفته میشوند. جزئیات مربوط به این گزینه برای اهداف اطلاعاتی در اینجا ارائه شده است.
- شناسههای تولید شده توسط سرور (گزینه پیشفرض) : کلاینت دادهها را بدون شناسه ارسال میکند و رابط برنامهنویسی کاربردی گوگل هلث یک شناسه سیستم منحصر به فرد تولید و برمیگرداند.
- شناسههای سفارشی اختصاص داده شده به کلاینت (طبق AIP-133 ، هنوز پشتیبانی نمیشود) : برنامه کلاینت یک شناسه منحصر به فرد (مثلاً یک UUID یا کلید اصلی پایگاه داده محلی) تولید میکند و آن را در مسیر منبع هنگام ایجاد قرار میدهد.
جدول زیر هر دو استراتژی شناسایی را مقایسه میکند تا به شما در انتخاب رویکرد مناسب برای ادغامتان کمک کند:
| ویژگی | شناسههای تولید شده توسط سرور | شناسههای سفارشی اختصاص داده شده توسط مشتری |
|---|---|---|
| تولید شناسه | سرور در طول اجرای POST شناسه سیستم تصادفی تولید میکند. | کلاینت قبل از نوشتن، شناسه پایدار را به صورت محلی (UUID نسخه ۴ / PK داخلی) تولید میکند. |
| مسیر منابع | .../dataPoints/{server_id} (در پاسخ برگردانده میشود) | .../dataPoints/{custom_id} |
| مرحله محلی پس از نوشتن | الزامی. باید server_id برگردانده شده را در پایگاه داده محلی ذخیره کند تا امکان بهروزرسانیها/حذفهای بعدی فراهم شود. | هیچکدام. برنامه از قبل مالک شناسه است. |
| جدول نگاشت شناسه | الزامی. کلاینت باید یک نگاشت دوطرفه ( local_id ↔ server_id ) را حفظ کند. | لازم نیست. کلاینت مستقیماً از کلید اصلی خود استفاده میکند. |
| رفتار تلاش مجدد (شبکه ضعیف) | خطر تکرار. تلاش مجدد برای ارسال یک POST با زمان انقضا، یک رکورد تکراری با شناسه سرور جدید ایجاد میکند. | ایمن و خودتوان. تلاش مجدد برای POST با همان custom_id از ایجاد مقادیر تکراری جلوگیری میکند (مقدار 409 ALREADY_EXISTS را برمیگرداند). |
| پشتیبانی از همگامسازی آفلاین | محدود. باید منتظر پاسخ سرور بماند تا شناسههای رسمی منابع را قبل از ارجاع به آنها دریافت کند. | کامل. موجودیتها میتوانند به صورت آفلاین با شناسههای پایدار ایجاد و تغییر داده شوند، سپس هنگام اتصال مجدد به صورت یکپارچه همگامسازی شوند. |
| محدودیتهای قالببندی | کاملاً توسط سرور مدیریت میشود. | باید بعد از ^[a-z0-9-]{4,63}$ (حروف کوچک، عدد و خط فاصله) قرار گیرد. |
| چه زمانی انتخاب کنیم | شناسههای تولید شده توسط سرور را انتخاب کنید اگر:
| اگر موارد زیر را دارید، شناسههای سفارشی را انتخاب کنید:
|
چرخه حیات همگامسازی فقط خواندنی
برنامهای که قصد دارد فقط از API گوگل هلث بخواند، باید دادهها را در پایگاه داده توسعهدهنده خود کپی کند و بخش تطبیق چرخه عمر را مدیریت کند.
همان وظایفی که در بخش «خواندن» پوشش داده شد، اینجا هم صدق میکند.
شکل ۲ چرخه حیات فقط خواندنی را نشان میدهد.
نشانگرهای زمانی فاصله زمانی و همگامسازی دستگاه متصل
دادههای فاصلهای نشاندهندهی اندازهگیریهای جمعآوریشده در طول یک دورهی زمانی، مانند تعداد قدمها، ضربان قلب یا جلسات ورزشی هستند. در مقابل، اندازهگیریهای نقطهای شامل ورودیهای دستی مانند گزارش غذا یا خواندن ترازو هستند. دادههای فاصلهای معمولاً از همگامسازی دستگاههای متصل، مانند ساعتهای هوشمند و ردیابهای تناسب اندام، سرچشمه میگیرند.
مهرهای زمانی بازه ( startTime و endTime ) هنگام کار با دادههای بازه، رفتارهای منحصر به فردی را نشان میدهند. این بخش توضیح میدهد که چرا بازههای همپوشانی رخ میدهند و list را مقایسه کرده و نقاط پایانی reconcile .
فواصل همپوشانی از دستگاههای متصل
دستگاههای متصل مانند ردیابهای Fitbit و Google Pixel Watch به طور مداوم دادههای بیومتریک با فرکانس بالا را هنگام استفاده جمعآوری میکنند. پس از اینکه دستگاه نقاط داده را با Google Health همگامسازی کرد، این سوابق موجود را به صورت گذشتهنگر تغییر نمیدهد. مهرهای زمانی ذخیره شده در فواصل زمانی آنها بدون تغییر باقی میمانند.
با این حال، قبل از چرخههای همگامسازی بعدی، الگوریتمهای روی دستگاه اغلب تلهمتری خام حسگر را دوباره تفسیر میکنند. دستگاه، دادههای جمعآوریشده در ساعات قبل را دوباره ذخیره میکند. وقتی دستگاه دوباره همگامسازی میکند، نقاط داده جدید را بارگذاری میکند. مرزهای شروع و پایان آنها میتواند با فواصل ذخیرهشده قبلی همپوشانی داشته باشد.
برای مثال، کاربری را در نظر بگیرید که ساعت هوشمندی به دست دارد و دادههای فعالیتش در دو دسته متوالی همگامسازی میشود:
- در طول اولین همگامسازی، دستگاه یک نقطه داده را که
10:00:00Zتا10:14:59Zرا پوشش میدهد، آپلود میکند. - پس از محاسبه مجدد روی دستگاه، همگامسازی دوم، نقطه داده دیگری را که
10:14:00Zتا10:28:59Zرا پوشش میدهد، آپلود میکند.
هر دو رکورد به طور مستقل در بکاند گوگل هلث ذخیره میشوند. در نتیجه، هر دو نقطه داده، بازه زمانی 10:14:00Z تا 10:14:59Z را پوشش میدهند. این امر باعث میشود هنگام جستجوی رکوردهای خام، همپوشانی ۵۹ ثانیهای ایجاد شود.
مقایسه لیست و تطبیق نقاط پایانی
شما میتوانید این فواصل همپوشانی را با استفاده از list یا نقطه پایانی reconcile مدیریت کنید. نقطه پایانی را انتخاب کنید که با الزامات برنامه شما مطابقت داشته باشد:
| ویژگی | نقطه پایانی list | نقطه پایانی را reconcile |
|---|---|---|
| روش HTTP | GET https://health.googleapis.com/v4/users/me/dataTypes/<var>dataType</var>/dataPoints | GET https://health.googleapis.com/v4/users/me/dataTypes/<var>dataType</var>/dataPoints:reconcile |
| رفتار همپوشانی | تمام رکوردهای ذخیره شده را به همان صورت که آپلود شدهاند، بدون حذف دادههای تکراری برمیگرداند. وقتی فواصل زمانی همپوشانی داشته باشند، هر دو رکورد برگردانده میشوند. | تداخلها را برطرف میکند و رکوردهای همپوشانی را در دستگاهها حذف میکند و جلسات را در یک جریان پیوسته واحد همگامسازی میکند. |
| مزایا | یک دنباله حسابرسی کامل و بدون تغییر از هر رکورد آپلود شده توسط هر دستگاه و دسته همگامسازی ارائه میدهد. | با مدیریت خودکار فواصل همپوشانی و تداخلات چند دستگاهی، رندر کردن جدول زمانی و محاسبات مدت زمان را ساده میکند. |
| معایب | برنامه شما مسئول تشخیص و حل فواصل همپوشانی، تداخل چند دستگاه و دورههای خارج از دسترس بودن مچ دست است. | رکوردهای همپوشانی فرعی از پاسخ حذف میشوند، بنابراین دستههای همگامسازی دستگاههای منفرد را نمیتوان به صورت جداگانه حسابرسی کرد. |
نقطه پایانی reconcile برای ترسیم رابطهای کاربری، رندر کردن جدولهای زمانی فعالیتها و محاسبه مجموع مدت زمانهای غیر همپوشانی طراحی شده است. این نقطه پایانی، فواصل زمانی متناقض از جلسات همگامسازی مجدد را حل میکند. همچنین فعالیتهای ثبتشده همزمان در چندین دستگاه، مانند ساعت و تلفن، را تطبیق میدهد.
تطبیق، جلسات متناقض را با انتخاب رکورد معتبر به جای ترکیب یک اتحاد زمانی مصنوعی حل میکند. به عنوان مثال، 11:00:00Z با 11:30:00Z و 11:20:00Z با 11:50:00Z را در 11:00:00Z با 11:50:00Z ادغام نمیکند. پاسخ تطبیق داده شده، نقطه داده برنده را با فاصله ثبت شده اصلی آن برمیگرداند. این امر یکپارچگی تلهمتری و معیارهای اندازهگیری شده آن جلسه را حفظ میکند.
شکل ۳ نشان میدهد که چگونه نقطه پایانی reconcile جلسات همپوشانی را مدیریت میکند. این نقطه پایانی به جای ایجاد یک اتحاد زمانی مصنوعی، رکورد معتبر را انتخاب میکند.
راهنمای Endpoints نمونههای کاملی از درخواست و پاسخ را ارائه میدهد. برای مقایسه رکوردهای list خام با خروجی reconcile ، به Get a matching view of interval data مراجعه کنید.
نقطه پایانی list برای تشخیص دستگاه و ممیزی دادهها طراحی شده است. زمانی که گردش کار شما نیاز به بررسی رکوردهای اصلاح نشده به صورت آپلود شده توسط هر دستگاه دارد، از آن استفاده کنید. هنگام پرس و جو با list ، منطق کلاینت شما باید هرگونه همپوشانی بازه در دادههای خام را مدیریت کند.
تغییرپذیری مهر زمانی و بهروزرسانیهای مالک
دستگاههای متصل، مهرهای زمانی ذخیره شده را در طول چرخههای همگامسازی عادی، به صورت گذشتهنگر تغییر نمیدهند. با این حال، مهرهای زمانی بازه ( startTime و endTime ) در تمام منابع داده به طور جهانی تغییرناپذیر نیستند. فقط سازنده یا مالک اصلی یک رکورد میتواند فیلدهای آن را تغییر دهد. سایر برنامهها نمیتوانند نقاط دادهای را که ایجاد نکردهاند، ویرایش کنند.
یک برنامهی مالک میتواند از نقطهی پایانی patch برای بهروزرسانی رکوردهای موجود خود استفاده کند. این شامل تغییر مهرهای زمانی شروع یا پایان نیز میشود. برای مثالی از بهروزرسانی مهرهای زمانی با PATCH ، به بخش «بهروزرسانی مهرهای زمانی فاصلهای برای دادههای موجود» در راهنمای نقاط پایانی مراجعه کنید.
به طور مشابه، نقاط دادهای که از پلتفرمهای خارجی مانند Health Connect یا برنامههای همکار همگامسازی میشوند، بهروزرسانیها را از منبع اصلی به ارث میبرند. هنگامی که برنامه اصلی یک رکورد موجود را تغییر میدهد، آن بهروزرسانیها به Google Health منتقل میشوند.