מצב דוח

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