مرحبًا بك في "مركز مطوّري Google Home"، الوجهة الجديدة لتعلّم كيفية تطوير المهام المنزلية الذكية. ملاحظة: ستواصل إنشاء إجراءات في "وحدة تحكّم المهام".

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

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

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

سمات الجهاز

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

السمات Type الوصف
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"
      }
    }
  ]
}

حالات الجهاز

قد تُبلِغ الكيانات التي تحمل هذه السمة عن الحالات التالية كجزء من عملية QUERY. للاطّلاع على مزيد من المعلومات حول التعامل مع عناصر intent في QUERY، يُرجى الاطّلاع على تنفيذ النية بالشراء.

الولايات Type الوصف
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.

حوالات الجهاز

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

action.devices.commands.Dispense

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

المعلّمات

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

توزيع المبلغ

المعلّمات Type الوصف
item سلسلة

اسم السلعة المطلوب توزيعها، من السمة item_name.

amount Number

مطلوب:

المبلغ المطلوب توزيعه.

unit سلسلة

مطلوب:

وحدة amount، من السمة supported_units

توزيعها مسبقًا

المعلّمات Type الوصف
presetName سلسلة

مطلوب:

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