Google Cloud מספק לכם את הכלים לניטור המהימנות של הפרויקטים שלכם באמצעות Google Cloud Monitoring ולניפוי באגים בבעיות באמצעות יומני השגיאות של Google Cloud Logging. בכל פעם שמתרחשת תקלה בהגשמת כוונות המשתמשים, צינור הנתונים של Google Home Analytics מתעד את התקלה במדדים שלכם ומפרסם יומן שגיאות ביומני הפרויקט.
יש שני שלבים לפתרון בעיות שגיאה:
- אפשר לעקוב אחרי מצב הפרויקטים באמצעות מדדים של בית חכם.
- כדי לבדוק בעיות, מעיינים בתיאורי השגיאות המפורטים ביומני השגיאות.
אם רוצים, אפשר לבדוק את הפעולה על ידי שיתוף שלה עם משתמשים אחרים. חשוב לטפל בשגיאות ובחריגים בצורה מתאימה.
מעקב אחרי שגיאות
אתם יכולים להשתמש ב-Google Cloud Monitoring dashboards כדי לגשת למדדים של הפרויקט. יש כמה תרשימים חשובים שמועילים במיוחד למעקב אחר האיכות ולניפוי באגים:
- התרשים שיעור ההצלחה הוא התרשים הראשון שמתחיל לפעול כשעוקבים אחרי המהימנות של הפרויקטים. ירידות בתרשים הזה יכולות להצביע על הפסקת שירות לחלק מבסיס המשתמשים או לכולו. מומלץ לעקוב אחרי התרשים הזה כדי לזהות חריגות אחרי כל שינוי או עדכון בפרויקט.
- התרשים 95th Percentile Latency הוא אינדיקטור חשוב לביצועי השילוב של Cloud-to-cloud עבור המשתמשים. תנודות פתאומיות בתרשים הזה עשויות להצביע על כך שהמערכות שלכם לא מצליחות לעמוד בקצב של הבקשות. מומלץ לבדוק את התרשים הזה מדי פעם כדי לזהות התנהגויות לא צפויות.
- תרשימי Error Breakdown הכי שימושיים כשמנסים לפתור בעיות בשילובים. לכל שגיאה שמודגשת בתרשים אחוז ההצלחה, מוצג קוד שגיאה בפירוט השגיאות. בטבלה שלמטה אפשר לראות את השגיאות שסומנו על ידי Google Home platform ואת הדרכים לפתור אותן.
קודי שגיאה נפוצים בפלטפורמה
ריכזנו כאן כמה קודי שגיאה נפוצים שאתם עשויים לראות ביומני הפרויקט כדי לזהות בעיות שזוהו על ידי Google Home platform. בטבלה הבאה מפורט מידע לפתרון בעיות. רשימה מלאה של קודי שגיאה זמינה במאמר שגיאות וחריגים.
| קוד השגיאה | תיאור | Partner Actionable |
|---|---|---|
ACTION_NOT_AVAILABLE |
הפקודה לא תקפה למצב הנוכחי של המכשיר (לדוגמה, 'הגדרת טמפרטורה' כשהמכשיר מושבת).
מאמתים את הלוגיקה של מאפייני המכשיר והמצב הנוכחי בקובץ ה-fulfillment. |
כן |
AGENT_ISSUE |
הייתה בעיה כללית עם סוכן הענן של השותף.
בודקים אם יש חריגים או קריסות שלא טופלו ביומני ההשלמה. |
כן |
AGENT_UNAVAILABLE_ERROR |
Google לא הצליחה להגיע לכתובת ה-URL של השותף למילוי בקשות.
מוודאים שהשרת מחובר לאינטרנט, שחומת האש לא חוסמת את Google וכתובת ה-URL נכונה. |
כן |
APP_LAUNCH_FAILED |
הפעלת אפליקציית הצד השלישי במכשיר היעד נכשלה.
צריך לוודא ש-appId תקין ושהאפליקציה נתמכת בחומרה של היעד. |
כן |
AUTH_EXPIRED |
תוקף אסימון הגישה של OAuth פג ואי אפשר לרענן אותו.
בודקים את הרוטציה של טוקן הרענון ומוודאים שהמשתמש לא ביטל את הגישה. |
כן |
BACKEND_FAILURE_URL_TIMEOUT |
הזמן שהוקצב לבקשה של Google פג במהלך הניסיון להגיע לשירות שלך.
מוודאים שהשירות שלכם מחובר לאינטרנט, מקבל חיבורים ולא חורג מהקיבולת. בנוסף, צריך לוודא שמכשיר היעד מופעל, מחובר לאינטרנט ומסונכרן. |
|
BACKEND_FAILURE_URL_UNREACHABLE |
Google קיבלה קוד שגיאה HTTP 5xx מהשירות שלך.
אפשר להשתמש ב- requestId ב-Google Cloud Logging כדי לבדוק את היומנים של שירות הבית החכם. בודקים קריסות של שרתים, פסק זמן או שגיאות שער 502/503.
|
|
CHANNEL_SWITCH_FAILED |
המכשיר לא הצליח לעבור לערוץ המדיה המבוקש.
בודקים את שמות הערוצים או המספרים שלהם ואת סטטוס המינוי של המשתמש. |
כן |
CHARGER_ISSUE |
המכשיר מדווח על בעיית חומרה במערכת הטעינה שלו.
השותף צריך לבדוק את הטלמטריה ברמת החומרה ואת תקינות הסוללה. |
כן |
CHECK_PARTNER_APP |
כדי לפתור את השגיאה, המשתמש צריך לפתוח את האפליקציה של השותף.
השתמשו בקוד הזה לשגיאות שדורשות אינטראקציה מורכבת עם ממשק המשתמש (לדוגמה, עדכוני קושחה). |
כן |
COMMAND_FAILED |
אירעה שגיאה כללית במהלך הביצוע של פקודה.
כדי למצוא את שורש הבעיה, צריך לבדוק את יומני הביצוע של requestId
ההזמנה הספציפית.
|
כן |
COMMAND_INSERT_FAILED |
Google לא הצליחה להוסיף את הפקודה לתור או לעבד אותה עבור המכשיר.
בודקים את ביצועי הכתיבה במסד הנתונים או את הלוגיקה של תורי הפקודות הפנימיים. |
כן |
DEVICE_NOT_FOUND |
מזהה המכשיר בבקשה לא קיים בצד השותף.
חשוב לוודא שהקצה העורפי תמיד מסנכרן את Home Graph. התקשרות אל requestSync בכל פעם שמוסיפים או מסירים מכשירים.
|
כן |
ERROR_STATUS |
התשובה הצביעה על סטטוס 'שגיאה' לא ספציפי ללא קוד.
תמיד כדאי לכלול מחרוזת errorCode ספציפית כדי לשפר את
הנתונים של TTS למשתמשים ושל לוחות הבקרה.
|
כן |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google קיבלה שגיאת HTTP 4xx (שאינה 401) מהמילוי שלכם.
צריך לבדוק אם יש תשובות 403, 404 או 400 ביומני שרת האינטרנט. |
כן |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
כתובת האתר של ההפניה לביצוע ההזמנה חסומה על ידי robots.txt או מסנני אבטחה.
מוודאים שנקודת הקצה של ההשלמה נגישה לסורקים ולשירותים של Google. |
כן |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google קיבלה שגיאת HTTP 5xx משירות הלוגיסטיקה שלכם.
מוודאים שכתובת ה-URL של נקודת הקצה יציבה, נכונה ונגישה לציבור, ושהשירות פועל. מוסיפים בדיקות תקינות וטיפול בניסיונות חוזרים. בודקים קריסות של שרתים, פסק זמן או שגיאות שער 502/503. |
כן |
EXECUTION_BAILOUT_INVALID_RESPONSE |
פורמט ה-JSON של התגובה היה כל כך לא תקין שהעיבוד בוטל.
משתמשים בכלי לאימות JSON כדי לוודא שהתגובה תואמת באופן מלא לסכימות של הכוונות. |
כן |
EXECUTION_GAL_BAD_3P_RESPONSE |
הקישור של החשבון נכשל בגלל פורמט לא תקין בתגובת הטוקן.
מוודאים שפורמט התגובה של שרת OAuth תואם לדרישות של Google. |
כן |
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES |
לחשבון של המשתמש אין את ההרשאות הנדרשות לביצוע הפעולה הזו.
בודקים את היקפי ההרשאות שנדרשו במהלך OAuth ומוודאים שהם תואמים לתכונות הנדרשות. |
כן |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
השותף בענן מציין שהמשתמש ביטל את הקישור של החשבון שלו.
מוודאים שהמיפוי של agentUserId יציב ולא נמחק.
|
כן |
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
השילוב נמצא במצב קריאה בלבד בצד השותף.
בודקים אם החשבון של המשתמש מושעה או במצב תחזוקה של צפייה בלבד. |
כן |
EXECUTION_GAL_UNLINKED_BY_3P |
שירות הצד השלישי ביטל את הקישור לחשבון באופן יזום.
בודקים למה המשתמש התנתק (לדוגמה, איפוס אבטחה). מוודאים ששרת ה-OAuth של השותף מגיב בצורה נכונה לבקשות של Google refresh_token להנפקת אסימוני גישה חדשים בצורה חלקה.
|
כן |
EXECUTION_INVALID_JSON |
Google לא הצליחה לנתח את מטען הנתונים של תגובת ה-JSON.
תבדוק אם יש שגיאות תחביר, סוגריים חסרים או תווים לא תקינים בתשובה שלך. |
כן |
FAULTY_BATTERY |
החומרה של המכשיר מדווחת שהסוללה לא תקינה או שהיא התרוקנה.
מנחים את המשתמש באמצעות TTS או אפליקציה להחלפת הסוללה הפיזית. |
כן |
FUNCTION_NOT_SUPPORTED |
המצב או הפונקציה המבוקשים לא נתמכים במכשיר.
חשוב לוודא שהתגובה של SYNC משקפת באופן מדויק את
היכולות של המכשיר.
|
|
HARD_ERROR |
כשל לא זמני שלא ייפתר ללא התערבות ידנית.
השתמשו באפשרות הזו אם יש כשלים קבועים בחומרה או אם מצב החשבון לא ניתן לשחזור. |
כן |
INVALID_AUTH_TOKEN |
Google קיבלה קוד שגיאה HTTP 401 מהשירות שלך.
תוקף טוקן הגישה לא פג, אבל השירות ביטל אותו. אפשר להשתמש ב- requestId ב-Google Cloud Logging כדי לבדוק את היומנים של שירות הבית החכם.
|
|
INVALID_JSON |
מבנה התגובה לא תקין (לדוגמה, חסרים שדות חובה).
מאמתים את התגובה בהתאם לסכימות של JSON של כוונות. |
כן |
LOCK_FAILURE |
המנעול החכם לא הצליח לעבור למצב המבוקש.
חוקרים שיבושים פיזיים, מתח נמוך או כשלים במנוע של נעילת החומרה. |
כן |
MALFORMED_JSON |
מבנה ה-JSON שבור (לדוגמה, מחרוזות או אובייקטים לא סגורים).
מוודאים שההשלמה משתמשת בספריית JSON רגילה כדי לבצע סריאליזציה של תגובות. |
כן |
MISSING_STATE |
תגובת השאילתה לא כללה את מצב המכשיר המבוקש.
חשוב לוודא שכל המאפיינים שמוגדרים ב- SYNC מופיעים בכל תגובה של QUERY או EXECUTE, ושהמערכת מחזירה את כל מצבי המאפיינים הנדרשים, גם אם הם לא השתנו.
|
כן |
NETWORK_PROFILE_NOT_RECOGNIZED |
פרופיל הרשת המבוקש לא מוכר למכשיר.
מוודאים שמחרוזת שם הפרופיל תואמת לפרופילים הנתמכים בתגובת SYNC.
|
כן |
NOT_IMPLEMENTED |
השותף לא הטמיע את הכוונה או המאפיין המבוקשים.
בתגובה SYNC, צריך לכלול רק מאפיינים שהטמעתם באופן מלא.
|
כן |
OAUTH_RECONNECT_CALL_TO_ACTION |
מפעיל התראה למשתמש כדי לקשר מחדש את החשבון שלו.
השתמשו בערך הזה אם תוקף הסשן של המשתמש פג ונדרשת הרשאה מחדש של OAuth באופן ידני. |
כן |
OPEN_AUTH_FAILURE |
תוקף אסימון הגישה של המשתמש פג ו-Google לא יכולה לרענן אותו,
או ש-Google קיבלה קוד שגיאה HTTP 401 מהשירות שלכם.
אם אתם רואים עלייה בשיעור הקוד הזה, כדאי לבדוק אם יש גם עלייה בשיעור השגיאות שקשורות לכוונות של בית חכם או לבקשות של טוקן רענון. |
|
PARTNER_RESPONSE_INVALID_ERROR_CODE |
המחרוזת errorCode שמוחזרת לא מופיעה ברשימה הנתמכת של Google.
ממפים את השגיאות הפנימיות לרשימת השגיאות הרשמית. |
כן |
PARTNER_RESPONSE_INVALID_PAYLOAD |
השדה payload בתגובה הוא לא אובייקט JSON תקין.
בודקים את מבנה הבסיס של תגובת הביצוע. |
כן |
PARTNER_RESPONSE_INVALID_STATUS |
התגובה status לא הייתה SUCCESS, ERROR או OFFLINE.
מוודאים שכל תוצאה של מכשיר בתגובה כוללת מחרוזת סטטוס תקינה. |
כן |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
התשובה לא כללה תוצאות לכל הפקודות או המכשירים המבוקשים.
כדאי לבדוק את מבנה התגובה בהשוואה לתיעוד למפתחים של Google Home. מוודאים שהתגובה לא נחתכת או שמחזירה גוף ריק בגלל שגיאה פנימית בשרת. לכל פריט במערך commands של הבקשה חייבת להיות רשומה תואמת בתגובה.
|
כן |
PARTNER_RESPONSE_MISSING_DEVICE |
מכשיר ספציפי ש-Google ביקשה לא נכלל בתשובה.
חשוב לוודא שהתשובה כוללת את כל ID שמופיעים במטען הייעודי (payload) של הבקשה.
|
כן |
PARTNER_RESPONSE_MISSING_PAYLOAD |
חסר בתגובה שדה החובה payload.
מוודאים שאובייקט ה-JSON ברמה העליונה כולל מפתח payload.
|
כן |
PARTNER_RESPONSE_NOT_OBJECT |
לא ניתן לנתח את כל התגובה כאובייקט JSON.
צריך לבדוק אם יש תווים מיותרים או תוכן שאינו JSON בגוף התגובה של HTTP. מוודאים ש- payload.commands[] הוא אובייקט JSON תקין עם מזהים, סטטוס ומצבים אופציונליים.
|
כן |
PROTOCOL_ERROR |
אירעה שגיאה בפרוטוקול התקשורת הבסיסי.
בודקים בעיות בכותרת HTTP או כשלים בלחיצת היד של SSL/TLS. |
כן |
RELINK_REQUIRED |
כדי להמשיך להשתמש בשילוב, המשתמש צריך לקשר מחדש את החשבון שלו.
מוודאים שהשרת מחזיר את הקוד הזה כש-refresh token לא תקף באופן סופי. |
כן |
REQUEST_ID_NOT_FOUND |
Google לא הצליחה למצוא את מזהה המעקב הפנימי של הבקשה.
בדרך כלל מדובר בשגיאה פנימית בפלטפורמה. צריך לעקוב אחרי העלייה הפתאומית ולפנות לתמיכה. |
כן |
RESOURCE_UNAVAILABLE |
המשאב המבוקש (מכשיר או trait) לא זמין.
בודקים אם המכשיר 'תפוס' או אם הוא הושבת באופן זמני. |
כן |
RESPONSE_TIMEOUT |
שירות ההזמנות לא הגיב תוך 9 שניות.
לשפר את זמן האחזור של ה-Backend. כדאי לבדוק אם יש שאילתות איטיות במסד הנתונים או השהיה ברשת האזורית. |
כן |
RESPONSE_UNAVAILABLE |
לא התקבלה תגובה מכתובת ה-URL של השותף לביצוע ההזמנה.
מוודאים שהשירות פועל ונקודת הקצה לא קורסת. |
כן |
SCENE_CANNOT_BE_APPLIED |
לא ניתן להפעיל את הסצנה המבוקשת (לדוגמה, חסרים
מכשירים).
בודקים את המצב הפנימי של הסצנות של המשתמש בענן של השותף. |
כן |
STREAM_UNPLAYABLE |
הפעלת הסטרימינג מהמצלמה נכשלה או שלא ניתן היה להפעיל אותה.
מאמתים את האיתות של WebRTC/HLS ומוודאים שכתובת ה-URL של הסטרימינג תקינה. |
כן |
TIMEOUT |
הזמן הקצוב לתפוגה פג במהלך עיבוד הכוונה.
כדאי לבדוק את היומנים לגבי פסק זמן פנימי של השירות בין הענן לבין מרכזי המכשירים. |
כן |
TRANSIENT_ERROR |
שגיאה זמנית היא שגיאה שנפתרת מעצמה.
ברוב המקרים, השגיאות האלה מתבטאות בניתוק של חיבור למכשיר או לשירות. גם אם אי אפשר לפתוח חיבורים חדשים לשרת. |
|
UNABLE_TO_LOCATE_DEVICE |
לא הצלחנו למצוא את המכשיר באמצעות מאפיין המיקום (לדוגמה, ניסיון הפינג נכשל).
בודקים את הקישוריות המקומית של המכשיר (Wi-Fi או Bluetooth). |
כן |
UNABLE_TO_RING_DEVICE |
הייתה אפשרות להגיע למכשיר, אבל לא הייתה אפשרות להפעיל את הפונקציה של הצלצול או ההתראה שלו.
בודקים את מצב ההתראה או הרמקול של החומרה ואת רמות עוצמת הקול. |
כן |
UNABLE_TO_SILENCE_DEVICE |
לא הייתה אפשרות להפסיק את ההתראה הפעילה או את הצלצול במכשיר.
בודקים את התקשורת בין הענן לבין המכשיר הפיזי. |
כן |
UNEXPECTED_ERROR_CHECK_DEVICE_APP |
קרתה שגיאה בלתי צפויה. המשתמש צריך לבדוק את אפליקציית השותף.
השימוש בשגיאה הזו הוא כפתרון כללי לשגיאות שאין להן מקבילה ספציפית שנתמכת על ידי Google. |
כן |
UNKNOWN_ERROR |
כישלון כללי ללא פרטים נוספים.
מוסיפים מיפוי שגיאות מתאים, בדיקות הגנה ורישום ביומן, כדי ששגיאות ידועות יחזירו קודי שגיאה ספציפיים במקום קודי שגיאה כלליים. |
כן |
UNLOCK_FAILURE |
הנעילה החכמה לא הצליחה להגיע למצב 'לא נעול'.
בודקים אם יש תקלות בחומרה, סוללה חלשה או הזנות לא תקינות של קוד אימות. |
כן |
לוגי חיפוש
אחרי שתתרגלו למעקב אחרי השילובים באמצעות מדדים, השלב הבא הוא לפתור בעיות ספציפיות באמצעות Cloud Logging. יומן שגיאות הוא רשומה בפורמט שדומה ל-JSON, עם שדות שמכילים מידע שימושי כמו שעה, קוד שגיאה ופרטים לגבי הכוונה המקורית של הבית החכם.
יש כמה מערכות ב-Google Cloud ששולחות יומנים לפרויקט שלכם בכל רגע. צריך לכתוב שאילתות כדי לסנן את היומנים ולמצוא את היומנים שדרושים לכם. אפשר לבסס שאילתות על טווח תאריכים, משאב, חומרה של יומן או על רשומות מותאמות אישית.
אפשר להשתמש בלחצני השאילתות כדי ליצור מסננים מותאמים אישית.
כדי לציין טווח זמן, לוחצים על לחצן בחירת טווח הזמן ובוחרים אחת מהאפשרויות שמופיעות. הפעולה הזו תסנן את היומנים ותציג את היומנים שמקורם בטווח הזמן שנבחר.
כדי לציין משאב, לוחצים על התפריט הנפתח משאב ובוחרים באפשרות פרויקט פעולה ב-Google Assistant. הפעולה הזו מוסיפה מסנן לשאילתה כדי להציג יומנים שמקורם בפרויקט.
משתמשים בלחצן מידת חומרה כדי לסנן לפי מקרה חירום, מידע, ניפוי באגים ורמות חומרה אחרות של יומן.
אפשר גם להשתמש בשדה Query ב-Logs Explorer כדי להזין רשומות בהתאמה אישית. מנוע השאילתות שמשמש בשדה הזה תומך גם בשאילתות בסיסיות כמו התאמת מחרוזות, וגם בסוגים מתקדמים יותר של שאילתות, כולל אופרטורים להשוואה (<, >=, !=) ואופרטורים בוליאניים (AND, OR, NOT).
לדוגמה, הרשומה המותאמת אישית שלמטה תחזיר שגיאות שמקורן בסוג מכשיר LIGHT:
resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"
בספריית השאילתות אפשר למצוא דוגמאות נוספות לשאילתות יעילות של יומנים.
בדיקת תיקונים
אחרי שתזהו את השגיאות ותיישמו עדכונים כדי לתקן אותן, מומלץ לבדוק את התיקונים באופן יסודי באמצעות Google Home Test Suite. אנחנו מספקים מדריך למשתמש בנושא השימוש ב-Test Suite, שכולל הסבר מפורט על בדיקת השינויים בצורה יעילה.
מקורות מידע ללמידה
במאמר הזה מפורטים השלבים לפתרון שגיאות בפעולות לבית חכם. אפשר גם לעיין ב-codelabs שלנו כדי לקבל מידע נוסף על ניפוי באגים:
- Debugging Smart Home Codelab: מדריך למתחילים לניפוי באגים בשילוב של בית חכם עם הענן.
- Codelab בנושא ניפוי באגים ב-Local Home: מדריך להתחלה מהירה של ניפוי באגים בשילוב מקומי של בית חכם.