مخطط سمة التوزيع في المنزل الذكي

‫action.devices.traits.Dispense: تنتمي هذه السمة إلى الأجهزة التي تتيح توزيع كمية محددة من سلعة مادية واحدة أو أكثر.

تتيح هذه السمة أيضًا توزيع إعداد مُسبَق، مثل "وعاء طعام القطط" في جهاز تغذية الحيوانات الأليفة أو "كوب" في صنبور المياه.

سمات الجهاز

قد تعرض الأجهزة التي تتضمّن هذه السمة السمات التالية كجزء من عملية SYNC. لمزيد من المعلومات حول التعامل مع طلبات SYNC، يمكنك الاطّلاع على مقالة تنفيذ الطلبات.

أمثلة

موزّع مياه يتيح استخدام وحدات قياس السوائل مع إعدادات مُسبقة

{
  "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": [
    {
      "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

توزيع العناصر

المعلمات

تحتوي الحمولة على أحد العناصر التالية:

الاستغناء حسب المبلغ

التوزيع حسب الإعداد المُسبَق

التوزيع بدون مَعلمات

أمثلة

أريد كوبًا من الماء.

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

أخطاء الجهاز

• ‫dispenseAmountRemainingExceeded: حاول المستخدم صرف مبلغ أو سلعة من جهاز لا يتضمّن المبلغ المتبقي الكافي.
• dispenseAmountAboveLimit: حاول المستخدم صرف مبلغ يتجاوز الحدود المسموح بها في طلب بحث واحد. ويتم ذلك لتجنُّب صرف كمية كبيرة من المياه بدون قصد (على سبيل المثال، 500,000 كوب من المياه).
• ‫dispenseAmountBelowLimit: حاول المستخدم صرف سلعة أو مبلغ من الجهاز الذي يقل عن الحد الأدنى للمبلغ الذي يمكن صرفه.
• ‫dispenseFractionalAmountNotSupported: حاول المستخدم توزيع كمية جزئية من سلعة لا يمكن للجهاز تقسيمها (على سبيل المثال، قد لا تكون السلع القابلة للعد، مثل مكافآت الكلاب، قابلة للقسمة بواسطة الجهاز).
• ‫genericDispenseNotSupported: يحاول المستخدم صرف دواء من جهاز بدون تحديد سلعة أو إعداد مسبق، ولكن الجهاز لا يتيح هذه الوظيفة (على سبيل المثال، إجراء صرف تلقائي).
• dispenseUnitNotSupported: يحاول المستخدم صرف دواء من جهاز لا يتوافق مع هذه الحالة (على سبيل المثال، لم يتم توفير الدواء، لذا تم تخطّي supported_unit validation).
• ‫dispenseFractionalUnitNotSupported: حاول المستخدم توزيع كمية جزئية من منتج يمكن تقسيمه ولكن ليس بالوحدة المحددة (على سبيل المثال، قد يكون الصنبور قادرًا على توزيع 2.7 كوب ولكن ليس 2.7 ملليلتر).
• deviceCurrentlyDispensing: يحاول المستخدم صرف منتج، ولكن الجهاز يصرف منتجًا بالفعل.
• deviceClogged: يحاول المستخدم توزيع سلعة ولكن الجهاز مسدود.
• ‫deviceBusy: يحاول المستخدم صرف سلعة ولكن الجهاز مشغول (عام).

استثناءات الأجهزة

يمكن الإبلاغ عن هذه الاستثناءات كـ exceptionCode في عنصر states الخاص باستجابتك:

• amountRemainingLow - يوزّع المستخدم سلعة أو مبلغًا من الجهاز، ما يؤدي إلى انخفاض المبلغ المتبقي إلى مستوى منخفض. أنت المسؤول عن تحديد ما يشكّل مستوى "منخفضًا".
• ‫userNeedsToWait - عندما يكون على المستخدم الانتظار قبل أن يتمكن من الحصول على السلعة أو المبلغ المطلوب (على سبيل المثال، سيوزع صنبور المياه الساخنة المياه، ولكن على المستخدم الانتظار حتى تسخن المياه قبل أن يبدأ الصنبور في توزيعها).