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

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

Esta característica también admite la distribución de un ajuste predeterminado, por ejemplo, un “tazón de comida para gatos” para un comedero para mascotas o un “vidrio” 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 el manejo de intents SYNC, consulta Entrega de intents.

Atributos Tipo Descripción
supportedDispenseItems Matriz

Contiene información sobre todos los artículos que el dispositivo puede dispensar.

[item, ...] Objeto

Artículo desechable.

item_name String

Obligatorio.

Es el nombre interno del artículo distribuido. Esto puede ser poco fácil de usar y se comparte en todos los idiomas.

item_name_synonyms Matriz

Obligatorio.

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

[item, ...] Objeto

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

synonyms Matriz

Obligatorio.

Son nombres de sinónimos del artículo dispensado. Los sinónimos deben incluir formas singulares y plurales, si corresponde. La primera string de esta lista debe ser la forma plural del elemento en ese idioma.

[item, ...] String

Nombre del sinónimo

lang String

Obligatorio.

Código de idioma (ISO 639-1). Consulta los idiomas compatibles.

supported_units Matriz

Obligatorio.

Es el conjunto de unidades que admite el dispositivo 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 típico del artículo que se puede expender.

amount Número entero

Obligatorio.

Importe distribuido.

unit String

Obligatorio.

Unidad dispensada.

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 del ajuste predeterminado en cada idioma admitido.

[item, ...] Objeto

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

synonyms Matriz

Obligatorio.

Nombres de sinónimos del ajuste predeterminado. Los sinónimos deben incluir formas singulares y plurales, si corresponde.

[item, ...] String

Nombre del sinónimo

lang String

Obligatorio.

Código de idioma (ISO 639-1). Consulta 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 alimentos 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 el manejo de intents QUERY, consulta Entrega de intents.

Estados Tipo Descripción
dispenseItems Matriz

Estados de los artículos que el dispositivo puede dispensar.

[item, ...] Objeto

Es el estado de un elemento determinado.

itemName String

Es el nombre del artículo del atributo item_name.

amountRemaining Objeto

Cantidad restante de ese elemento en el dispositivo. Si el dispositivo se está expendiendo, se informará el importe restante o cuál será el importe una vez que el dispositivo termine de hacerlo.

amount Número

Importe restante

unit String

Unidad para amount del atributo supported_units.

amountLastDispensed Objeto

Indica la cantidad de ese artículo que el dispositivo entregó más recientemente. Si el dispositivo está expendiendo el contenido, este deberá informar la cantidad que se usó antes de la dosificación actual.

amount Número

Importe restante

unit String

Unidad para amount del atributo supported_units.

isCurrentlyDispensing Booleano

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

Ejemplos

¿Cuántos dulces para perros hay en 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 de gato te dije antes?

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

¿El grifo sigue dispensando agua?

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

amountRemaining y amountLastDispensed solo se deben informar con una unidad de medida.

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

Dispositivo COMMANDS

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 el manejo de intents EXECUTE, consulta Entrega de intents.

action.devices.commands.Dispense

Dispensar artículos.

Parámetros

La carga útil contiene una de las siguientes opciones:

Dispensar por importe.

Parámetros Tipo Descripción
item String

Es el nombre del artículo que se distribuirá desde el 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 dispensará, 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 del gato.

{
  "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 desde un dispositivo que no tiene suficiente cantidad restante.
  • dispenseAmountAboveLimit: El usuario intentó entregar un importe que está fuera de los límites de lo que puede solicitar en una sola consulta. Esto es para evitar dispensar una cantidad excesiva (por ejemplo, 500,000 tazas de agua).
  • dispenseAmountBelowLimit: El usuario intentó entregar un artículo o una cantidad desde el dispositivo que está por debajo de la cantidad mínima que puede entregar.
  • dispenseFractionalAmountNotSupported: El usuario intentó dispensar una cantidad fraccionaria de un elemento que el dispositivo no puede dividir (por ejemplo, el dispositivo no puede dividir los artículos contables, como golosinas para perros).
  • genericDispenseNotSupported: El usuario intenta dispensar un dispositivo sin especificar un artículo o ajuste predeterminado, pero el dispositivo no admite esa funcionalidad (por ejemplo, una acción predeterminada de distribución).
  • dispenseUnitNotSupported: El usuario intenta dispensar un dispositivo con una unidad no compatible en ese caso (por ejemplo, no se proporcionó el elemento, por lo que se omitió supported_unit validation).
  • dispenseFractionalUnitNotSupported: El usuario intentó dispensar una cantidad fraccionaria de un artículo que se puede dividir, pero no para la unidad específica especificada (por ejemplo, un grifo puede expender 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 entregar un artículo, pero el dispositivo está ocupado (genérico).

Dispositivo EXCEPCIONES

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

  • amountRemainingLow: El usuario distribuye un elemento o una cantidad desde el 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 antes de que la cantidad o el artículo solicitado se distribuya correctamente (por ejemplo, un grifo dispensará agua caliente, pero el usuario deberá esperar a que se caliente antes de comenzar a hacerlo).