מצב דוח

‫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
• יצירת מפתח לחשבון שירות
• שליחת קריאה ל-API

הפעלת Google HomeGraph API

1. ב-Google Cloud Console, עוברים לדף HomeGraph API.

   כניסה לדף HomeGraph API
2. בוחרים את הפרויקט שתואם למזהה הפרויקט smart home.
3. לוחצים על הפעלה.

יצירת מפתח של חשבון שירות

כדי ליצור מפתח לחשבון שירות מ-Google Cloud Console, פועלים לפי ההוראות הבאות:

1. ב-Google Cloud Console, עוברים לדף Service accounts.

   מעבר לדף Service Accounts

   יכול להיות שתצטרכו לבחור פרויקט לפני שתועברו לדף 'חשבונות שירות'.

2. לוחצים על addיצירת חשבון שירות.

3. כותבים שם בשדה Service account name.

4. מזינים מזהה בשדה Service account ID.

5. כותבים תיאור בשדה Service account description.

6. לוחצים על יצירה והמשך.

7. בתפריט הנפתח Role, בוחרים באפשרות Service Accounts > Service Account OpenID Connect Identity Token Creator.

8. לוחצים על המשך.

9. לוחצים על סיום.

10. בוחרים את חשבון השירות שיצרתם מהרשימה של חשבונות השירות ובוחרים באפשרות ניהול מפתחות בתפריט more_vert פעולות.

11. בוחרים באפשרות Add key (הוספת מפתח) > Create new key (יצירת מפתח חדש).

12. בסוג המפתח, בוחרים באפשרות JSON.

13. לוחצים על יצירה. קובץ JSON שמכיל את המפתח יורד למחשב.

שליחת קריאה ל-API

בוחרים באחת מהאפשרויות בכרטיסיות שלמטה:

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
          }
        }
      }
    }
  }
});
    

  // 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 מתבצע בצורה תקינה.

דיווח על מצב אונליין ואופליין

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }