این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

رویداد

رویدادها ناهمزمان هستند و توسط Google Cloud Pub/Sub، در یک موضوع واحد برای هر نفر، مدیریت می‌شوند. Projectرویدادها به‌روزرسانی‌هایی را برای همه دستگاه‌ها و ساختارها ارائه می‌دهند و دریافت رویدادها تا زمانی که توکن دسترسی توسط کاربر لغو نشده و پیام‌های رویداد منقضی نشده باشند، تضمین می‌شود.

فعال کردن رویدادها

رویدادها یک ویژگی اختیاری از API SDM هستند. ببینید فعال کردن رویدادها برای یادگیری نحوه فعال کردن آنها برای شما Project.

میخانه/زیرمجموعه گوگل کلود

برای کسب اطلاعات بیشتر در مورد نحوه کار Pub/Sub، به مستندات Google Cloud Pub/Sub مراجعه کنید. به طور خاص:

اصول اولیه Pub/Sub را با راهنماهای آموزشی آنها بیاموزید.
درک کنید که احراز هویت چگونه کار می‌کند.
یک کتابخانه کلاینت ارائه شده را انتخاب کنید یا خودتان آن را بنویسید و از سطوح REST/HTTP یا gRPC API استفاده کنید.

اشتراک رویداد

قبل از ژانویه ۲۰۲۵، اگر رویدادها برای شما فعال بودند Project، موضوعی مختص به آن به شما ارائه می‌شد Project شناسه، به شکل:

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

پروژه‌هایی که پس از ژانویه ۲۰۲۵ ایجاد شده‌اند باید موضوعات Pub/Sub خود را به صورت خودکار میزبانی کنند و شما باید شناسه موضوع خود را ارائه دهید. برای اطلاعات بیشتر به بخش «ایجاد موضوع» مراجعه کنید.

برای دریافت رویدادها، بسته به مورد استفاده خود، یک اشتراک pull یا push برای آن موضوع ایجاد کنید. اشتراک‌های چندگانه برای موضوع SDM پشتیبانی می‌شوند. برای اطلاعات بیشتر به مدیریت اشتراک‌ها مراجعه کنید.

رویدادها را آغاز کنید

برای شروع رویدادها برای اولین بار پس از ایجاد اشتراک Pub/Sub، یک فراخوانی API devices.list به عنوان یک تریگر یکبار مصرف انجام دهید. رویدادهای مربوط به همه ساختارها و دستگاه‌ها پس از این فراخوانی منتشر خواهند شد.

برای مثال، به صفحه مجوز در راهنمای شروع سریع مراجعه کنید.

ترتیب رویداد

Pub/Sub تحویل مرتب رویدادها را تضمین نمی‌کند و ترتیب دریافت رویدادها ممکن است با ترتیب وقوع واقعی آنها مطابقت نداشته باشد. از فیلد timestamp برای تطبیق ترتیب رویدادها استفاده کنید. رویدادها همچنین ممکن است به صورت جداگانه یا در قالب یک پیام رویداد واحد دریافت شوند.

برای اطلاعات بیشتر، به پیام‌های سفارش مراجعه کنید.

شناسه‌های کاربری

اگر پیاده‌سازی شما بر اساس کاربران است (به جای ساختار یا دستگاه)، از فیلد userID از payload رویداد برای مرتبط کردن منابع و رویدادها استفاده کنید. این فیلد یک شناسه مبهم است که نشان‌دهنده یک کاربر خاص است.

userID همچنین در هدر پاسخ HTTP هر فراخوانی API موجود است.

رویدادهای رابطه‌ای

رویدادهای رابطه‌ای نشان‌دهنده‌ی به‌روزرسانی رابطه‌ای برای یک منبع هستند. برای مثال، وقتی یک دستگاه به یک ساختار اضافه می‌شود یا وقتی یک دستگاه از یک ساختار حذف می‌شود.

سه نوع رویداد رابطه‌ای وجود دارد:

ایجاد شده
حذف شده
به‌روزرسانی‌شده

بار مفید برای یک رویداد رابطه به شرح زیر است:

بار مفید

