إجراء طلب بيانات من واجهة برمجة التطبيقات الأول من Google Health

1. مقدمة

يمكن أن يتيح لك Visual Studio Code (VS Code) وإضافة Rest Client من Huachao Mao اختبار مسار الموافقة على Google OAuth وGoogle Health API. سيوضّح لك هذا الدرس التطبيقي حول الترميز كيفية إعداد إضافة Rest Client، وكيفية بدء عملية التفويض وإجراء طلبك الأول إلى أحد نقاط نهاية Google Health API. بعد ذلك، يمكنك قراءة مستندات Rest Client ومستندات Fitbit لإنشاء نقاط النهاية الأخرى في مشروع HTTP.

إذا كنت لا تريد استخدام VS Code وRest Client، يمكن إجراء طلبات البيانات من واجهة برمجة التطبيقات باستخدام أوامر curl.

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

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

المتطلبات

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

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

لتثبيت أدوات Visual Studio، اتّبِع الخطوات التالية:

  1. نزِّل VS Code. عادةً ما يحتوي التنزيل على الملف التنفيذي.
  2. ابدأ تشغيل VS Code.
  3. ثبِّت إضافة Rest Client من Huachao Mao.
    • انقر على رمز الإضافة ميزة "تأكيد السلامة" على يمين بيئة التطوير المتكاملة (IDE).
    • ابحث عن REST Client by Huachao Mao، ثم انقر على Install (تثبيت).

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). أدخِل "https://www.google.com" كمعرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه.
  14. انقر على الزر إنشاء.
  15. ستعرض "وحدة تحكّم Google" رسالة تفيد بأنّه تم إنشاء معرّف العميل. انقر على الرابط تنزيل JSON لتنزيل معرّف العميل وسر العميل، أو اكتب القيم. لن تتمكّن من استرداد سر العميل بعد ذلك.
  16. انقر على موافق. ستتم إعادتك إلى صفحة "معرّفات العميل لبروتوكول OAuth 2.0".
  17. ستتم إضافة معرّف العميل إلى مشروعك. انقر على عنوان URL لمعرّف العميل للاطّلاع على التفاصيل.

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

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

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

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

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

3- إنشاء مسار التفويض

  1. افتح تطبيق VS Code على جهازك.
  2. في شاشة الترحيب، انقر على فتح.
  3. اختَر مجلدًا لإنشاء هذا المشروع واضغط على فتح. يجب أن تظهر شاشتك بشكل مشابه لما يلي، مع عرض اسم المجلد أو المشروع في "المستكشف".VSC
  4. من القائمة الرئيسية، اختَر ملف -> ملف نصي جديد.
  5. احفظ الملف لتسميته. من القائمة الرئيسية، اختَر ملف (File) -> حفظ باسم (Save As) -> Codelab.http. سيؤدي ذلك إلى وضع الملف في مشروعك. يجب أن يكون امتداد الملف ‎ .http أو ‎ .rest. في هذا الدرس التطبيقي، سنستخدم .http.

خلال هذا المشروع، سنستخدم عدة قيم عدة مرات. وهذه القيم هي:

client_id

قيمة معرّف العميل من وحدة تحكّم Google

secret

قيمة سر العميل من وحدة تحكّم Google

redirect_uri

نقطة نهاية في تطبيقك تعالج رمز التفويض. في هذا الدرس العملي، سنستخدم https://www.google.com

access_token

رمز الدخول الذي تم إنشاؤه للمستخدم بعد انتهاء مسار الموافقة

refresh_token

الرمز المميز لإعادة التحميل الذي تم إنشاؤه للمستخدم بعد انتهاء مسار الموافقة

أضِف الرمز التالي الذي يحدّد المتغيّرات المستخدَمة في هذا المشروع. يجب أن تكون في أعلى ملف Codelab.http. املأ قيمتَي client_id وsecret.

### File Variables for the Codelab
@client_id =
@secret =
@redirect_uri = https://www.google.com
@accessToken={{user.response.body.access_token}}
@refreshToken={{user.response.body.refresh_token}}

