إعداد Google Cloud وOAuth

يمكن الوصول إلى Google Health API من خلال Google Cloud. لتفعيل واجهة برمجة التطبيقات والموافقة على حساب Google، يجب أن يكون لديك مشروع على Google Cloud.

سواء كنتم من مطوّري Fitbit API الحاليين أو تستخدمون Google Health API للمرة الأولى، يجب إكمال هذه الخطوة لإجراء طلبات إلى واجهة برمجة التطبيقات.

إنشاء مشروع وعميل OAuth

استخدِم الزر تفعيل واجهة برمجة التطبيقات والحصول على معرّف عميل OAuth 2.0 لتفعيل Google Health API والحصول على معرّف عميل OAuth 2.0:

1. إذا كان لديكم مشروع حالي على Google Cloud تريدون استخدامه مع Google Health API، تأكَّدوا أولاً من تسجيل الدخول إلى حساب المشرف لهذا المشروع. بعد ذلك، اختاروا المشروع الحالي من قائمة المشاريع المتاحة بعد النقر على الزر. وإلا، أنشئوا مشروعًا جديدًا.
2. اختاروا خادم الويب عندما يُطلب منكم تحديد "المكان الذي تجرون منه الطلب".
3. أدخِلوا https://www.google.com كقيمة لـ عناوين URI المصرّح بها لإعادة التوجيه. يجب توفير عنوان URI لإعادة التوجيه للحصول على رمز تفويض باستخدام OAuth 2.0.
4. بعد اكتمال الإعداد، انسخوا معرّف عميل OAuth 2.0 وقيم سر العميل، ونزِّلوا ملف JSON لبيانات الاعتماد على جهازكم المحلي.

تفعيل واجهة برمجة التطبيقات والحصول على معرّف عميل OAuth 2.0

إذا أردتم إعداد مشروعكم على Google Cloud يدويًا أو التحقّق من الإعداد واسترداد بيانات الاعتماد مرة أخرى، اتّبِعوا الخطوات التالية:

1. فعِّلوا Google Health API في صفحة تفعيل واجهة برمجة التطبيقات.
2. احصلوا على معرّف عميل OAuth 2.0 في صفحة بيانات الاعتماد.

لمزيد من المعلومات حول إعداد OAuth 2.0 باستخدام وحدة تحكّم Google، يُرجى الاطّلاع على استخدام OAuth 2.0 للدخول إلى Google APIs.

إضافة مستخدمين للاختبار

تكون برامج OAuth التي تم إنشاؤها حديثًا في حالة لم يتم التحقّق منها، ويبلغ الحد الأقصى لعدد المستخدمين 100 مستخدم لأغراض الاختبار والإصدار العلني. لتفعيل التفويض خلال هذه الفترة، يجب إضافة عنوان البريد الإلكتروني لكل مستخدم يدويًا إلى قائمة "المستخدمون للاختبار" في إعدادات مشروعكم.

عدِّلوا قائمة المستخدمين للاختبار في صفحة الجمهور:

1. في هذه الصفحة، من المفترض أن تظهر لكم "حالة النشر" على أنّها الاختبار، و يجب أن يظهر "نوع المستخدم" على أنّه خارجي.
2. ضمن القسم "المستخدمون للاختبار"، انقروا على + إضافة مستخدمين. أدخِلوا عنوان البريد الإلكتروني لأي مستخدمين للاختبار يجب السماح لهم بمنح تطبيقكم إذن الوصول إلى بياناتهم الصحية.
3. انقروا على حفظ.

لاستخدام Google Health API مع أكثر من 100 مستخدم، يجب إكمال مراجعة أمان من جهة خارجية. يمكنكم الاطّلاع على معلومات إضافية في مركز مساعدة التحقّق من تطبيقات OAuth.

إضافة النطاقات

يجب تحديد النطاقات التي يُسمح لعميلكم بطلبها في صفحة الوصول إلى البيانات:

