Esquema de la función de distribución de hogares inteligentes

action.devices.traits.Dispense: Esta característica pertenece a los dispositivos que admiten la entrega de una cantidad específica de uno o más artículos físicos.

Esta característica también es compatible con el uso de un ajuste predeterminado, por ejemplo, como un “tazón de comida para gatos” para un comedero para mascotas o un “vaso” para un grifo.

ATRIBUTOS DEL Dispositivo

Los dispositivos con esta característica pueden informar los siguientes atributos como parte de la operación SYNC. Para obtener más información sobre cómo manejar los intents SYNC, consulta Entrega de intents.

Atributos	Tipo	Descripción
supportedDispenseItems	Matriz	Contiene información sobre todos los artículos que el dispositivo puede expender.
[item, ...]	Objeto	Elemento desechable.
item_name	String	Obligatorio. Es el nombre interno del artículo distribuido. Esta opción no es fácil de usar y se comparte en todos los idiomas.
item_name_synonyms	Matriz	Obligatorio. Nombres sinónimos de la distribución en cada idioma admitido.
[item, ...]	Objeto	Nombres sinónimos para el elemento de distribución en un idioma determinado.
synonyms	Matriz	Obligatorio. Nombres sinónimos para el artículo de distribución. Los sinónimos deben incluir formas singulares y plurales, si corresponde. La primera string de esta lista debe ser el plural del elemento en ese idioma.
[item, ...]	String	Nombre del sinónimo
lang	String	Obligatorio. Código de idioma (ISO 639-1). Consulte los idiomas compatibles.
supported_units	Matriz	Obligatorio. Es el conjunto de unidades que el dispositivo admite para ese elemento.
[item, ...]	String	Unidades admitidas. Valores admitidos: CENTIMETERS CUPS DECILITERS FLUID_OUNCES GALLONS GRAMS KILOGRAMS LITERS MILLIGRAMS MILLILITERS MILLIMETERS NO_UNITS OUNCES PINCH PINTS PORTION POUNDS QUARTS TABLESPOONS TEASPOONS
default_portion	Objeto	Obligatorio. Importe habitual del artículo que se puede repartir.
amount	Número entero	Obligatorio. Importe expendido
unit	String	Obligatorio. Unidad distribuida.
supportedDispensePresets	Matriz	Predeterminados compatibles con el dispositivo
[item, ...]	Objeto	Ajuste predeterminado.
preset_name	String	Obligatorio. Nombre interno del ajuste predeterminado. Este nombre puede ser poco fácil de usar y se comparte en todos los idiomas.
preset_name_synonyms	Matriz	Obligatorio. Nombres de sinónimos para el ajuste predeterminado en cada idioma admitido.
[item, ...]	Objeto	Nombres de sinónimos para el ajuste predeterminado en un idioma determinado.
synonyms	Matriz	Obligatorio. Nombres de sinónimos para el ajuste predeterminado. Los sinónimos deben incluir formas en singular y plural, si corresponde.
[item, ...]	String	Nombre del sinónimo
lang	String	Obligatorio. Código de idioma (ISO 639-1). Consulte los idiomas compatibles.

Ejemplos

Dispensador de agua que admite unidades para líquidos con ajustes predeterminados.

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

Dispensador de alimento para mascotas sin ajustes predeterminados.

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

Dispositivo STATEs

Las entidades con esta característica pueden informar los siguientes estados como parte de la operación QUERY. Para obtener más información sobre cómo manejar los intents QUERY, consulta Entrega de intents.

Estados	Tipo	Descripción
dispenseItems	Matriz	Estados de los artículos que el dispositivo puede expender.
[item, ...]	Objeto	Es el estado de un elemento determinado.
itemName	String	Es el nombre del artículo del atributo item_name.
amountRemaining	Objeto	Cantidad de ese artículo restante en el dispositivo. Si el dispositivo está expendiendo el dispositivo en ese momento, se informará el importe restante o cuál será el importe cuando el dispositivo termine de distribuirse.
amount	Número	Importe restante
unit	String	Unidad para amount del atributo supported_units.
amountLastDispensed	Objeto	La cantidad de ese artículo que se entregó recientemente. Si el dispositivo está expendiendo el dispositivo en ese momento, se debe informar el importe que se distribuyó antes de la cantidad actual.
amount	Número	Importe restante
unit	String	Unidad para amount del atributo supported_units.
isCurrentlyDispensing	Booleano	Indica si el dispositivo está expendiendo actualmente de este artículo.

