الأحداث

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

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

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

Google Cloud Pub/Sub

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

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

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

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

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

يجب أن تستضيف جميع المشاريع الآن مواضيع Pub/Sub ذاتيًا في مشروع Google Cloud الخاص بها (وهو شرط إلزامي للمشاريع الجديدة منذ يناير 2025، ويجب استيفاؤه في جميع المشاريع الحالية بحلول 30 نوفمبر 2026)، وذلك بالتنسيق التالي:

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

إذا كان project يستخدم موضوعًا مستضافًا ذاتيًا في مشروعك على Google Cloud، ليس عليك اتّخاذ أي إجراء. لا يؤدي نقل إعدادات موضوع Pub/Sub إلى إبطال رموز الدخول الحالية للمستخدمين أو أذونات OAuth. تخضع المواضيع والاشتراكات المستضافة ذاتيًا لأسعار Google Cloud Pub/Sub العادية (التي تتضمّن مستوى استخدام مجانيًا يبلغ 10 غيغابايت في الشهر). لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء موضوع.

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

أحداث البدء

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "eventId" : "c873a147-2a89-40ed-8ccb-68e8475430e1",
  "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" : "16e90a37-d13b-4057-857b-127273cf9447",
  "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" : "f23283c6-968a-48c0-a92e-415577715b0e",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "V1y7sbSe1Bc_1aaJPwuk_qqpzU...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

الحقول

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

في مسار تفويض OAuth ثنائي الأطراف:

• 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

الأخطاء

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

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