اشتراكات الويب هوك

ستتوفّر الاشتراكات قريبًا.

تتيح واجهة برمجة التطبيقات Google Health API لتطبيقك تلقّي إشعارات في الوقت الفعلي عند حدوث تغيير في بيانات الصحة الخاصة بالمستخدم. بدلاً من الاستقصاء عن التغييرات، يتلقّى الخادم طلب HTTPS POST (ويب هوك) فور توفّر البيانات في Google Health API.

أنواع البيانات المتوافقة

تتوفّر إشعارات Webhook لأنواع البيانات التالية:

• الخطوات
• الارتفاع
• المسافة
• الطوابق
• الوزن
• النوم

يتم إرسال الإشعارات لأنواع البيانات هذه فقط عندما يمنح المستخدم موافقته على أحد النطاقات التالية:

• النشاط، الذي يشمل أنواع البيانات المتعلقة بالخطوات والارتفاع والمسافة والأدوار:
  • https://www.googleapis.com/auth/googlehealth.activity_and_fitness
  • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
• مقاييس الصحة، التي تشمل نوع بيانات الوزن:
  • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements
  • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
• النوم، الذي يغطي نوع بيانات النوم:
  • https://www.googleapis.com/auth/googlehealth.sleep
  • https://www.googleapis.com/auth/googlehealth.sleep.readonly

إدارة المشتركين

قبل أن تتمكّن من تلقّي الإشعارات، عليك تسجيل "مشترك"، وهو يمثّل نقطة نهاية الإشعارات في تطبيقك. يمكنك إدارة المشتركين باستخدام REST API المتاحة على projects.subscribers.

يجب أن يستخدم نقطة نهاية المشترك بروتوكول HTTPS (الإصدار 1.2 من TLS أو أحدث) وأن تكون متاحة للجميع. أثناء إنشاء المشتركين وتعديلهم، تنفِّذ Google Health API عملية التحقّق من خلال طرح سؤال للتأكّد من أنّك تملك معرّف الموارد المنتظم (URI) لنقطة النهاية. في حال فشل عملية التحقّق، ستفشل عمليات إنشاء المشتركين وتعديلهم مع ظهور الخطأ FailedPreconditionException.

إنشاء مشترك

لتسجيل مشترك جديد في مشروعك، استخدِم نقطة النهاية create. يجب تقديم ما يلي:

• ‫endpointUri: تحدّد عنوان URL المقصود لإشعارات الويب هوك.
• subscriberConfigs: أنواع البيانات التي تريد تلقّي إشعارات بشأنها، وسياسة الاشتراك لكل نوع
• endpointAuthorization: آلية التفويض لنقطة النهاية يجب أن يحتوي هذا الحقل على authorization_token تقدّمه أنت. يتم إرسال قيمة authorization_token في العنوان Authorization مع كل رسالة إشعار. يمكنك استخدام هذا الرمز المميز للتأكّد من أنّ الطلبات الواردة صادرة من Google Health API. على سبيل المثال، يمكنك ضبط authorization_token على Bearer R4nd0m5tr1ng123 لمصادقة Bearer، أو Basic dXNlcjpwYXNzd29yZA== لمصادقة Basic.
• subscriberId: معرّف فريد تقدّمه للمشترك. يجب أن يتراوح عدد الأحرف في هذا المعرّف بين 4 و36 حرفًا، وأن يتطابق مع التعبير العادي ([a-z]([a-z0-9-]{2,34}[a-z0-9])).

في subscriberConfigs، يجب ضبط subscriptionCreatePolicy لكل نوع بيانات. اضبط القيمة على AUTOMATIC لاستخدام الاشتراكات التلقائية، أو على MANUAL إذا كنت تنوي إدارة اشتراكات المستخدمين بنفسك. يمكنك الاطّلاع على الاشتراكات التلقائية والاشتراكات اليدوية لمعرفة المزيد من التفاصيل حول كل خيار.

طلب

POST https://health.googleapis.com/v4/projects/project-id/subscribers?subscriberId=subscriber-id
{
  "endpointUri": "https://myapp.com/webhooks/health",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorization_token": "Bearer example-secret-token"
  }
}

الردّ

