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

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

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

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

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

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

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

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

حسابات الخدمة في "إدارة الهوية وإمكانية الوصول" (IAM)

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

بيانات الاعتماد التلقائية القصيرة الأجل: عند إرفاق حسابات الخدمة ببيئة تنفيذ على Google Cloud (مثل Compute Engine أو Cloud Run أو Google Kubernetes Engine)، تحصل هذه الحسابات تلقائيًا على بيانات اعتماد آمنة وقصيرة الأجل وتُجدّدها. ويزيل ذلك مخاطر إدارة المفاتيح الثابتة الدائمة وتخزينها.
مبدأ منح الحد الأدنى من الامتيازات: توفّر حسابات الخدمة هويات مخصّصة لأحمال العمل. يمكنك منحها الأذونات المحدّدة اللازمة لإدارة نقاط نهاية المشتركين فقط، ما يمنع الوصول الأوسع إلى مواردك على Google Cloud.
استقلالية دورة الحياة: تعمل حسابات الخدمة بشكل مستقل عن حساب أي مستخدم فردي، ما يضمن عدم تأثُّر استقرار المصادقة على المدى الطويل بتغييرات الموظفين.

إعداد حساب خدمة

لضبط تطبيق المشترك للمصادقة باستخدام حساب خدمة:

إنشاء حساب خدمة: في Google Cloud Console، انتقِل إلى صفحة "المشرف وإدارة الهوية وإمكانية الوصول" في مشروعك لـ إنشاء حساب خدمة جديد يديره المستخدم.
منح أدوار "إدارة الهوية وإمكانية الوصول" اللازمة: عليك منح حساب الخدمة الأدوار المناسبة المطلوبة لإدارة المشتركين في مشروعك على Google Cloud.
إرفاق حساب الخدمة بحمل العمل: عليك ضبط البيئة التي تستضيف منطق المشترك لتشغيلها كحساب الخدمة الجديد. يسمح ذلك لـ الرمز البرمجي للتطبيق (مثل مكتبات برامج Google API) برصد بيانات الاعتماد القصيرة الأجل لحساب الخدمة واستخدامها تلقائيًا عند استدعاء واجهة برمجة التطبيقات projects.subscribers من نوع REST API.

أدوار CPE

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

القراءة في واجهة برمجة التطبيقات Google Health API
محرِّر في واجهة برمجة التطبيقات Google Health API
مشرف في واجهة برمجة التطبيقات Google Health API

مزيد من المعلومات حول أدوار وأذونات "إدارة الهوية وإمكانية الوصول" في واجهة برمجة التطبيقات Google Health API.

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

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

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

إنشاء مشترك

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

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

في 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": {
    "secret": "Bearer example-secret-token"
  }
}

الردّ

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

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

استخدِم نقطة النهاية 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",
      "subscriberConfigs": [
        {
          "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
          "subscriptionCreatePolicy": "AUTOMATIC"
        },
        {
          "dataTypes": ["sleep"],
          "subscriptionCreatePolicy": "MANUAL"
        }
      ],
      "endpointAuthorization": {
        "authorizationTokenSet": true
      }
    }
  ],
  "totalSize": 1
}

تعديل مشترك

استخدِم نقطة النهاية 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",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ]
}

حذف مشترك

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

طلب

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

الردّ

يتم عرض نص ردّ فارغ مع حالة HTTP `200 OK` إذا نجحت عملية الحذف.

{}

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

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

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

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

تجديد المفاتيح

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

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

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

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

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

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

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

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

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

إذا تم ضبط المشترك باستخدام subscription_create_policy من نوع MANUAL لأنواع بيانات محدّدة، عليك إنشاء الاشتراكات وإدارتها بشكل صريح لكل مستخدم. يربط الاشتراك مستخدمًا معيّنًا بنقطة نهاية المشترك لمجموعة محدّدة من أنواع البيانات. يمكن للمطوّرين استخدام واجهات برمجة تطبيقات محدّدة لإجراء ما يلي:

إنشاء اشتراكات (يدوية) لكل healthUserId : يؤدي ذلك إلى إنشاء اشتراك جديد لمستخدم معيّن. تتطلب هذه الطريقة أن يكون لدى المشترك SubscriptionCreatePolicy مضبوط على MANUAL لأنواع البيانات المطلوبة.
تعديل الاشتراك (اليدوي): يؤدي ذلك إلى تعديل أنواع البيانات لاشتراك مستخدم حالي.
حذف الاشتراك (اليدوي): يؤدي ذلك إلى حذف اشتراك مستخدم معيّن. بعد حذف الاشتراك، لن تتلقّى نقطة نهاية المشترك بعد ذلك إشعارات لهذا المستخدم لأنواع البيانات المرتبطة.
إدراج الاشتراكات (اليدوية): يؤدي ذلك إلى إدراج جميع الاشتراكات النشطة لمشترك معيّن. يمكنك فلترة النتائج حسب المستخدم أو نوع البيانات.

الإشعارات

عندما تتغيّر بيانات المستخدم لنوع بيانات مشترك فيه، تُرسِل واجهة برمجة التطبيقات 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-08T01: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 في الإشعار.

تجميع التعديلات

