إجراء أول طلب بيانات من واجهة برمجة التطبيقات Google Health باستخدام OAuth2 Playground

1- مقدمة

مساحة بروتوكول OAuth 2.0 هي أداة مستندة إلى الويب تساعدك في اختبار عمليات Google OAuth 2.0 بدون كتابة أي رمز. سيوضّح لك هذا الدرس التطبيقي حول الترميز كيفية إعداد مشروع Google Cloud والحصول على بيانات الاعتماد وبدء عملية التفويض باستخدام مساحة بروتوكول OAuth 2.0 وإجراء أول طلب إلى أحد نقاط نهاية Google Health API.

أهداف الدورة التعليمية

  • كيفية إعداد معرّف عميل ضمن Google Cloud Console
  • كيفية إجراء عملية تفويض Google OAuth 2.0 للحصول على رمز دخول ورمز إعادة تحميل باستخدام مساحة بروتوكول OAuth 2.0
  • كيفية إجراء طلبات إلى نقاط نهاية Google Health API باستخدام مساحة بروتوكول OAuth 2.0

المتطلبات

لإعداد تطبيق Fitbit للأجهزة الجوّالة، اتّبِع الخطوات التالية:

  1. في Apple App Store أو Google Play Store، ابحث عن تطبيق Fitbit للأجهزة الجوّالة ونزِّله.
  2. انقر على رمز التطبيق.
  3. انقر على تسجيل الدخول باستخدام حساب Google ‏(Sign in With Google).
  4. اختَر حسابك على Google وانقر على الزر متابعة.

2. إعداد مشروع Google Cloud

ستستخدم Google Cloud Console لإنشاء معرّف عميل وتفعيل استخدام Google Health API.

  1. سجِّل الدخول إلى Google Cloud Console.
  2. لإنشاء مشروع جديد:
    1. انقر على اختيار مشروع من أداة اختيار المشاريع.
    2. في أعلى يسار الشاشة، انقر على مشروع جديد.
    3. أدخِل اسم المشروع.
    4. أدخِل الموقع الجغرافي (مثل "بدون مؤسسة").
    5. انقر على الزر إنشاء.
    6. اختَر مشروعك.

تفعيل Google Health API

  1. في أعلى يمين الشاشة، انقر على رمز القائمة:القائمة
  2. انقر على واجهات برمجة التطبيقات والخدمات > المكتبة.
  3. ابحث عن "Google Health API" وفعِّله.

إعداد بيانات اعتماد OAuth

إذا لم تكن في Google Cloud Console، انتقِل إلى Google Cloud Console.

  1. في أعلى يمين الشاشة، انقر على رمز القائمة:القائمة
  2. انقر على واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.
  3. في أعلى وسط الشاشة، انقر على + إنشاء بيانات اعتماد > معرّف عميل OAuth.
  4. انقر على الزر إعداد شاشة الموافقة. إذا ظهرت الرسالة "لم يتم إعداد منصة مصادقة Google بعد"، انقر على الزر البدء.
  5. في القسم 1:
    1. أدخِل اسم التطبيق.
    2. أدخِل عنوان البريد الإلكتروني لدعم المستخدم.
    3. انقر على الزر التالي.
  6. في القسم 2:
    1. انقر على خارجي.
    2. انقر على الزر التالي.
  7. في القسم 3:
    1. أدخِل عنوان بريدك الإلكتروني في حقل معلومات الاتصال.
    2. انقر على الزر التالي.
  8. في القسم 4:
    1. ضَع علامة في مربّع الاختيار للموافقة على سياسة بيانات مستخدمي خدمات Google API.
    2. انقر على الزر إنشاء.
  9. انتقِل إلى واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد وانقر على + إنشاء بيانات اعتماد > معرّف عميل OAuth.
  10. اختَر نوع التطبيق تطبيق الويب.
  11. أدخِل اسم معرّف العميل.
  12. اترك حقل مصادر JavaScript المفوَّضة فارغًا.
  13. ضمن معرّفات الموارد المنتظمة (URI) المفوَّضة لإعادة التوجيه، انقر على + إضافة عنوان URI وأضِف عناوين URI التالية:
    • https://www.google.com
    • https://developers.google.com/oauthplayground
  14. انقر على الزر إنشاء.
  15. ستعرض Google Console رسالة تفيد بإنشاء معرّف العميل. انقر على الرابط تنزيل JSON لتنزيل معرّف العميل وسرّ العميل، أو اكتب القيم. لن تتمكّن من استرداد سرّ العميل بعد ذلك.
  16. انقر على حسنًا. ستعود إلى صفحة "معرّفات عملاء OAuth 2.0".
  17. ستتم إضافة معرّف العميل إلى مشروعك. انقر على عنوان URL لمعرّف العميل للاطّلاع على التفاصيل.

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

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

