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

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

שגיאות

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

ניתן לצרף קודי שגיאה ברמת המכשיר או ברמה הגלובלית. לדוגמה, אם למשתמש יש הרבה נורות מספק אחד והן נשלטות על ידי רכזת, כשהמשתמש מבקש לכבות את כל האורות, הספק עשוי להחזיר שגיאה ברמת המכשיר אם נורת אחת לא מחוברת לאינטרנט, או שגיאה ברמת העולם אם הרכזת כולה לא מחוברת ולא ניתן לשלוט באורות. אם כל המכשירים לא מחוברים לאינטרנט, אין הבדל בין שגיאות ברמת המכשיר לבין שגיאות ברמת המכשיר. כשהמכשיר במצב אופליין, צריך לדווח על המצב {"online": false} ב-reportState, גם אם מחזירים את קוד השגיאה deviceOffline.

לסיכום:

• שגיאה ברמת העולם: כל המכשירים בתגובה כוללים את אותה השגיאה
• שגיאה ברמה המקומית: תגובה מעורבת עם שגיאות ושגיאות הצלחה

שגיאות ברמת העולם

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

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "device-id-1": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      },
      "device-id-2": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      }
    }
  }
}

הפעלת התגובה

קטע ה-JSON הבא מראה איך מחזירים שגיאות ברמת המכשיר בתגובה מסוג ECECUTE.

{
  "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 המשויך במכשיר.

חריגים

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

אם הפקודה הצליחה (סטטוס = "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

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

{
  "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 המשויך במכשיר.