الأحداث

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

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

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

Google Cloud Pub/Sub

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

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

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

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

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

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

بدء الأحداث

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "eventId" : "00696c74-5b86-447c-acd9-b5e2b69f833d",
  "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 إلا غرفة أو تركيبًا. إذا لم يكن لديه إذن عرض تركيب ، يكون subject فارغًا دائمًا. a developer user

الحقول

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

أمثلة

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

"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" : "9e90d62e-0364-479c-9abf-b718543cdf94",
  "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" : "5893d30e-d829-44d7-a99b-a97f35598e7e",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "QePER1_CgEmc4U1lETPTiY8tbI...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

الحقول

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

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

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

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

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

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

حالة السلسلة

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

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

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

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

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

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

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

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

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

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

يستخدم تفويض حساب الخدمة لواجهة برمجة التطبيقات Pub/Sub مصادقة OAUTH على مرحلتين (2LO).

في عملية تفويض 2LO:

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

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

التفويض

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

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

oauth2l

أداة oauth2l من Google هي أداة سطر أوامر لبروتوكول 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...

يُرجى الاطّلاع على ملف 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

الأخطاء

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

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