إضافة نطاقات إلى معرّف العميل

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

لقد انتهيت من إعداد معرّف العميل.

3. إضافة بيانات إلى تطبيق Fitbit للأجهزة الجوّالة

بالنسبة إلى المستخدمين الجدد في Fitbit، قد لا تتوفّر بيانات في حسابك على Fitbit لإجراء طلبات بحث عنها. سنضيف سجلًّا يدويًا للتمارين يمكننا إجراء طلبات بحث عنه من خلال أحد نقاط النهاية. لتسجيل تمرين يدويًا، اتّبِع الخطوات التالية:

  1. افتح تطبيق Fitbit للأجهزة الجوّالة على جهازك. سجِّل الدخول إلى حسابك على Fitbit إذا لزم الأمر.
  2. في أسفل يسار الشاشة، انقر على الزر +.
  3. في قسم "التسجيل يدويًا"، انقر على النشاط.
  4. ابحث عن نوع التمرين المشي وانقر عليه.
  5. أدخِل وقت بدء اليوم.
  6. غيِّر المدة إلى 15 دقيقة.
  7. اترك المسافة 1.0 ميل.
  8. انقر على إضافة.
  9. يمكنك مزامنة تطبيق الأجهزة الجوّالة مع خوادم Fitbit من خلال النقر مع الاستمرار على الشاشة وسحبها للأسفل. عند رفع إصبعك، من المفترض أن تتم مزامنة تطبيق الأجهزة الجوّالة.
  10. في قسم "النشاط"، من المفترض أن يظهر لك إدخال "المشي" الذي سجّلته يدويًا.لقطة شاشة تعرض نشاط المشي

4. التفويض في مساحة بروتوكول OAuth 2.0

انتقِل إلى مساحة بروتوكول OAuth 2.0.

يتطلّب Google Health API استخدام بيانات اعتماد OAuth الخاصة بك مع مساحة بروتوكول OAuth 2.0.

  1. انقر على رمز الترس إعداد OAuth 2.0 في أعلى يسار الشاشة.
  2. انقر على استخدام بيانات اعتماد OAuth الخاصة بك.
  3. أدخِل معرّف عميل OAuth وسرّ عميل OAuth اللذين حصلت عليهما أثناء إعداد مشروع Google Cloud.

تنقسم واجهة مساحة بروتوكول OAuth 2.0 إلى ثلاث خطوات رئيسية سنتّبعها:

  1. اختيار واجهات برمجة التطبيقات وتفويضها
  2. تبديل رمز التفويض بالرموز المميّزة
  3. إرسال طلب إلى واجهة برمجة التطبيقات

اختيار واجهات برمجة التطبيقات وتفويضها

هذا هو المكان الذي تختار فيه نطاقات واجهة برمجة التطبيقات التي تريد طلبها.

  1. في الخطوة 1، ابحث عن Google Health API v4 في قائمة واجهات برمجة التطبيقات وانقر على السهم لتوسيعها.
  2. اختَر https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly. إذا لم يظهر النطاق الذي تحتاجه في القائمة، يمكنك إدخاله يدويًا في حقل "إدخال نطاقاتك الخاصة".
  3. انقر على تفويض واجهات برمجة التطبيقات.
  4. يتم إرسال طلب إلى نقطة نهاية تفويض OAuth 2.0 من Google، ويتم تضمين النطاقات التي تم اختيارها في الطلب، ثم تتم إعادة توجيهك إلى شاشة الموافقة على حساب Google.
  5. سجِّل الدخول باستخدام حساب مستخدم للاختبار أعددته في قسم إعداد مشروع Google Cloud (إذا لم تكن قد سجّلت الدخول بعد).
  6. راجِع الأذونات المطلوبة وانقر على متابعة لمنح إذن الوصول.

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

