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

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

رویداد

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

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

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

Google Cloud Pub/Sub

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

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

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

انتقال تا ۳۰ نوامبر ۲۰۲۶ الزامی است: پس‌از ۳۰ نوامبر ۲۰۲۶، اعلان‌های رویداد دیگر در موضوعات Pub/Sub میزبانی‌شده توسط Google منتشر نخواهند شد. اگر ادغام شما از موضوعی با میزبانی Google استفاده می‌کند، باید قبل‌از مهلت مقرر به موضوع Pub/Sub با میزبانی خودتان که در پروژه Google Cloud خودتان ایجاد شده است منتقل شوید، درغیراین‌صورت جاری‌سازی رویداد متوقف خواهد شد و برنامه شما دیگر به‌روزرسانی‌های هم‌زمان وضعیت دستگاه یا رویدادهای ویژگی را دریافت نخواهد کرد. برای مراحل انتقال، مشترک شدن در رویدادها را ببینید.

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

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

اکنون همه پروژه‌ها باید موضوعات Pub/Sub خود را در پروژه Google Cloud خودشان میزبانی کنند (برای پروژه‌های جدید از ژانویه ۲۰۲۵ اجباری است و برای همه پروژه‌های موجود تا ۳۰ نوامبر ۲۰۲۶ الزامی است)، به این شکل:

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

اگر project شما ازقبل از موضوعی با میزبانی خودتان در پروژه Google Cloud خودتان استفاده می‌کند، هیچ اقدامی لازم نیست. انتقال پیکربندی موضوع Pub/Sub شما، کدهای دسترسی کاربر یا اجازه‌های OAuth موجود را نامعتبر نمی‌کند. موضوعات و اشتراک‌های خودمیزبان مشمول قیمت‌گذاری استاندارد Google Cloud Pub/Sub (که شامل سطح رایگان ۱۰ گیگابایت در ماه است) می‌شوند. برای اطلاعات بیشتر، ایجاد موضوع را ببینید.

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

رویدادهای شروع

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

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

ترتیب رویداد

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

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

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

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

userID در سرایند پاسخ HTTP هر فراخوانی میانای برنامه‌سازی کاربردی نیز دردسترس است.

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

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

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

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

پایه‌بار برای رویداد رابطه به‌صورت زیر است:

پایه‌بار

{
  "eventId" : "1a2e13bc-c23c-4bc4-8366-6b5669607f0e",
  "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` مثال: «a121b435-e3bb-4ba1-9dea-945686b7dabf»
`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" : "caec1000-1cab-43d3-946f-bc3c5f8615c9",
  "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" : "0111d3f2-5e7d-4ecf-88ed-8f3b0324f75c",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "jOvQqNOSL76837k_JxTR4BJ6nw...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

فیلدها

فیلد	شرح	نوع داده
`eventId`	شناسه یکتای رویداد.	`string` مثال: «0111d3f2-5e7d-4ecf-88ed-8f3b0324f75c»
`timestamp`	زمانی که رویداد رخ داده است.	`string` مثال: «‎2019-01-01T00:00:01Z»
`resourceUpdate`	شیئی که اطلاعات مربوط به به‌روزرسانی منبع را شرح می‌دهد.	`object`
`userId`	شناسه یکتای مبهمی که کاربر را نشان می‌دهد.	`string` مثال: «AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi»
`eventThreadId`	شناسه یکتای رشته رویداد.	`string` مثال: «d67cd3f7-86a7-425e-8bb3-462f92ec9f59»
`eventThreadState`	وضعیت رشته رویداد.	`string` مقادیر: «STARTED» (شروع‌شده)، «UPDATED» (به‌روزشده)، «ENDED» (پایان‌یافته)
`resourceGroup`	شیئی که منابعی را نشان می‌دهد که ممکن است به‌روزرسانی‌های مشابهی با این رویداد داشته باشند. منبع خود رویداد (از شیء `resourceUpdate`) همیشه در این شیء وجود خواهد داشت.	`object`

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

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

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

رویدادهای منتخب از اعلان‌های قابل‌به‌روزرسانی پشتیبانی می‌کنند و در اسناد با برچسب قابل‌به‌روزرسانی مشخص شده‌اند. این رویدادها فیلد دیگری به‌نام eventThreadId در محموله داده‌شان دارند. از این فیلد برای پیوند دادن رویدادهای تکی به یکدیگر با هدف به‌روزرسانی اعلان موجودی که برای کاربر نمایش داده شده است استفاده کنید.

رشته رویداد با جلسه رویداد یکسان نیست. رشته رویداد وضعیت به‌روزشده رویداد قبلی را در همان رشته شناسایی می‌کند. جلسه رویداد رویدادهای جداگانه‌ای را که به یکدیگر مرتبط هستند شناسایی می‌کند و می‌تواند چندین رشته رویداد برای یک جلسه رویداد معین وجود داشته باشد.

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

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

وضعیت رشته

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

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

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

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

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

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

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

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

حساب‌های سرویس

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

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

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

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

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

صدور مجوز

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

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

oauth2l

Google oauth2l ابزار خط فرمان برای OAuth است که در Go نوشته شده است. آن را برای Mac یا Linux بااستفاده از 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...

برای اطلاعات بیشتر درباره استفاده، به 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`	تصاویر رویداد ۳۰ ثانیه پس‌از انتشار رویداد منقضی می‌شود. حتماً تصویر را قبل‌از انقضا بارگیری کنید.
شناسه رویداد متعلق به دوربین نیست.	`FAILED_PRECONDITION`	از `eventID` صحیح برگردانده‌شده توسط رویداد دوربین استفاده کنید.

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

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

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

Google Cloud Pub/Sub

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

رویدادهای شروع

ترتیب رویداد

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

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

پایه‌بار

فیلدها

مثال‌ها

زمان ایجاد

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

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

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

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

دستگاه منتقل شد

حذف شد

ساختمان حذف شد

دستگاه حذف شد

دستگاه حذف شد

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

پایه‌بار

پایه‌بار

فیلدها

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

وضعیت رشته

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

حساب‌های سرویس

صدور مجوز

oauth2l

کتابخانه‌های کارخواه Google API

خطاها

رویداد