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

الأحداث

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

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

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

Google Cloud Pub/Sub

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

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

اشتراك في حدث

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

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

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

بدء الأحداث

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

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

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

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

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

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

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

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

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

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

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

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

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

الحمولة

{
  "eventId" : "d5c0f0bd-de65-44fd-ac60-686c302e56eb",
  "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` مثال: "64b87b46-1aec-42a4-8c01-997a407814df"
`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" : "a88bc884-d2b8-42d6-adba-b7be92c232a3",
  "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" : "4f80de08-1b77-42a4-b33e-40876a2a1865",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "MWJ253hZMPAsJZJWbrGM4ThsKM...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

الحقول

الحقل	الوصف	نوع البيانات
`eventId`	المعرّف الفريد للحدث	`string` مثال: "4f80de08-1b77-42a4-b33e-40876a2a1865"
`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 تجميع سلاسل المحادثات ومنطق التوقيت هذا، وهو يخضع للتغيير في أي وقت. يجب أن يعدّل A developer الإشعارات استنادًا إلى مناقشات الأحداث والجلسات التي تقدّمها واجهة برمجة التطبيقات SDM API.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

التفويض

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

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

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 README للحصول على مزيد من المعلومات عن استخدام البيانات.

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

تتوفّر عدة مكتبات عملاء لواجهات برمجة تطبيقات Google تستخدم بروتوكول 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` الصحيح الذي يعرضه حدث الكاميرا.

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