تعرض لوحة الطلب / الردّ على يسار الشاشة عملية إعادة التوجيه الكاملة لبروتوكول HTTP.

الردّ من طلب التفويض الأولي هو عملية إعادة توجيه 302 Found:

HTTP/1.1 302 Found
Location: https://accounts.google.com/o/oauth2/v2/auth?redirect_uri=https%3A%2F%2Fdevelopers.google.com%2Foauthplayground&prompt=consent&response_type=code&client_id=your_client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgooglehealth.activity_and_fitness.readonly&access_type=offline

يحتوي الطلب الناتج الذي تمت إعادة توجيهه إلى مساحة بروتوكول OAuth 2.0 على رمز التفويض:

GET /oauthplayground/?iss=https://accounts.google.com&code=authorization_code&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly HTTP/1.1
Host: developers.google.com

رمز التفويض هو القيمة الأبجدية الرقمية التي يمثّلها authorization_code بين code= و&scope في عنوان URL لطلب GET. في هذا المثال، تكون القيمة مشابهة لما يلي: 4/0AbPOj...

تبديل رمز التفويض بالرموز المميّزة

في هذه الخطوة، يتم تبديل الرمز بالرموز المميّزة التي تسمح لك بإجراء طلبات إلى واجهة برمجة التطبيقات.

بعد إكمال اختيار واجهات برمجة التطبيقات وتفويضها ، تملأ مساحة بروتوكول OAuth 2.0 حقل رمز التفويض تلقائيًا. لتبديله بالرموز المميّزة، اتّبِع الخطوات التالية:

  1. انقر على الزر تبديل رمز التفويض بالرموز المميّزة في الخطوة 2.
  2. يظهر access_token وrefresh_token في لوحة الطلب/الردّ على يسار الشاشة.

من المفترض أن يظهر لك ردّ مشابه لما يلي:

{
  "access_token": "ya29.a0AFH6S....",
  "refresh_token_expires_in": 604799,
  "expires_in": 3599,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly",
  "refresh_token": "1/og..."
}

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

عند تبديل رمز التفويض، قد يتضمّن الردّ refresh_token بالإضافة إلى access_token. تكون access_token قصيرة الأجل (عادةً ساعة واحدة). عند انتهاء صلاحية access_token، عليك استخدام refresh_token للحصول على access_token جديد بدون أن يُطلب من المستخدم تسجيل الدخول أو منح الموافقة مرة أخرى. هذا ممكن لأنّنا تضمّنا access_type=offline في طلب التفويض.

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

refresh_token صالح لفترة طويلة، ولكن يمكن أن تنتهي صلاحيته أو يصبح غير صالح إذا لم يتم استخدامه لمدة 6 أشهر، أو إذا أوقف المستخدم إمكانية وصول تطبيقك إلى بياناته، أو لأسباب أخرى. عليك تخزين refresh_token بشكل آمن لاستخدامه في المستقبل.

لمحة عن تعديل النطاقات

إذا كان تطبيقك بحاجة لاحقًا إلى الوصول إلى نطاقات إضافية في Google Health API، عليك أن تطلب من المستخدم إعادة تفويض تطبيقك وطلب المجموعة الكاملة من النطاقات (الحالية والجديدة).

لتعديل النطاقات في طلب التفويض الخاص بتطبيقك، اتّبِع الخطوات التالية:

  1. حدِّد القائمة الكاملة بـ النطاقات التي يحتاجها تطبيقك.
  2. عدِّل المَعلمة scope في عنوان URL للتفويض لتضمين القائمة المعدَّلة لقيم النطاقات مفصولة بمسافات.
  3. ألحِق prompt=consent بمعلّمات عنوان URI للمصادقة. عند تضمين prompt=consent، تظهر شاشة الموافقة في كل مرة يطلب فيها تطبيقك تفويض النطاقات، ما يطلب من المستخدم الموافقة على القائمة المعدَّلة.

بعد أن يكمل المستخدم عملية الموافقة، تتلقّى رمز تفويض جديدًا يمكن تبديله بالرموز المميّزة التي تغطي المجموعة الكاملة من النطاقات.

