تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

الأحداث

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

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

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

خدمة Google Cloud Pub/Sub

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

اطّلِع على أساسيات النشر/الاشتراك من خلال الأدلّة الإرشادية.
تعرّف على آلية عمل المصادقة.
اختَر مكتبة عميل متاحة أو اكتب بنفسك مكتبة العميل الخاصة بك واستخدِم مساحات عرض ReST/HTTP أو gRPC API.

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

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

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

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

بدء الأحداث

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

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

ترتيب الحدث

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

لمزيد من المعلومات، راجِع ترتيب الرسائل.

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

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

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

أحداث ذات صلة

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

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

تم الإنشاء
محذوف
تم تعديلها

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

المحتوى

{
  "eventId" : "eed9763a-8735-45d9-81d9-e0621c130eb1",
  "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` مثال: "1362476b-4ac4-4608-a8be-4c8cf4101426"
`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" : "5b98a768-6771-4d4d-836d-58cce3a62cca",
  "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" : "3426d266-406b-48f3-9595-5192229a39a0",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "8XZ1cQ76Becovj551YfM9ZnuwB...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

الحقول

الحقل	الوصف	نوع البيانات
`eventId`	المعرّف الفريد للحدث	`string` مثال: "3426d266-406b-48f3-9595-5192229a39a0"
`timestamp`	وقت وقوع الحدث.	`string` مثال: "2019-01-01T00:00:01Z"
`resourceUpdate`	يشير ذلك المصطلح إلى عنصر يعرِض معلومات عن تعديل الموارد.	`object`
`userId`	تمثّل هذه السمة معرّفًا فريدًا يتضمّن تشويشًا ويمثّل المستخدم.	`string` مثال: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
`eventThreadId`	المعرّف الفريد لسلسلة محادثات الحدث	`string` مثال: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
`eventThreadState`	حالة سلسلة الحدث	`string` القيم: "STARTED"، "تم التحديث"، "ENDED"
`resourceGroup`	يشير هذا المصطلح إلى عنصر يشير إلى الموارد التي قد تتضمَّن تعديلات مشابهة لهذا الحدث. سيكون مورد الحدث نفسه (من الكائن `resourceUpdate`) متاحًا دائمًا في هذا الكائن.	`object`

يمكنك الاطّلاع على الأحداث للحصول على مزيد من المعلومات حول الأنواع المختلفة من الأحداث وآلية عملها.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يستخدم تفويض حساب الخدمة لواجهة برمجة التطبيقات Pub/Sub بروتوكول OAuth الثنائي (2LO).

في تدفق تفويض 2LO:

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

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

التفويض

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

فعِّل واجهة برمجة التطبيقات Cloud Pub/Sub في Google Cloud.
أنشئ حساب خدمة ومفتاح حساب خدمة كما هو موضَّح في إنشاء حساب خدمة. ننصحك بمنحه دور المشترِك في النشر/الاشتراك فقط. احرص على تنزيل مفتاح حساب الخدمة على الجهاز الذي سيستخدم واجهة برمجة التطبيقات Pub/Sub.
قدِّم بيانات اعتماد المصادقة (مفتاح حساب الخدمة) لرمز تطبيقك من خلال اتّباع التعليمات الواردة في الصفحة في الخطوة السابقة، أو احصل على رمز الدخول يدويًا باستخدام 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...

يمكنك الاطّلاع على 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` الصحيحة التي يعرضها حدث الكاميرا.

راجِع مرجع رموز خطأ واجهة برمجة التطبيقات للاطّلاع على القائمة الكاملة لرموز أخطاء واجهة برمجة التطبيقات.