للحدّ من حركة بيانات الشبكة، تُجمِّع واجهة برمجة التطبيقات Google Health API الرسائل معًا. تم ضبط النظام على إرسال 99 رسالة كحد أقصى لكل دفعة، ويتم إرسالها تلقائيًا فور توفّرها.

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

يجب أن يردّ خادمك على الإشعارات برمز حالة 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
    });
});

هناك ثلاث استراتيجيات شائعة لتعديل قاعدة البيانات بعد تلقّي إشعار بتغيير البيانات:

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

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

أفضل الممارسات

اتّبِع أفضل الممارسات التالية لضمان معالجة تعديلات البيانات بشكل موثوق وفعّال:

استخدِم Subscription API: استخدِم Subscription API لتلقّي إشعار عندما يكون لدى المستخدم بيانات جديدة لتنزيلها بدلاً من التحقّق من نقاط النهاية.
ضع الإشعارات في قائمة الانتظار وعالجها بشكل منفصل: عند تلقّي إشعارات الاشتراك ، ضعها في قائمة انتظار وعالجها بشكل منفصل استنادًا إلى موارد نظامك. حافظ على نقطة نهاية ويب هوك خفيفة الوزن من خلال تأكيد الطلب على الفور.

التحقّق من التوقيع

لضمان صحة إشعارات ويب هوك، يتم توقيع حمولة JSON غير المنسّقة لكل إشعار ويب هوك صادر باستخدام مفتاح خاص باستخدام PublicKeySign من Tink، ما يوفّر التوقيع المرمَّز بـ Base64 في عنوان HTTP GOOGLE-HEALTH-API-SIGNATURE في الطلب. يتم تجديد مفاتيح التوقيع هذه تلقائيًا كل 30 يومًا، ويتم توزيع مجموعة المفاتيح العلنية الرسمية المقابلة كملف JSON على عنوان URL الدائم https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json.

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

باستخدام Tink (ننصح بذلك): يمكن للمطوّرين التحقّق من التوقيع باستخدام PublicKeyVerify من Tink. عليك جلب مجموعة المفاتيح العلنية من عنوان URL الدائم، وإنشاء PublicKeyVerify باستخدام مجموعة المفاتيح، والتحقّق من عنوان GOOGLE-HEALTH-API-SIGNATURE الذي تم فك ترميزه مقابل حمولة JSON غير المنسّقة لويب هوك.

التحقّق اليدوي (بدون Tink): إذا اختار المطوّرون عدم استخدام Tink، يمكنهم التحقّق من التوقيع يدويًا باتّباع الخطوات التالية:

فك ترميز عنوان GOOGLE-HEALTH-API-SIGNATURE باستخدام Base64 لفصل بادئة Tink المكوّنة من 5 بايت (التي تحتوي على بادئة إصدار مكوّنة من بايت واحد وkeyId مكوّن من 4 بايت) عن التوقيع الفعلي المرمَّز بـ DER.
عليك جلب مجموعة مفاتيح JSON من https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json.
عليك تحديد المفتاح الذي يتطابق مع keyId الذي تم تحليله وفك ترميز حقل القيمة باستخدام Base64، والذي يحتوي على مخزن مؤقت للبروتوكول EcdsaPublicKey الذي تم تسلسله.
عليك استخراج الإحداثيات x وy الكبيرة (علامتا Protobuf 3 و4) من حمولة البيانات الثنائية هذه.
عليك إنشاء مفتاح علني قياسي ECDSA P-256 في مكتبة تشفير مضمّنة باستخدام الإحداثيات x وy المستخرَجة.
عليك التحقّق من حمولة JSON غير المنسّقة لويب هوك مقابل توقيع DER المستخرَج باستخدام خوارزمية SHA-256.

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

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

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

الأخطاء الشائعة

رمز الخطأ	رسالة	الوصف	الاقتراح
400 طلب غير صالح	رقم تعريف مشروع غير صالح في اسم المورد	عند حذف مشترك أو تعديل بياناته باستخدام رقم تعريف مشروعك على Google Cloud في عنوان URL للطلب بدلاً من رقم تعريف المشروع. ينطبق ذلك على اشتراكات ويب هوك باستخدام نقطة النهاية `projects.subscribers`.	استخدِم رقم تعريف مشروعك على Google Cloud في عنوان URL للطلب، وليس رقم تعريف المشروع.
403 Forbidden	ليس لدى المتصل إذن	عند إنشاء مشتركين أو إدراجهم باستخدام رقم تعريف مشروعك على Google Cloud في عنوان URL للطلب بدلاً من رقم تعريف المشروع. ينطبق ذلك على اشتراكات ويب هوك باستخدام نقطة النهاية `projects.subscribers`.	استخدِم رقم تعريف مشروعك على Google Cloud في عنوان URL للطلب، وليس رقم تعريف المشروع.

الروابط العامة وروابط التطبيقات

تحديد المشاكل وحلّها

اشتراكات الويب هوك تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

حسابات الخدمة في "إدارة الهوية وإمكانية الوصول" (IAM)

إعداد حساب خدمة

أدوار CPE

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

إنشاء مشترك

طلب

الردّ

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

طلب

الردّ

تعديل مشترك

طلب

الردّ

حذف مشترك

طلب

الردّ

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

تجديد المفاتيح

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

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

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

الإشعارات

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

تجميع التعديلات

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

أفضل الممارسات

التحقّق من التوقيع

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

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

الأخطاء الشائعة

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