הסכימה של מאפיין הפצה לבית חכם

action.devices.traits.Dispense – המאפיין הזה שייך למכשירים שתומכים במתן כמות מסוימת של פריט פיזי אחד או יותר.

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

מאפייני המכשיר

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

מאפיינים	סוג	תיאור
supportedDispenseItems	מערך	מכיל מידע על כל הפריטים שהמכשיר יכול למכור.
[item, ...]	אובייקט	פריט שאפשר להסתדר בלעדיו.
item_name	String	חובה. שם פנימי של הפריט שנזקק. האפשרות הזו עשויה להיות לא ידידותית למשתמש, והיא משותפת בכל השפות.
item_name_synonyms	מערך	חובה. שמות נרדפות של המוצרים שנמכרו בכל שפה נתמכת.
[item, ...]	אובייקט	שמות של שמות נרדפים לפריט שמופק בשפה נתונה.
synonyms	מערך	חובה. שמות נרדפות של הפריט שנקנה. המילים הנרדפות צריכות לכלול גם את הצורה היחידה וגם את הצורה הרבים, אם רלוונטי. המחרוזת הראשונה ברשימה הזו צריכה להיות צורת הרבים של הפריט בשפה הזו.
[item, ...]	String	שם המילה הנרדפת
lang	String	חובה. קוד השפה (ISO 639-1). כאן מפורטות השפות הנתמכות.
supported_units	מערך	חובה. קבוצה של יחידות שהמכשיר תומך בהן עבור הפריט הזה.
[item, ...]	String	יחידות נתמכות. ערכים נתמכים: CENTIMETERS CUPS DECILITERS FLUID_OUNCES GALLONS GRAMS KILOGRAMS LITERS MILLIGRAMS MILLILITERS MILLIMETERS NO_UNITS OUNCES PINCH PINTS PORTION POUNDS QUARTS TABLESPOONS TEASPOONS
default_portion	אובייקט	חובה. הכמות האופיינית של הפריט שאפשר לוותר.
amount	Integer	חובה. הסכום שלא נוצל.
unit	String	חובה. יחידה שהונפקה.
supportedDispensePresets	מערך	הגדרות קבועות מראש שנתמכות במכשיר.
[item, ...]	אובייקט	הגדרה קבועה מראש.
preset_name	String	חובה. השם הפנימי של ההגדרה המוגדרת מראש. השם הזה יכול להיות לא ידידותי למשתמש והוא משותף לכל השפות.
preset_name_synonyms	מערך	חובה. שמות נרדפות של ההגדרה הקבועה מראש בכל שפה נתמכת.
[item, ...]	אובייקט	שמות נרדפות של ההגדרה הקבועה מראש בשפה נתונה.
synonyms	מערך	חובה. שמות של מילים נרדפות להגדרה הקבועה מראש. המילים הנרדפות צריכות לכלול גם את הצורה היחידה וגם את הצורה הרבים, אם רלוונטי.
[item, ...]	String	שם המילה הנרדפת
lang	String	חובה. קוד השפה (ISO 639-1). כאן מפורטות השפות הנתמכות.

דוגמאות

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

{
  "supportedDispenseItems": [
    {
      "item_name": "Water",
      "item_name_synonyms": [
        {
          "lang": "en",
          "synonyms": [
            "Water"
          ]
        }
      ],
      "supported_units": [
        "TEASPOONS",
        "TABLESPOONS",
        "FLUID_OUNCES",
        "CUPS",
        "PINTS",
        "QUARTS",
        "GALLONS",
        "MILLILITERS",
        "LITERS",
        "DECILITERS"
      ],
      "default_portion": {
        "amount": 2,
        "unit": "CUPS"
      }
    }
  ],
  "supportedDispensePresets": [
    {
      "preset_name": "cat_bowl",
      "preset_name_synonyms": [
        {
          "lang": "en",
          "synonyms": [
            "Cat water bowl",
            "Cat water dish",
            "Cat water cup"
          ]
        }
      ]
    },
    {
      "preset_name": "glass_1",
      "preset_name_synonyms": [
        {
          "lang": "en",
          "synonyms": [
            "Glass of water",
            "Glass"
          ]
        }
      ]
    }
  ]
}

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

{
  "supportedDispenseItems": [
    {
      "item_name": "Treat",
      "item_name_synonyms": [
        {
          "lang": "en",
          "synonyms": [
            "Treats",
            "Dog treats",
            "Treat",
            "Dog treat"
          ]
        }
      ],
      "supported_units": [
        "NO_UNITS"
      ],
      "default_portion": {
        "amount": 1,
        "unit": "NO_UNITS"
      }
    }
  ]
}

מצבי המכשיר

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

מדינות	סוג	תיאור
dispenseItems	מערך	מספר הפריטים שהמכשיר יכול לנפק.
[item, ...]	אובייקט	המצב של פריט נתון.
itemName	String	שם הפריט מהמאפיין item_name.
amountRemaining	אובייקט	כמות הפריט שנותרה במכשיר. אם המכשיר יפיק כרגע את מכסת האחסון, ההודעה הזו מדווחת על הסכום שנותר, או מה יהיה הסכום כשיוציא המכשיר.
amount	מספר	הסכום שנותר
unit	String	היחידה של amount מהמאפיין supported_units.
amountLastDispensed	אובייקט	הכמות של הפריט שהמכשיר הנפיק בפעם האחרונה. אם המכשיר פורק כרגע, המערכת אמורה לדווח על הסכום שפרק לפני הסכום הנוכחי.
amount	מספר	הסכום שנותר
unit	String	היחידה של amount מהמאפיין supported_units.
isCurrentlyDispensing	בוליאני	מראה אם המכשיר פורס כרגע את הפריט הזה.

