Google Home Vitals (Cloud)

חבילת לוחות הבקרה וההתראות הזו עוזרת לכם לשמור על אינטגרציה באיכות גבוהה עם הסביבה העסקית של Google Home. ‫Google מחויבת לתמוך בשותפים בפיתוח סביבה איכותית לכל הלקוחות.

מרכז הבקרה מחולק לשלושה חלקים, שכל אחד מהם מתייחס לחלק חשוב שמשפיע על האיכות הכוללת של השילוב.

1. ‫Google to Partner Metrics – מדד שבודק את תקינות הקריאות מ-Google אל הבק אנד בענן.

2. System Health - Partner to Google Metrics – מדד שבודק את תקינות הקריאות מהמערכת שלכם אל Google.

3. ‫Device Health - State Accuracy – מדד שבודק את הדיוק של המצבים שמאוחסנים במערכות של Google, שמשמשים כדי להחזיר תשובות לשאילתות של משתמשים.

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

אם הלחיצה על הלחצן הבא לא מעבירה אתכם ישירות ללוח הבקרה, אתם יכולים להגיע אליו על ידי בחירה בדף סקירה כללית, בחירה באפשרות מרכזי בקרה ואז בחירה באפשרות לוח הבקרה של Google Home Vitals (Cloud) מתוך הרשימה לוחות הבקרה שלי.

כניסה לדף Dashboard

מדדי Google לשותף

המדד Query/Execute Success Rate >= 99.5%‎ מודד את התדירות שבה הפקודות של המשתמשים מבוצעות בצורה נכונה. המדד הזה עוזר להימנע מתשובות של Assistant כמו "אין לי גישה למכשיר" או מאישור שגוי של פקודה שעדיין לא בוצעה.

מה מגדיר 'הצלחה'?

עסקה מסומנת כהצלחה אם פלטפורמת Google Home מקבלת תגובה תקפה שמציינת שהפעולה המבוקשת בוצעה או שהמצב המבוקש אוחזר.

תשובות שכוללות חריגים שלא חוסמים (לדוגמה, סטטוס SUCCESS עם חריג lowBattery) נספרות כעסקאות מוצלחות. הפקודה הגיעה למכשיר והכוונה הושגה למרות האזהרה.

מהי הגדרה של 'כשל'?

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

המדד ‎Query/Execute Latency (p90) <= 1000ms מודד את זמן ההמתנה של פעולה שבוקשה ועוזר לוודא שהמשתמשים לא צריכים לחכות יותר מדי זמן, למשל, לחכות כמה שניות עד שהאור ייכבה.

מדדי זמן האחזור

זמן האחזור הוא מדד קריטי לרמת ההיענות של השילוב למשתמש הקצה. בלוח הבקרה מוצג נתון השהייה באחוזון ה-90 (P90), שמייצג את החוויה של המשתמשים ה "איטיים" ביותר (לדוגמה, P90 של 800 אלפיות השנייה פירושו ש-90% מהבקשות מאושרות תוך 800 אלפיות השנייה או פחות).

‫Google מודדת את זמן האחזור באופן שונה בבדיקות סטטוס לעומת בפקודות למכשירים, כדי להבטיח דיוק טכני.

1. זמן האחזור של השאילתה (שאילתה)

המדד הזה מודד את Cloud-to-cloud זמן הלוך ושוב כש-Google מבקשת את המצב הנוכחי של מכשיר.

• התחלה: Google שולחת בקשת action.devices.QUERY לכתובת ה-URL של מרכז הבקשות.
• חלון המדידה: הזמן שלוקח לענן שלך לקבל, לעבד ולהעביר את תגובת ה-HTTP המלאה בחזרה אל Google.
• סיום: Google מקבלת את מטען הנתונים של התגובה הסופית מהשירות שלכם ומאשרת את קבלתו.

2. זמן האחזור של הפעולה EXECUTE (הפעלה)

המדד הזה מודד את הזמן שחולף מרגע ש-Google שולחת בקשת שליטה למכשיר ועד לקבלת אישור על הפקודה.

• התחלה: Google שולחת בקשת action.devices.EXECUTE לכתובת ה-URL של מרכז הבקשות.
• חלון המדידה: הזמן שחלף מרגע שליחת הפקודה לענן ועד לקבלת תשובת אישור.
• סיום: Google מקבלת את תגובת הסטטוס SUCCESS, PENDING או OFFLINE.
• היקף טכני: המדד הזה מודד את הזמן שחלף בין קבלת אישור התגובה בענן של Google לבין קבלת אישור התגובה בענן שלכם. המדד לא מודד את הזמן שנדרש לחומרה הפיזית (לדוגמה, נורת LED) כדי להשלים את השינוי במצב הפיזי, כי לעיתים קרובות זה כולל השהיה ברשת אריג מקומית מחוץ לנתיב הענן לענן.

