الأحداث

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

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

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

Google Cloud Pub/Sub

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

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

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

projects/sdm-prod/topics/enterprise-project-id

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

بدء الأحداث

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

على سبيل المثال، يمكنك الاطّلاع على صفحة Authorize في دليل البدء السريع.

ترتيب الحدث

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

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

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

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

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

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

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

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

  • تم الإنشاء
  • محذوف
  • تم تعديلها

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

الحمولة

{
  "eventId" : "049ce833-c330-476f-952f-b3dda83ae0f6",
  "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 دائمًا فارغًا.

الحقول

الحقل الوصف نوع البيانات
eventId المعرّف الفريد للحدث string
مثال: "665fa8b2-ba4a-401f-aad7-bd2740f7ec41"
timestamp وقت وقوع الحدث. string
مثال: "2019-01-01T00:00:01Z"
relationUpdate عنصر يوضّح معلومات عن تعديل العلاقة object
userId معرّف فريد غير واضح يمثّل المستخدم string
مثال: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"

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

أمثلة

تختلف حِزم بيانات الأحداث لكل نوع من أنواع أحداث العلاقات:

تاريخ الإنشاء

تم إنشاء البنية.

"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" : "d89bda44-0d9d-42aa-9ab2-a685a0f1ca0d",
  "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" : "d7b54476-0d5d-4d37-8d80-14261981144b",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "E5kcTftnwgacvbdKS69vufvvP0...", } } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] }

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

الحقول

الحقل الوصف نوع البيانات
eventId المعرّف الفريد للحدث string
مثال: "d7b54476-0d5d-4d37-8d80-14261981144b"
timestamp الوقت الذي وقع فيه الحدث string
مثال: "2019-01-01T00:00:01Z"
resourceUpdate كائن يوضح تفاصيل المعلومات عن تعديل المورد. object
userId معرّف فريد مشفَّر يمثّل المستخدم string
مثال: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
eventThreadId المعرّف الفريد لسلسلة الأحداث string
مثال: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
eventThreadState حالة سلسلة محادثات الحدث. string
القيم: "STARTED" و"UPDATED" و"ENDED"
resourceGroup عنصر يشير إلى الموارد التي قد تحتوي على تعديلات مشابهة لهذا الحدث. سيكون مرجع الحدث نفسه (من كائن resourceUpdate) متوفّرًا دائمًا في هذا الكائن. object

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

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

يمكن تنفيذ الإشعارات المستندة إلى أحداث الموارد في تطبيق، مثل Android أو iOS. لتقليل عدد الإشعارات المُرسَلة، يمكن تنفيذ ميزة تُسمى الإشعارات القابلة للتحديث، حيث يتم تعديل الإشعارات الحالية باستخدام معلومات جديدة استنادًا إلى الأحداث اللاحقة في سلسلة محادثات الأحداث نفسها.

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

سلسلة محادثات الحدث ليست هي نفسها جلسة الحدث. سلسلة الأحداث تحدّد حالة معدَّلة لحدث سابق في سلسلة المحادثات نفسها. تحدِّد جلسة الأحداث أحداثًا منفصلة ذات صلة ببعضها، ويُمكن أن يكون هناك سلاسل محادثات أحداث متعدّدة لجلسة أحداث معيّنة.

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

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

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

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

  • STARTED (البدء): الحدث الأول في سلسلة أحداث.
  • تم تعديله: حدث في سلسلة أحداث جارية يمكن أن يكون هناك صفر أو أكثر من الأحداث التي تحمل هذه الحالة في سلسلة محادثات واحدة.
  • ENDED - الحدث الأخير في سلسلة أحداث، وقد يكون تكرارًا لآخر حدث UPDATED، بناءً على نوع سلسلة المحادثات.

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

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

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

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

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

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

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

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

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

في مسار تفويض 2LO:

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

لمزيد من المعلومات عن Google 2LO وكيفية إعداده، يمكنك الاطّلاع على استخدام OAuth 2.0 لتطبيقات الخادم إلى الخادم.

التفويض

يجب تفويض حساب الخدمة لاستخدامه مع واجهة برمجة التطبيقات Pub/Sub API:

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

بروتوكول 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...

راجِع الدليل التمهيدي oauth2l للحصول على مزيد من المعلومات حول الاستخدام.

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

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

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

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

الأخطاء

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

رسالة الخطأ متوسط عائد النقرة تحديد المشاكل وحلّها
لم تعُد صورة الكاميرا متاحة للتنزيل. DEADLINE_EXCEEDED تنتهي صلاحية صور الحدث بعد 30 ثانية من نشر الحدث. احرص على تنزيل الصورة قبل انتهاء الصلاحية.
رقم تعريف الحدث لا يعود للكاميرا. FAILED_PRECONDITION استخدِم القيمة eventID الصحيحة التي يعرضها حدث الكاميرا.

يمكنك الاطّلاع على مرجع رمز خطأ واجهة برمجة التطبيقات للحصول على قائمة كاملة برموز أخطاء واجهة برمجة التطبيقات.