1. في هذه الصفحة، انقروا على إضافة نطاقات أو إزالتها.
2. في عمود "واجهة برمجة التطبيقات"، ابحثوا عن "Google Health API". اختاروا النطاقات التي تحتاجونها لتطبيقكم.
3. بعد اختيار جميع النطاقات المطلوبة، انقروا على تعديل للرجوع إلى صفحة "الوصول إلى البيانات".
4. انقروا على حفظ.

قبل اختيار النطاقات، راجعوا عملية تنفيذ النطاق .

لقد انتهيتم من إعداد معرّف العميل، ويجب أن تتمكنوا الآن من إجراء طلبات إلى Google Health API.

تعديل النطاقات

يمكنكم مطالبة المستخدم بإعادة منح الإذن لتطبيقكم من خلال ضبط المَعلمة `prompt` على `consent` في طلب المصادقة. عند تضمين prompt=consent، تظهر شاشة طلب الموافقة في كل مرة يطلب فيها تطبيقكم إذن الوصول إلى النطاقات، حتى إذا تم منح جميع النطاقات سابقًا لمشروعكم على Google APIs.

لإضافة نطاقات أو تغييرها باستخدام المَعلمة prompt=consent، اتّبِعوا الخطوات التالية:

1. حدِّدوا القائمة الكاملة بـ النطاقات التي يحتاجها تطبيقكم. يجب أن تتضمّن هذه القائمة النطاقات الحالية وأي نطاقات جديدة تحتاجون إلى إضافتها.

2. عدِّلوا المَعلمة `scope` في عنوان URL الخاص بالتفويض لتضمين القائمة المعدَّلة بقيم النطاقات المفصولة بمسافات.

3. ألحِقوا prompt=consent بمعلَمات عنوان URI الخاص بالمصادقة. يفرض ذلك على خادم التفويض مطالبة المستخدم بالموافقة قبل عرض المعلومات على عميلكم.

   يوضِّح المثال التالي طلب استرداد بيانات باستخدام GET عبر HTTPS إلى نقطة نهاية تفويض OAuth 2.0 من Google يطلب نطاقات متعددة مع إلحاق 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 إلا عند الضرورة، مثلاً عندما تحتاجون إلى الحصول على الرمز المميز لإعادة التحميل أو عندما تكون النطاقات المطلوبة قد تغيّرت.

مكتبات عملاء OAuth2

يمكنكم الاطّلاع على قائمة مكتبات عملاء OAuth2 المتاحة التي تُستخدم للدمج مع الأطر الشائعة في استخدام OAuth 2.0 للدخول إلى Google APIs.

الرموز المميّزة لإعادة التحميل

للحفاظ على إمكانية الوصول إلى Google APIs على المدى الطويل بدون الحاجة إلى إعادة مصادقة المستخدم باستمرار، يجب أن يستخدم تطبيقكم رمزًا مميّزًا لإعادة التحميل. للاطّلاع على تفاصيل التنفيذ الشاملة، بما في ذلك طلبات HTTP والمعلَمات المحدّدة المطلوبة، يُرجى الرجوع إلى مستندات "منصة هوية Google".

لاستبدال رمز مميّز لإعادة التحميل برمز مميّز للوصول، يجب إجراء طلب 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
}

وقت إعادة تحميل الرمز المميّز

يجب إعادة تحميل الرموز المميّزة عند الطلب كجزء من التقدّم الطبيعي لجلسة نشطة للمستخدم عندما تنتهي صلاحية الرموز المميّزة للوصول أو تكون على وشك الانتهاء. تجنَّبوا إعادة تحميل الرموز المميّزة على دفعات (مثلاً، باستخدام مهمة cron أو خدمة مجدولة لإعادة تحميل الرموز المميّزة لجميع المستخدمين في وقت محدّد).

لا يُنصح بإعادة تحميل الرموز المميّزة على دفعات للأسباب التالية:

