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

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

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

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

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

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

שגיאות במעקב

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

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

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

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

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

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

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

יצירת שאילתות ביומני Cloud Logging

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

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

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