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

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

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

الجهاز ATTRIBUTES

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

السمات	النوع	الوصف
supportedDispenseItems	المصفوفة	يحتوي على معلومات عن جميع العناصر التي يستطيع الجهاز توزيعها.
[item, ...]	العنصر	عنصر يمكن الاستغناء عنه.
item_name	سلسلة	مطلوبة. الاسم الداخلي للعنصر الموزَّع. يمكن أن يكون هذا غير سهل الاستخدام، وتتم مشاركته عبر جميع اللغات.
item_name_synonyms	المصفوفة	مطلوبة. مرادفات للأسماء التي تم الاستغناء عنها في كل لغة مدعومة.
[item, ...]	العنصر	مرادفات لأسماء العنصر الموزع بلغة معينة.
synonyms	المصفوفة	مطلوبة. أسماء المرادفات للعنصر الموزَّع. يجب أن تتضمن المرادفات صيغ المفرد والجمع، إن أمكن. يجب أن تكون السلسلة الأولى في هذه القائمة هي صيغة الجمع للعنصر بهذه اللغة.
[item, ...]	سلسلة	اسم المرادفات
lang	سلسلة	مطلوبة. رمز اللغة (ISO 639-1). راجع اللغات المعتمدة.
supported_units	المصفوفة	مطلوبة. مجموعة من الوحدات التي يتوافق معها الجهاز لهذا العنصر.
[item, ...]	سلسلة	الوحدات المتوافقة. القيم المسموح بها: 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	عدد صحيح	مطلوبة. المبلغ الذي تم إنفاقه.
unit	سلسلة	مطلوبة. تم الاستغناء عن الوحدة.
supportedDispensePresets	المصفوفة	الإعدادات المسبقة المتوافقة مع الجهاز.
[item, ...]	العنصر	إعداد مسبق.
preset_name	سلسلة	مطلوبة. الاسم الداخلي للإعداد المسبق. يمكن أن يكون هذا الاسم غير سهل الاستخدام، وتتم مشاركته عبر جميع اللغات.
preset_name_synonyms	المصفوفة	مطلوبة. أسماء مترادفات للإعداد المسبق في كل لغة مدعومة.
[item, ...]	العنصر	أسماء مترادفات للإعداد المسبق بلغة معينة.
synonyms	المصفوفة	مطلوبة. أسماء مترادفات للإعداد المسبق. ويجب أن تتضمن المرادفات صيغ المفرد والجمع، إن أمكن.
[item, ...]	سلسلة	اسم المرادفات
lang	سلسلة	مطلوبة. رمز اللغة (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"
      }
    }
  ]
}

حالة الجهاز STATES

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

الولايات	النوع	الوصف
dispenseItems	المصفوفة	حالات العناصر التي يمكن للجهاز توزيعها.
[item, ...]	العنصر	حالة سلعة معيّنة
itemName	سلسلة	اسم السلعة من السمة item_name
amountRemaining	العنصر	مقدار تلك السلعة المتبقية في الجهاز. إذا كان الجهاز ينفّذ حاليًا طريقة لتوزيع الكمية، يشير هذا إلى المبلغ المتبقّي أو المبلغ المتوقّع عند انتهاء صرف الجهاز.
amount	Number	المبلغ المتبقي
unit	سلسلة	وحدة amount من السمة supported_units
amountLastDispensed	العنصر	مقدار السلعة التي تم توزيعها مؤخرًا على الجهاز. إذا كان الجهاز الموزَّع حاليًا، يجب الإبلاغ عن الكمية التي تم توزيعها قبل مبلغ الصرف الحالي.
amount	Number	المبلغ المتبقي
unit	سلسلة	وحدة 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.

مفاتيح COMMAND

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

action.devices.commands.Dispense

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

المَعلمات

تحتوي الحمولة على واحد مما يلي:

تُوزَّع حسب المقدار.

المَعلمات	النوع	الوصف
item	سلسلة	اسم السلعة المطلوب توزيعها من السمة item_name
amount	Number	مطلوبة. مبلغ يتم توزيعه.
unit	سلسلة	مطلوبة. وحدة amount، من السمة supported_units.

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

المَعلمات	النوع	الوصف
presetName	سلسلة	مطلوبة. تمثل هذه الخاصية اسم الإعداد المسبق المراد توزيعه من السمة preset_name.

الاستغناء عنها بدون معلمات.

المَعلمات	النوع	الوصف
ما من مواقع

أمثلة

يُرجى إعطاء كوب واحد من الماء.

{
  "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 - عندما يضطر المستخدم إلى الانتظار قبل أن يتم توزيع السلعة أو المبلغ المطلوب بنجاح (على سبيل المثال، يوزّع الصنبور الماء الساخن، ولكن يحتاج المستخدم إلى انتظار تسخين المياه قبل بدء عملية التوزيع).