Google Cloud מספק לכם כלים למעקב אחרי האמינות של הפרויקטים באמצעות Google Cloud Monitoring, ולניפוי באגים באמצעות יומני השגיאות של Google Cloud Logging. בכל פעם שמתרחש כשל בביצוע כוונות המשתמש (Intent), צינור עיבוד הנתונים של Google Home Analytics מתעד את הכשל במדדים ומפרסם יומן שגיאות ביומני הפרויקט.
יש שני שלבים לפתרון השגיאות:
- מעקב אחרי מצב הפרויקטים באמצעות מדדים של בית חכם.
- כדי לבדוק בעיות, אפשר לעיין בתיאורי השגיאות המפורטים ביומני השגיאות.
אם רוצים, אפשר לבדוק את הפעולה על ידי שיתוף שלה עם משתמשים אחרים. חשוב לוודא שמטפלים בשגיאות ובחריגות בצורה מתאימה.
שגיאות במעקב
אתם יכולים להשתמש ב-Google Cloud Monitoring dashboards כדי לגשת למדדי הפרויקט. יש כמה תרשימים מרכזיים שמועילים במיוחד למעקב אחר האיכות ולניפוי באגים:
- תרשים Success Rate הוא התרשים הראשון שצריך להתחיל ממנו כשעוקבים אחרי האמינות של הפרויקטים. ירידות בתרשים הזה יכולות להצביע על הפסקה בשירות לחלק מבסיס המשתמשים או לכולו. מומלץ לעקוב מקרוב אחרי התרשים הזה כדי לזהות חריגות אחרי כל שינוי או עדכון בפרויקט.
- התרשים 95th Percentile Latency הוא אינדיקטור חשוב לביצועי השילוב של Cloud-to-cloud עבור המשתמשים. תנודות פתאומיות בתרשים הזה עשויות להצביע על כך שהמערכות שלכם לא מצליחות לעמוד בקצב של הבקשות. מומלץ לבדוק את התרשים הזה מדי פעם כדי לראות אם יש התנהגות לא צפויה.
- התרשימים של Error Breakdown הם הכי שימושיים כשצריך לפתור בעיות בשילובים. לכל שגיאה שמודגשת בתרשים אחוזי ההצלחה, מוצג קוד שגיאה בפירוט השגיאות. בטבלה הבאה מפורטות השגיאות שסומנו על ידי Google Home platform (GHP) ודרכים לפתור אותן.
קודי שגיאה נפוצים בפלטפורמה
ריכזנו כאן כמה קודי שגיאה נפוצים שמופיעים ביומני הפרויקט, כדי לזהות בעיות שזוהו על ידי GHP. בטבלה הבאה מפורט מידע על פתרון בעיות. לרשימה המלאה של קודי השגיאה, ראו שגיאות וחריגות.
| קוד השגיאה | תיאור | פעולות שהשותף יכול לבצע |
|---|---|---|
AGENT_ISSUE |
בעיה כללית בסוכן הענן של השותף.
בודקים אם יש חריגות לא מטופלות או קריסות ביומני המילוי. |
כן |
AGENT_UNAVAILABLE_ERROR |
Google לא הצליחה לגשת לכתובת ה-URL של השותף למילוי הבקשה.
צריך לוודא שהשרת במצב אונליין, שחומת האש לא חוסמת את Google ושכתובת ה-URL נכונה. |
כן |
COMMAND_FAILED |
אירעה שגיאה כללית במהלך ביצוע הפקודה.
כדי למצוא את שורש הבעיה, בודקים את יומני המילוי של requestId הספציפי.
|
כן |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google קיבלה שגיאת HTTP 4xx (חוץ מ-401) ממילוי הבקשה.
צריך לבדוק אם יש ביומני שרת האינטרנט תגובות 403, 404 או 400. |
כן |
EXECUTION_BACKEND_FAILURE_URL_TIMEOUT |
הזמן הקצוב לתפוגה של הבקשה של Google פג בזמן הניסיון להגיע לשירות שלכם.
צריך לוודא שהשירות מחובר לאינטרנט, מקבל חיבורים ולא חורג מהקיבולת. בנוסף, צריך לוודא שמכשיר היעד מופעל, מחובר לאינטרנט ומסונכרן. |
כן |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
כתובת ה-URL של המילוי חסומה על ידי קובץ robots.txt או מסנני אבטחה.
מוודאים שנקודת הקצה למילוי הבקשה נגישה לסורקים או לשירותים של Google. |
כן |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google קיבלה שגיאת HTTP 5xx משירות מילוי ההזמנות שלכם.
צריך לוודא ששירות כתובת ה-URL של נקודת הקצה יציב, תקין ונגיש לכולם, ושהשירות פועל. משתמשים ב- requestId ב-Google Cloud Logging כדי לבדוק את יומני השירות של הבית החכם.
הוסיפו בדיקות תקינות וטיפול בניסיונות חוזרים.
בודקים אם יש קריסות של השרת, זמן קצוב לתפוגה או שגיאות שער 502/503.
|
כן |
EXECUTION_BAILOUT_INVALID_RESPONSE |
תגובת ה-JSON הייתה כל כך לא תקינה שהעיבוד הופסק.
כדי לוודא שהתשובה תואמת בדיוק לסכימות של Intent, אפשר להשתמש בכלי לאימות JSON. |
כן |
EXECUTION_GAL_BAD_3P_RESPONSE |
קישור החשבון נכשל בגלל פורמט לא תקין בתגובת הטוקן.
צריך לוודא שפורמט התגובה של שרת ה-OAuth תואם לדרישות של Google. |
כן |
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES |
למשתמש אין את ההרשאות הנדרשות כדי לבצע את הפעולה הזו.
בודקים את היקפי ההרשאות שהתבקשו במהלך OAuth ומוודאים שהם תואמים לתכונות הנדרשות. |
כן |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
בענן של השותף מצוין שהמשתמש ביטל את הקישור של החשבון שלו.
צריך לוודא שהמיפוי של agentUserId יציב ולא
נמחק.
|
כן |
EXECUTION_GAL_NOT_FOUND |
טוקני הגישה וטוקני הרענון של המשתמש ששמורים ב-Google לא תקינים או שאי אפשר לרענן אותם, ולכן אי אפשר לאמת את המשתמש ולתת לו גישה לשירות של השותף.
צריך לוודא שהאסימונים נשארים תקפים ומסונכרנים, לטפל בשינויים בסטטוס החשבון בצורה מתאימה ולדרוש מהמשתמשים לקשר מחדש את החשבון אם האסימונים בוטלו. |
|
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
השילוב נמצא במצב קריאה בלבד בצד של השותף.
בודקים אם החשבון של המשתמש מושעה או נמצא במצב תחזוקה של "צפייה בלבד". |
כן |
EXECUTION_GAL_UNLINKED_BY_3P |
הקישור לחשבון בוטל באופן יזום על ידי שירות הצד השלישי.
בודקים למה המשתמש נותק (לדוגמה, איפוס אבטחה). מוודאים ששרת ה-OAuth של השותף מגיב בצורה נכונה לבקשות refresh_token של Google להנפקת טוקני גישה חדשים בצורה חלקה.
|
כן |
EXECUTION_INVALID_JSON |
Google לא הצליחה לנתח את המטען הייעודי (payload) של תגובת ה-JSON.
צריך לבדוק אם יש שגיאות תחביר, סוגריים חסרים או תווים לא תקינים בתשובה. |
כן |
INVALID_AUTH_TOKEN |
Google קיבלה קוד שגיאה HTTP 401 מהשירות שלך.
התוקף של טוקן הגישה לא פג, אבל השירות שלכם ביטל אותו. משתמשים ב- requestId ב-Google Cloud Logging כדי לבדוק את יומני השירות של הבית החכם.
|
|
INVALID_JSON |
מבנה התגובה לא תקין (לדוגמה, חסרים שדות חובה).
מאמתים את התשובה בהתאם לסכימות ה-JSON של Intent. |
כן |
MALFORMED_JSON |
מבנה ה-JSON פגום (לדוגמה, מחרוזות או אובייקטים לא סגורים).
חשוב לוודא שהמילוי משתמש בספריית JSON רגילה כדי ליצור סריאליזציה של התגובות. |
כן |
NOT_IMPLEMENTED |
השותף לא הטמיע את הכוונה או התכונה המבוקשת.
צריך לכלול בתשובה של SYNC רק תכונות
שהטמעת באופן מלא.
|
כן |
OPEN_AUTH_FAILURE |
פג התוקף של טוקן הגישה של המשתמש ו-Google לא מצליחה לרענן אותו, או ש-Google קיבלה קוד שגיאה HTTP 401 מהשירות שלכם.
אם אתם רואים עלייה בשיעור השגיאות עם הקוד הזה, כדאי לבדוק אם יש גם עלייה בשיעור השגיאות שקשורות ל-Intent של הבית החכם או לבקשות של טוקן רענון. |
|
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 תקין עם מזהים, סטטוס ומצבים אופציונליים.
|
כן |
REQUEST_ID_NOT_FOUND |
Google לא הצליחה למצוא את המזהה הפנימי לצורכי מעקב של הבקשה.
בדרך כלל מדובר בשגיאה פנימית בפלטפורמה. כדאי לעקוב אחרי עלייה חדה במספר השגיאות ולפנות לתמיכה. |
כן |
RESOURCE_UNAVAILABLE |
המשאב המבוקש (מכשיר או תכונה) לא זמין.
בודקים אם המכשיר "עסוק" או הושבת באופן זמני. |
כן |
RESPONSE_TIMEOUT |
שירות מילוי הבקשות לא הגיב תוך 9 שניות.
מבצעים אופטימיזציה של זמן האחזור בקצה העורפי, בודקים אם יש שאילתות איטיות במסד הנתונים או עיכובים ברשת האזורית. |
כן |
RESPONSE_UNAVAILABLE |
לא התקבלה תגובה מכתובת ה-URL של השותף למילוי הבקשה.
מוודאים שהשירות פועל ונקודת הקצה לא קורסת. |
כן |
TIMEOUT |
הזמן הקצוב לתפוגה פג במהלך עיבוד ה-intent.
בודקים ביומנים אם יש זמן קצוב לתפוגה של שירות פנימי בין הענן לבין מרכזי המכשירים. |
כן |
לוגי חיפוש
אחרי שתלמדו איך לעקוב אחרי השילובים באמצעות מדדים, תוכלו לפתור שגיאות ספציפיות באמצעות Cloud Logging. יומן שגיאות הוא רשומה דמוית JSON עם שדות שמכילים מידע שימושי כמו זמן, קוד שגיאה ופרטים לגבי ה-Intent המקורי של הבית החכם.
יש כמה מערכות ב-Google Cloud ששולחות יומנים לפרויקט כל הזמן. כדי למצוא את היומנים שאתם צריכים, אתם צריכים לכתוב שאילתות לסינון היומנים. השאילתות יכולות להתבסס על טווח תאריכים, משאב, חומרת היומן או רשומות בהתאמה אישית.
אתם יכולים להשתמש בלחצני השאילתות כדי ליצור מסננים בהתאמה אישית.
כדי לציין טווח תאריכים, לוחצים על הלחצן לבחירת טווח תאריכים ובוחרים אחת מהאפשרויות שמופיעות. הפעולה הזו תסנן את היומנים ותציג את אלה שמקורם בטווח תאריכים שנבחר.
כדי לציין משאב, לוחצים על התפריט הנפתח Resource ובוחרים באפשרות Google Assistant Action Project. הפעולה הזו מוסיפה מסנן לשאילתה כדי להציג יומנים שמקורם בפרויקט.
משתמשים בלחצן Severity כדי לסנן לפי Emergency, Info, Debug ורמות חומרה אחרות של יומנים.
אפשר גם להשתמש בשדה 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 מוסבר איך להשתמש בכלי כדי לבדוק את השינויים בצורה יעילה.
מקורות מידע ללמידה
במאמר הזה מוסבר איך לפתור שגיאות ב-Smart Home Action. אתם יכולים גם לעיין ב-Codelabs שלנו כדי לקבל מידע נוסף על ניפוי באגים:
- Codelab: ניפוי באגים בבית חכם: מדריך למתחילים לניפוי באגים בשילוב של בית חכם בענן.
- Codelab לניפוי באגים ב-Local Home: מדריך למתחילים לניפוי באגים בשילוב מקומי של בית חכם.