راه‌اندازی گوگل کلود و OAuth

دسترسی به API گوگل هلث از طریق گوگل کلود (Google Cloud) فراهم می‌شود. برای فعال کردن API و تأیید حساب گوگل، به یک پروژه گوگل کلود نیاز دارید.

چه از قبل یک توسعه‌دهنده‌ی API فیت‌بیت باشید و چه به تازگی با API گوگل هلث آشنا شده باشید، برای برقراری تماس با API باید این مرحله را تکمیل کنید.

ایجاد یک پروژه و یک کلاینت OAuth

برای فعال کردن API گوگل هلث و دریافت شناسه کلاینت OAuth 2.0، از دکمه‌ی «فعال کردن API و دریافت شناسه کلاینت OAuth 2.0» استفاده کنید:

  1. اگر یک پروژه Google Cloud موجود دارید که می‌خواهید برای Google Health API از آن استفاده کنید، ابتدا مطمئن شوید که وارد حساب کاربری مدیر آن پروژه شده‌اید. سپس پس از کلیک روی دکمه، پروژه موجود را از لیست پروژه‌های موجود انتخاب کنید. در غیر این صورت، یک پروژه جدید ایجاد کنید.
  2. وقتی از شما می‌پرسد «از کجا تماس می‌گیرید؟» ، گزینه‌ی «وب سرور» را انتخاب کنید.
  3. برای دریافت کد مجوز با استفاده از OAuth 2.0، به آدرس https://www.google.com به عنوان مقدار برای Authorized redirect URIs نیاز است.
  4. پس از اتمام نصب، مقادیر OAuth 2.0 Client ID و Client Secret را کپی کنید و فایل JSON مربوط به Credentials را روی دستگاه محلی خود دانلود کنید .
فعال کردن API و دریافت شناسه کلاینت OAuth 2.0

اگر می‌خواهید پروژه Google Cloud خود را به صورت دستی تنظیم کنید، یا تنظیمات را تأیید کنید و دوباره اعتبارنامه‌های خود را بازیابی کنید:

  1. API گوگل هلث را در صفحه فعال‌سازی API فعال کنید.
  2. یک شناسه کلاینت OAuth 2.0 در صفحه اعتبارنامه‌ها دریافت کنید.

برای اطلاعات بیشتر در مورد راه‌اندازی OAuth 2.0 با استفاده از کنسول گوگل، به بخش «استفاده از OAuth 2.0 برای دسترسی به APIهای گوگل» مراجعه کنید.

افزودن کاربران آزمایشی

به طور پیش‌فرض، کلاینت‌های OAuth تازه ایجاد شده در حالت تأیید نشده با محدودیت ۱۰۰ کاربر برای اهداف آزمایشی و عملیاتی هستند. برای فعال کردن مجوز در این دوره، باید آدرس ایمیل هر کاربر را به صورت دستی به لیست کاربران آزمایشی در پیکربندی پروژه خود اضافه کنید.

فهرست کاربران آزمایشی را در صفحه مخاطبان به‌روزرسانی کنید:

  1. در این صفحه، باید ببینید که «وضعیت انتشار» روی «در حال آزمایش » و «نوع کاربر» روی «خارجی» تنظیم شده است.
  2. در بخش «کاربران آزمایشی»، روی + افزودن کاربران کلیک کنید. آدرس ایمیل هر کاربر آزمایشی که باید به برنامه شما اجازه دسترسی به داده‌های سلامت خود را بدهد، وارد کنید.
  3. روی ذخیره کلیک کنید.

پشتیبانی از بیش از ۱۰۰ کاربر با رابط برنامه‌نویسی کاربردی گوگل هلث (Google Health API) نیازمند تکمیل بررسی امنیتی توسط شخص ثالث است. اطلاعات بیشتر را می‌توانید در مرکز راهنمایی تأیید اعتبار برنامه OAuth بیابید.

اضافه کردن محدوده‌ها

شما باید محدوده‌هایی را که کلاینت شما مجاز به فراخوانی آن‌ها است، در صفحه دسترسی به داده‌ها مشخص کنید:

  1. در این صفحه، روی افزودن یا حذف محدوده‌ها کلیک کنید.
  2. در ستون API، عبارت «Google Health API» را جستجو کنید. محدوده‌های مورد نیاز برای برنامه خود را انتخاب کنید.
  3. پس از انتخاب تمام حوزه‌های مورد نیاز، برای بازگشت به صفحه دسترسی به داده‌ها، روی به‌روزرسانی کلیک کنید.
  4. روی ذخیره کلیک کنید.

شما تنظیم شناسه کلاینت خود را به پایان رسانده‌اید و اکنون باید بتوانید با API گوگل هلث تماس برقرار کنید.

به‌روزرسانی محدوده‌ها

شما می‌توانید با تنظیم پارامتر prompt به صورت consent در درخواست احراز هویت خود، از کاربر بخواهید که برنامه شما را مجدداً تأیید کند. وقتی prompt=consent گنجانده شده باشد، صفحه رضایت هر بار که برنامه شما درخواست تأیید دامنه‌های دسترسی را می‌کند، نمایش داده می‌شود، حتی اگر قبلاً همه دامنه‌ها به پروژه Google API شما اعطا شده باشند.

