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 |
הפקודה לא תקפה למצב הנוכחי של המכשיר (לדוגמה, Set temperature כשמצב המכשיר הוא Off).
מוודאים את הלוגיקה של מאפייני המכשיר והמצב הנוכחי ב-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 כדי לבדוק את היומנים של שירות הבית החכם.
|
|
CHANNEL_SWITCH_FAILED |
המכשיר לא הצליח לעבור לערוץ המדיה המבוקש.
בודקים את שמות הערוצים או המספרים שלהם ואת סטטוס המינוי של המשתמש. |
כן |
CHARGER_ISSUE |
המכשיר מדווח על בעיית חומרה במערכת הטעינה שלו.
השותף צריך לבדוק את הטלמטריה ברמת החומרה ואת תקינות הסוללה. |
כן |
CHECK_PARTNER_APP |
כדי לפתור את השגיאה, המשתמש צריך לפתוח את האפליקציה של השותף.
אפשר להשתמש בקוד הזה לשגיאות שדורשות אינטראקציה מורכבת עם ממשק המשתמש (לדוגמה, עדכוני קושחה). |
כן |
COMMAND_FAILED |
אירעה שגיאה כללית במהלך הביצוע של פקודה.
כדי למצוא את שורש הבעיה, צריך לבדוק את היומנים של requestId
ההזמנות.
|
כן |
COMMAND_INSERT_FAILED |
Google לא הצליחה להוסיף את הפקודה לתור או לעבד אותה עבור המכשיר.
בודקים את ביצועי הכתיבה במסד הנתונים או את הלוגיקה הפנימית של תור הפקודות. |
כן |
DEVICE_NOT_FOUND |
מזהה המכשיר בבקשה לא קיים בצד השותף.
מוודאים שהענן מפעיל 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 משירות הלוגיסטיקה שלכם.
בודקים קריסות שרת, פסק זמן או שגיאות שער 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 |
שירות הצד השלישי ביטל את הקישור לחשבון באופן יזום.
בודקים למה המשתמש התנתק (לדוגמה, איפוס אבטחה). |
כן |
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.
|
כן |
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 |
התשובה לא כללה תוצאות לכל הפקודות או המכשירים המבוקשים.
לכל פריט במערך commands של הבקשה חייבת להיות רשומה תואמת בתגובה.
|
כן |
PARTNER_RESPONSE_MISSING_DEVICE |
מכשיר ספציפי ש-Google ביקשה לא נכלל בתשובה.
חשוב לוודא שהתשובה כוללת את כל ID שסופקו במטען הייעודי (payload) של הבקשה.
|
כן |
PARTNER_RESPONSE_MISSING_PAYLOAD |
בתגובה חסר שדה החובה payload.
מוודאים שאובייקט ה-JSON ברמה העליונה כולל מפתח payload.
|
כן |
PARTNER_RESPONSE_NOT_OBJECT |
לא ניתן לנתח את כל התגובה כאובייקט JSON.
בודקים אם יש תווים מיותרים או תוכן שאינו JSON בגוף התגובה של HTTP. |
כן |
PROTOCOL_ERROR |
אירעה שגיאה בפרוטוקול התקשורת הבסיסי.
בודקים בעיות בכותרת ה-HTTP או כשלים בלחיצת יד בפרוטוקול TLS. |
כן |
RELINK_REQUIRED |
המשתמש צריך לקשר מחדש את החשבון שלו כדי להמשיך להשתמש באינטגרציה.
מוודאים שהשרת מחזיר את הקוד הזה כשמבצעים רענון של טוקן שלא תקף יותר. |
כן |
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 שלנו כדי לקבל מידע נוסף על ניפוי באגים:
- Codelab לניפוי באגים של בית חכם: מדריך למתחילים לניפוי באגים בשילוב של בית חכם עם הענן.
- Codelab לניפוי באגים ב-Local Home: מדריך למתחילים לניפוי באגים בשילוב מקומי של בית חכם.