يجب اتخاذ إجراء بحلول 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 API.

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

يجب إكمال عملية نقل البيانات بحلول 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" : "7c786f36-8068-4b86-ba67-d6e0d28ebb11",
  "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` مثال: "9252cbe7-f438-4e15-a65f-619fb497f78a"
`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" : "59381967-62e1-427b-98b8-67d5dbbd590c",
  "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" : "1608503f-fedf-43cc-b29c-aa4e3b685a60",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "Ki0F7T-Joca_uRg42loDugGevl...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

الحقول

الحقل	الوصف	نوع البيانات
`eventId`	المعرّف الفريد للحدث	`string` مثال: "1608503f-fedf-43cc-b29c-aa4e3b685a60"
`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 أولي. بعد ذلك، سيتم فلترة الرسائل الأخرى التي تتلقّاها 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 إذا أردت اختبار الوصول إلى واجهة برمجة التطبيقات بسرعة.
استخدِم بيانات اعتماد حساب الخدمة أو رمز الدخول مع واجهة برمجة التطبيقات project.subscriptions Pub/Sub لسحب الرسائل وتأكيد استلامها.

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

الأخطاء

الأحداث