מצב דוח

התכונה Report State היא תכונה חשובה שמאפשרת לפעולה Home לדווח באופן יזום על הסטטוס העדכני של המכשיר של המשתמש אל Google Home Graph, במקום להמתין ל-QUERY Intent.

Report State מדווח ל-Google על המצבים של מכשירי המשתמשים שמשויכים אליהם agentUserId שצוין (נשלח בבקשת SYNC המקורית). כאשר Google Assistant רוצה לבצע פעולה שמחייבת הבנה של המצב הנוכחי של המכשיר, הוא יכול פשוט לחפש את פרטי המצב ב-Home Graph במקום להנפיק כוונה (QUERY) לעננים שונים של צד שלישי לפני הנפקת ה-Intent ב-EXECUTE.

בלי Report State, בהתחשב בתאורה של מספר ספקים בסלון, הפקודה Ok Google, Bright my living room מחייבת לפתור כמה אובייקטים מסוג QUERY Intent שנשלחו לכמה עננים, ולא לחפש רק את ערכי הבהירות הנוכחיים על סמך מה שדווח. כדי לספק את חוויית המשתמש הטובה ביותר, Assistant צריך להיות במצב הנוכחי של המכשיר, ללא צורך בהעברה הלוך ושוב למכשיר.

אחרי SYNC הראשוני של המכשיר, הפלטפורמה שולחת Intent מסוג QUERY שאוספת את המצב של המכשיר כדי לאכלס את Home Graph. לאחר מכן, ב-Home Graph נשמרים רק המצב שנשלח עם Report State.

כשקוראים לפונקציה Report State, חשוב לספק את נתוני המצב המלאים של תכונה נתונה. הפונקציה Home Graph מעדכנת מצבים על בסיס של כל תכונה, ומחליפה את כל הנתונים של התכונה הזו בכל פעם שמבוצעת קריאה ל-Report State. לדוגמה, אם רוצים לדווח על המצב של ה-trait StartStop, המטען הייעודי צריך לכלול ערכים של isRunning וגם של isPaused.

שנתחיל?

כדי להטמיע את Report State, צריך לפעול לפי השלבים הבאים:

• הפעלת ממשק ה-API של Google HomeGraph
• יצירת מפתח לחשבון שירות
• קריאה ל-API

הפעלת ממשק ה-API של Google HomeGraph

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

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

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

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

1. בGoogle Cloud Console, נכנסים לדף Create service account key.

   כניסה לדף Create Service Account Key
2. מהרשימה Service account בוחרים את האפשרות New service account.
3. כותבים שם בשדה Service account name.
4. מזינים מזהה בשדה Service account ID.

5. ברשימה Role בוחרים Service Accounts > Service Account Token Creator.

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

7. לוחצים על יצירה. קובץ 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);
}
    

מצב דוח בדיקה

כדי להתכונן לקבלת אישור, חשוב לבדוק את Report State.

לשם כך, מומלץ להשתמש בכלי Viewer של Home Graph, שהוא אפליקציית אינטרנט עצמאית שלא מצריכה הורדה או פריסה.

מרכז הבקרה של Report State עדיין זמין, אבל הוא הוצא משימוש ולא נתמך יותר.

מרכז הבקרה של מצב הדוח

דרישות מוקדמות

כדי לבדוק את הפעולה, תצטרכו את המַפְתח לחשבון השירות ואת agentUserId. אם כבר יש לכם מפתח לחשבון השירות ו agentUserId עיינו בפריסת Report State מרכז השליטה.

פריסת מרכז הבקרה של מצב הדוח

אחרי שמקבלים את המפתח של חשבון השירות ואת מזהה המשתמש של הסוכן לפרויקט, מורידים את הגרסה האחרונה ופורסים אותה מReport Stateמרכז הבקרה. אחרי שמורידים את הגרסה האחרונה, צריך לפעול לפי ההוראות מהקובץ README.MD הכלול.

אחרי שפורסים את מרכז הבקרה של Report State, צריך להיכנס למרכז הבקרה מכתובת ה-URL הבאה (צריך להחליף את your_project_id במזהה הפרויקט):

http://<your-project-id>.appspot.com

במרכז השליטה, מבצעים את הפעולות הבאות:

• בחירת קובץ מפתח של חשבון
• הוספת מזהה של סוכן

לאחר מכן לוחצים על רשימה.

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

תגובות שגיאה

יכול להיות שתקבלו את אחת מהשגיאות הבאות בהתקשרות אל Report State. התגובות האלה מופיעות בצורת קודי סטטוס HTTP.

• 400 Bad Request – השרת לא הצליח לעבד את הבקשה שנשלחה על ידי הלקוח בגלל תחביר לא חוקי. הסיבות הנפוצות לכך כוללות פורמט JSON שגוי או שימוש ב-null במקום ב-"" לערך מחרוזת.
• 404 Not Found – לא הצלחנו למצוא את המשאב המבוקש, אבל יכול להיות שהוא יהיה זמין בעתיד. בדרך כלל, המשמעות היא שלא הצלחנו למצוא את המכשיר המבוקש. ייתכן גם שחשבון המשתמש לא מקושר ל-Google או שקיבלנו agentUserId לא חוקי. צריך לוודא שה-agentUserId תואם לערך שצוין בתגובת SYNC, ושאפשר לטפל כראוי באובייקטים מסוג DISCONNECT.