פתרון בעיות שקשורות לשילובים

‫Google Cloud מספק לכם את הכלים לניטור המהימנות של הפרויקטים שלכם באמצעות Google Cloud Monitoring ולניפוי באגים באמצעות יומני השגיאות של Google Cloud Logging. בכל פעם שמתרחשת תקלה בביצוע כוונות המשתמשים, צינור הנתונים של Google Home Analytics מתעד את התקלה במדדים שלכם ומפרסם יומן שגיאות ביומני הפרויקט.

יש שני שלבים לפתרון בעיות שגיאה:

  1. אפשר לעקוב אחרי מצב הפרויקטים באמצעות מדדים של הבית החכם.
  2. כדי לבדוק בעיות, מעיינים בתיאורי השגיאות המפורטים ביומני השגיאות.

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

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

מעקב אחרי שגיאות

אתם יכולים להשתמש ב-Google Cloud Monitoring dashboards כדי לגשת למדדים של הפרויקט. יש כמה תרשימים חשובים שמועילים במיוחד למעקב אחר האיכות ולניפוי באגים:

  • התרשים שיעור ההצלחה הוא התרשים הראשון שמתחילים ממנו כשעוקבים אחרי המהימנות של הפרויקטים. ירידות בתרשים הזה יכולות להצביע על הפסקת שירות בחלק מבסיס המשתמשים או בכולו. מומלץ לעקוב אחרי התרשים הזה כדי לזהות חריגות אחרי כל שינוי או עדכון בפרויקט.
  • התרשים 95th Percentile Latency הוא אינדיקטור חשוב לביצועי השילוב של Cloud-to-cloud עבור המשתמשים. תנודות פתאומיות בתרשים הזה עשויות להצביע על כך שהמערכות שלכם לא מצליחות לעמוד בקצב של הבקשות. מומלץ לבדוק את התרשים הזה מדי פעם כדי לזהות התנהגות לא צפויה.
  • תרשימי Error Breakdown הכי שימושיים כשמנסים לפתור בעיות בשילובים. לכל שגיאה שמודגשת בתרשים אחוז ההצלחה, מוצג קוד שגיאה בפירוט השגיאות. בטבלה שלמטה אפשר לראות את השגיאות שסומנו על ידי Google Home platform ואת הדרכים לפתור אותן.

קודי שגיאה נפוצים בפלטפורמה

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

קוד השגיאה תיאור Partner Actionable
AGENT_ISSUE הייתה בעיה כללית עם סוכן הענן של השותף.

בודקים אם יש חריגים או קריסות שלא טופלו ביומני מילוי הבקשה. 		כן
AGENT_UNAVAILABLE_ERROR ‫Google לא הצליחה להגיע לכתובת ה-URL של השותף למילוי בקשות.

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

מוודאים שהשירות שלכם מחובר לאינטרנט, מקבל חיבורים ולא חורג מהקיבולת. בנוסף, צריך לוודא שמכשיר היעד מופעל, מחובר לאינטרנט ומסונכרן.
BACKEND_FAILURE_URL_UNREACHABLE ‫Google קיבלה קוד שגיאה HTTP 5xx מהשירות שלך.

אפשר להשתמש ב-requestId ב-Google Cloud Logging כדי לבדוק את היומנים של שירות הבית החכם. בודקים קריסות של שרתים, פסק זמן או שגיאות שער 502/503.
COMMAND_FAILED אירעה שגיאה כללית במהלך הביצוע של פקודה.

כדי למצוא את שורש הבעיה, צריך לבדוק את היומנים של requestId. 		כן
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 כדי לוודא שהתגובה תואמת באופן מלא לסכימות של ה-Intent. 		כן
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 של השותף מגיב בצורה נכונה לבקשות של Google להנפקת טוקנים חדשים לגישה בצורה חלקה.refresh_token 		כן
EXECUTION_INVALID_JSON ‫Google לא הצליחה לנתח את מטען הנתונים של תגובת ה-JSON.

כדאי לבדוק אם יש שגיאות תחביר, סוגריים חסרים או תווים לא תקינים בתשובה. 		כן
INVALID_AUTH_TOKEN ‫Google קיבלה קוד שגיאה HTTP 401 מהשירות שלך.

תוקף טוקן הגישה לא פג, אבל השירות ביטל אותו. אפשר להשתמש ב-requestId ב-Google Cloud Logging כדי לבדוק את היומנים של שירות הבית החכם.
INVALID_JSON מבנה התגובה לא תקין (לדוגמה, חסרים שדות חובה).

מאמתים את התגובה בהתאם לסכימות של JSON של כוונות. 		כן
MALFORMED_JSON יש בעיה במבנה ה-JSON (לדוגמה, מחרוזות או אובייקטים לא סגורים).

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

בתשובה SYNC צריך לכלול רק מאפיינים שהטמעתם באופן מלא. 		כן
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 תקין עם מזהים, סטטוס ומצבים אופציונליים. 		כן
REQUEST_ID_NOT_FOUND ‫Google לא הצליחה למצוא את מזהה המעקב הפנימי של הבקשה.

בדרך כלל מדובר בשגיאה פנימית בפלטפורמה. צריך לעקוב אחרי העלייה הפתאומית ולפנות לתמיכה. 		כן
RESOURCE_UNAVAILABLE המשאב המבוקש (מכשיר או מאפיין) לא זמין.

בודקים אם המכשיר 'תפוס' או אם הוא הושבת באופן זמני. 		כן
RESPONSE_TIMEOUT שירות מילוי הבקשה לא הגיב תוך 9 שניות.

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

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

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

לוגי חיפוש

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

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

שאילתות ביומני Cloud

אפשר להשתמש בלחצני השאילתות כדי ליצור מסננים בהתאמה אישית.

יצירת שאילתות ביומני 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 שלנו כדי לקבל מידע נוסף על ניפוי באגים:

הקודם
רישום ביומן Cloud להעברה מענן לענן
הבא
סקירה כללית