Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

الأحداث

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

يجب أن تستضيف المشاريع التي تم إنشاؤها بعد يناير 2025 مواضيع Pub/Sub بنفسها، وعليك تقديم رقم تعريف الموضوع الخاص بك. يُرجى الاطّلاع على إنشاء موضوع لمزيد من المعلومات.

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

بدء الأحداث

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

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

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

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

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

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

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

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

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

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

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

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

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

الحمولة

{
  "eventId" : "9be24f96-45c8-4029-980b-701b69c153f5",
  "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` Example: "7d13899e-cf01-45a7-85c1-a8c103e902b1"
`timestamp`	الوقت الذي وقع فيه الحدث	`string` Example: "‎2019-01-01T00:00:01Z"
`relationUpdate`	عنصر يقدّم تفاصيل حول آخر التعديلات من العلاقة	`object`
`userId`	معرّف فريد ومشوَّش يمثّل المستخدِم	`string` Example: "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" : "3a2f70dd-78b0-4342-849a-2ebf120f0eff",
  "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" : "d0f634f3-fe44-4ddb-a194-8d6480f52226",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "ch_jjbEjxNkuX9XgxTEwGuSKO9...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

الحقول

الحقل	الوصف	نوع البيانات
`eventId`	المعرّف الفريد للحدث	`string` Example: "d0f634f3-fe44-4ddb-a194-8d6480f52226"
`timestamp`	الوقت الذي وقع فيه الحدث	`string` مثال: "‎2019-01-01T00:00:01Z"
`resourceUpdate`	عنصر يقدّم تفاصيل حول آخر التعديلات من المورد.	`object`
`userId`	معرّف فريد ومشوَّش يمثّل المستخدِم.	`string` Example: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
`eventThreadId`	المعرّف الفريد لسلسلة الأحداث	`string` Example: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
`eventThreadState`	حالة سلسلة الأحداث	`string` القيم: "STARTED" أو "UPDATED" أو "ENDED"
`resourceGroup`	عنصر يشير إلى الموارد التي قد تتضمّن تعديلات مشابهة لهذا الحدث سيكون مورد الحدث نفسه (من العنصر `resourceUpdate`) متاحًا دائمًا في هذا العنصر.	`object`

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

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

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

تتوافق ميزة الأحداث مع الإشعارات القابلة للتعديل، ويتم وضع علامة قابلة للتعديل عليها في المستندات. تحتوي هذه الأحداث على حقل إضافي يُسمى 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:

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

oauth2l

أداة oauth2l من Google هي أداة سطر أوامر لبروتوكول 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` الصحيح الذي يعرضه حدث رصدته الكاميرا.

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

الأحداث تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

Google Cloud Pub/Sub

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

بدء الأحداث

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

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

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

الحمولة

الحقول

أمثلة

تاريخ الإنشاء

تم إنشاء التركيب

تم إنشاء الجهاز

تم إنشاء الجهاز

تم تعديلها

تم نقل الجهاز

محذوف

تم حذف التركيب

تم حذف الجهاز

تم حذف الجهاز

أحداث الموارد

الحمولة

الحمولة

الحقول

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

حالة السلسلة

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

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

التفويض

oauth2l

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

الأخطاء

الأحداث