דף זה תורגם על ידי Cloud Translation API.

אירועים

האירועים הם אסינכרוניים ומנוהלים על ידי Google Cloud Pub/Sub, במסגרת נושא אחד לכל Projectאירועים מספקים עדכונים לכל המכשירים והמבנים, וקבלה של אירועים מובטחת, כל עוד אסימון הגישה לא מבוטל על ידי המשתמש והודעות האירוע פג תוקף.

הפעל אירועים

אירועים הם תכונה אופציונלית של SDM API. צפייה הפעלת אירועים כך אפשר להפעיל אותן עבור Project.

Google Cloud Pub/Sub

אפשר לקרוא מידע נוסף במסמכי התיעוד של Google Cloud Pub/Sub. על אופן הפעולה של Pub/Sub. הקפידו במיוחד על הדברים הבאים:

מידע בסיסי על Pub/Sub מדריכים
הסבר על אימות
לבחור ספריית לקוח שסופקה או לכתוב משלכם ולהשתמש פלטפורמות של API ל-REST/HTTP או ל-gRPC.

מינוי לאירוע

כשאירועים יופעלו עבור Project, יסופק לך נושא ספציפי Project מזהה, בפורמט:

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

כדי לקבל אירועים, צריך ליצור משיכה או התראות לנושא הזה, בהתאם הוא תרחיש לדוגמה. יש תמיכה במספר מינויים לנושא ה-SDM. צפייה ניהול מינויים, לקבלת מידע נוסף מידע.

הפעלת אירועים

כדי להתחיל אירועים בפעם הראשונה אחרי יצירת מינוי Pub/Sub, צריך להגדיר devices.list קריאה ל-API כטריגר חד-פעמי. אירועים של כל המבנים והמכשירים יתפרסמו לאחר מכן שיחה.

לדוגמה, אפשר להיכנס אל מתן הרשאה להתחלה המהירה מדריך.

סדר האירוע

Pub/Sub לא מבטיחה אספקה של אירועים, וסדר קבלת האירועים עשוי שלא להיות מובטח תואמים לסדר שבו התרחשו האירועים בפועל. שימוש בtimestamp בשדה כדי לסייע בהתאמה של סדר האירוע. אירועים יכולים גם להגיע בנפרד או יחד בהודעת אירוע אחת.

מידע נוסף זמין במאמר הבא: סידור ההודעות לפי סדר מסוים.

מזהי משתמשים

אם ההטמעה מבוססת על משתמשים (ולא על מבנה או מכשיר), כדאי להשתמש השדה userID מהמטען הייעודי (payload) של האירוע לצורך קישור בין משאבים לאירועים. השדה הזה הוא מזהה מעורפל שמייצג משתמש ספציפי.

ה-userID זמין גם בכותרת התגובה של ה-HTTP של כל קריאה ל-API.

אירועי קשר

אירועי קשר מייצגים עדכון יחסי של משאב. לדוגמה, כשמכשיר נוספים למבנה, או כשמכשיר נמחק ממבנה.

יש שלושה סוגים של אירועי קשר:

נוצרה
נמחק
מעודכן

המטען הייעודי (Payload) של אירוע קשור הוא:

מטען ייעודי (payload)

{
  "eventId" : "a02e4f56-85e4-402f-a76b-cb3b69e864c3",
  "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` דוגמה: 'a98e5ea1-5d09-4da2-a1b6-2ef63b5d18de'
`timestamp`	השעה שבה התרחש האירוע.	`string` לדוגמה: '2019-01-01T00:00:01Z'
`relationUpdate`	אובייקט שמפרט מידע על עדכון הקשר.	`object`
`userId`	מזהה ייחודי ומעורפל שמייצג את המשתמש.	`string` דוגמה: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"

בקטע אירועים אפשר למצוא מידע נוסף על ההבדלים סוגי אירועים שונים ואיך הם פועלים.

דוגמאות

מטענים ייעודיים (payloads) של אירועים משתנים בהתאם לכל סוג של אירוע קשר:

מועד היצירה

המבנה נוצר

"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 במכשיר:

מטען ייעודי (payload)

{
  "eventId" : "b36b540f-8bc5-4ab6-9a96-d8952a275f00",
  "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"
  ]
}

משתמשים ב אישי מסמכי תיעוד של trait כדי להבין את הפורמט של המטען הייעודי (payload) לכל משאב של שינוי שדה trait. אירוע.

