במסמך הזה מפורטים השגיאות והחריגות הנתמכות באופן רשמי במכשירי בית חכם. יש להשתמש בקודים האלה של השגיאות וההחרגות בתשובה לכוונה, או בהתראות אם הטמעתם אותן, כדי ש-Google Assistant תוכל להתריע למשתמשי הקצה על בעיות שקשורות לפקודה או למצב מסוימים של המכשיר. אם התשובה מכילה errorCode
או עיצוב שגוי, Google Assistant מציגה למשתמשים הודעת שגיאה כללית, למשל "מצטערים, המכשיר לא זמין כרגע".
שגיאות
צריך להחזיר קוד שגיאה כשבעיה גורמת לכישלון של בקשת הפעלה או של שאילתה. לדוגמה, אם מנעול הדלת נתקע ואי אפשר לנעול או לפתוח אותו, צריך להחזיר למשתמש הודעת שגיאה לגבי המצב הזה.
אפשר לצרף קודי שגיאה ברמת המכשיר או ברמה הגלובלית. לדוגמה, אם למשתמש יש הרבה נורות מספק אחד והן נשלטות על ידי מרכז, כשהמשתמש מבקש לכבות את כל הנורות, יכול להיות שהספק יחזיר שגיאה ברמת המכשיר אם נורה אחת במצב אופליין, או שגיאה ברמת המערכת אם כל המרכז במצב אופליין ולא ניתן לשלוט באף נורה. אם כל המכשירים נמצאים במצב אופליין, אין הבדל בין שימוש בשגיאות ברמת המכשיר לבין שימוש בשגיאות ברמת החשבון.
כשמכשיר נמצא במצב אופליין, צריך לדווח על {"online": false}
לReport State תוך 5 דקות מההתנהגות של המכשיר.
לסיכום:
- שגיאה ברמת המערכת: לכל המכשירים בתגובה יש את אותה שגיאה
- שגיאה ברמת המיקום: תגובה מעורבת עם מקרים של שגיאה והצלחה
שגיאות ברמה הגלובלית
קטע הקוד הבא ב-JSON מראה איך מחזירים שגיאות ברמה הגלובלית בתגובה של QUERY או של EXECUTE.
דוגמה לשגיאה ברמה הגלובלית מסוג deviceOffline
בגלל שהרכז במצב אופליין:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "errorCode": "deviceOffline", "status" : "ERROR" } }
דוגמה לשגיאה ברמה הגלובלית מסוג inSoftwareUpdate
בגלל שהרכז מתעדכן:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "errorCode": "inSoftwareUpdate", "status" : "ERROR" } }
שגיאות ברמת המכשיר
תגובה של QUERY
קטע הקוד הבא ב-JSON מראה איך מחזירים שגיאות ברמת המכשיר בתגובה של השאילתה.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "devices": { "device-id-1": { "errorCode": "deviceOffline", "status" : "ERROR" }, "device-id-2": { "errorCode": "deviceOffline", "status" : "ERROR" } } } }
תגובה של EXECUTE
קטע ה-JSON הבא מראה איך מחזירים שגיאות ברמת המכשיר בתגובה ל-EXECUTE.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "device-id-1" ], "status": "ERROR", "errorCode": "deviceOffline" }, { "ids": [ "device-id-2" ], "status": "SUCCESS", "states": { "on": true, "online": true } } ] } }
התראות עם שגיאות
התראה יזומה
קטע הקוד הבא בפורמט JSON מראה איך מדווחים על שגיאות ברמת המכשיר בהתראה יזומה.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "agent-user-id-1", "eventId": "unique-event-id-1", "payload": { "devices": { "notifications": { "device-id-1": { "RunCycle": { "priority": 0, "status": "FAILURE", "errorCode": "deviceDoorOpen" } } } } } }
תשובה בהמשך
קטע הקוד הבא בפורמט JSON מראה איך מדווחים על שגיאות ברמת המכשיר בתגובה עוקבת.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "agent-user-id-1", "eventId": "unique-event-id-1", "payload": { "devices": { "notifications": { "device-id-1": { "LockUnlock": { "priority": 0, "followUpResponse": { "status": "FAILURE", "errorCode": "deviceJammingDetected", "followUpToken": "PLACEHOLDER" } } } } } } }
רשימת שגיאות
השגיאות הבאות יגרמו להפעלת ה-TTS המשויך במכשיר.
- aboveMaximumLightEffectsDuration : המשך הזמן שלהם ארוך מהמשך הזמן המקסימלי של שעה אחת. אפשר לנסות שוב.
- aboveMaximumTimerDuration : אפשר להגדיר את <המכשיר/ים> רק למשך <פרק זמן>
- actionNotAvailable : מצטערים, נראה שאין לי אפשרות לעשות את זה כרגע.
- actionUnavailableWhileRunning : <device(s)> <is/are> currently running, so I can't make any changes.
- alreadyArmed : <device(s)> <is/are> already armed.
- alreadyAtMax : <device(s)> <is/are> already set to the maximum temperature.
- alreadyAtMin : <device(s)> <is/are> already set to the minimum temperature.
- alreadyClosed : <device(s)> <is/are> already closed.
- alreadyDisarmed : <device(s)> <is/are> already disarmed.
- alreadyDocked : <device(s)> <is/are> already docked.
- alreadyInState : <device(s)> <is/are> already in that state.
- alreadyLocked : <device(s)> <is/are> already locked.
- alreadyOff : <device(s)> <is/are> already off.
- alreadyOn : <device(s)> <is/are> already on.
- alreadyOpen : <device(s)> <is/are> already open.
- alreadyPaused : <device(s)> <is/are> already paused.
- alreadyStarted : <device(s)> <is/are> already started.
- alreadyStopped : <device(s)> <is/are> already stopped.
- alreadyUnlocked : <device(s)> <is/are> already unlocked.
- ambiguousZoneName : מצטערים, <device(s)> לא יכול לזהות לאיזה תחום התכווננת. עליך לוודא לשמות של האזורים יש שמות ייחודיים ולנסות שוב.
- amountAboveLimit : הערך גדול מהערך ש<device(s)> יכול לתמוך בו.
- appLaunchFailed : לצערנו, לא הצלחנו להפעיל את <שם האפליקציה> ב <מכשירים>.
- armFailure : לא ניתן היה להפעיל את <המכשיר/ים>.
- armLevelNeeded : לא ברור לי באיזה רמה להגדיר את <device(s)>. אפשר לנסות לומר "Set <device(s)> to <low security>" או "Set <device(s)> to <high security>"
- authFailure : לא הצלחתי להגיע אל <מכשירים>. כדאי לבדוק באפליקציה אם <המכשיר/המכשירים> מוגדרים באופן מלא.
- bagFull : <device(s)> <has/have> <a full bag/full bags>. Please empty <it/them> and try again.
- belowMinimumLightEffectsDuration : האורך קצר מהאורך המינימלי של 5 דקות. אפשר לנסות שוב.
- belowMinimumTimerDuration : לא ניתן להגדיר את <המכשירים> לזמן קצר כל כך. אפשר לנסות שוב.
- binFull : <device(s)> <has/have> <a full bin/full bins>.
- cancelArmingRestricted : סליחה, לא הצלחתי לבטל את ההפעלה של <device(s)>.
- cancelTooLate : סליחה, כבר לא ניתן לבטל. במקום זאת, צריך להשתמש ב-<device(s)> או באפליקציה.
- channelSwitchFailed : מצטערים, לא הצלחנו לעבור לערוץ <channel name>. אפשר לנסות שוב מאוחר יותר.
- chargerIssue : צר לי, נראה ש <מכשירים> <יש/יש להם> <בעיה במטען/בעיות במטען>.
- commandInsertFailed : לא ניתן לעבד פקודות עבור <device(s)>.
- deadBattery : <device(s)> <has/have> <a dead battery/dead batteries>.
- degreesOutOfRange : המעלות המבוקשות מחוץ לטווח של <device(s)>.
- deviceAlertNeedsAssistance : <device(s)> <has/have> an active alert and <need(s)> your assistance.
- deviceAtExtremeTemperature : <device(s)> <is/are> at <an extreme temperature/extreme temperatures>.
- deviceBusy : מצטערים, נראה ש <device(s)> כבר עושה משהו כרגע.
- deviceCharging : צר לי, נראה ש<device(s)> לא יכול לעשות את זה כי (ha_shared.ItsTheyre size=$item.devices.total_device_count) בטעינה.
- deviceClogged : צר לי, נראה ש <device(s)> סתום.
- deviceCurrentlyDispensing : <device(s)> כבר מפיץ משהו כרגע.
- deviceDoorOpen : הדלת פתוחה במכשירים <device(s)>. צריך לסגור אותה ולנסות שוב.
- deviceHandleClosed : הידית סגורה ב <מכשירים>. עליך לפתוח אותה ולנסות שוב.
- deviceJammingDetected : <device(s)> <is/are> jammed.
- deviceLidOpen : המכסה פתוח במכשירים <device(s)>. צריך לסגור אותו ולנסות שוב.
- deviceNeedsRepair : <device(s)> <need(s)> to be repaired. יש לפנות לסוכנות השירות המקומית.
- deviceNotDocked : צר לי, נראה ש<מכשירים> <לא> מחוברים למטען. יש להניח את <המכשיר/המכשירים> באביזר העגינה ולנסות שוב.
- deviceNotFound : <device(s)> <is/are>n't available. כדאי לנסות להגדיר את <הוא/היא> מחדש.
- deviceNotMounted : צר לי, נראה ש<מכשירים> לא יכולים לעשות את זה כי <הוא/הם> <לא> מותקנים.
- deviceNotReady : <device(s)> <is/are>n't ready.
- deviceStuck : <device(s)> <is/are> stuck and needs your help.
- deviceTampered : <device(s)> <has/have> been tampered with.
- deviceThermalShutdown : צר לי, נראה שהמכשירים <device(s)> כבויים בגלל טמפרטורות קיצוניות.
- directResponseOnlyUnreachable : <device(s)> <doesn't/don't> support remote control.
- disarmFailure : לא ניתן היה להשבית את <המכשיר(ים)>.
- discreteOnlyOpenClose : צר לי, אפשר לפתוח או לסגור את <המכשירים> רק עד הסוף.
- dispenseAmountAboveLimit : <device(s)> לא יכולים למלא כמות גדולה כל כך.
- dispenseAmountBelowLimit : <device(s)> לא יכולים למלא כמות קטנה כל כך.
- dispenseAmountRemainingExceeded : אין מספיק <dispense item> במכשירים <device(s)> כדי לבצע את הפעולה הזו.
- dispenseFractionalAmountNotSupported : <device(s)> לא יכולים למכור חלקים מ<dispense item>.
- dispenseFractionalUnitNotSupported : <device(s)> לא תומך בחלקים של היחידות האלה עבור <dispense item>.
- dispenseUnitNotSupported : המכשירים <device(s)> לא תומכים ביחידה הזו עבור <dispense item>.
- doorClosedTooLong : עבר זמן מה מאז שהדלת של <device(s)> נפתחה. עליך לפתוח את הדלת, לוודא שיש משהו בפנים ולנסות שוב.
- emergencyHeatOn : <device(s)> <is/are> in Emergency Heat Mode, so <it/they>'ll have to be adjusted by hand.
- faultyBattery : <device(s)> <has/have> <a faulty battery/faulty batteries>.
- floorUnreachable : <device(s)> לא יכולים להגיע לחדר הזה. יש להעביר <את/אתם> לקומה המתאימה ולנסות שוב.
- functionNotSupported : Actually, <device(s)> <doesn't/don't> support that functionality.
- genericDispenseNotSupported : מה רצית למלא? יש לנסות שוב עם שם הפריט.
- hardError : מצטערים, משהו השתבש ואין לי אפשרות לשלוט במכשיר הביתי שלך.
- hardError : מצטערים, משהו השתבש ואין לי אפשרות לשלוט במכשיר הביתי שלך.
- inAutoMode : <device(s)> <is/are> currently set to auto mode. כדי לשנות את הטמפרטורה, צריך להעביר את <המכשיר> למצב אחר.
- inAwayMode : <device(s)> <is/are> currently set to away mode. כדי לשלוט בתרמוסטט, צריך להעביר אותו באופן ידני למצב בית באמצעות אפליקציית Nest בטלפון, בטאבלט או במחשב.
- inDryMode : <device(s)> <is/are> currently set to dry mode. כדי לשנות את הטמפרטורה, צריך להעביר את <המכשיר> למצב אחר.
- inEcoMode : <device(s)> <is/are> currently set to eco mode. כדי לשנות את הטמפרטורה, צריך להעביר את <המכשיר> למצב אחר.
- inFanOnlyMode : <device(s)> <is/are> currently set to fan-only mode. כדי לשנות את הטמפרטורה, צריך להעביר את <המכשיר> למצב אחר.
- inHeatOrCool : <device(s)> <is/are>n't in heat/cool mode.
- inHumidifierMode : <device(s)> <is/are> currently set to humidifier mode. כדי לשנות את הטמפרטורה, צריך להעביר את <המכשיר> למצב אחר.
- inOffMode : <המכשיר/ים> <מושבתים/ות> כרגע. כדי לשנות את הטמפרטורה, צריך להעביר <אותם/ה> למצב אחר.
- inPurifierMode : <device(s)> <is/are> currently set to purifier mode. כדי לשנות את הטמפרטורה, צריך להעביר את <המכשיר> למצב אחר.
- inSleepMode : <device(s)> <is/are> in sleep mode. אפשר לנסות שוב מאוחר יותר.
- inSoftwareUpdate : <device(s)> <is/are> currently in a software update.
- lockFailure : לא ניתן היה לנעול את <device(s)>.
- lockedState : <device(s)> <is/are> currently locked.
- lockedToRange : הטמפרטורה הזו לא בטווח הנעול במכשירים <device(s)>.
- lowBattery : <device(s)> <has/have> low battery.
- maxSettingReached : <device(s)> <is/are> already set to the highest setting.
- maxSpeedReached : <device(s)> <is/are> already set to the maximum speed.
- minSettingReached : <device(s)> <is/are> already set to the lowest setting.
- minSpeedReached : <device(s)> <is/are> already set to the minimum speed.
- monitoringServiceConnectionLost : <device(s)> <has/have> lost <its/their> connection to the monitoring service
- needsAttachment : מצטערים, נראה של <מכשירים> <חסר/ים> קובץ מצורף נדרש. צריך להחליף אותו ולנסות שוב.
- needsBin : מצטערים, נראה שהמיכל של <המכשיר/ים> <חסר/ים>. צריך להחליף אותו ולנסות שוב.
- needsPads : <device(s)> <need(s)> new pads.
- needsSoftwareUpdate : <device(s)> <need(s)> a software update.
- needsWater : <device(s)> <need(s)> water.
- networkProfileNotRecognized : סליחה, לא זיהיתי את "<network profile>" ב-<device(s)>.
- networkSpeedTestInProgress : אני כבר בודק את <הרשת> <המהירות/המהירויות>>.
- noAvailableApp : צר לי, נראה ש-<app name> לא זמינה.
- noAvailableChannel : צר לי, נראה שהערוץ <channel name> לא זמין.
- noChannelSubscription : לצערנו, בשלב הזה אין לך מינוי לערוץ <channel name>.
- noTimerExists : צר לי, נראה שלא מוגדרים טיימרים ב<מכשירים>.
- notSupported : מצטערים, המצב הזה לא זמין עבור <מכשירים>.
- obstructionDetected : <device(s)> detected an obstruction
- offline , deviceOffline : מצטערים, נראה ש <device(s)> <is/are>n't available right now.
- onRequiresMode : יש לציין את המצב שרוצים להפעיל.
- passphraseIncorrect : מצטערים, נראה שקוד האימות שגוי.
- percentOutOfRange : מצטערים, לא ניתן להגדיר את <device(s)> ל-<percent>.
- pinIncorrect : (passphraseIncorrect)
- rainDetected : לא פתחתי את <device(s)> כי זוהה גשם.
- rangeTooClose : הטמפרטורות האלה קרובות מדי לטווח החימום והקירור של <מכשירים>. צריך לבחור טמפרטורות שמרוחקות יותר זו מזו.
- relinkRequired : צר לי, נראה שמשהו השתבש בחשבון שלך. עליך להשתמש באפליקציית Google Home או Assistant כדי לקשר מחדש את <המכשירים>.
-
remoteSetDisabled
:
- פרמטר אופציונלי
errorCodeReason
currentlyArmed
- מצטערים, מכיוון שהאבטחה כבר מופעלת, צריך להשתמש ב <מכשירים> או באפליקציה כדי לבצע שינויים.remoteUnlockNotAllowed
- סליחה, אין לי אפשרות לבטל את הנעילה של <המכשירים> מרחוק.remoteControlOff
– הפעולה הזו מושבתת כרגע. עליך להפעיל את השליטה מרחוק ב <מכשירים> ולנסות שוב.childSafetyModeActive
– הפעולה הזו מושבתת במכשירים <device(s)> בזמן שמצב הבטיחות לילדים פעיל.
- פרמטר אופציונלי
- roomsOnDifferentFloors : <device(s)> לא יכול להגיע לחדרים האלה כי הם נמצאים בקומות אחרות.
- safetyShutOff : <device(s)> <is/are> in Safety Shut-Off Mode, so <it/they>'ll have to be adjusted by hand.
- sceneCannotBeApplied : מצטערים, לא ניתן להחיל את <device(s)>.
- securityRestriction : <device(s)> <has/have> a security restriction.
- softwareUpdateNotAvailable : לצערנו, אין עדכון תוכנה זמין ב<מכשירים>.
- startRequiresTime : כדי לעשות זאת, עליך לומר לי כמה זמן ברצונך להפעיל את <device(s)>.
- stillCoolingDown : <device(s)> <is/are> still cooling down.
- stillWarmingUp : <device(s)> <is/are> still warming up.
- streamUnavailable : מצטערים, נראה שהשידור לא זמין כרגע במכשירים <device(s)>.
- streamUnplayable : מצטערים, אין לי אפשרות להפעיל את הסטרימינג מהמכשירים <device(s)> כרגע.
- tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>. Please fill <it/them> and try again.
- targetAlreadyReached : מצטערים, נראה שכבר זו הטמפרטורה הנוכחית.
- timerValueOutOfRange : לא ניתן להגדיר את <device(s)> למשך הזמן הזה.
- tooManyFailedAttempts : Sorry, too many failed attempts. עליך לעבור לאפליקציה במכשיר כדי להשלים את הפעולה הזו.
- transientError : מצטערים, משהו השתבש בשליטה על <device(s)>. יש לנסות שוב.
- turnedOff , deviceTurnedOff : <device(s)> <is/are> off right now.
- unableToLocateDevice : לא הצלחתי לאתר את <device(s)>.
- unknownFoodPreset : <device(s)> לא תומך בהגדרה המוגדרת מראש של המזון הזה.
- unlockFailure : לא ניתן היה לבטל את הנעילה של <device(s)>.
- unpausableState : לא ניתן להשהות כרגע את <device(s)>.
- userCancelled : ok
- valueOutOfRange : לא ניתן להגדיר את הטמפרטורה הזו ב<מכשירים>.
חריגים
צריך להחזיר חריגה כשיש בעיה או התראה שמשויכות לפקודה. הפקודה יכולה להצליח או להיכשל.
אם הפקודה בוצעה בהצלחה (status = "SUCCESS"), מדווחים על חריגים באמצעות המאפיין StatusReport
(למכשירים שאינם היעד) או על ידי החזרת exceptionCode
מתאים (למכשיר היעד).
לדוגמה, אם מסנן האבנית של המייבש מלא, המשתמש עדיין יכול להפעיל את המייבש, אבל כדאי להזהיר אותו לגבי המצב הזה. באופן דומה, כשהסוללה במכשיר חלשה אבל לא ריקה, עדיין אפשר לבצע את הפקודה, אבל צריך להודיע להם שהסוללה במכשיר חלשה.
אם הפקודה נכשלת בגלל חריגות, הסטטוס צריך להיות 'EXCEPTIONS', וצריך לדווח על החריגות באמצעות המאפיין StatusReport
.
חריגה לא חוסמת (SUCCESS) לגבי מכשיר היעד
הדוגמה הזו היא לנעילת הדלת:
רמת הטעינה של הסוללה במנעול הדלת הקדמית נמוכה. נעילת הדלת הקדמית.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["device-id-1"], "status": "SUCCESS", "states": { "on": true, "online": true, "isLocked": true, "isJammed": false, "exceptionCode": "lowBattery" } }] } }
חריגה לא חוסמת (SUCCESS) לגבי מכשיר אחר באמצעות StatusReport
הדוגמה הזו היא להפעלת מערכת אבטחה: Ok, arming the security system. החלון הקדמי פתוח.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["device-id-1"], "status": "SUCCESS", "states": { "on": true, "online": true, "isArmed": true, "currentArmLevel": "L2", "currentStatusReport": [{ "blocking": false, "deviceTarget": "sensor_id1", "priority": 0, "statusCode": "deviceOpen" }] } }] } }
החרגה לחסימה של מכשיר אחר באמצעות StatusReport
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "devices": { "device-id-1": { "on": true, "online": true, "status": "EXCEPTIONS", "currentStatusReport": [{ "blocking": true, "deviceTarget": "device-id-1", "priority": 0, "statusCode": "lowBattery" }, { "blocking": true, "deviceTarget": "front_window_id", "priority": 1, "statusCode": "deviceOpen" }, { "blocking": true, "deviceTarget": "back_window_id", "priority": 1, "statusCode": "deviceOpen" } ] } } } }
רשימת החרגות
החרגות הבאות יגרמו ליצירת ה-TTS המשויך במכשיר.
- bagFull : <device(s)> <has/have> <a full bag/full bags>. Please empty <it/them> and try again.
- binFull : <device(s)> <has/have> <a full bin/full bins>.
- carbonMonoxideDetected : זוהה פחמן חד-חמצני ב <שם הבית>.
- deviceAtExtremeTemperature : <device(s)> <is/are> at <an extreme temperature/extreme temperatures>.
- deviceJammingDetected : <device(s)> <is/are> jammed.
- deviceMoved : <device(s)> <was/were> moved.
- deviceOpen : <device(s)> <is/are> open.
- deviceTampered : <device(s)> <has/have> been tampered with.
- deviceUnplugged : <device(s)> <is/are> unplugged.
- floorUnreachable : <device(s)> לא יכולים להגיע לחדר הזה. יש להעביר <את/אתם> לקומה המתאימה ולנסות שוב.
- hardwareFailure : <device(s)> <has/have> a hardware problem.
- inSoftwareUpdate : <device(s)> <is/are> currently in a software update.
- isBypassed : <device(s)> <is/are> currently bypassed.
- lowBattery : <device(s)> <has/have> low battery.
- motionDetected : <device(s)> <detect(s)> motion.
- needsPads : <device(s)> <need(s)> new pads.
- needsSoftwareUpdate : <device(s)> <need(s)> a software update.
- needsWater : <device(s)> <need(s)> water.
- networkJammingDetected : החיבור לרשת הביתית של <מכשירים> לא פועל כראוי.
- noIssuesReported : לא דווחו בעיות ב<מכשירים>.
- roomsOnDifferentFloors : <device(s)> לא יכול להגיע לחדרים האלה כי הם נמצאים בקומות אחרות.
- runCycleFinished : <device(s)> <has/have> finished running.
- securityRestriction : <device(s)> <has/have> a security restriction.
- smokeDetected : זוהה עשן ב <house name>.
- tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>. Please fill <it/them> and try again.
- usingCellularBackup : <device(s)> <is/are> using cellular backup.
- waterLeakDetected : <device(s)> <detect(s)> a water leak.