שגיאות וחריגים

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

חריגים

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

אם הפקודה בוצעה בהצלחה (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 המשויך במכשיר.