מצב דוח

Report State היא תכונה חשובה שמאפשרת לפעולה Google Home לדווח באופן יזום על הסטטוס העדכני של המכשיר של המשתמש בחזרה אל Google Home Graph, במקום להמתין לכוונה 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 מעדכן את המצבים לפי מאפיין, ומחליף את כל הנתונים של המאפיין הזה כשמתבצעת קריאה ל-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. לוחצים על ENABLE.

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

פועלים לפי ההוראות הבאות כדי ליצור מפתח לחשבון שירות מה-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. בKey type, בוחרים באפשרות 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);
}
    

מצב דוח הבדיקה

כדי שהשילוב של Cloud-to-cloud יהיה מוכן לקבלת אישור, חשוב לבדוק את Report State.

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

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

מרכז הבקרה של סטטוס הדוחות

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

כדי לבדוק את השילוב של Cloud-to-cloud, צריך את מפתח חשבון השירות ואת agentUserId. אם כבר יש לכם מפתח לחשבון השירות ו-agentUserId מופיע, עיינו במאמר פריסה של מרכז הבקרה Report State.

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

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

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

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

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

• בחירת קובץ מפתח החשבון
• הוספת agentUserId

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

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

תגובות שגיאה

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

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