تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

الأحداث

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

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

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

Google Cloud Pub/Sub

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

تعرَّف على أساسيات النشر/الاشتراك من خلال أدلة إرشادية
تعرَّف على آلية عمل المصادقة.
اختيار مكتبة عميل مقدَّمة أو اكتب نصك الخاص واستخدِم مساحات عرض واجهة برمجة التطبيقات RST/HTTP أو gRPC

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

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

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

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

بدء الأحداث

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

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

ترتيب الحدث

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

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

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

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

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

أحداث ذات صلة

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

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

تاريخ الإنشاء:
محذوف
تم تعديلها

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

الحمولة

{
  "eventId" : "096cde55-2e67-4708-8b0d-1ca0913b077d",
  "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` مثال: "94099140-e525-4e12-92b6-2226a521f6d5"
`timestamp`	وقت وقوع الحدث.	`string` مثال: "2019-01-01T00:00:01Z"
`relationUpdate`	عنصر يعرض معلومات تفصيلية عن تعديل العلاقة	`object`
`userId`	معرّف فريد مشفَّر يمثّل المستخدم	`string` مثال: "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" : "64473d81-d201-4e29-8281-ac74ac22e24f",
  "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" : "ad458fd9-a64a-45ed-a183-79f74538336b",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "TkahNphxcly8HACE4M5B9pHMoF...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

الحقول

الحقل	الوصف	نوع البيانات
`eventId`	المعرّف الفريد للحدث	`string` مثال: "ad458fd9-a64a-45ed-a183-79f74538336b"
`timestamp`	وقت وقوع الحدث.	`string` مثال: "2019-01-01T00:00:01Z"
`resourceUpdate`	كائن يوضح تفاصيل المعلومات عن تعديل المورد.	`object`
`userId`	معرّف فريد مشفَّر يمثّل المستخدم	`string` مثال: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
`eventThreadId`	المعرّف الفريد لسلسلة محادثات الأحداث	`string` مثال: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
`eventThreadState`	حالة سلسلة الأحداث.	`string` القيم: "تم البدء"، "تم التعديل"، "ENDED"
`resourceGroup`	كائن يشير إلى الموارد التي قد تحتوي على تعديلات مشابهة لهذا الحدث. سيكون مورد الحدث نفسه (من الكائن `resourceUpdate`) متوفرًا دائمًا في هذا الكائن.	`object`

يمكنك الاطّلاع على الأحداث للحصول على مزيد من المعلومات حول مختلف وأنواع الأحداث وكيف تعمل.

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

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

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

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

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

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

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

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

البدء: الحدث الأول في سلسلة أحداث
تم التعديل — حدث في سلسلة أحداث جارية. ولا يمكن أن تتضمّن سلسلة محادثات واحدة أي أحداث أو أكثر.
ENDED - الحدث الأخير في سلسلة أحداث، وقد يكون تكرارًا لآخر حدث UPDATED، بناءً على نوع سلسلة المحادثات.

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

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

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

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

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

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

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

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

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

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

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

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

التفويض

يجب أن يكون حساب الخدمة مفوضًا للاستخدام مع واجهة برمجة تطبيقات النشر/الاشتراك:

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

بروتوكول 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 لمعرفة المزيد حول استخدامه المعلومات.

مكتبات عملاء 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

الأخطاء

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

رسالة الخطأ	متوسط عائد النقرة	تحديد المشاكل وحلّها
لم تعُد صورة الكاميرا متاحة للتنزيل.	`DEADLINE_EXCEEDED`	تنتهي صلاحية صور الحدث بعد 30 ثانية من نشر الحدث. احرص على تنزيل الصورة قبل انتهاء الصلاحية.
لا ينتمي معرّف الحدث إلى الكاميرا.	`FAILED_PRECONDITION`	استخدِم القيمة `eventID` الصحيحة التي يعرضها حدث الكاميرا.

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