אפשרויות להפחתת זמן הטעינה

המלצות לארכיטקטורה של ניתוב גיאוגרפי

אם הטמעה של כתובת IP מסוג Anycast לא אפשרית, מומלץ להשתמש בחלופות הבאות שחוסכות עלויות כדי לוודא שהמשתמשים מקבלים שירות ממרכז הנתונים האזורי הקרוב ביותר.

1. איזון עומסים גלובלי (GLB)

   במקום ניתוב סטטי, משתמשים במאזן עומסים של אפליקציות גלובלי (זמין מרוב ספקי הענן הגדולים).

   • איך זה עובד: מגדירים נקודת כניסה גלובלית אחת (כתובת URL) שנמצאת בקצה הרשת. מאזן העומסים מזהה אוטומטית את המקור הגיאוגרפי של הבקשה מאשכולות המילוי של Google ומנתב את התנועה אל קצה העורפי האזורי הקרוב ביותר שפועל בצורה תקינה.

   • היתרון: הפתרון הזה מספק את הביצועים של Anycast עם מורכבות הגדרה ועלות נמוכות משמעותית.

2. מערכת DNS שמודעת למיקום גיאוגרפי (GeoDNS)

   • איך זה עובד: מגדירים את ספק ה-DNS כך שיפענח את כתובת ה-URL של מרכז הלוגיסטיקה לכתובות IP שונות על סמך המיקום הגיאוגרפי של שאילתת ה-DNS.

   • הטמעה: צריך לוודא שספק ה-DNS שלכם מותאם לנקודות היציאה של Google. כששירותי ההשלמה האזוריים של Google (למשל בארה"ב, באיחוד האירופי או באסיה) פותרים את הדומיין שלכם, הם מקבלים את כתובת ה-IP של מרכז הנתונים באזור הספציפי הזה.

אסטרטגיות אופטימיזציה בשכבת האפליקציה

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

1. שיטת ה-Proxy של Trampoline

   אם אתם חייבים לשמור על מרכז נתונים ראשי, השתמשו בשרתי proxy אזוריים קלי משקל (Trampolines) כדי לטפל בלחיצת היד הראשונית.

   1. מערכת Google ניגשת לכתובת ה-URL הגלובלית.

   2. בקשה מתקבלת על ידי שרת proxy אזורי (לדוגמה, פונקציית Nginx או Lambda קלילה).

   3. ה-proxy מעביר את מטען הנתונים דרך עמוד השדרה הפנימי והמהיר שלכם למסד הנתונים הראשי.

   היתרון: הפעולה הזו מקצרת את הזמן של 'לחיצת היד של TCP', שלרוב תורמת הכי הרבה לזמן האחזור של בקשות למרחקים ארוכים.

2. רמזים לגבי אזור טוקן הגישה

   במהלך תהליך קישור החשבון (OAuth), המערכת יכולה לזהות את האזור הביתי של המשתמש.

   הטמעה: מקודדים מזהה אזור ב-access_token שמונפק ל-Google. כש-Google שולחת בקשת הפצה, שער התשלומים יכול לבדוק את הטוקן באופן מיידי ולהפנות את הבקשה לאשכול האזורי הנכון בלי לבצע חיפוש במסד נתונים.

תקינות המערכת – מדדי שותף ל-Google

שמירה על שיעור הצלחה של ‎99.5%‎ ומעלה עוזרת לוודא שהסטטוסים של המכשירים נכונים ב-Google Home, שהמכשירים מתווספים ומוסרים, שהאוטומציות מופעלות ושאירועי ההיסטוריה מופיעים בכרטיסייה "פעילות" של Google Home app (GHA).

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

מה מגדיר 'הצלחה'?

‫2xx (הצלחה): עדכון המצב התקבל ועבר עיבוד בהצלחה על ידי HomeGraph.

מהי הגדרה של 'כשל'?

שגיאות 4xx (שגיאה של שותף) מייצגות כשלים ומעידות על בעיה בבקשה שנשלחה מהענן שלכם. דוגמאות לקודים נפוצים:

‫400 בקשה שגויה

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

פתרון: מוודאים שגוף הבקשה הוא JSON תקין (אין מבנה פגום או ערכי null בשדות מחרוזת), ומוודאים שהערך agentUserId תואם לערך מתגובת ה-SYNC.

שגיאת 404

הסיבה: לא נמצאו deviceId או agentUserId ב-HomeGraph (עדיין לא סונכרנו, כבר בוטל הקישור או שיש אי התאמה במזהה).

פתרון:

1. מוודאים שהערך של agentUserId זהה לערך שצוין בתגובת הסנכרון.
2. כדי לקבוע אם השגיאה 404 Not Found נגרמת בגלל מכשיר או משתמש חסרים ב-HomeGraph, צריך להשתמש ב-Home Graph SYNC API.
3. חשוב להפעיל את requestSync אחרי שמוסיפים, מסירים, משנים את השם או מעדכנים מכשיר או חשבון, כדי לוודא שהסטטוס מעודכן.
4. כדי להפסיק את הדיווח על מכשירים לא פעילים, צריך לטפל בצורה נכונה ב-intents של DISCONNECT. אחרי קבלת ה-intent של DISCONNECT, שירות הענן צריך להפסיק לפרסם שינויים ב-Google באמצעות Request Sync ו-Report State.

‫429: המשאבים מוצו

הסיבה: חרגתם מהמכסה שהוקצתה לשילוב.

פתרון: אפשר לעיין בהוראות שבקטע 'שלב 2א: ניפוי באגים בבעיות שקשורות למכסת השימוש' בלוח הבקרה לניהול מכסת השימוש. מידע נוסף זמין במאמר מכסות ומגבלות של בית חכם.

תקינות המכשיר – דיוק המצב

אם רמת הדיוק של המצב היא 99.5%ומעלה, המשתמשים יראו תוצאות נכונות כשהם יסתכלו על המצבים של המכשיר או ישתמשו בתכונות מבוססות-AI כמו Ask Home. אם רמת הדיוק של המצב נמוכה, יכול להיות שהאוטומציות לא יופעלו והערכים בהיסטוריה לא יופיעו בכרטיסיית הפעילות של GHA בזמן הנכון. מידע נוסף מופיע במאמר בנושא מצב הדוח. שימו לב: צריך לעמוד ביעד הדיוק של המדינה בכל המאפיינים הנתמכים.

1. רכיבי הדיוק

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

• דיוק מבוסס-שאילתה: מאומת כשמשתמש או מערכת בודקים באופן פעיל את הסטטוס הנוכחי של מכשיר.
• דיוק של EXECUTE: מאומת על ידי הערכת מצב המכשיר אחרי הפקודה שדווח בעקבות בקשת בקרה.

2. מדדים בלוח הבקרה (חישוב שעתי)

לוח הבקרה מחשב את רמת הדיוק על סמך מרווח של שעה. כדי להבטיח מהימנות סטטיסטית ולמנוע הטלת עונשים על שילובים עם רעשי רקע של אותות חלשים, Google אוכפת סף מינימלי של נפח תנועה. אם שילוב ספציפי של מאפיין ומכשיר צובר פחות מ-100 דגימות כוללות במהלך חלון מתגלגל של 5 ימים, רמת הדיוק שלו נחשבת ללא מובהקת מבחינה סטטיסטית ומוגדרת כ-N/A.

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

דיוק המצב לפי שעה = (דיוק השאילתה % + דיוק הביצוע %) / 2

כאשר כל נתיב מוגדר כך:

• דיוק השאילתה % = (דגימות מדויקות של שאילתות לפי שעה) / (דגימות כוללות של שאילתות לפי שעה)
• דיוק הביצוע (%) = (דגימות מדויקות של ביצוע לפי שעה) / (סה"כ דגימות של ביצוע לפי שעה)

ציון הדיוק של המאפיין (מחושב לכל מאפיין) = סכום(דוגמאות מדויקות של שאילתות + דוגמאות מדויקות של ביצוע) / סכום(דוגמאות כוללות של שאילתות + דוגמאות כוללות של ביצוע)

ציון האיכות מבוסס על הערכת הביצועים המינימליים במערכת האקולוגית שלכם, ולכן כל מאפיין נתמך שעומד בדרישות צריך לעמוד בנפרד ביעד של 99.5% דיוק במצב (זה לא ממוצע של כל המאפיינים).

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

3. שיפור הדיוק של תקינות המכשיר והמצב שלו

אי התאמות מתרחשות כשהמצב שמאוחסן ב-Home Graph לא תואם לתוצאות של שאילתה בזמן אמת.

שגיאות מסוג 'שדה חסר'

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD"
    deviceId: "curtain"
    deviceType: "action.devices.types.CURTAIN"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-13T12:20:26Z"
    queryReportStateDifferences: {
      queryState: "open_close    {
        open_percent: 0.0
        missing open_direction
      }"
      reportState: "open_close   {
        open_state {
          open_percent: 100.0
          open_direction: "LEFT"
        }
      }"
    }
    reportedTime: "2022-05-13T07:14:35Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T12:20:26Z"
    stateName: "open_state"
    traitName: "TRAIT_OPEN_CLOSE"
  }
  

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD"
    deviceId: "sensor"
    deviceType: "action.devices.types.SENSOR"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-28T10:40:33Z"
    queryReportStateDifferences: {
      queryState: "temperature_setting {
         thermostat_mode: "off"
         thermostat_temperature_ambient: 20.0
         active_thermostat_mode: "none"
      }"
      reportState: "temperature_setting {
         thermostat_mode: "off"
         active_thermostat_mode: "none"
      }"
    }
    reportedTime: "2024-09-20T15:00:00Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-28T10:40:33Z"
    stateName: "thermostat_temperature_ambient"
    traitName: "TRAIT_TEMPERATURE_SETTING"
  }
  