5. إرسال طلب إلى واجهة برمجة التطبيقات

يمكنك الآن استخدام رمز الدخول لإجراء طلبات إلى Google Health API. في الخطوة 3 في مساحة بروتوكول OAuth 2.0، اضبط طلب HTTP من خلال تحديد عنوان URI للطلب وطريقة HTTP والعناوين ونص الطلب.

  1. اضبط طريقة HTTP على GET.
  2. اضبط عنوان URI للطلب على https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints.
  3. انقر على إرسال الطلب.

من المفترض أن يبدو الردّ مشابهًا لما يلي:

{
  "dataPoints": [
    {
      "name": "users/2515055256096816351/dataTypes/exercise/dataPoints/8896720705097069096",
      "dataSource": {
        "recordingMethod": "MANUAL",
        "platform": "FITBIT"
      },
      "exercise": {
        "interval": {
          "startTime": "2026-02-23T13:10:00Z",
          "startUtcOffset": "-18000s",
          "endTime": "2026-02-23T13:25:00Z",
          "endUtcOffset": "-18000s"
        },
        "exerciseType": "WALKING",
        "metricsSummary": {
          "caloriesKcal": 16,
          "distanceMillimiters": 1609344,
          "steps": "2038",
          "averagePaceSecondsPerMeter": 0.55923407301360051,
          "activeZoneMinutes": "0"
        },
        "exerciseMetadata": {},
        "displayName": "Walk",
        "activeDuration": "900s",
        "exerciseEvents": [
          {
            "eventTime": "2026-02-23T13:10:00Z",
            "eventUtcOffset": "-18000s",
            "exerciseEventType": "START"
          },
          {
            "eventTime": "2026-02-23T13:25:00Z",
            "eventUtcOffset": "-18000s",
            "exerciseEventType": "STOP"
          }
        ],
        "updateTime": "2026-02-24T01:19:22.450466Z"
      }
    },
    {
      "name": "users/2515055256096816351/dataTypes/exercise/dataPoints/5870930690409355408",
      "dataSource": {
        "recordingMethod": "MANUAL",
        "platform": "FITBIT"
      },
      "exercise": {
        "interval": {
          "startTime": "2026-02-23T06:00:00Z",
          "startUtcOffset": "-18000s",
          "endTime": "2026-02-23T06:15:00Z",
          "endUtcOffset": "-18000s"
        },
        "exerciseType": "WALKING",
        "metricsSummary": {
          "caloriesKcal": 17,
          "distanceMillimiters": 1609344,
          "steps": "2038",
          "averagePaceSecondsPerMeter": 0.55923407301360051,
          "averageHeartRateBeatsPerMinute": "81",
          "activeZoneMinutes": "0",
          "heartRateZoneDurations": {
            "lightTime": "900s"
          }
        },
        "exerciseMetadata": {},
        "displayName": "Walk",
        "activeDuration": "900s",
        "exerciseEvents": [
          {
            "eventTime": "2026-02-23T06:00:00Z",
            "eventUtcOffset": "-18000s",
            "exerciseEventType": "START"
          },
          {
            "eventTime": "2026-02-23T06:15:00Z",
            "eventUtcOffset": "-18000s",
            "exerciseEventType": "STOP"
          }
        ],
        "updateTime": "2026-02-23T08:29:39.480437Z"
      }
    }
  ],
  "nextPageToken": ""
}

تتيح العديد من نقاط النهاية معلّمات طلب البحث للفلترة أو التقسيم على صفحات. على سبيل المثال، لعرض التمارين ضمن نطاق زمني محدّد، غيِّر عنوان URI للطلب لتضمين مَعلمة فلتر:

https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints?filter=exercise.interval.civil_start_time >= "2026-02-22T00:00:00"

انقر على إرسال الطلب مرة أخرى للاطّلاع على النتائج التي تم فلترتها.

6. تهانينا

تهانينا!

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

نأمل أن تستمتع بإنشاء تطبيقات تتكامل مع المنظومة المتكاملة لـ Google Health API. لمزيد من المعلومات، استكشِف نقاط نهاية Google Health API الأخرى في المستندات المرجعية وتعرَّف أكثر على Google OAuth 2.0 لـ تطبيقات خادم الويب.