برای اضافه کردن یا تغییر محدوده‌ها با استفاده از پارامتر prompt=consent ، مراحل زیر را دنبال کنید:

  1. فهرست کاملی از محدوده‌هایی که برنامه شما به آنها نیاز دارد را مشخص کنید. این فهرست باید شامل محدوده‌های موجود و هر محدوده جدیدی که باید اضافه کنید، باشد.

  2. پارامتر scope را در آدرس URL مربوط به مجوز تغییر دهید تا لیست به‌روز شده‌ی مقادیر scope که با فاصله از هم جدا شده‌اند، در آن لحاظ شود.

  3. prompt=consent به پارامترهای URI احراز هویت خود اضافه کنید. این کار سرور احراز هویت را مجبور می‌کند قبل از ارسال اطلاعات به کلاینت، از کاربر رضایت‌نامه دریافت کند.

    مثال زیر یک درخواست HTTPS GET به نقطه پایانی احراز هویت OAuth 2.0 گوگل را نشان می‌دهد که چندین محدوده را با prompt=consent درخواست می‌کند:

    https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=redirect-uri&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly%20https://www.googleapis.com/auth/googlehealth.sleep.readonly&prompt=consent

  4. وقتی کاربر لینک به‌روزرسانی‌شده را دنبال کند، صفحه‌ای برای رضایت‌نامه نمایش داده می‌شود که تمام حوزه‌های درخواستی را فهرست می‌کند. به محض اینکه کاربر روی «ادامه» یا «مجاز» کلیک کند، یک کد مجوز جدید دریافت خواهید کرد که می‌تواند با توکن‌هایی که کل مجموعه حوزه‌ها را پوشش می‌دهند، تعویض شود.

    فقط در مواقع ضروری، از prompt=consent استفاده کنید، مثلاً زمانی که نیاز به دریافت یک refresh token جدید دارید یا زمانی که scopeهای درخواستی تغییر کرده‌اند.

کتابخانه‌های کلاینت OAuth2

فهرست کتابخانه‌های کلاینت OAuth2 موجود که برای ادغام با چارچوب‌های محبوب استفاده می‌شوند را می‌توانید در «استفاده از OAuth 2.0 برای دسترسی به APIهای گوگل» بیابید.

توکن‌های تازه‌سازی

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

برای تبادل یک توکن به‌روزرسانی با یک توکن دسترسی، یک فراخوانی HTTPS POST به نقطه پایانی توکن Google OAuth 2.0 انجام دهید. قطعه کد زیر یک نمونه درخواست و پاسخ را نشان می‌دهد:

درخواست 

curl -L -X POST 'https://oauth2.googleapis.com/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=client-id&client_secret=client-secret&refresh_token=refresh-token&grant_type=refresh_token'

پاسخ 

{
  "access_token": "access-token",
  "expires_in": 3599,
  "scope": "scope-list",
  "token_type": "Bearer",
  "refresh_token": "refresh-token",
  "refresh_token_expires_in": 112154
}

رفتار توکن در طول آزمایش

از نحوه رفتار توکن‌های به‌روزرسانی بسته به وضعیت انتشار پروژه Google Cloud خود آگاه باشید:

  • حالت آزمایشی: اگر صفحه رضایت OAuth شما با وضعیت انتشار "در حال آزمایش" پیکربندی شده باشد، توکن‌های به‌روزرسانی صادر شده مبتنی بر زمان هستند و پس از 7 روز منقضی می‌شوند. در طول این دوره، شما یک توکن به‌روزرسانی واحد دریافت خواهید کرد که تا زمان رسیدن به تاریخ انقضا، معتبر و قابل استفاده برای دریافت توکن‌های دسترسی جدید است.
  • حالت منتشر شده: هنگامی که برنامه شما به وضعیت "در حال تولید" منتقل می‌شود، توکن‌های به‌روزرسانی معمولاً منقضی نمی‌شوند، مگر اینکه لغو شوند یا برای مدت طولانی (معمولاً شش ماه) بلااستفاده بمانند.

برای یک تجربه کاربری روان، مطمئن شوید که برنامه خود را قبل از انتقال به محیط تولید منتشر می‌کنید تا از انقضای توکن‌های ۷ روزه جلوگیری شود.

محافظت بین حساب‌های کاربری (RISC API)

اگر می‌خواهید از تغییرات توکن‌های رویداد یا پیوند حساب‌ها، مانند حساب‌های قطع‌شده یا توکن‌های لغوشده، برای پاک کردن توکن‌های ذخیره‌شده و به‌روزرسانی وضعیت اتصال رابط کاربری مطلع شوید، اشتراک‌گذاری و هماهنگی ریسک و حادثه (RISC) را فعال کنید. فعال کردن API RISC اختیاری است.

برای فعال کردن API RISC برای پروژه Google Cloud خود:

  1. صفحه RISC API را در کنسول Google Cloud باز کنید. مطمئن شوید پروژه‌ای که برای Google Health API استفاده می‌کنید، انتخاب شده است.
  2. شرایط RISC را بخوانید و مطمئن شوید که الزامات را درک کرده‌اید.
  3. اگر با شرایط موافقت می‌کنید، روی فعال کردن کلیک کنید.

پس از فعال کردن API، باید یک نقطه پایانی HTTPS ایجاد و ثبت کنید تا توکن‌های رویداد ارسالی توسط گوگل را دریافت و اعتبارسنجی کند.

برای اطلاعات بیشتر در مورد محافظت از حساب‌های کاربری بین‌حسابی و RISC، به بخش «محافظت از حساب‌های کاربری با محافظت از حساب‌های کاربری بین‌حسابی» مراجعه کنید.