الأحداث

الأحداث غير متزامنة وتتم إدارتها من خلال خدمة Cloud Pub/Sub من Google، وذلك في موضوع واحد لكل Project. توفّر الأحداث تعديلات لجميع الأجهزة والتركيبات، ويتم ضمان تلقّي الأحداث ما دام المستخدم لم يبطِل رمز الدخول ولم تنتهِ صلاحية رسائل الأحداث.

تفعيل الأحداث

الأحداث هي ميزة اختيارية في واجهة برمجة التطبيقات SDM API. اطّلِع على تفعيل الأحداث لمعرفة كيفية تفعيلها في Project.

‫Google Cloud Pub/Sub

راجِع مستندات Google Cloud Pub/Sub لمعرفة المزيد حول طريقة عمل Pub/Sub. وعلى وجه الخصوص:

• يمكنك التعرّف على أساسيات Pub/Sub من خلال الأدلّة الإرشادية.
• تعرَّف على طريقة عمل المصادقة.
• اختَر مكتبة برامج متوفّرة أو اكتب مكتبتك الخاصة واستخدِم واجهات REST/HTTP أو gRPC API.

الاشتراك في الأحداث

قبل يناير 2025، إذا كانت الأحداث مفعّلة في Project، كان سيتم تزويدك بموضوع خاص بهذا Project المعرّف، وذلك على النحو التالي:

projects/gcp-project-name/subscriptions/topic-id

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

أحداث البدء

لبدء الأحداث لأول مرة بعد إنشاء اشتراك Pub/Sub، عليك إجراء طلب devices.list API كعملية تشغيل لمرة واحدة. سيتم نشر أحداث جميع التركيبات والأجهزة بعد إجراء هذه المكالمة.

للاطّلاع على مثال، يُرجى الانتقال إلى صفحة التفويض في دليل البدء السريع.

ترتيب الأحداث

لا تضمن خدمة Pub/Sub تسليم الأحداث بالترتيب، وقد لا يتطابق ترتيب استلام الأحداث مع ترتيب وقوعها الفعلي. استخدِم الحقل timestamp للمساعدة في مطابقة ترتيب الأحداث. قد تصل الأحداث أيضًا بشكل فردي أو مجمّعة في رسالة حدث واحدة.

لمزيد من المعلومات، يُرجى الاطّلاع على ترتيب الرسائل.

أرقام تعريف المستخدمين

إذا كان تنفيذك يستند إلى المستخدمين (بدلاً من البنية أو الجهاز)، استخدِم الحقل userID من حمولة الحدث لربط الموارد والأحداث. هذا الحقل هو معرّف غير واضح يمثّل مستخدمًا معيّنًا.

يتوفّر userID أيضًا في عنوان استجابة HTTP لكل طلب بيانات من واجهة برمجة التطبيقات.

أحداث العلاقة

تمثّل أحداث العلاقة تعديلاً متعلقًا بالعلاقة لمورد. على سبيل المثال، عند إضافة جهاز إلى بنية أو عند حذف جهاز من بنية.

هناك ثلاثة أنواع من أحداث العلاقة:

• CREATED
• محذوف
• تم تعديلها

في ما يلي حمولة حدث العلاقة:

{
  "eventId" : "0d155a80-20a2-4a5a-b704-363ea9a53b82",
  "timestamp" : "2019-01-01T00:00:01Z",
  "relationUpdate" : {
    "type" : "CREATED",
    "subject" : "enterprises/project-id/structures/structure-id",
    "object" : "enterprises/project-id/devices/device-id"
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
}

في حدث العلاقة، يمثّل object المورد الذي أدّى إلى بدء الحدث، بينما يمثّل subject المورد الذي أصبح object مرتبطًا به. في المثال أعلاه، منح user إذن الوصول إلى هذا الجهاز المحدّد إلى developer، وأصبح الجهاز المعتمد الخاص بـ userمرتبطًا ببنيته المعتمدة، ما يؤدي إلى تشغيل الحدث.

يمكن أن يكون subject غرفة أو بنية فقط. إذا لم يكن لدى a developer إذن بالاطّلاع على بنية user، يكون subject فارغًا دائمًا.

الحقول

اطّلِع على الأحداث للحصول على مزيد من المعلومات حول الأنواع المختلفة من الأحداث وطريقة عملها.

أمثلة

تختلف حمولات الأحداث باختلاف نوع حدث العلاقة:

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

"relationUpdate" : {
  "type" : "UPDATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

لا يتم إرسال أحداث العلاقة في الحالات التالية:

• تم حذف غرفة

أحداث الموارد

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

يحتوي الحدث الذي يتم إنشاؤه استجابةً لتغيير في قيمة حقل السمة على الكائن traits، وهو مشابه لطلب GET الخاص بالجهاز:

{
  "eventId" : "daeb72a3-8ab9-4a44-9f0c-a0984825175b",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "traits" : {
      "sdm.devices.traits.ThermostatMode" : {
        "mode" : "COOL"
      }
    }
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

استخدِم مستندات سمات المستخدم الفردي للتعرّف على تنسيق الحمولة لأي حدث خاص بمورد تغيير حقل سمة.

يتضمّن الحدث الذي يتم إنشاؤه استجابةً لإجراء على الجهاز ولا يؤدي إلى تغيير حقل سمة أيضًا حمولة تتضمّن عنصر resourceUpdate، ولكن مع عنصر events بدلاً من عنصر traits:

{
  "eventId" : "55ff0256-98a9-45b0-83cb-2260f33ae761",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "sp0_pIRR48vIfRVokpMF_aISgq...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

يتم تحديد أنواع أحداث الموارد هذه في سمات معيّنة. على سبيل المثال، يتم تحديد حدث "الحركة" في السمة CameraMotion . راجِع مستندات كل سمة لفهم تنسيق الحمولة لأنواع أحداث الموارد هذه.

الحقول

اطّلِع على الأحداث للحصول على مزيد من المعلومات حول الأنواع المختلفة من الأحداث وطريقة عملها.

الإشعارات القابلة للتعديل

اختَر الأحداث التي تتوافق مع ميزة الإشعارات القابلة للتعديل، والتي يتم تصنيفها على أنّها قابلة للتعديل  في المستندات. تحتوي هذه الأحداث على حقل إضافي باسم eventThreadId في حمولاتها. استخدِم هذا الحقل لربط الأحداث الفردية معًا بغرض تعديل إشعار حالي تم عرضه للمستخدم.

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

لأغراض الإشعارات، يتم تجميع الأنواع المختلفة من الأحداث في سلاسل محادثات مختلفة.

تتولّى Google معالجة منطق تجميع سلاسل المحادثات وتحديد توقيتها، ويخضع هذا المنطق للتغيير في أي وقت. يجب أن تعدّل A developer الإشعارات استنادًا إلى سلاسل الأحداث والجلسات التي توفّرها واجهة برمجة التطبيقات SDM.

حالة سلسلة المحادثات

تحتوي الأحداث التي تتيح إمكانية تعديل الإشعارات أيضًا على حقل eventThreadState يشير إلى حالة سلسلة المحادثات الخاصة بالحدث في ذلك الوقت. يتضمّن هذا الحقل القيم التالية:

• STARTED: الحدث الأول في سلسلة أحداث.
• تم التعديل — حدث في سلسلة أحداث مستمرة يمكن أن يكون هناك صفر أو أكثر من الأحداث بهذه الحالة في سلسلة محادثات واحدة.
• ENDED: الحدث الأخير في سلسلة الأحداث، والذي قد يكون نسخة مكرّرة من آخر حدث UPDATED، وذلك حسب نوع السلسلة.

يمكن استخدام هذا الحقل لتتبُّع مدى تقدّم سلسلة أحداث ووقت انتهائها.

فلترة الأحداث

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

على سبيل المثال، قد يتم نشر رسالة في موضوع SDM لحدث "رصد حركة" أولي. بعد ذلك، سيتم فلترة الرسائل الأخرى المتعلقة بـ Motion ومنع نشرها إلى أن تمر فترة زمنية محدّدة. بعد انقضاء تلك الفترة الزمنية، قد يتم نشر رسالة حدث لنوع الحدث هذا مرة أخرى.

في تطبيق Google Home، ستستمر الأحداث التي تمت فلترتها في الظهور في سجلّ الأحداث الخاص بـ user. ومع ذلك، لا تؤدي هذه الأحداث إلى إنشاء إشعار في التطبيق (حتى إذا كان نوع الإشعار هذا مفعّلاً).

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

حسابات الخدمة

ننصح باستخدام حسابات الخدمة لإدارة اشتراكات SDM API ورسائل الأحداث. يستخدم التطبيق أو الجهاز الافتراضي حساب الخدمة، وليس شخصًا، وله مفتاح حساب فريد خاص به.

يستخدم تفويض حساب الخدمة لواجهة برمجة تطبيقات Pub/Sub بروتوكول OAuth الثنائي (2LO).

في مسار التفويض المكوّن من خطوتين:

• developer يطلب رمز دخول باستخدام مفتاح خدمة.
• يستخدم developer رمز الدخول مع طلبات البيانات من واجهة برمجة التطبيقات.

لمزيد من المعلومات حول نظام المصادقة الثنائي من Google وكيفية إعداده، يُرجى الاطّلاع على استخدام OAuth 2.0 لتطبيقات الخادم إلى الخادم.

التفويض

يجب أن يكون حساب الخدمة مفوَّضًا للاستخدام مع Pub/Sub API:

1. فعِّل واجهة برمجة التطبيقات Cloud Pub/Sub في Google Cloud.
2. أنشئ حساب خدمة ومفتاح حساب خدمة كما هو موضّح في مقالة إنشاء حساب خدمة. ننصح بمنحه دور مشترك Pub/Sub فقط. احرص على تنزيل مفتاح حساب الخدمة على الجهاز الذي سيستخدم واجهة برمجة التطبيقات Pub/Sub API.
3. قدِّم بيانات المصادقة (مفتاح حساب الخدمة) إلى رمز تطبيقك باتّباع التعليمات الواردة في الصفحة في الخطوة السابقة، أو احصل على رمز مميّز للوصول يدويًا باستخدام oauth2l، إذا أردت اختبار إمكانية الوصول إلى واجهة برمجة التطبيقات بسرعة.
4. استخدِم بيانات اعتماد حساب الخدمة أو رمز الدخول مع واجهة برمجة التطبيقات project.subscriptions Pub/Sub لسحب الرسائل وتأكيد استلامها.

oauth2l

‫Google oauth2l هي أداة سطر أوامر لبروتوكول OAuth مكتوبة بلغة Go. يمكنك تثبيتها على أجهزة Mac أو Linux باستخدام Go.

1. إذا لم يكن Go مثبّتًا على نظامك، عليك تنزيله وتثبيته أولاً.
2. بعد تثبيت Go، ثبِّت oauth2l وأضِف موقعه الجغرافي إلى متغيّر البيئة PATH:

   go install github.com/google/oauth2l@latest
   export PATH=$PATH:~/go/bin

3. استخدِم oauth2l للحصول على رمز دخول إلى واجهة برمجة التطبيقات، وذلك باستخدام نطاقات OAuth المناسبة:

   oauth2l fetch --credentials path-to-service-key.json --scope https://www.googleapis.com/auth/pubsub
   https://www.googleapis.com/auth/cloud-platform

   على سبيل المثال، إذا كان مفتاح الخدمة متوفّرًا في ~/myServiceKey-eb0a5f900ee3.json:

   oauth2l fetch --credentials ~/myServiceKey-eb0a5f900ee3.json --scope https://www.googleapis.com/auth/pubsub
   https://www.googleapis.com/auth/cloud-platform
   ya29.c.Elo4BmHXK5...

يمكنك الاطّلاع على ملف README الخاص بـ oauth2l للحصول على مزيد من المعلومات حول الاستخدام.

مكتبات العملاء في Google API

تتوفّر العديد من مكتبات العملاء لواجهات Google APIs التي تستخدم بروتوكول OAuth 2.0. اطّلِع على مكتبات برامج Google API للحصول على مزيد من المعلومات حول اللغة التي تختارها.

عند استخدام هذه المكتبات مع Pub/Sub API، استخدِم سلاسل النطاق التالية:

https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform

الأخطاء

قد يتم عرض رموز الخطأ التالية في ما يتعلق بهذا الدليل:

اطّلِع على مرجع رموز الخطأ في واجهة برمجة التطبيقات للاطّلاع على القائمة الكاملة برموز الخطأ في واجهة برمجة التطبيقات.