Report State היא תכונה חשובה שמאפשרת ל-Google Home Action לדווח באופן יזום ל-Google Home Graph על הסטטוס העדכני של המכשיר של המשתמש, במקום לחכות ל-intent של QUERY
.
Report State מדווח ל-Google על מצבי המכשירים של המשתמשים עם agentUserId
שמשויך אליהם (נשלח בבקשה המקורית SYNC
). כשGoogle Assistant רוצה לבצע פעולה שנדרש לה להבין את המצב הנוכחי של המכשיר, היא יכולה פשוט לחפש את פרטי המצב ב-Home Graph במקום להוציא כוונת QUERY
לעננים שונים של צד שלישי לפני שהיא מוציאה את הכוונה EXECUTE
.
בלי Report State, אם יש בסלון נורות של כמה ספקים, הפקודה Ok Google, brighten my living room מחייבת לפתור כמה כוונות QUERY
שנשלחות לכמה עננים, במקום פשוט לחפש את ערכי הבהירות הנוכחיים על סמך מה שדווח בעבר. כדי לספק את חוויית המשתמש הטובה ביותר,
Assistant צריך לדעת מה המצב הנוכחי של המכשיר,
בלי שיהיה צורך לבצע שליחה וקבלה של נתונים מהמכשיר.
אחרי הSYNC
הראשוני למכשיר, הפלטפורמה שולחת כוונה QUERY
שמקבלת את מצב המכשיר כדי לאכלס את Home Graph.
אחרי הנקודה הזו, Home Graph מאחסן רק את הסטטוס שנשלח עם Report State.
כשמתקשרים אל Report State, חשוב לספק נתוני מצב מלאים של מאפיין מסוים. Home Graph מעדכן את הסטטוסים לפי מאפיין, ומחליף את כל הנתונים של המאפיין הזה כשמתבצעת קריאה ל-Home Graph.Report State לדוגמה, אם מדווחים על מצב המאפיין StartStop, מטען הייעוד צריך לכלול ערכים גם ל-isRunning
וגם ל-isPaused
.
שנתחיל?
כדי להטמיע את Report State, מבצעים את השלבים הבאים:
הפעלת Google HomeGraph API
-
ב-Google Cloud Console, עוברים לדף HomeGraph API.
כניסה לדף HomeGraph API - בוחרים את הפרויקט שתואם למזהה הפרויקט smart home.
- לוחצים על הפעלה.
יצירת מפתח של חשבון שירות
כדי ליצור מפתח לחשבון שירות מ-Google Cloud Console, פועלים לפי ההוראות הבאות:
-
ב-Google Cloud Console, עוברים לדף Service accounts.
מעבר לדף Service Accountsיכול להיות שתצטרכו לבחור פרויקט לפני שתועברו לדף 'חשבונות שירות'.
לוחצים על
יצירת חשבון שירות.כותבים שם בשדה Service account name.
מזינים מזהה בשדה Service account ID.
כותבים תיאור בשדה Service account description.
לוחצים על יצירה והמשך.
בתפריט הנפתח Role, בוחרים באפשרות Service Accounts > Service Account OpenID Connect Identity Token Creator.
לוחצים על המשך.
לוחצים על סיום.
בוחרים את חשבון השירות שיצרתם מהרשימה של חשבונות השירות ובוחרים באפשרות ניהול מפתחות בתפריט
פעולות.בוחרים באפשרות Add key (הוספת מפתח) > Create new key (יצירת מפתח חדש).
בסוג המפתח, בוחרים באפשרות JSON.
לוחצים על יצירה. קובץ JSON שמכיל את המפתח יורד למחשב.
שליחת קריאה ל-API
בוחרים באחת מהאפשרויות בכרטיסיות שלמטה:
HTTP
Home Graph מספק נקודת קצה (endpoint) של HTTP
- משתמשים בקובץ ה-JSON של חשבון השירות שהורד כדי ליצור אסימון אינטרנט מסוג JSON (JWT). מידע נוסף זמין במאמר אימות באמצעות חשבון שירות.
- מקבלים אסימון גישה מסוג OAuth 2.0 עם ההיקף
https://www.googleapis.com/auth/homegraph
באמצעות oauth2l: - יוצרים את בקשת ה-JSON עם
agentUserId
. דוגמה לבקשת JSON לדוח מצב ולהתראה: - משלבים את ה-JSON של מצב הדוח וההתראה ואת האסימון בבקשת HTTP POST לנקודת הקצה של Google Home Graph. הנה דוגמה לאופן שבו אפשר לשלוח את הבקשה בשורת הפקודה באמצעות
curl
, כבדיקה:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "requestId": "123ABC", "agentUserId": "user-123", "payload": { "devices": { "states": { "light-123": { "on": true } } } } }
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d @request-body.json \ "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
gRPC
Home Graph מספק נקודת קצה של gRPC
- אפשר לקבל את הגדרת השירות של Protocol Buffers עבור Home Graph API.
- פועלים לפי ההוראות בתיעוד למפתחים של gRPC כדי ליצור stub של לקוח לאחת מהשפות הנתמכות.
- מפעילים את השיטה ReportStateAndNotification.
Node.js
לקוח Google APIs Node.js מספק קשירות ל-API Home Graph.
- מאתחלים את שירות
google.homegraph
באמצעות Application Default Credentials. - מפעילים את השיטה
reportStateAndNotification
עם ReportStateAndNotificationRequest. היא מחזירהPromise
עם ReportStateAndNotificationResponse.
const homegraphClient = homegraph({ version: 'v1', auth: new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/homegraph' }) }); const res = await homegraphClient.devices.reportStateAndNotification({ requestBody: { agentUserId: 'PLACEHOLDER-USER-ID', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { states: { "PLACEHOLDER-DEVICE-ID": { on: true } } } } } });
Java
ספריית הלקוח של HomeGraph API ל-Java מספקת קשירות ל-Home Graph API.
- מאתחלים את
HomeGraphApiService
באמצעות Application Default Credentials. - מפעילים את השיטה
reportStateAndNotification
עםReportStateAndNotificationRequest
. הפונקציה מחזירהReportStateAndNotificationResponse
.
// Get Application Default credentials. GoogleCredentials credentials = GoogleCredentials.getApplicationDefault() .createScoped(List.of("https://www.googleapis.com/auth/homegraph")); // Create Home Graph service client. HomeGraphService homegraphService = new HomeGraphService.Builder( GoogleNetHttpTransport.newTrustedTransport(), GsonFactory.getDefaultInstance(), new HttpCredentialsAdapter(credentials)) .setApplicationName("HomeGraphExample/1.0") .build(); // Build device state payload. Map<?, ?> states = Map.of("on", true); // Report device state. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states)))); homegraphService.devices().reportStateAndNotification(request); }
מצב דוח הבדיקה
כדי להכין את השילוב של Cloud-to-cloud לאישור, חשוב לבדוק את Report State.
לשם כך, מומלץ להשתמש בכלי Home Graph Viewer, שהוא אפליקציית אינטרנט עצמאית שלא דורשת הורדה או פריסה.
לוח הבקרה Report State עדיין זמין, אבל הוא הוצא משימוש ואין יותר תמיכה בו.
לוח הבקרה של מצב הדוח
דרישות מוקדמות
כדי לבדוק את השילוב של Cloud-to-cloud, צריך את מפתח חשבון השירות ואת agentUserId
. אם כבר יש לכם מפתח לחשבון שירות וagentUserId
אתם רואים את האפשרות Deploy the Report State Dashboard.
פריסת מרכז הבקרה Report State
אחרי שמקבלים את מפתח חשבון השירות ואת מזהה המשתמש של הסוכן בפרויקט, מורידים את הגרסה האחרונה מReport Stateמרכז הבקרה ומבצעים פריסה.
אחרי שמורידים את הגרסה העדכנית, פועלים לפי ההוראות בקובץ README.MD
שמצורף.
אחרי שפורסים את לוח הבקרה Report State, ניגשים אליו מכתובת ה-URL הבאה (מחליפים את your_project_id במזהה הפרויקט):
http://<your-project-id>.appspot.com
במרכז הבקרה, מבצעים את הפעולות הבאות:
- בחירת קובץ מפתח החשבון
- הוספת agentUserId
אחר כך לוחצים על רשימה.
כל המכשירים שלכם מופיעים ברשימה. אחרי שהרשימה מתמלאת, אפשר להשתמש בלחצן רענון כדי לעדכן את מצבי המכשירים. אם יש שינוי במצב המכשיר, השורה מודגשת בירוק.
דיווח על אי התאמה במצב
המדד 'דיוק מצב הדוח מבוסס-השאילתה' מודד את מידת ההתאמה בין המצב העדכני של הדוח במכשיר לבין הסטטוס של המכשיר בזמן שמשתמש שולח שאילתה לגביו. הערך הזה צפוי להיות 99.5%.
תשובות שגיאה
יכול להיות שתקבלו אחת מהתשובות הבאות לשגיאה כשמתקשרים אל Report State. התשובות האלה מגיעות בצורה של קודי סטטוס HTTP.
-
400 Bad Request
– השרת לא הצליח לעבד את הבקשה שנשלחה מהלקוח בגלל תחביר לא תקין. סיבות נפוצות לכך הן JSON לא תקין או שימוש ב-null
במקום '' לערך מחרוזת. -
404 Not Found
– לא נמצא המשאב המבוקש, אבל יכול להיות שהוא יהיה זמין בעתיד. בדרך כלל, המשמעות היא שלא הצלחנו למצוא את המכשיר המבוקש. יכול להיות גם שחשבון המשתמש לא מקושר ל-Google או שקיבלנוagentUserId
לא תקין. חשוב לוודא שהערך שלagentUserId
זהה לערך שמופיע בתגובת SYNC, ושהטיפול בכוונות DISCONNECT מתבצע בצורה תקינה.
דיווח על מצב אונליין ואופליין
כשמכשיר נמצא במצב אופליין, צריך לדווח על <code{"online": code="" dir="ltr" false}<="" translate="no"> אל Report State תוך חמש דקות מההתנהגות של המכשיר. לעומת זאת, כשמכשיר חוזר למצב אונליין, צריך לשלוח את הערך <code{"online": code="" dir="ltr" translate="no" true}<=""> אל Report State תוך חמש דקות מההתנהגות של המכשיר. בכל פעם שמכשיר חוזר למצב אונליין, השותף צריך לדווח על כל מצבי המכשיר הנוכחיים באמצעותreportStateAndNotification
API.
בדוגמה הזו אפשר לראות שסוג המכשיר light
מחובר לאינטרנט, ומוצגים כל מצבי המכשיר הנוכחיים.
"requestId": "test-request-id",
"agentUserId": "agent-user-1",
"payload":{
"devices": {
"states": {
"device-id-1": {
"brightness": 65,
"on": true,
"online": true
}
"notifications": {},
}
}
}