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

1. مقدمة

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

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

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

المتطلبات

• حساب على Google
• تطبيق Fitbit للأجهزة الجوّالة
• مساحة بروتوكول OAuth 2.0

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

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

2. إعداد مشروع على السحابة الإلكترونية من Google

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

ملاحظة: إذا لم تنزّل مفتاح سرّ العميل أو تحفظه، عليك إنشاء مفتاح جديد لأنّه لا يمكنك الاطّلاع عليه مرة أخرى. انقر على حسنًا، ثم في صفحة بيانات الاعتماد، اختَر معرّف العميل من معرّفات عملاء OAuth 2.0. انتقِل إلى قسم أسرار العميل وانقر على + إضافة سر. يتم إنشاء سر عميل جديد، ويجب تنزيله أو حفظه. لأسباب تتعلّق بالأمان، عليك حذف أي أسرار عملاء لم يعُد يتم استخدامها من خلال النقر على رمز الحذف.

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

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

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

1. في اللوحة اليمنى، اختَر الوصول إلى البيانات.
2. انقر على الزر إضافة نطاقات أو إزالتها.
3. في عمود API، ابحث عن "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 الخاصة بك مع Playground.

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

تنقسم واجهة Playground إلى ثلاث خطوات رئيسية سنتبعها:

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 إلى Playground وتوفّر رمز تفويض للأداة، ويتم استخدامه في الخطوة التالية.

تعرض لوحة الطلب / الردّ على يسار الشاشة مسار إعادة التوجيه الكامل عبر 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

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

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...

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

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

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

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 بشكل آمن لاستخدامه في المستقبل.

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

يمكنك الآن استخدام رمز الدخول لإرسال طلبات إلى Google Health API. في الخطوة 3 في "ساحة بروتوكول OAuth"، اضبط طلب 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. تهانينا

تهانينا!

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

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