מצב דוח

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

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 מעדכן את המצבים על בסיס כל מאפיין ומחליף את כל הנתונים של המאפיין הזה כשמתבצעת קריאה ל-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, עוברים לדף Service accounts.

   מעבר לדף Service Accounts

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

2. לוחצים על addיצירת חשבון שירות.

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 עדיין זמין, אבל הוא הוצא משימוש ולא נתמך יותר.

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

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

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

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

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

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

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

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

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

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

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

דיווח על אי התאמה במצב

המדד 'דיוק המצב של הדוח מבוסס השאילתה' בודק את מידת ההתאמה בין המצב העדכני של הדוח לגבי מכשיר מסוים לבין הסטטוס של המכשיר כשהמשתמש שולח שאילתה לגביו. הערך הזה צפוי להיות 99.5%. לפרטים נוספים על הסטטוס הנוכחי של דיוק הדיווח על מצב המכשיר בפרויקט, אפשר לעיין במאמר תקינות המכשיר – דיוק הדיווח על מצב המכשיר. אפשר גם לראות את הפרטים של 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. הפסקת השליחה של Report State ו-Request Sync למכשירים של המשתמש הזה.
   • אם SYNC מחזיר 200 OK, חשבון המשתמש עדיין מקושר, כלומר שגיאת 404 היא ספציפית למכשיר.
2. ‫Reconcile device list: אם 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": {},
        }
      }
    }