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

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

שגיאות

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

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

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