מצב דוח

Report State היא תכונה חשובה שמאפשרת לפעולה 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. לוחצים על הפעלה.

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

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

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

כדי שהפעולה תהיה מוכנה לקבלת אישור, חשוב לבדוק את 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

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

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

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

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

תגובות שגיאה

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

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