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

رویداد

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

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

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

Google Cloud Pub/Sub

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

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

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

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

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

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

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

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

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

سفارش رویداد

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

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

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

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

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

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

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

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

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

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

بار

{
  "eventId" : "d5c0f0bd-de65-44fd-ac60-686c302e56eb",
  "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 دسترسی به این دستگاه خاص را به a developer، و userدستگاه مجاز اکنون به ساختار مجاز آنها مرتبط است، که این رویداد را آغاز می کند.

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

فیلدها

میدان	توضیحات	نوع داده
`eventId`	شناسه منحصر به فرد رویداد.	`string` مثال: "64b87b46-1aec-42a4-8c01-997a407814df"
`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" : "a88bc884-d2b8-42d6-adba-b7be92c232a3",
  "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" : "4f80de08-1b77-42a4-b33e-40876a2a1865",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "MWJ253hZMPAsJZJWbrGM4ThsKM...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

فیلدها

میدان	توضیحات	نوع داده
`eventId`	شناسه منحصر به فرد رویداد.	`string` مثال: "4f80de08-1b77-42a4-b33e-40876a2a1865"
`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 مدیریت می شود و در هر زمان ممکن است تغییر کند. الف developer باید اعلان ها را بر اساس رشته ها و جلسات ارائه شده توسط SDM API به روز کند.

وضعیت نخ

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

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

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

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

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

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

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

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

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

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

مجوز حساب سرویس برای Pub/Sub API از 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 یک نشانه دسترسی را به صورت دستی دریافت کنید.
از اعتبارنامه حساب سرویس یا رمز دسترسی با Pub/Sub project.subscriptions API برای کشیدن و تایید پیام ها استفاده کنید.

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...

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