מצב דוח

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

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

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

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

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

בוא נתחיל

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

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

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

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

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

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

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

1. ב-Google Cloud Console, עוברים לדף Create key account key.

   כניסה לדף Key Create 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. בהגדרה Key type, בוחרים באפשרות JSON.

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

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

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

דוח מצבי דיווח

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

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

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

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

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

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

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

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

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

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

תגובות שגיאה

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

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