{
  "name": "projects/project-id/subscribers/subscriber-id",
  "endpointUri": "https://myapp.com/webhooks/health",
  "state": "ACTIVE",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorizationTokenSet": true
  }
}

عرض قائمة المشتركين

استخدِم نقطة نهاية list لاسترداد جميع المشتركين المسجّلين في مشروعك.

طلب

GET https://health.googleapis.com/v4/projects/project-id/subscribers

الردّ

{
  "subscribers": [
    {
      "name": "projects/project-id/subscribers/subscriber-id",
      "endpointUri": "https://myapp.com/webhooks/health",
      "state": "ACTIVE",
      "subscriberConfigs": [
        {
          "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
          "subscriptionCreatePolicy": "AUTOMATIC"
        },
        {
          "dataTypes": ["sleep"],
          "subscriptionCreatePolicy": "MANUAL"
        }
      ],
      "endpointAuthorization": {
        "authorizationTokenSet": true
      }
    }
  ],
  "nextPageToken": ""
}

تعديل مشترك

استخدِم نقطة النهاية patch لتعديل بيانات أحد المشتركين في مشروعك. الحقول التي يمكن تعديلها هي endpointUri وsubscriberConfigs وendpointAuthorization.

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

في حال تعديل endpointUri أو endpointAuthorization، يتم إجراء عملية التحقّق من نقطة النهاية. يُرجى الاطّلاع على مقالة التحقّق من نقطة النهاية لمعرفة التفاصيل.

عند تعديل subscriberConfigs، يُرجى العِلم أنّ ذلك سيؤدي إلى استبدال كامل، وليس إلى دمج. في حال تضمين subscriberConfigs في updateMask، سيتم استبدال جميع عمليات الإعداد المخزّنة للمشترك بالقائمة المقدَّمة في نص الطلب. لإضافة إعداد أو إزالته، يجب تقديم المجموعة الكاملة من الإعدادات. إذا كنت تعدّل حقولاً أخرى وأردت الاحتفاظ بإعداداتك الحالية، احذف subscriberConfigs من updateMask.

طلب

PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id?updateMask=endpointUri
{
  "endpointUri": "https://myapp.com/new-webhooks/health"
}

الردّ

{
  "name": "projects/project-id/subscribers/subscriber-id",
  "endpointUri": "https://myapp.com/new-webhooks/health",
  "state": "ACTIVE",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorizationTokenSet": true
  }
}

التحقّق من نقطة النهاية

لضمان أمان عملية إرسال الإشعارات وموثوقيتها، تنفّذ واجهة برمجة التطبيقات Google Health API عملية تأكيد الاتصال الإلزامي بخطوتين عند إنشاء مشترك أو تعديل إعدادات نقطة النهاية (endpointUri أو endpointAuthorization). ويتم تنفيذ هذه العملية بشكل متزامن أثناء طلب البيانات من واجهة برمجة التطبيقات. ترسل الخدمة طلبَي POST آليَين إلى معرّف الموارد المنتظم (URI) لنقطة النهاية، باستخدام User-Agent Google-Health-API-Webhooks-Verifier، مع نص JSON {"type": "verification"}.

• المصافحة المصرَّح بها: يتم إرسال الطلب الأول مع عنوان Authorization الذي تم ضبطه. يجب أن يستجيب الخادم برمز حالة 200 OK أو 201 Created.
• التحقّق غير المصرّح به: يتم إرسال الطلب الثاني بدون بيانات اعتماد. يجب أن يستجيب الخادم برمز حالة 401 Unauthorized أو 403 Forbidden.

يؤكّد هذا المصافحة أنّ نقطة النهاية نشطة وتفرض الأمان بشكل صحيح. في حال تعذُّر تنفيذ أيّ من الخطوتَين، سيتعذّر تنفيذ طلب البيانات من واجهة برمجة التطبيقات وسيظهر الخطأ FAILED_PRECONDITION. ولن يتم حفظ المشترك وتفعيله لتلقّي إشعارات بيانات الصحة إلا بعد نجاح عملية المصافحة هذه.

تدوير المفتاح

إذا كنت بحاجة إلى تدوير المفاتيح لـ endpointAuthorization، اتّبِع الخطوات التالية:

