يجب اتخاذ إجراء بحلول 30 نوفمبر 2026: سيتم إيقاف مواضيع Pub/Sub المُستضافة على Google للأحداث نهائيًا. إذا كان الدمج يستخدِم موضوعًا مستضافًا على Google، عليك نقل البيانات إلى موضوع Pub/Sub مستضاف ذاتيًا قبل 30 تشرين الثاني (نوفمبر) 2026 لمواصلة تلقّي إشعارات الأحداث.

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

الأحداث

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

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

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

Google Cloud Pub/Sub

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

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

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

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

قبل يناير 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" : "1a2e13bc-c23c-4bc4-8366-6b5669607f0e",
  "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` مثال: "a121b435-e3bb-4ba1-9dea-945686b7dabf"
`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" : "caec1000-1cab-43d3-946f-bc3c5f8615c9",
  "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" : "0111d3f2-5e7d-4ecf-88ed-8f3b0324f75c",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "jOvQqNOSL76837k_JxTR4BJ6nw...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

الحقول

الحقل	الوصف	نوع البيانات
`eventId`	المعرّف الفريد للحدث	`string` مثال: "0111d3f2-5e7d-4ecf-88ed-8f3b0324f75c"
`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 معالجة منطق تجميع سلاسل المحادثات وتوقيتها، وهو عرضة للتغيير في أي وقت. developer يجب أن تعدّل الإشعارات استنادًا إلى سلاسل الأحداث والجلسات التي توفّرها واجهة SDM API.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

التفويض

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

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

oauth2l

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

إذا لم يكن لديك Go على نظامك، يمكنك تنزيله وتثبيته أولاً.
بعد تثبيت Go، ثبِّت oauth2l وأضِف موقعه الجغرافي إلى متغيّر بيئة PATH:
```
go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
```

استخدِم 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

الأخطاء

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

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

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

الأحداث تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

Google Cloud Pub/Sub

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

بدء الأحداث

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

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

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

الحمولة

الحقول

أمثلة

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

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

تم إنشاء الجهاز

تم إنشاء الجهاز

تم تعديلها

تم نقل الجهاز

محذوف

تم حذف البنية

تم حذف الجهاز

تم حذف الجهاز

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

الحمولة

الحمولة

الحقول

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

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

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

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

التفويض

oauth2l

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

الأخطاء

الأحداث