سيتم إرسال عنوان URL الخاص بالتفويض، والذي يُستخدَم لبدء مسار الموافقة، إلى كل مستخدم تريد الوصول إلى بياناته. لإنشاء عنوان URL الخاص بالتفويض، نحتاج إلى معرفة نقطة نهاية Google OAuth واستخدام مَعلمات طلب البحث لتحديد معرّف العميل والنطاقات التي نريد الوصول إليها والمكان الذي ستتم إعادة توجيه المستخدم إليه عند موافقته على النطاقات. يمكنك العثور على المستندات الكاملة الخاصة بإنشاء سلسلة تفويض Google في المستندات.

تتوفّر نقطة نهاية OAuth 2.0 من Google على الرابط https://accounts.google.com/o/oauth2/v2/auth. لا يمكن الوصول إلى نقطة النهاية هذه إلا عبر HTTPS. يتم رفض اتصالات HTTP العادية.

يتيح خادم التفويض من Google العديد من مَعلمات سلسلة طلب البحث لتطبيقات خادم الويب من أجل تخصيص مسار التفويض. سنستخدم مَعلمات طلب البحث المطلوبة التالية: client_id وredirect_uri وresponse_type وscope. تقدّم المستندات قائمة بجميع مَعلمات طلب البحث ووصفها.

قيم مَعلمات طلب البحث هي

client_id

قيمة معرّف العميل من وحدة تحكّم Google

redirect_uri

نقطة نهاية في تطبيقك تعالج رمز التفويض. بالنسبة إلى الدرس العملي، استخدِم https://www.google.com

response_type

code (قيمة مسموح بها لتطبيقات الويب)

scope

تأتي النطاقات من وحدة تحكّم Google مع بنية https://www.googleapis.com متبوعة باسم النطاق. على سبيل المثال، https://www.googleapis.com/auth/googlehealth.activity_and_fitness.

لطلب نطاقات متعددة، أدرِج جميع النطاقات في مَعلمة النطاق، مع الفصل بينها بمسافات (مثلاً، scope1 scope2 scope3). عندما تكون المسافات جزءًا من عنوان URL، يجب ترميزها بعنوان URL (مثلاً، %20).

بعد المتغيرات، اكتب عنوان URL الخاص بالتفويض كما هو موضّح. لا يمكن استخدام المَعلمات المحدّدة في أعلى المشروع في سلسلة التفويض. لذلك، علينا تضمين قيم client_id وredirect_uri. استبدِل السلسلة client-id بمعرّف العميل.

### Google Health API Rest Client Example

### Authorization String
https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=https://www.google.com&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly

عندما يمنح المستخدم الموافقة، تقدّم Google رمز تفويض يمكنك استبداله برمز دخول من خلال طلب نقطة نهاية الرمز المميّز من Google. أضِف التعريف التالي لاستدعاء نقطة نهاية الرمز المميز إلى Codelab.http أسفل سلسلة التفويض. ستستبدل authorization-code برمز تفويض في الخطوة التالية.

### AUTHORIZATION ENDPOINTS
######################################################################
# @name user
POST https://oauth2.googleapis.com/token
Content-Type: application/x-www-form-urlencoded

code=authorization-code&client_id={{clientId}}&client_secret={{secret}}&redirect_uri={{redirect_uri}}&grant_type=authorization_code

يشير @name user إلى المستخدم الحالي الذي يتم الوصول إلى بياناته.

4. تفويض حساب والحصول على رموز مميّزة

سنشرح الآن مسار التفويض للحصول على رموز التفويض.

يتم استخدام سلسلة التفويض في Codelab.http لبدء مسار الموافقة المستند إلى المتصفّح من Google. قد تعرض إضافة Rest Client رابط إرسال الطلب لعنوان URL هذا. لا تستخدِم الزر إرسال الطلب لعنوان URL المحدّد هذا. بدلاً من ذلك، انسخ الرابط والصقه في المتصفّح، أو استخدِم Ctrl+Click (في Windows أو Linux) أو Cmd+Click (في Mac) في VS Code لفتحه في المتصفّح التلقائي.

