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

الأحداث

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

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

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

Google Cloud Pub/Sub

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

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

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

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

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

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

بدء الأحداث

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

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

ترتيب الحدث

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

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

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

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

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

أحداث ذات صلة

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

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

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

تكون حمولة حدث العلاقة على النحو التالي:

المحتوى

{
  "eventId" : "9a8ecd50-964f-47df-8b5d-1433e310f525",
  "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` مثال: "be180c3f-7250-4019-89b1-867cc8d93faf"
`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" : "61fdafdd-769f-494f-87fc-e1c531c7b6e4",
  "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" : "356a7393-7368-44e5-87e3-da97d645f5f6",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "bntS0GyA_XgiUftR-pcz5aw-Te...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

الحقول

الحقل	الوصف	نوع البيانات
`eventId`	المعرّف الفريد للحدث	`string` مثال: "356a7393-7368-44e5-87e3-da97d645f5f6"
`timestamp`	وقت وقوع الحدث.	`string` مثال: "2019-01-01T00:00:01Z"
`resourceUpdate`	كائن يوضح تفاصيل المعلومات عن تحديث المورد.	`object`
`userId`	معرّف فريد مشفَّر يمثّل المستخدم	`string` مثال: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
`eventThreadId`	المعرّف الفريد لسلسلة محادثات الأحداث	`string` مثال: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
`eventThreadState`	حالة سلسلة الأحداث.	`string` القيم: "تم البدء"، "تم التعديل"، "ENDED"
`resourceGroup`	كائن يشير إلى الموارد التي قد تحتوي على تعديلات مشابهة لهذا الحدث. سيكون مورد الحدث نفسه (من الكائن `resourceUpdate`) متوفرًا دائمًا في هذا الكائن.	`object`

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

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

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

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

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

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

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

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

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

البدء: الحدث الأول في سلسلة أحداث
تم التعديل — حدث في سلسلة أحداث جارية. ولا يمكن أن تتضمّن سلسلة محادثات واحدة أي أحداث أو أكثر.
ENDED - الحدث الأخير في سلسلة أحداث، وقد يكون تكرارًا لآخر حدث UPDATED، بناءً على نوع سلسلة المحادثات.

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

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

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

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

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

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

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

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

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

في مسار تفويض 2LO:

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

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

التفويض

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

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

بروتوكول oauth2l

oauth2l Google هي أداة سطر أوامر لـ 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` الصحيحة التي يعرضها حدث الكاميرا.

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