رویداد

placeholder57 l10n-placeholder58 -placeholder68 l10n-

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

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

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

Google Cloud Pub/Sub

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

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

وقتی رویدادها برای Projectشما فعال می شوند، موضوعی خاص برای شناسه Project به شما ارائه می شود، به شکل:

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

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

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

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

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

سفارش رویداد

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

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

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

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

userID نیز در سربرگ پاسخ HTTP هر تماس API موجود است.

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

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

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

  • CREATED
  • حذف شده
  • به روز شد

بارگذاری برای یک رویداد رابطه به شرح زیر است:

ظرفیت ترابری

{
  "eventId" : "0ebaf6d5-c3a6-4da0-8b36-53b8dc74ed97",
  "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 دسترسی به این دستگاه خاص را به یک partnerاعطا کرده است، و دستگاه مجاز userاکنون به ساختار مجاز آنها مرتبط است، که این رویداد را آغاز می کند.

یک subject فقط می تواند یک اتاق یا یک سازه باشد. اگر a developer اجازه مشاهده ساختار userرا نداشته باشد، subject همیشه خالی است.

زمینه های

رشته شرح نوع داده
eventId شناسه منحصر به فرد رویداد. string
مثال: "f044e0e8-a92a-4096-8cee-52d0700f2881"
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" : "7ced16bd-0bcb-4134-a9b3-835da0457557",
  "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" : "284c805e-b846-43b4-8f5b-680b75b29d61",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "wPN0CWvIgPreoQmZmIg9rkLLq2...", } } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] }

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

زمینه های

رشته شرح نوع داده
eventId شناسه منحصر به فرد رویداد. string
مثال: "284c805e-b846-43b4-8f5b-680b75b29d61"
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 مدیریت می شود و در هر زمان ممکن است تغییر کند. یک partner باید اعلان‌ها را براساس رشته‌های رویداد و جلسات ارائه‌شده توسط SDM API به‌روزرسانی کند.

وضعیت نخ

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

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

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

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

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

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

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

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

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

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

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

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

  • partner یک نشانه دسترسی با استفاده از یک کلید سرویس درخواست می کند.
  • partner از نشانه دسترسی با فراخوانی به API استفاده می کند.

برای کسب اطلاعات بیشتر در مورد 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 نصب کنید.

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

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

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