مخطط سمات توزيع المنزل المزوّد بأجهزة ذكية

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

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

سمات الجهاز

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

السمات	Type	الوصف
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	عدد صحيح	يجب ملء هذا الحقل. المبلغ الذي تم صرفه.
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، يُرجى الاطّلاع على تنفيذ النية.

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

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

المَعلمات

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

التوزيع حسب الكمية.

المَعلمات	Type	الوصف
item	String	اسم العنصر المطلوب توزيعه من السمة item_name
amount	Number	يجب ملء هذا الحقل. الكمية المطلوب توزيعها
unit	String	يجب ملء هذا الحقل. وحدة السمة amount من السمة supported_units

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

المَعلمات	Type	الوصف
presetName	String	يجب ملء هذا الحقل. تمثّل هذه السمة اسم الإعداد المسبق للتوزيع من السمة preset_name.

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

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

أمثلة

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

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