• تمنع عملية إعادة التحميل على دفعات مطابقة تعديلات الرموز المميّزة مع أنماط مزامنة المستخدم النشط. على الرغم من أنّه يمكنكم استخدام طلب Get Devices للاطّلاع على آخر وقت مزامنة للمستخدم، يتطلب ذلك نطاق OAuth إضافيًا ليس على المستخدمين الموافقة عليه.
• تعالج عملية المعالجة على دفعات الرموز المميّزة التي لا تحتاج إلى إعادة تحميل، ما يؤدي إلى زيادة عبء المعالجة غير الضروري على أنظمتكم وخوادم Google.
• في حال حدوث مشكلة في الشبكة أو انقطاع في الخادم أثناء إعادة التحميل على دفعات، ستتأثر جميع الرموز المميّزة للمستخدمين المتأثرين في آن واحد. تؤدي إعادة تحميل الرموز المميّزة بشكل فردي أثناء التقدّم الطبيعي لعمليات مزامنة المستخدمين إلى حصر تأثير حالات الإخفاق المؤقتة على مستخدم واحد.
• يصعب تشخيص المشاكل باستخدام المهام على دفعات. نظرًا إلى أنّ الطلبات على دفعات تحدث بشكل أقل تكرارًا وتؤدي إلى إنشاء عدد كبير من إدخالات السجلّ في آن واحد، يصبح تحديد بداية الحادثة أكثر صعوبة.
• تزيد الارتفاعات الكبيرة في طلبات الرموز المميّزة المتزامنة أثناء عمليات التشغيل على دفعات من احتمالية بلوغ الحدود القصوى أو حدوث أخطاء متقطعة في المصادقة.

سلوك الرموز المميّزة أثناء الاختبار

يجب أن تكونوا على دراية بسلوك الرموز المميّزة لإعادة التحميل استنادًا إلى حالة النشر لمشروعكم على Google Cloud:

• وضع الاختبار: إذا تم ضبط شاشة طلب موافقة OAuth على حالة النشر "الاختبار"، تكون الرموز المميّزة لإعادة التحميل الصادرة مستندة إلى الوقت وتنتهي صلاحيتها بعد 7 أيام. خلال هذه الفترة، ستتلقّون رمزًا مميّزًا واحدًا لإعادة التحميل يظل صالحًا وقابلاً للاستخدام للحصول على رموز مميّزة جديدة للوصول إلى أن يحين تاريخ انتهاء صلاحيته.
• وضع النشر: بعد نقل تطبيقكم إلى حالة "في مرحلة الإنتاج"، لا تنتهي صلاحية الرموز المميّزة لإعادة التحميل بشكل عام إلا إذا تم إبطالها أو إذا ظلت غير مستخدَمة لفترة طويلة (عادةً ستة أشهر).

لضمان توفير تجربة سلسة للمستخدمين، احرصوا على نشر تطبيقكم قبل نقله إلى بيئة التشغيل الفعلي لتجنُّب انتهاء صلاحية الرموز المميّزة بعد 7 أيام.

الحماية العابرة للحساب (RISC API)

فعِّلوا ميزة "مشاركة المخاطر والحوادث والتنسيق" (RISC) إذا أردتم تلقّي إشعارات بالتغييرات التي تطرأ على الرموز المميّزة للأحداث أو ربط الحسابات، مثل الحسابات غير المرتبطة أو الرموز المميّزة التي تم إبطالها، لتنظيف الرموز المميّزة المخزّنة وتعديل حالة الاتصال بواجهة المستخدم. إنّ تفعيل RISC API اختياري.

لتفعيل RISC API لمشروعكم على Google Cloud، اتّبِعوا الخطوات التالية:

1. افتحوا صفحة RISC API في Google Cloud Console. تأكَّدوا من اختيار المشروع الذي تستخدمونه مع Google Health API.
2. اقرأوا بنود RISC و تأكَّدوا من فهم المتطلبات.
3. انقروا على تفعيل إذا كنتم توافقون على البنود.

بعد تفعيل واجهة برمجة التطبيقات، يجب إنشاء نقطة نهاية HTTPS وتسجيلها لتلقّي الرموز المميّزة للأحداث التي ترسلها Google والتحقّق من صحتها.

لمزيد من المعلومات حول "الحماية العابرة للحساب" وRISC، يُرجى الاطّلاع على حماية حسابات المستخدمين باستخدام ميزة "الحماية العابرة للحساب".