الأحداث

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

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

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

‫Google Cloud Pub/Sub

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

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

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

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

projects/gcp-project-name/subscriptions/topic-id

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

أحداث البدء

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

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

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

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

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

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

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

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

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

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

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

• CREATED
• محذوف
• تم تعديلها

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

{
  "eventId" : "ba715dab-5a85-4fb3-bffa-79da30c2e6f3",
  "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 فارغة دائمًا.

الحقول

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

أمثلة

تختلف حمولات الأحداث باختلاف نوع حدث العلاقة:

"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" : "fa16dff7-f78f-487d-8d5f-a3a820c13f5d",
  "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" : "896d941c-3768-4f63-a8fb-b05ee6630bc1",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "MQDu1Ue5_3wZrOZbCTf2Ah3rD6...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

الحقول

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

في مسار التفويض المكوّن من خطوتين، اتّبِع الخطوات التالية:

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

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

التفويض

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

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

oauth2l

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

1. إذا لم يكن Go مثبّتًا على نظامك، عليك تنزيله وتثبيته أولاً.
2. بعد تثبيت Go، ثبِّت oauth2l وأضِف موقعه الجغرافي إلى متغيّر بيئة PATH:

   go install github.com/google/oauth2l@latest
   export PATH=$PATH:~/go/bin

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

الأخطاء

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

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