1. اضبط نقطة النهاية لقبول القيم القديمة والجديدة endpointAuthorization.
2. عدِّل إعدادات المشترك باستخدام قيمة endpointAuthorization الجديدة باستخدام طلب patch مع ?updateMask=endpointAuthorization.
3. اضبط نقطة النهاية لقبول القيمة الجديدة endpointAuthorization فقط بعد التأكّد من نجاح الخطوة 2.

حذف مشترك

استخدِم نقطة النهاية delete لإزالة مشترك من مشروعك. بعد حذف المشترك، لن يتلقّى أي إشعارات.

طلب

DELETE https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id

الردّ

يتم عرض نص استجابة فارغ مع حالة HTTP‏ `200 OK` في حال تم الحذف بنجاح.

{}

اشتراكات المستخدم

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

الاشتراكات التلقائية

ننصح باستخدام الاشتراكات التلقائية. لتفعيل هذه الميزة، اضبط قيمة subscriptionCreatePolicy على AUTOMATIC في subscriberConfigs لأنواع البيانات المحدّدة. إنّ dataTypes الذي تحدّده باستخدام سياسة AUTOMATIC هو نفسه أنواع البيانات التي ترسل Google Health API إشعارات بشأنها، شرط أن يوافق المستخدم أيضًا على أنواع البيانات هذه.

عندما يمنح المستخدم موافقة التطبيق لنطاقات تتوافق مع أنواع البيانات التي تتضمّن سياسة AUTOMATIC، تتتبّع Google Health API تلقائيًا أنواع البيانات الناتجة عن التقاطع بين أنواع البيانات التي يمكن جمعها بموافقة المستخدم وأنواع البيانات التلقائية لإعدادات المشترك لهذا المستخدم، وترسل إشعارات بشأنها. بعد ذلك، يتم إرسال الإشعارات إلى نقطة النهاية كلما أنشأ هذا المستخدم بيانات جديدة لهذه الأنواع. ويعمل ذلك مع المستخدمين الذين يمنحون الموافقة قبل إنشاء المشترك أو بعده. لا تتم إعادة ملء الإشعارات بالبيانات التي تم إنشاؤها قبل إنشاء المشترك.

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

الاشتراكات اليدوية

إذا كنت تفضّل إدارة الاشتراكات لكل مستخدم يدويًا، اضبط قيمة subscriptionCreatePolicy على MANUAL في subscriberConfigs. باستخدام هذه السياسة، لن يتم إنشاء اشتراكات المستخدمين تلقائيًا. سيتم استخدام هذه الوظيفة في المستقبل عند توفّر واجهات برمجة التطبيقات لإدارة الاشتراكات اليدوية. إلى أن تتوفّر واجهات برمجة التطبيقات هذه، ننصحك باستخدام AUTOMATICالاشتراكات.

الإشعارات

عندما تتغيّر بيانات المستخدم لنوع بيانات تم الاشتراك فيه، ترسل Google Health API طلب HTTPS POST إلى عنوان URL لنقطة نهاية المشترك.

تنسيق الإشعار

حمولة الإشعار هي عنصر JSON يحتوي على تفاصيل حول تغيير البيانات. ويشمل ذلك معرّف المستخدم ونوع البيانات والفواصل الزمنية التي يمكنك استخدامها للاستعلام عن البيانات المعدَّلة.

{
  "data": {
    "version": "1",
    "clientProvidedSubscriptionName": "subscription-name",
    "healthUserId": "health-user-id",
    "operation": "UPSERT",
    "dataType": "steps",
    "intervals": [
      {
        "physicalTimeInterval": {
          "startTime": "2026-03-0B01:29:00Z",
          "endTime": "2026-03-08T01:34:00Z"
        },
        "civilDateTimeInterval": {
          "startDateTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 7
            },
            "time": {
              "hours": 17,
              "minutes": 29
            }
          },
          "endDateTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 7
            },
            "time": {
              "hours": 17,
              "minutes": 34
            }
          }
        },
        "civilIso8601TimeInterval": {
          "startTime": "2026-03-07T17:29:00",
          "endTime": "2026-03-07T17:34:00"
        }
      }
    ]
  }
}

يشير الحقل operation إلى نوع التغيير الذي أدّى إلى إرسال الإشعار:

• UPSERT: يتم إرسالها عند إضافة أي بيانات أو تعديلها.
• DELETE: يتم إرسال هذا النوع من الإشعارات عندما يحذف المستخدم البيانات، أو عندما تتم إزالة البيانات بسبب حدث في النظام، مثل إلغاء المستخدم الإذن أو حذف حسابه.

ننصحك بجعل منطق معالجة الإشعارات غير قابل للتكرار، خاصةً بالنسبة إلى عمليات UPSERT، لأنّ عمليات إعادة المحاولة يمكن أن تؤدي إلى إرسال إشعارات مكرّرة.

الحقل clientProvidedSubscriptionName هو معرّف فريد. بالنسبة إلى الاشتراكات التي تتضمّن سياسة MANUAL، يحتوي هذا الحقل على اسم الاشتراك الدائم الذي يقدّمه المطوّر والذي تم تحديده عند إنشاء الاشتراك. يوفّر ذلك معرّفًا ثابتًا لإدارة الاشتراكات اليدوية. بالنسبة إلى الاشتراكات التي تم إنشاؤها باستخدام سياسة AUTOMATIC، تنشئ Google Health API تلقائيًا معرّفًا فريدًا (معرّف UUID عشوائي) وتعيّنه لهذا الحقل لكل إشعار. يضمن تضمين clientProvidedSubscriptionName لكل من السياسات اليدوية والتلقائية تنسيقًا متسقًا لحِزمة بيانات الإشعارات في جميع أنواع الاشتراكات.

‫healthUserId هو معرّف Google Health API للمستخدم الذي تم تغيير بياناته. إذا كان تطبيقك يتيح استخدام حسابات متعددة، قد تتلقّى إشعارات لأي مستخدم منح تطبيقك الموافقة. عند تلقّي إشعار، استخدِم healthUserId لتحديد بيانات المستخدم التي تم تغييرها، حتى تتمكّن من استخدام بيانات اعتماد OAuth الخاصة به للاستعلام عن بياناته.

لربط بيانات اعتماد OAuth الخاصة بالمستخدم بحسابه على healthUserId، استخدِم نقطة النهاية getIdentity. يمكنك طلب نقطة النهاية هذه باستخدام بيانات اعتماد المستخدم أثناء عملية إعداد المستخدم لاسترداد healthUserId وتخزين عملية الربط هذه. لا تتغيّر عملية الربط هذه بمرور الوقت، لذا يمكن تخزينها مؤقتًا إلى أجل غير مسمى. للاطّلاع على مثال، يُرجى الرجوع إلى الحصول على رقم تعريف المستخدم. يتيح لك ذلك اختيار بيانات اعتماد المستخدم الصحيحة عند طلب البيانات استنادًا إلى healthUserId في أحد الإشعارات.

الردّ على إشعار

يجب أن يستجيب الخادم للإشعارات برمز الحالة HTTP 204 No Content على الفور. لتجنُّب انتهاء المهلة، عالِج حمولة الإشعار بشكل غير متزامن بعد إرسال الرد. إذا تلقّت واجهة برمجة التطبيقات Google Health API أي رمز حالة آخر أو انتهت مهلة الطلب، ستعيد محاولة إرسال الإشعار لاحقًا.

مثال على Node.js (Express):

app.post('/webhook-receiver', (req, res) => {
    // 1. Immediately acknowledge the notification
    res.status(204).send();

    // 2. Process the data asynchronously in the background
    const notification = req.body;
    setImmediate(() => {
        console.log(`Update for user ${notification.data.healthUserId} of type ${notification.data.dataType}`);
        // Trigger your data retrieval logic here
    });
});

حالة الاشتراك واسترداده

إذا أصبح عنوان URL لنقطة نهاية المشترك غير متاح أو عرض رمز حالة خطأ (أي رمز آخر غير 204)، سيخزّن Google Health API الإشعارات المعلقة لمدة تصل إلى 7 أيام وسيعيد محاولة تسليمها باستخدام التراجع الأسي.

بعد أن يعود الجهاز إلى الاتصال بالإنترنت ويستجيب بالرمز 204، ستسلّم واجهة برمجة التطبيقات تلقائيًا الرسائل المتراكمة المخزّنة. يتم تجاهل الإشعارات التي مضى عليها أكثر من 7 أيام ولا يمكن استردادها.