الأحداث

الأحداث غير متزامنة وتتم إدارتها من خلال خدمة 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 لكل طلب بيانات من واجهة برمجة التطبيقات.

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

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

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

• تاريخ الإنشاء: توفير الموقع الإلكتروني أو الجهاز
• محذوف
• تم تعديلها

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

{
  "eventId" : "afe33940-1627-4d94-923c-58397027474e",
  "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" : "adb76f6f-4bd3-4704-8735-faa6e94471c3",
  "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" : "73d758a1-7d19-4e45-8a19-6506399af5a7",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "MkhXoQ0QFEcU9at0j380_gUlJA...",
      }
    }
  }
  "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

لمزيد من المعلومات عن بروتوكول 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 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

الأخطاء

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

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