الأحداث

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

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

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

‫Google Cloud Pub/Sub

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

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

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

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

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

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

أحداث البدء

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "eventId" : "e73314bd-eb36-42c6-86a5-bb3d2706ccb3",
  "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" : "ec33a442-8b89-449a-a438-6c6229937434",
  "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" : "ea1090ee-c801-4532-87eb-1f43bf640693",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "k-rZHyK3y6wE5Uub8IQKPwpdf4...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

الحقول

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

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

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

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

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

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

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

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

• STARTED: الحدث الأول في سلسلة الأحداث
• UPDATED: حدث في سلسلة أحداث مستمرة. يمكن أن يكون هناك صفر أو أكثر من الأحداث بهذه الحالة في سلسلة محادثات واحدة.
• 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 API في 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

الأخطاء

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

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