הסיבה: בשגיאה DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD או DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD, קבוצת שדות המטען שונה בין תגובת ה-QUERY לבין בקשת Report State עבור אותו מכשיר.

פתרון: מוודאים שמבנה הנתונים זהה בשני הנתיבים. אם תכונה כלולה ב-SYNC, השדות התואמים שלה חייבים להיות נוכחים ועקביים גם בדוחות הפרואקטיביים וגם בשאילתות הריאקטיביות.

שגיאות מסוג 'לא מדויק'

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_INACCURATE"
    deviceId: "outlet"
    deviceType: "action.devices.types.OUTLET"
    isMissingField: false
    isOffline: false
    queriedTime: "2026-04-12T16:02:58Z"
    queryReportStateDifferences: {
      queryState: "on_off    {
        on: false
      }"
      reportState: "on_off   {
        on: true
      }"
    }
    reportedTime: "2025-03-10T01:56:44Z"
    requestId: "abc"
    result: "INACCURATE"
    snapshotTime: "2026-04-12T16:02:58Z"
    stateName: "on"
    traitName: "TRAIT_ON_OFF"
  }
  

הסיבה: בשגיאה DETAILED_ACCURACY_RESULT_INACCURATE, יש אי התאמה בין הערך שמוחזר בתגובת השאילתה לבין הערך האחרון של מצב הדוח.

