رویداد

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

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

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

Google Cloud Pub/Sub

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

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

قبل‌از ژانویه ۲۰۲۵، اگر رویدادها برای 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 به‌عنوان راه‌انداز یک‌باره انجام دهید. رویدادهای همه ساختارها و دستگاه‌ها پس‌از این تماس منتشر خواهد شد.

برای مثال، صفحه Authorize (مجوز دادن) را در «راهنمای شروع سریع» ببینید.

ترتیب رویداد

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

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

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

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

userID در سرصفحه پاسخ HTTP هر تماس API نیز دردسترس است.

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

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

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

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

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

پایه‌بار

{
  "eventId" : "768e4eea-b61d-428b-8926-c67e2abaddf9",
  "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
مثال: «d575caa5-75d3-4536-9ee3-287610a433a8»
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" : "ae3f760e-9e1f-4c14-b911-28482e86e56d",
  "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" : "aecdfca3-25ec-4738-bdbf-d24c4a209d93",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "jE1ZfUIAp6z2anjwTJp5E8QxvC...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

فیلدها

فیلد شرح نوع داده
eventId شناسه یکتای رویداد. string
مثال: «aecdfca3-25ec-4738-bdbf-d24c4a209d93»
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 — اولین رویداد در رشته رویداد.
  • به‌روزشده — رویدادی در رشته رویداد جاری. در یک رشته، می‌تواند صفر یا چند رویداد با این وضعیت وجود داشته باشد.
  • پایان‌یافته — آخرین رویداد در رشته رویداد، که ممکن است بسته به نوع رشته، تکراری از آخرین رویداد «به‌روزرسانی‌شده» باشد.

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

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

در برخی موارد، رویدادهای شناسایی‌شده توسط دستگاه ممکن است از انتشار در موضوع 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 مجاز باشد:

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

oauth2l

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

  1. اگر Go را در سیستم خود ندارید، ابتدا آن را بارگیری و نصب کنید.
  2. پس‌از نصب Go،‏ oauth2l را نصب کنید و مکان آن را به متغیر محیطی PATH اضافه کنید: 
    go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
  3. بااستفاده از دامنه‌های OAuth مناسب، از oauth2l برای دریافت کد دسترسی برای میانای برنامه‌سازی کاربردی استفاده کنید: 
    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

خطاها

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

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

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