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