מצב דוח

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

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

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

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

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

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

2. לוחצים על addCreate service account.

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. בוחרים את חשבון השירות שיצרתם מרשימת חשבונות השירות ולוחצים על Manage keys בתפריט more_vert Actions.

11. לוחצים על Add key ואז על Create new key.

12. ב-Key type, בוחרים באפשרות 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).execute();
}
    

סטטוס דוח הבדיקה

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

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

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

דיווח על לוח הבקרה של סטטוס שירותי Google

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

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

פריסת מרכז הבקרה של Report State

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

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

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

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

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

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

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

דיווח על אי-התאמה בסטטוס

המדד "דיוק מצב הדוח שמבוסס על שאילתות" בודק עד כמה מצב הדוח האחרון של המכשיר תואם לסטטוס של המכשיר כשמשתמש שולח שאילתה לגביו. הערך הזה אמור להיות 99.5%. לפרטים נוספים על הסטטוס הנוכחי של Report State Accuracy בפרויקט, ראו תקינות המכשיר – דיוק המצב. אפשר גם לראות את הפרטים של Report State Discrepancy Log ב-Logs Explorer.

דוגמה ליומן פערים במצב הדיווח:

{
  "insertId": "abcdefgh",
  "jsonPayload": {
    "reportStateLog": {
      "result": "INACCURATE",
      "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_INACCURATE",
      "isOffline": false,
      "queriedTime": "2026-01-17T03:22:01.732938Z",
      "reportedTime": "2024-11-30T15:24:34.052751Z",
      "agentId": "google-smart-home-agent-id-example",
      "requestId": "84920571364829501736",
      "queryReportStateDifferences": {
        "queryState": "on_off \t {\n  on: true\n}\n",
        "reportState": "on_off \t {\n  on: false\n}\n"
      },
      "traitName": "TRAIT_ON_OFF",
      "snapshotTime": "2026-01-17T03:22:01.732938Z",
      "isMissingField": false,
      "deviceType": "action.devices.types.OUTLET",
      "stateName": "on",
      "deviceId": "sample-device-id",
      "accuracy": "INACCURATE"
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "google-smart-home-agent-id-example"
    }
  },
  "timestamp": "2026-01-17T07:16:13.712708257Z",
  "severity": "ERROR",
  "logName": "projects/google-smart-home-agent-id-example/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2026-01-17T07:16:13.712708257Z"
}

הגדרות השדות ביומן "דיווח על פערים במצב"

תגובות שגיאה

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

‫400 בקשה לא תקינה

השרת לא הצליח לעבד את הבקשה שנשלחה על ידי הלקוח בגלל תחביר לא תקין. סיבות נפוצות כוללות JSON בפורמט שגוי או שימוש ב-null במקום "" לערך מחרוזת.

שגיאת 404

המשאב המבוקש לא נמצא, אבל יכול להיות שיהיה זמין בעתיד. בדרך כלל, זה אומר שאנחנו לא מצליחים למצוא את המכשיר המבוקש. יכול להיות גם שחשבון המשתמש לא מקושר ל-Google או שקיבלנו agentUserId לא תקין. חשוב לוודא שהערך של agentUserId תואם לערך שצוין בתגובה של SYNC, ושהטיפול בכוונות מסוג DISCONNECT מתבצע בצורה תקינה.

כשקריאה ל-ReportState נכשלת עם השגיאה 404 NOT_FOUND, זה מצביע על חוסר התאמה בסנכרון בין הענן שלכם לבין Home Graph. זה יכול לקרות אם מכשיר הוסר מ-Home Graph, או אם משתמש ביטל את הקישור של החשבון שלו.

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

1. בדיקת הסטטוס של חשבון המשתמש: מפעילים את השיטה devices.sync עבור ה-agentUserId שהחזיר שגיאת 404. כך אפשר לדעת אם השגיאה היא בכל חשבון המשתמש או במכשיר ספציפי.
   • אם SYNC מחזיר שגיאת 404, חשבון המשתמש כבר לא מקושר ל-Google. להפסיק לשלוח את מצב הדיווח ואת בקשת הסנכרון למכשירים של המשתמש הזה.
   • אם SYNC מחזיר את הערך 200 OK, חשבון המשתמש עדיין מקושר, כלומר השגיאה 404 היא ספציפית למכשיר.
2. התאמה של רשימת המכשירים: אם SYNC מחזיר את הערך 200 OK, צריך לזהות אילו מכשירים כבר לא מוכרים ל-Google. מומלץ להשוות בין רשימת המכשירים של המשתמש שקיימת ב-Google לבין מסד הנתונים של המכשירים שלכם, ולזהות מכשירים במערכת שלכם שלא מופיעים ברשימה של Google. אם מכשיר צריך להיות מסונכרן עם Google אבל הוא עדיין לא משותף עם Google, צריך להשתמש ב-SYNC כדי לוודא שהמכשיר מסונכרן עם Google. אם צריך לבטל את הקישור של מכשיר מסוים ל-Google, צריך להפסיק לדווח על המצב של המכשיר הספציפי הזה ולהמשיך לדווח על מכשירים תקינים אחרים באותו agentUserId.

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

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