Ejemplos

¿Cuántas golosinas tiene para mi dispensador?

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

¿Cuánta agua queda en el enfriador de agua?

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

¿Cuánta comida para gatos di como anterior?

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

¿El grifo todavía expende agua?

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

amountRemaining y amountLastDispensed solo deben informarse con una unidad de medida.

Se pueden proporcionar varios elementos dentro del array dispenseItems. Cada nombre debe ser único y corresponde a un elemento del atributo supportedDispenseItems.

Dispositivo COMMAND

Los dispositivos con esta característica pueden responder a los siguientes comandos como parte de la operación EXECUTE. Para obtener más información sobre cómo manejar los intents EXECUTE, consulta Entrega de intents.

action.devices.commands.Dispense

Dispensar artículos.

Parámetros

La carga útil contiene una de las siguientes opciones:

Distribución según el importe.

Parámetros	Tipo	Descripción
item	String	Nombre del artículo que se enviará, del atributo item_name.
amount	Número	Obligatorio. Importe para dispensar.
unit	String	Obligatorio. Unidad para amount del atributo supported_units.

Distribución predeterminada.

Parámetros	Tipo	Descripción
presetName	String	Obligatorio. Nombre del ajuste predeterminado que se enviará, desde el atributo preset_name.

Distribución sin parámetros.

Parámetros	Tipo	Descripción
Sin propiedades

Ejemplos

Dame 1 taza de agua.

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

Llena el recipiente de agua para gatos.

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

Distribución de agua.

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

Dispositivo ERRORS

Consulta la lista completa de errores y excepciones.

• dispenseAmountRemainingExceeded: El usuario intentó entregar un artículo o una cantidad de un dispositivo que no tiene suficiente cantidad.
• dispenseAmountAboveLimit: El usuario intentó distribuir una cantidad que excede los límites de lo que puede solicitar en una sola consulta. Esto evita la distribución accidental de una cantidad excesiva (por ejemplo, 500,000 tazas de agua).
• dispenseAmountBelowLimit: El usuario intentó expender un artículo o una cantidad por debajo del importe mínimo que puede expender.
• dispenseFractionalAmountNotSupported: El usuario intentó dispensar una cantidad fraccionaria de un elemento que el dispositivo no puede dividir (por ejemplo, los elementos contables, como los bocadillos para perros, no pueden ser divisibles por el dispositivo).
• genericDispenseNotSupported: El usuario intenta dispersar desde un dispositivo sin especificar un elemento o ajuste predeterminado, pero el dispositivo no admite esa funcionalidad (por ejemplo, una acción de disyunción predeterminada).
• dispenseUnitNotSupported: El usuario intenta dispensar desde un dispositivo con una unidad no compatible en ese caso (por ejemplo, el elemento no se proporciona, por lo que se omitió supported_unit validation).
• dispenseFractionalUnitNotSupported: El usuario intentó dispensar una cantidad fraccionaria de un elemento que se puede dividir, pero no para la unidad específica especificada (por ejemplo, un grifo puede distribuir 2.7 tazas, pero no 2.7 ml).
• deviceCurrentlyDispensing: Los usuarios intentan dispensar un artículo, pero el dispositivo ya está expendiendo.
• deviceClogged: Los usuarios intentan dispensar un artículo, pero el dispositivo está obstruido.
• deviceBusy: Los usuarios intentan dispensar un artículo, pero el dispositivo está ocupado (genérico).

Dispositivo EXCEPTIONS

Estas excepciones se pueden informar como exceptionCode en el objeto states de tu respuesta:

• amountRemainingLow: El usuario expende un artículo o una cantidad del dispositivo, lo que lleva la cantidad restante a un nivel bajo. Eres responsable de definir qué constituye un nivel "bajo".
• userNeedsToWait: Cuando el usuario tiene que esperar a que la cantidad o el artículo solicitados se puedan expender de forma correcta (por ejemplo, un grifo dispensará agua caliente, pero el usuario deberá esperar a que se caliente para poder expenderla).