الأحداث

الأحداث غير متزامنة وتديرها خدمة 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، كان سيتم تزويدك بموضوع مستضاف على Google خاص برقم التعريف هذا Project ، على النحو التالي:

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

يجب أن تستضيف جميع المشاريع الآن مواضيع Pub/Sub ذاتيًا في مشروعها على Google Cloud (إلزامي للمشاريع الجديدة منذ يناير 2025، ومطلوب لجميع المشاريع الحالية بحلول 30 نوفمبر 2026)، على النحو التالي:

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

إذا كان project يستخدم حاليًا موضوعًا مستضافًا ذاتيًا في مشروعك على Google Cloud، ليس عليك اتّخاذ أي إجراء. لا يؤدي نقل إعدادات موضوع Pub/Sub إلى إبطال رموز الدخول الحالية للمستخدمين أو أذونات OAuth. تخضع المواضيع والاشتراكات المستضافة ذاتيًا لأسعار Google Cloud Pub/Sub العادية (التي تتضمّن طبقة مجانية بسعة 10 غيغابايت في الشهر). يُرجى الاطّلاع على المقالة إنشاء موضوع لمزيد من المعلومات.

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

بدء الأحداث

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "eventId" : "768e4eea-b61d-428b-8926-c67e2abaddf9",
  "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" : "ae3f760e-9e1f-4c14-b911-28482e86e56d",
  "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" : "aecdfca3-25ec-4738-bdbf-d24c4a209d93",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "jE1ZfUIAp6z2anjwTJp5E8QxvC...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

الحقول

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

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

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

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

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

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

حالة السلسلة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

التفويض

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

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

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 APIs تستخدم OAuth 2.0. يُرجى الاطّلاع على مكتبات برامج عميل Google API لمزيد من المعلومات عن اللغة التي تختارها.

عند استخدام هذه المكتبات مع Pub/Sub API، استخدِم سلاسل النطاقات التالية:

https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform

الأخطاء

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

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