פתרון: מוודאים שהפונקציה Report State מופעלת בכל פעם שסטטוס המכשיר משתנה, ושהפונקציות Report State ו-QUERY תמיד מספקות את אותם ערכים מדויקים ועדכניים ואת כל השדות הנדרשים כדי לשמור על עקביות הנתונים.

"reportStateLog": {
   "isMissingField": false,
   "snapshotTime": "2026-04-13T07:56:21Z",
   "traitName": "TRAIT_ON_OFF",
   "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE",
   "executionReportStateDifferences": {
      "expectedPostExecutionDeviceState": {
         "onOff": {
         "on": false
         }
      },
      "preExecutionDeviceState": {
         "onOff": {
         "on": true
         }
      },
      "executionCommand": {
         "requestId": "test001",
         "beginTimestamp": "2026-04-13T07:56:20Z",
         "action": {
         "trait": "TRAIT_ON_OFF",
         "actionType": "ONOFF_OFF"
         },
         "status": {
         "statusType": "SUCCESS_STATUS"
         },
         "endTimestamp": "2026-04-13T07:56:21Z",
         "executionType": "PARTNER_CLOUD"
      },
      "reportState": {}
   },
   "accuracy": "MISSING_REPORT_STATE",
   "deviceType": "action.devices.types.LIGHT",
   "agentId": "abc",
   "stateName": "on",
   "result": "MISSING_REPORT_STATE"
   }
  

הסיבה: בשגיאה DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE, השותף ביצע את הפקודה בהצלחה, אבל לא דיווח ל-Google על מצב המכשיר המעודכן.

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

eportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED"
    deviceId: "switch"
    deviceType: "action.devices.types.SWITCH"
    isMissingField: false
    isOffline: true
    queriedTime: "2026-04-13T13:53:26Z"
    queryReportStateDifferences: {
      queryState: "online    {
        online: false
      }
      "
      reportState: ""
    }
    reportedTime: "1970-01-01T00:00:00Z"
    requestId: "test001"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T13:53:26Z"
    stateName: "online"
    traitName: "TRAIT_ONLINE"
   }
  

הסיבה: לגבי השגיאה DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED, לא התקבל Report State עבור המכשיר הזה (המצב ריק וחותמת הזמן שדווחה היא epoch), למרות שתוצאות ה-QUERY מספקות את הסטטוס הנוכחי. המשמעות היא שעדכוני המצב לא מופעלים, לא מגיעים ל-HomeGraph או שהמכשיר לא מדווח על מעברים בקישוריות או בסטטוס התפעולי שלו.

פתרון: מוודאים שהפעלת הדוח על מצב המכשיר מתבצעת ושליחתו מצליחה בכל שינוי במצב. בודקים שהלוגיקה של ה-Backend מטפלת נכון בעדכוני הסטטוס, מאשרת את הצלחת המסירה ל-Google HomeGraph ומוודאת שהמכשיר מסנכרן באופן עקבי את המצב שלו כדי לשמור על דיוק ממשק המשתמש ומנוע האוטומציה.