رویداد

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

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

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

Google Cloud Pub/Sub

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

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

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

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

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

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

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

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

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

{
  "eventId" : "7c786f36-8068-4b86-ba67-d6e0d28ebb11",
  "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 همیشه خالی است.

فیلدها

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

مثال‌ها

بار داده رویداد برای هر نوع رویداد رابطه متفاوت است:

"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" : "59381967-62e1-427b-98b8-67d5dbbd590c",
  "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" : "1608503f-fedf-43cc-b29c-aa4e3b685a60",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "Ki0F7T-Joca_uRg42loDugGevl...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

فیلدها

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

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

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

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

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

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

وضعیت رشته

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

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

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

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

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

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

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

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

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

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

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

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

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

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

صدور مجوز

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

1. Cloud Pub/Sub API را در Google Cloud فعال کنید.
2. حساب خدمات و کلید حساب خدمات را همان‌طور که در ایجاد حساب خدمات توضیح داده شده است ایجاد کنید. توصیه می‌کنیم فقط نقش Pub/Sub Subscriber را به آن بدهید. حتماً کلید حساب سرویس را در دستگاهی که از Pub/Sub API استفاده خواهد کرد بارگیری کنید.
3. با دنبال کردن دستورالعمل‌های صفحه در مرحله قبلی، اعتبارنامه‌های اصالت‌سنجی (کلید حساب سرویس) را به کد برنامه ارائه دهید، یا اگر می‌خواهید دسترسی به میانای برنامه‌سازی کاربردی را سریعاً آزمایش کنید، بااستفاده از 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

خطاها

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

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