לאירוע שנוצר בתגובה לפעולה במכשיר שלא משנה את שדה התכונה, יש גם מטען ייעודי (payload) עם אובייקט resourceUpdate, אבל עם אובייקט events במקום אובייקט traits:

מטען ייעודי (payload)

{
  "eventId" : "62c78247-dc81-4dd6-95fd-fd378b9eff97",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "gA5POI6_6FKfSRH4A-YnfSEouc...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

סוגים אלה של אירועי משאבים מוגדרים בתכונות ספציפיות. לדוגמה, אירוע התנועה מוגדר CameraMotion trait. לעיון במסמכי התיעוד של כל תכונה כדי להבין את הפורמט של המטען הייעודי (Payload) לסוגים האלה של אירועי משאבים.

שדות

שדה	תיאור	סוג הנתונים
`eventId`	המזהה הייחודי של האירוע.	`string` דוגמה: '62c78247-dc81-4dd6-95fd-fd378b9eff97'
`timestamp`	השעה שבה התרחש האירוע.	`string` לדוגמה: '2019-01-01T00:00:01Z'
`resourceUpdate`	אובייקט שמכיל מידע על עדכון המשאב.	`object`
`userId`	מזהה ייחודי ומעורפל שמייצג את המשתמש.	`string` דוגמה: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
`eventThreadId`	המזהה הייחודי של שרשור האירוע.	`string` דוגמה: 'd67cd3f7-86a7-425e-8b3-462f92ec9f59'
`eventThreadState`	מצב השרשור של האירוע.	`string` ערכים: "STARTED", "UPDATED", "ENDED"
`resourceGroup`	אובייקט שמציין משאבים שייתכן שיש להם עדכונים דומים לאירוע הזה. המשאב של האירוע עצמו (מהאובייקט `resourceUpdate`) תמיד יופיע באובייקט הזה.	`object`

בקטע אירועים אפשר למצוא מידע נוסף על ההבדלים סוגי אירועים שונים ואיך הם פועלים.

התראות הניתנות לעדכון

אפשר להטמיע באפליקציה התראות שמבוססות על אירועים של משאבים, למשל עבור Android או iOS. כדי לצמצם את מספר ההתראות שנשלחות, תכונה שנקראת ייתכן שניישם התראות הניתנות לעדכון, במקרים שבהם התראות קיימות מעודכנים במידע חדש על סמך אירועים עתידיים באותו אירוע של שרשור.

בחירת תכונות של אירועים שתומכים בהתראות שניתן לעדכן, והם מתויגים בתור עדכונים בתיעוד. האירועים האלה כוללים שדה נוסף בשם eventThreadId במטענים הייעודיים (payloads) שלהם. שימוש בטיוטה הזו שדה לקישור אירועים נפרדים כדי לעדכן אירוע קיים התראה שהוצגה למשתמש.

שרשור של אירוע הוא לא סשן של אירוע. השרשור של האירוע מזהה סטטוס מעודכן של אירוע קודם באותו השרשור. בסשן של אירוע המערכת מזהה אירועים נפרדים שקשורים זה לזה, וגם בכל סשן של אירוע יכולים להיות מספר שרשורים של אירועים.

למטרות התראות, סוגים שונים של אירועים מקובצים שרשורים.

לוגיקת הקיבוץ והתזמון של שרשורים זו מטופלת על ידי Google כפופה ל בכל שלב. developer צריך לעדכן את ההתראות על סמך שרשורי אירועים וסשנים שסופקו על ידי SDM API.

מצב השרשור

גם לאירועים שתומכים בהתראות שניתנות לעדכון יש eventThreadState שמציין את המצב של שרשור האירוע באותה נקודת זמן. הזה מכיל את הערכים הבאים:

התחיל – האירוע הראשון בשרשור של אירועים.
עודכן – אירוע בשרשור של אירוע פעיל. בשרשור אחד יכולים להיות אפס אירועים או יותר במצב הזה.
הסתיים – האירוע האחרון בשרשור של אירוע, שיכול להיות כפילות של האירוע האחרון שמעודכן, בהתאם לסוג השרשור.

אפשר להשתמש בשדה הזה כדי לעקוב אחרי ההתקדמות של שרשור אירוע, וכשיש לו הסתיים.

סינון אירועים

במקרים מסוימים, יכול להיות שאירועים שזוהו על ידי מכשיר יסוננו כדי שלא יפורסמו לנושא SDM Pub/Sub. ההתנהגות הזו נקראת סינון אירועים. מטרת סינון האירועים היא פרסום יותר מדי הודעות אירועים דומות בפרק זמן קצר.

לדוגמה, ייתכן שהודעה תפורסם בנושא SDM לאירוע ראשוני של תנועה. המלצות אחרות הודעות ל'תנועה' שלאחר מכן יהיו הן מסוננות ולא מאפשרות לפרסם עד שיחלוף פרק זמן מוגדר. אחרי התקופה הזו הזמן שחלף, ייתכן שהודעה על אירוע מסוג זה תפורסם שוב.

באפליקציית Google Home (GHA), אירועים עדיין יוצגו בהיסטוריית האירועים של user. אבל, למשל, אירועים לא יוצרים התראה לאפליקציה (גם אם סוג ההתראה הזה ).

לכל סוג של אירוע יש לוגיקה משלו לסינון אירועים, שמוגדרת לפי Google וכפופה לשינויים בכל עת. הלוגיקה הזו של סינון האירועים ללא תלות בשרשור של האירוע ובלוגיקת הסשן.

חשבונות שירות

מומלץ להשתמש בחשבונות שירות לניהול SDM API מינויים והודעות על אירועים. חשבון שירות משמש אפליקציה או למכונה וירטואלית ולא לאדם, ויש לה מפתח חשבון ייחודי משלה.

ב-Pub/Sub API נעשה שימוש בהרשאה באמצעות חשבון שירות OAuth דו-שלבי (2LO).

בתהליך ההרשאה של 2LO:

התקבלה בקשה של developer לאסימון גישה באמצעות מפתח שירות.
ה- developer משתמש באסימון הגישה עם קריאות ל-API.

לקבלת מידע נוסף על Google 2LO ועל אופן ההגדרה, אפשר להיכנס אל שימוש ב-OAuth 2.0 לשרת לשרת אפליקציות.

אישור

חשבון השירות צריך להיות מורשה לשימוש עם API של Pub/Sub:

הפעלת Cloud Pub/Sub API ב-Google Cloud.
יוצרים חשבון שירות ומפתח של חשבון שירות כפי שמתואר ב יצירת חשבון שירות. מומלץ להקצות לו רק את התפקיד מנוי ב-Pub/Sub. צריך לוודא להוריד את המפתח של חשבון השירות למכונה שתשתמש בה API של Pub/Sub
מזינים את פרטי הכניסה לאימות (המפתח של חשבון השירות) את הקוד של האפליקציה לפי ההוראות שבדף או לקבל אסימון גישה באופן ידני באמצעות oauth2l, אם שרוצים לבדוק במהירות את הגישה ל-API.
משתמשים בפרטי הכניסה של חשבון השירות או באסימון הגישה באמצעות Pub/Sub project.subscriptions API לקבל הודעות ולאשר אותן.

Oauth2l

oauth2l של Google הוא כלי שורת פקודה ל-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...

מידע נוסף זמין בקובץ ה-README של oauth2l מידע.

ספריות הלקוח של Google API

יש כמה ספריות לקוח שזמינות ל-Google APIs שמשתמשות ב-OAuth 2.0. למידע נוסף על ספריות הלקוח של Google API, ראו ספריות לקוח של Google API. בשפה הרצויה.

כשמשתמשים בספריות האלה עם Pub/Sub API, צריך להשתמש מחרוזות ההיקף הבאות:

https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform

שגיאות

קודי השגיאה הבאים עשויים להיות מוחזרים בהקשר למדריך הזה:

הודעת שגיאה	הכנסה לקליק	פתרון בעיות
תמונת המצלמה כבר לא זמינה להורדה.	`DEADLINE_EXCEEDED`	התוקף של תמונות האירוע פג 30 שניות לאחר פרסום האירוע. חשוב להקפיד להוריד את התמונה לפני שהתוקף שלה יפוג.
מזהה האירוע לא שייך למצלמה.	`FAILED_PRECONDITION`	צריך להשתמש ב`eventID` הנכון שהוחזר על ידי אירוע המצלמה.

מידע נוסף זמין בחומר העזר בנושא קוד שגיאה של API את הרשימה המלאה של קודי השגיאה של ה-API.