דוגמאות

כמה חטיפים לכלבים נותרו במאגר?

{
  "dispenseItems": [
    {
      "itemName": "Dog treats",
      "amountRemaining": {
        "amount": 83,
        "unit": "NO_UNITS"
      },
      "amountLastDispensed": {
        "amount": 2,
        "unit": "NO_UNITS"
      },
      "isCurrentlyDispensing": false
    }
  ]
}

כמה מים נותרו במקרר המים?

{
  "dispenseItems": [
    {
      "itemName": "Water",
      "amountRemaining": {
        "amount": 6.2,
        "unit": "GALLONS"
      },
      "amountLastDispensed": {
        "amount": 1,
        "unit": "CUPS"
      },
      "isCurrentlyDispensing": false
    }
  ]
}

כמה מזון לחתולים נתתי בעבר?

{
  "dispenseItems": [
    {
      "itemName": "cat_food",
      "amountRemaining": {
        "amount": 16.5,
        "unit": "CUPS"
      },
      "amountLastDispensed": {
        "amount": 2.5,
        "unit": "CUPS"
      },
      "isCurrentlyDispensing": false
    }
  ]
}

האם המים עדיין יוצאים מהברז?

{
  "dispenseItems": [
    {
      "itemName": "Water",
      "isCurrentlyDispensing": true
    }
  ]
}

יש לדווח על amountRemaining ו-amountLastDispensed רק באמצעות יחידת מידה אחת.

אפשר לספק כמה פריטים במערך dispenseItems. כל שם של פריט צריך להיות ייחודי ולהתאים לפריט במאפיין supportedDispenseItems.

פקודות למכשיר

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

action.devices.commands.Dispense

צריך לוותר על פריטים.

פרמטרים

המטען הייעודי מכיל אחד מהפריטים הבאים:

מחלקים לפי סכום.

פרמטרים	סוג	תיאור
item	String	שם הפריט להנפקה, מהמאפיין item_name.
amount	מספר	חובה. הסכום לניצול.
unit	String	חובה. היחידות של amount, מהמאפיין supported_units.

חלוקה לפי הגדרה מוגדרת מראש.

פרמטרים	סוג	תיאור
presetName	String	חובה. שם ההגדרה הקבועה מראש להנפקה, מהמאפיין preset_name.

פיזור ללא פרמטרים.

פרמטרים	סוג	תיאור
אין נכסים

דוגמאות

Give me 1 cup of water.

{
  "command": "action.devices.commands.Dispense",
  "params": {
    "amount": 1,
    "unit": "CUPS",
    "item": "Water"
  }
}

ממלאים את קערת המים של החתול.

{
  "command": "action.devices.commands.Dispense",
  "params": {
    "presetName": "cat_bowl"
  }
}

מזיגים מים.

{
  "command": "action.devices.commands.Dispense",
  "params": {}
}

ERRORS במכשיר

כאן מפורטת הרשימה המלאה של שגיאות וחריגים.

• dispenseAmountRemainingExceeded: המשתמש ניסה להוציא פריט או סכום ממכשיר שלא נותרה בו מספיק כמות.
• dispenseAmountAboveLimit: המשתמש ניסה להנפיק סכום שמעבר למגבלות של מה שהוא יכול לבקש בשאילתה אחת. מטרת ההגבלה הזו היא למנוע לפזר בטעות כמות גדולה מדי (לדוגמה, 500,000 כוסות מים).
• dispenseAmountBelowLimit: המשתמש ניסה להוציא מהמכשיר פריט או סכום שנמוך מהסכום המינימלי שהמכשיר יכול להוציא.
• dispenseFractionalAmountNotSupported: המשתמש ניסה לנפק כמות חלקית של פריט שהמכשיר לא יכול לפצל (לדוגמה, המכשיר לא יכול לפצל פריטים שניתן לספור כמו חטיפים לכלבים).
• genericDispenseNotSupported: המשתמש מנסה להוציא מוצר ממכשיר בלי לציין פריט או הגדרה מוגדרת מראש, אבל המכשיר לא תומך בפונקציונליות כזו (לדוגמה, פעולת הפצה שמוגדרת כברירת מחדל).
• dispenseUnitNotSupported: המשתמש מנסה למלא את התעודה ממכשיר עם יחידה שלא נתמכת באותו מקרה (לדוגמה, הפריט לא מסופק ולכן supported_unit validation עבר על פני השלב הזה).
• dispenseFractionalUnitNotSupported: המשתמש ניסה למדוד כמות חלקית של פריט שאפשר לפצל, אבל לא ביחידת המידה הספציפית שצוינה (לדוגמה, ברז יכול למדוד 2.7 כוסות אבל לא 2.7 מ"ל).
• deviceCurrentlyDispensing: המשתמש מנסה להוציא פריט אבל המכשיר כבר מוציא פריט.
• deviceClogged: המשתמשים מנסים להוציא פריט אבל המכשיר סתום.
• deviceBusy: המשתמש מנסה לנפק פריט, אבל המכשיר עסוק (כללי).

החרגות של מכשירים

אפשר לדווח על החריגות האלה כ-exceptionCode באובייקט states של התשובה:

• amountRemainingLow – המשתמש מוציא פריט או סכום מהמכשיר, וכתוצאה מכך הסכום שנותר נמוך. אתם אחראים להגדיר מה נחשב לרמה 'נמוכה'.
• userNeedsToWait – כשהמשתמש צריך להמתין לפני שהפריט או הכמות המבוקשים יוכלו להופיע (לדוגמה, ברז שבו מופיע מים חמים, אבל המשתמש צריך להמתין עד שהמים יתחממו כדי שהם יתחילו לזרום).