{
  "eventId" : "e2db94fc-1d19-40ab-9424-5a16c2bf6214",
  "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` مثال: "af53d5eb-693c-480f-9204-e79dd9ed48ca"
`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"
}

رویدادهای رابطه‌ای در موارد زیر ارسال نمی‌شوند:

یک اتاق حذف شده است

رویدادهای منابع

یک رویداد منبع، نشان‌دهنده‌ی به‌روزرسانی مختص به یک منبع است. این به‌روزرسانی می‌تواند در پاسخ به تغییر مقدار یک فیلد ویژگی (trait field) باشد، مانند تغییر حالت یک ترموستات. همچنین می‌تواند نشان‌دهنده‌ی یک عمل دستگاه باشد که فیلد ویژگی را تغییر نمی‌دهد، مانند فشار دادن دکمه‌ی دستگاه.

رویدادی که در پاسخ به تغییر مقدار فیلد trait ایجاد می‌شود، حاوی یک شیء traits است، مشابه فراخوانی GET دستگاه:

بار مفید

{
  "eventId" : "88d26712-7482-4cb7-aef1-3ffc195da636",
  "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"
  ]
}

برای درک قالب بار مفید برای هر رویداد تغییر منبع فیلد ویژگی، از مستندات مربوط به هر ویژگی استفاده کنید.

رویدادی که در پاسخ به یک اقدام دستگاه ایجاد می‌شود و فیلد trait را تغییر نمی‌دهد، دارای یک payload با شیء resourceUpdate نیز هست، اما به جای شیء traits از شیء events استفاده می‌کند:

بار مفید

{
  "eventId" : "a2df968d-9df6-4eb1-a16e-191acf4a61e1",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "uUC6s89QIkuqQtZprIjpo1pL5J...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

این نوع رویدادهای منبع در ویژگی‌های خاصی تعریف می‌شوند. برای مثال، رویداد حرکت در ... تعریف شده است. دوربین موشن برای درک قالب بار مفید برای این نوع رویدادهای منبع، به مستندات هر ویژگی مراجعه کنید.

فیلدها

میدان	توضیحات	نوع داده
`eventId`	شناسه منحصر به فرد برای رویداد.	`string` مثال: "a2df968d-9df6-4eb1-a16e-191acf4a61e1"
`timestamp`	زمانی که رویداد رخ داده است.	`string` مثال: "2019-01-01T00:00:01Z"
`resourceUpdate`	شیء‌ای که اطلاعات مربوط به به‌روزرسانی منابع را شرح می‌دهد.	`object`
`userId`	یک شناسه منحصر به فرد و مبهم که نمایانگر کاربر است.	`string` مثال: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
`eventThreadId`	شناسه منحصر به فرد برای رشته رویداد.	`string` مثال: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
`eventThreadState`	وضعیت رشته رویداد.	`string` مقادیر: "شروع"، "به‌روزرسانی"، "پایان"
`resourceGroup`	شیء‌ای که منابعی را نشان می‌دهد که ممکن است به‌روزرسانی‌های مشابهی با این رویداد داشته باشند. منبع خود رویداد (از شیء `resourceUpdate` ) همیشه در این شیء وجود خواهد داشت.	`object`

برای اطلاعات بیشتر در مورد انواع مختلف رویدادها و نحوه عملکرد آنها، به بخش رویدادها مراجعه کنید.

اعلان‌های قابل به‌روزرسانی

اعلان‌های مبتنی بر رویدادهای منبع را می‌توان در یک برنامه، مانند اندروید یا iOS، پیاده‌سازی کرد. برای کاهش تعداد اعلان‌های ارسالی، می‌توان ویژگی‌ای به نام اعلان‌های قابل به‌روزرسانی را پیاده‌سازی کرد که در آن اعلان‌های موجود با اطلاعات جدید بر اساس رویدادهای بعدی در همان رشته رویداد به‌روزرسانی می‌شوند.

رویدادهای Select از اعلان‌های قابل به‌روزرسانی پشتیبانی می‌کنند و در مستندات با عنوان Updateable برچسب‌گذاری شده‌اند. این رویدادها در فایل‌های اجرایی خود فیلد اضافی به نام eventThreadId دارند. از این فیلد برای پیوند دادن رویدادهای منفرد به یکدیگر به منظور به‌روزرسانی اعلان موجودی که برای کاربر نمایش داده شده است، استفاده کنید.

یک رشته رویداد (event thread) با یک جلسه رویداد (event session) یکسان نیست. رشته رویداد (event thread) وضعیت به‌روز شده یک رویداد قبلی در همان رشته را مشخص می‌کند. جلسه رویداد (event session) رویدادهای جداگانه‌ای را که به یکدیگر مرتبط هستند شناسایی می‌کند و می‌تواند چندین رشته رویداد برای یک جلسه رویداد مشخص وجود داشته باشد.

برای اهداف اطلاع‌رسانی، انواع مختلف رویدادها در رشته‌های مختلف گروه‌بندی می‌شوند.

این منطق گروه‌بندی و زمان‌بندی موضوعات توسط گوگل مدیریت می‌شود و ممکن است در هر زمانی تغییر کند. developer باید اعلان‌ها را بر اساس رشته‌ها و جلسات رویداد ارائه شده توسط SDM API به‌روزرسانی کند.

حالت نخ

رویدادهایی که از اعلان‌های قابل به‌روزرسانی پشتیبانی می‌کنند، یک فیلد eventThreadState نیز دارند که وضعیت thread رویداد را در آن نقطه از زمان نشان می‌دهد. این فیلد دارای مقادیر زیر است:

شروع‌شده - اولین رویداد در یک رشته رویداد.
به‌روزرسانی‌شده - رویدادی در یک رشته رویداد در حال انجام. می‌تواند صفر یا چند رویداد با این وضعیت در یک رشته واحد وجود داشته باشد.
پایان یافته - آخرین رویداد در یک رشته رویداد، که بسته به نوع رشته، ممکن است تکراری از آخرین رویداد UPDATED باشد.

از این فیلد می‌توان برای پیگیری پیشرفت یک رویداد و زمان پایان آن استفاده کرد.

فیلتر کردن رویداد

در برخی موارد، رویدادهای شناسایی شده توسط یک دستگاه ممکن است از انتشار به یک موضوع SDM Pub/Sub فیلتر شوند. این رفتار فیلترینگ رویداد نامیده می‌شود. هدف از فیلترینگ رویداد، جلوگیری از انتشار پیام‌های رویداد مشابه زیاد در مدت زمان کوتاه است.

برای مثال، ممکن است پیامی برای یک رویداد اولیه Motion در یک تاپیک SDM منتشر شود. سایر پیام‌های Motion پس از آن تا گذشت یک دوره زمانی مشخص، از انتشار باز می‌مانند. پس از گذشت آن دوره زمانی، یک پیام رویداد برای آن نوع رویداد ممکن است دوباره منتشر شود.

در برنامه Google Home (GHA)، رویدادهایی که فیلتر شده‌اند همچنان در ... نمایش داده می‌شوند. userتاریخچه رویدادهای برنامه. با این حال، چنین رویدادهایی اعلان برنامه ایجاد نمی‌کنند (حتی اگر آن نوع اعلان فعال باشد).

هر نوع رویداد، منطق فیلترینگ رویداد مخصوص به خود را دارد که توسط گوگل تعریف شده و در هر زمانی قابل تغییر است. این منطق فیلترینگ رویداد، مستقل از منطق رشته رویداد و جلسه است.

حساب‌های خدماتی

حساب‌های سرویس برای مدیریت اشتراک‌های SDM API و پیام‌های رویداد توصیه می‌شوند. یک حساب سرویس توسط یک برنامه یا ماشین مجازی استفاده می‌شود، نه یک شخص، و کلید حساب منحصر به فرد خود را دارد.

احراز هویت حساب کاربری سرویس برای Pub/Sub API از Two-legged OAuth (2LO) استفاده می‌کند.

در جریان مجوزدهی 2LO:

developer با استفاده از کلید سرویس، یک توکن دسترسی درخواست می‌کند.
developer از توکن دسترسی با فراخوانی‌های API استفاده می‌کند.

برای کسب اطلاعات بیشتر در مورد Google 2LO و نحوه راه‌اندازی آن، به بخش «استفاده از OAuth 2.0 برای برنامه‌های سرور به سرور» مراجعه کنید.

مجوز

حساب کاربری سرویس باید برای استفاده با Pub/Sub API مجاز باشد:

فعال کردن Cloud Pub/Sub API در Google Cloud.
همانطور که در بخش «ایجاد حساب کاربری سرویس» توضیح داده شد، یک حساب کاربری سرویس و کلید حساب کاربری سرویس ایجاد کنید. توصیه می‌کنیم فقط نقش Pub/Sub Subscriber را به آن بدهید. حتماً کلید حساب کاربری سرویس را برای دستگاهی که از Pub/Sub API استفاده خواهد کرد، دانلود کنید.
با دنبال کردن دستورالعمل‌های صفحه‌ی مربوط به مرحله‌ی قبل، اطلاعات احراز هویت (کلید حساب سرویس) خود را به کد برنامه ارائه دهید، یا اگر می‌خواهید دسترسی به API را به سرعت آزمایش کنید، با استفاده از oauth2l یک توکن دسترسی به صورت دستی دریافت کنید.
از اعتبارنامه‌های حساب سرویس یا توکن دسترسی با API مربوط به Pub/ project.subscriptions برای دریافت و تأیید پیام‌ها استفاده کنید.

oauth2l

Google oauth2l یک ابزار خط فرمان برای OAuth است که با زبان Go نوشته شده است. آن را برای مک یا لینوکس با استفاده از Go نصب کنید.

اگر Go را روی سیستم خود ندارید، ابتدا آن را دانلود و نصب کنید .
پس از نصب Go، oauth2l را نصب کنید و مکان آن را به متغیر محیطی PATH خود اضافه کنید:
```
go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
```

از oauth2l برای دریافت توکن دسترسی برای API، با استفاده از محدوده(های) 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...

برای اطلاعات بیشتر در مورد نحوه‌ی استفاده، به فایل README oauth2l مراجعه کنید.

کتابخانه‌های کلاینت API گوگل

چندین کتابخانه کلاینت برای APIهای گوگل که از OAuth 2.0 استفاده می‌کنند، در دسترس است. برای اطلاعات بیشتر در مورد زبان مورد نظر خود، به کتابخانه‌های کلاینت API گوگل مراجعه کنید.

هنگام استفاده از این کتابخانه‌ها با Pub/Sub API، از رشته(های) محدوده زیر استفاده کنید:

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

خطاها

کد(های) خطای زیر ممکن است در رابطه با این راهنما نمایش داده شوند:

پیام خطا	آر پی سی	عیب‌یابی
تصویر دوربین دیگر برای دانلود در دسترس نیست.	`DEADLINE_EXCEEDED`	تصاویر رویداد ۳۰ ثانیه پس از انتشار رویداد منقضی می‌شوند. حتماً قبل از انقضا، تصویر را دانلود کنید.
شناسه رویداد متعلق به دوربین نیست.	`FAILED_PRECONDITION`	از `eventID` صحیح برگردانده شده توسط رویداد دوربین استفاده کنید.

برای مشاهده لیست کامل کدهای خطای API به مرجع کدهای خطای API مراجعه کنید.

رویداد با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

فعال کردن رویدادها

میخانه/زیرمجموعه گوگل کلود

اشتراک رویداد

رویدادها را آغاز کنید

ترتیب رویداد

شناسه‌های کاربری

رویدادهای رابطه‌ای

بار مفید

فیلدها

مثال‌ها

ایجاد شده

ساختار ایجاد شده

دستگاه ایجاد شده

دستگاه ایجاد شده

به‌روزرسانی‌شده

دستگاه جابجا شد

حذف شده

ساختار حذف شد

دستگاه حذف شد

دستگاه حذف شد

رویدادهای منابع

بار مفید

بار مفید

فیلدها

اعلان‌های قابل به‌روزرسانی

حالت نخ

فیلتر کردن رویداد

حساب‌های خدماتی

مجوز

oauth2l

کتابخانه‌های کلاینت API گوگل

خطاها

رویداد