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

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

שגיאות

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

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

לסיכום:

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

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

קטע הקוד הבא של JSON מראה איך מחזירים שגיאות ברמה הגלובלית בתגובה מסוג QUERY או מתגובה EXECUTE.

דוגמה לשגיאה ברמה הגלובלית deviceOffline עקב שה-Hub נמצא במצב אופליין:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "errorCode": "deviceOffline",
    "status" : "ERROR"
  }
}

דוגמה לשגיאה ברמה הגלובלית inSoftwareUpdate עקב עדכון של ה-Hub:

{
  "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 מראה איך מחזירים שגיאות ברמת המכשיר בתגובה 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 המשויך במכשיר.

חריגים

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

אם הפקודה הצליחה (סטטוס = 'הצלחה'), דווחו על חריגים באמצעות התכונה StatusReport (למכשירים שאינם היעד), או על ידי החזרת ערך exceptionCode מתאים (למכשיר היעד).

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

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

חריג ללא חסימה (הצלחה) לגבי מכשיר היעד

הדוגמה הזו מיועדת לנעילת הדלת:

רמת הטעינה של הסוללה במנעול הדלת הקדמית נמוכה. מתבצעת נעילה של הדלת הקדמית.

{
  "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"
      }
    }]
  }
}

חריג ללא חסימה (הצלחה) לגבי מכשיר אחר באמצעות דוח סטטוס

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

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