الأحداث

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

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

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

Google Cloud Pub/Sub

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

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

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

projects/gcp-project-name/subscriptions/topic-id
 يجب أن تستضيف المشاريع التي تم إنشاؤها بعد يناير 2025 مواضيع Pub/Sub بنفسها، ويجب تقديم رقم تعريف الموضوع الخاص بك. يُرجى الاطّلاع على إنشاء موضوع لمزيد من المعلومات.

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

بدء الأحداث

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

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

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

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

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

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

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

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

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

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

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

  • تاريخ الإنشاء: توفير الموقع الإلكتروني أو الجهاز
  • محذوف
  • تم تعديلها

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

الحمولة

{
  "eventId" : "2574c3f7-149c-4c02-b71c-80821651e5d1",
  "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 إلا غرفة أو تركيبًا. إذا لم يكن لديه إذن عرض تركيب ، يكون subject فارغًا دائمًا. a developer user

الحقول

الحقل الوصف نوع البيانات
eventId المعرّف الفريد للحدث string
مثال: "6ae1f7f6-1c05-4f6b-8183-888918c33ee3"
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" : "f7b9f284-3859-4664-afff-23929c769f6e",
  "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" : "83c33ce2-47e3-48c1-a813-1ca9be0de22e",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "nKK_kxKN0Whakp59tFxGw-GQiU...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

الحقول

الحقل الوصف نوع البيانات
eventId المعرّف الفريد للحدث string
مثال: "83c33ce2-47e3-48c1-a813-1ca9be0de22e"
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 معالجة منطق تجميع السلاسل هذا وتوقيته، وقد يتم تغييره في أي وقت. يجب أن تعدّل الإشعارات استنادًا إلى سلاسل الأحداث والجلسات التي يوفّرها SDM API. developer

حالة السلسلة

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

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

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

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

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

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

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

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

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

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

يستخدم تفويض حساب الخدمة لواجهة برمجة التطبيقات Pub/Sub مصادقة OAUTH على مرحلتين (2LO).

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

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

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

التفويض

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

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

oauth2l

أداة oauth2l من Google هي أداة سطر أوامر لبروتوكول 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 README الخاص بـ لمزيد من المعلومات عن الاستخدام.

مكتبات العملاء في 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 الصحيح الذي يعرضه حدث رصدته الكاميرا.

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