https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=https://www.google.com&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  1. سيُطلب منك تسجيل الدخول إلى حساب Google. يجب تسجيل الدخول باستخدام أحد حسابات المستخدمين التجريبيين التي أعددتها في قسم إضافة مستخدمين تجريبيين.
  2. قد تظهر لك رسالة تفيد بأنّه لم يتم التحقّق من التطبيق. ويرجع ذلك إلى عدم نشر التطبيق. اضغط على "متابعة".

لقطة شاشة تعرض تحذيرًا بشأن تطبيق لم يتم التحقّق منه

  1. تعرض صفحة الموافقة النطاقات المطلوب الوصول إليها. يُتاح للمستخدم اختيار النطاقات التي يريد مشاركتها مع هذا التطبيق. انقر على "متابعة".

بعد الموافقة على مشاركة النطاقات المطلوبة، سيُعاد توجيهك إلى redirect_uri الذي حدّدته (في هذا الدرس التطبيقي حول الترميز، https://www.google.com). تضيف Google رمز تفويض ومَعلمات أخرى إلى redirect_uri، لذا يجب أن يظهر عنوان URL في شريط عناوين المتصفّح على النحو التالي:

https://www.google.com/?code=4/0Ab32j93oyGWqaXE112sP1IKmh3kV1fE4tcHIMXYJQYWgNEtAa_0-YsfkS9Ekj3Be89u3fw&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly

رمز التفويض هو القيمة الأبجدية الرقمية بين "code=‎" و "&scope". في المثال أعلاه، تكون القيمة:

4/0Ab32j93oyGWqaXE112sP1IKmh3kV1fE4tcHIMXYJQYWgNEtAa_0-YsfkS9Ekj3Be89u3fw

في تطبيق متاح للجميع، سيحلّل الخادم هذا الرمز من مَعلمات عنوان URL. بالنسبة إلى هذا الدرس العملي، انسخ رمز التفويض من عنوان URL في المتصفّح.

الآن، بدِّل رمز التفويض هذا برمز access_token وrefresh_token. في Codelab.http، استبدِل authorization-code في نص طلب POST /token برمز التفويض الذي نسخته.

POST https://oauth2.googleapis.com/token
Content-Type: application/x-www-form-urlencoded

code=authorization-code&client_id={{client_id}}&client_secret={{secret}}&redirect_uri={{redirect_uri}}&grant_type=authorization_code

انقر على الرابط إرسال الطلب فوق السطر POST https://oauth2.googleapis.com/token مباشرةً.

يجب أن تبدو الاستجابة مشابهة لما يلي:

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

عند تلقّي هذا الردّ، يملأ Rest Client تلقائيًا المتغيّرات @accessToken و@refreshToken المحدّدة في أعلى Codelab.http لاستخدامها في الطلبات اللاحقة.

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

عند استبدال رمز التفويض، قد تتضمّن الاستجابة 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- إضافة بيانات إلى تطبيق Fitbit للأجهزة الجوّالة

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

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

6. استرداد البيانات باستخدام طريقة القائمة

لاستدعاء طريقة list، أضِف الرمز التالي إلى Codelab.http، أسفل نقطة النهاية /token مباشرةً.

### users.dataTypes.dataPoints
#####################################################

### LIST exercise
GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer {{accessToken}}
Accept: application/json

يطلب هذا الرمز نقطة النهاية list لعرض الخطوات التي سجّلها المستخدم في حسابه على Fitbit. سيتم عرض عدد الخطوات لكل دقيقة في الردّ، على غرار نقطة نهاية Activity Intraday في الإصدار 1 من Fitbit Web API.

لتنفيذ الطلب، انقر على الرابط إرسال الطلب لنقطة نهاية GET. يجب أن تبدو استجابتك مشابهة لما يلي:

{
  "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": ""
}

تتيح العديد من نقاط النهاية مَعلمات طلب البحث للفلترة أو التقسيم إلى صفحات. على سبيل المثال، تتيح التمارين استخدام الفلتر interval.civil_start_time. أضِف الطلب التالي إلى Codelab.http لإدراج التمارين ضمن نطاق زمني محدّد:

### LIST exercise >= civil start time
GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints?filter=exercise.interval.civil_start_time >= "2026-02-22T00:00:00"
Authorization: Bearer {{accessToken}}
Accept: application/json

7. تهانينا

تهانينا!

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

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