Esquema de rasgo de distribución para el hogar inteligente

action.devices.traits.Dispense: Esta característica pertenece a dispositivos que admiten la distribución de una cantidad específica de uno o más elementos físicos.

Esta característica también admite el uso de un ajuste predeterminado, por ejemplo, un "tazón de comida para gatos" para un comedero para mascotas o un "vidrio" para un grifo.

Dispositivo ATTRIBUTES

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 controlar 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

Artículo dispensable.

item_name String

Obligatorio.

Nombre interno del artículo distribuido. Esta opción puede no ser fácil de usar y se comparte en todos los idiomas.

item_name_synonyms Matriz

Obligatorio.

Son los nombres de sinónimos que se difunden en cada idioma admitido.

[item, ...] Objeto

Son los nombres de sinónimos del artículo proporcionado en un idioma determinado.

synonyms Matriz

Obligatorio.

Son los nombres de sinónimos del artículo entregado. Los sinónimos deben incluir formas singular y plural, si corresponde. La primera string de la lista debe tener el plural del elemento en ese idioma.

[item, ...] String

Nombre de sinónimos

lang String

Obligatorio.

Es el código de idioma (ISO 639-1). Consulta 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 entregar.

amount Número entero

Obligatorio.

Importe distribuido.

unit String

Obligatorio.

Unidad distribuida.

supportedDispensePresets Matriz

Los ajustes predeterminados compatibles con el dispositivo.

[item, ...] Objeto

Ajuste predeterminado.

preset_name String

Obligatorio.

Nombre interno del ajuste predeterminado. Es posible que este nombre no sea fácil de usar y se comparta en todos los idiomas.

preset_name_synonyms Matriz

Obligatorio.

Los nombres de sinónimos de los ajustes predeterminados en cada idioma admitido.

[item, ...] Objeto

Son los nombres de sinónimos de los ajustes predeterminados en un idioma determinado.

synonyms Matriz

Obligatorio.

Los nombres de sinónimos del ajuste predeterminado. Los sinónimos deben incluir formas singular y plural, si corresponde.

[item, ...] String

Nombre de sinónimos

lang String

Obligatorio.

Es el código de idioma (ISO 639-1). Consulta los idiomas compatibles.

Ejemplos

Dispensador de agua que admite unidades de 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 comida 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 controlar 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 elemento restante en el dispositivo. Si el dispositivo se está distribuyendo actualmente, se informa el importe restante o cuál será el importe una vez que el dispositivo termine de dispensar.

amount Número

Importe restante

unit String

Unidad para el amount del atributo supported_units.

amountLastDispensed Objeto

Cantidad de ese artículo que expendió el dispositivo más recientemente. Si el dispositivo se está distribuyendo actualmente, debería indicar el importe que expendió antes de la cantidad actual.

amount Número

Importe restante

unit String

Unidad para el amount del atributo supported_units.

isCurrentlyDispensing Booleano

Indica si el dispositivo está expendiendo este artículo en este momento.

Ejemplos

¿Cuántos bocadillos para perros quedan en el dispensador?

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

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

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

¿Cuánta comida para gatos le di antes?

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

¿El grifo sigue expendiendo agua?

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

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

Se pueden proporcionar varios elementos en el array dispenseItems. Cada nombre de elemento debe ser único y debe corresponder a un elemento en el atributo supportedDispenseItems.

COMANDOS del dispositivo

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 controlar los intents EXECUTE, consulta Entrega de intents.

action.devices.commands.Dispense

Distribuye artículos.

Parámetros

La carga útil contiene uno de los siguientes elementos:

Distribuye por cantidad.

Parámetros Tipo Descripción
item String

Es el nombre del artículo que se expenderá, del atributo item_name.

amount Número

Obligatorio.

Importe que se enviará.

unit String

Obligatorio.

Unidad para el amount, del atributo supported_units.

Dispensar por ajuste predeterminado.

Parámetros Tipo Descripción
presetName String

Obligatorio.

Nombre del ajuste predeterminado que se expenderá, del atributo preset_name.

Distribuye 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"
  }
}

Llene el recipiente de agua del gato.

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

Extiende agua.

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

ERRORS de dispositivos

Consulta la lista completa de errores y excepciones.
  • dispenseAmountRemainingExceeded: El usuario intentó expender un artículo o una cantidad desde un dispositivo que no tiene suficiente cantidad.
  • dispenseAmountAboveLimit: El usuario intentó dispensar una cantidad que supera los límites de lo que puede solicitar en una sola consulta. De esta manera, se evita que se expida en exceso de forma accidental (por ejemplo, 500,000 tazas de agua).
  • dispenseAmountBelowLimit: El usuario intentó expender un artículo o una cantidad del dispositivo que está por debajo de la cantidad mínima que puede expender.
  • dispenseFractionalAmountNotSupported: El usuario intentó expender una cantidad fraccionaria de un artículo que el dispositivo no puede dividir (por ejemplo, los elementos contables, como golosinas para perros, pueden no ser divisibles por el dispositivo).
  • genericDispenseNotSupported: El usuario intenta expender desde un dispositivo sin especificar un elemento o ajuste predeterminado, pero el dispositivo no admite esa funcionalidad (por ejemplo, una acción de expende predeterminada).
  • dispenseUnitNotSupported: El usuario intenta expender desde un dispositivo con una unidad no compatible para ese caso (por ejemplo, no se proporcionó el artículo, por lo que se omitió supported_unit validation).
  • dispenseFractionalUnitNotSupported: El usuario intentó expender una cantidad fraccionaria de un artículo que se puede dividir, pero no para la unidad específica especificada (por ejemplo, un grifo puede dispensar 2.7 tazas, pero no 2.7 ml).
  • deviceCurrentlyDispensing: El usuario intenta expender un artículo, pero el dispositivo ya lo está expendiendo.
  • deviceClogged: El usuario intenta expender un artículo, pero el dispositivo está obstruido.
  • deviceBusy: Los usuarios intentan expender un artículo, pero el dispositivo está ocupado (genérico).

Excepciones del dispositivo

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

  • amountRemainingLow: El usuario entrega un artículo o una cantidad desde el dispositivo, lo que lleva el importe restante a un nivel bajo. Eres responsable de definir qué constituye un nivel "bajo".
  • userNeedsToWait: Ocurre cuando el usuario tiene que esperar antes de que se pueda suministrar correctamente el artículo o la cantidad solicitados (por ejemplo, un grifo expenderá agua caliente, pero el usuario debe esperar a que el agua se caliente antes de comenzar a dispensar).