Te damos la bienvenida al Developer Center de Google Home, el nuevo destino para aprender a desarrollar acciones de la casa inteligente.

Se usó la API de Cloud Translation para traducir esta página.

Esquema de atributos de dispensación de la casa inteligente

action.devices.traits.Dispense: Este atributo pertenece a los dispositivos que admiten la dispensación de una cantidad especificada de uno o más artículos físicos.

Esta función también admite la entrega de un valor predeterminado, por ejemplo, un “plato de comida para gatos” para un alimentador de 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 controlar intents SYNC, consulta Cómo entregar intents.

Atributos	Tipo	Descripción
`supportedDispenseItems`	Matriz	Contiene información sobre todos los artículos que puede dispensar el dispositivo.
`[item, ...]`	Objeto	Elemento prescindible.
`item_name`	String	Obligatorio. Es el nombre interno del artículo dispensado. Esto puede no ser fácil de usar y se comparte en todos los idiomas.
`item_name_synonyms`	Matriz	Obligatorio. Son los nombres de los sinónimos para los medicamentos dispensados en cada idioma admitido.
`[item, ...]`	Objeto	Son nombres de sinónimos para el artículo dispensado en un idioma determinado.
`synonyms`	Matriz	Obligatorio. Son nombres sinónimos para el artículo dispensado. Los sinónimos deben incluir las formas singular y plural, si corresponde. La primera cadena 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 admitidos.
`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. Es la cantidad típica del artículo que se puede dispensar.
`amount`	Número entero	Obligatorio. Importe dispensado
`unit`	String	Obligatorio. Unidad dispensada.
`supportedDispensePresets`	Matriz	Los parámetros preestablecidos compatibles con el dispositivo
`[item, ...]`	Objeto	Ajuste predeterminado.
`preset_name`	String	Obligatorio. Es el nombre interno del parámetro de configuración predeterminado. Este nombre puede no ser fácil de usar y se comparte en todos los idiomas.
`preset_name_synonyms`	Matriz	Obligatorio. Son los nombres de sinónimos para el parámetro predeterminado en cada idioma admitido.
`[item, ...]`	Objeto	Son nombres de sinónimos para el parámetro predeterminado en un idioma determinado.
`synonyms`	Matriz	Obligatorio. Nombres de sinónimos del ajuste predeterminado. Los sinónimos deben incluir las formas singular y plural, si corresponde.
`[item, ...]`	String	Nombre del sinónimo
`lang`	String	Obligatorio. Código de idioma (ISO 639-1). Consulta los idiomas admitidos.

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 este atributo pueden informar los siguientes estados como parte de la operación QUERY. Para obtener más información sobre cómo controlar intents QUERY, consulta Cómo entregar 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 restante en el dispositivo de ese artículo. Si el dispositivo está inyectando, se informa el importe restante o cuál será el importe una vez que el dispositivo termine de emitirlo.
`amount`	Número	Importe restante
`unit`	String	Es la unidad para el `amount` del atributo `supported_units`.
`amountLastDispensed`	Objeto	Es la cantidad de ese artículo que el dispositivo dispensó más recientemente. Si el dispositivo está dispensando el dispositivo actualmente, se debería informar el importe que expendió antes del importe de dispensació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ántas golosinas 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 el enfriador?

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

¿Cuánta comida para gatos di antes?

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

¿Todavía se está expendiendo agua del grifo?

{
  "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 del 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 intents EXECUTE, consulta Cómo entregar intents.

`action.devices.commands.Dispense`

Dispensa artículos.

Parámetros

La carga útil contiene una de las siguientes opciones:

Dispensar por importe

Parámetros Tipo Descripción

Parámetros	Tipo	Descripción
`item`	String	Es el nombre del artículo que se debe dispensar, del atributo `item_name`.
`amount`	Número	Obligatorio. Es el importe que se debe dispensar.
`unit`	String	Obligatorio. Unidad para `amount`, del atributo `supported_units`.

item

String

Es el nombre del artículo que se debe dispensar, del atributo item_name.

amount

Número

Obligatorio.

Es el importe que se debe dispensar.

unit

String

Obligatorio.

Unidad para amount, del atributo supported_units.

Distribución por ajuste predeterminado.

Parámetros Tipo Descripción

Parámetros	Tipo	Descripción
`presetName`	String	Obligatorio. Es el nombre del ajuste predeterminado que se dispensará, del atributo `preset_name`.

presetName

String

Obligatorio.

Es el nombre del ajuste predeterminado que se dispensará, del atributo preset_name.

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

Distribuir agua.

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

ERRORES DE DISPOSITIVO

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 restante.
dispenseAmountAboveLimit: El usuario intentó dispensar una cantidad que superaba los límites de lo que puede solicitar en una sola consulta. De esta manera, se evita que se expulse una cantidad excesiva por accidente (por ejemplo, 500,000 tazas de agua).
dispenseAmountBelowLimit: El usuario intentó dispensar un artículo o un importe del dispositivo que es inferior al importe mínimo que puede dispensar.
dispenseFractionalAmountNotSupported: El usuario intentó dispensar una cantidad fraccionaria de un elemento que el dispositivo no puede dividir (por ejemplo, es posible que los elementos contables, como las golosinas para perros, no sean divisibles por el dispositivo).
genericDispenseNotSupported: El usuario intenta dispensar desde un dispositivo sin especificar un artículo o un valor predeterminado, pero el dispositivo no admite esa funcionalidad (por ejemplo, una acción de dispensación predeterminada).
dispenseUnitNotSupported: El usuario intenta dispensar desde un dispositivo con una unidad que no se admite para ese caso (por ejemplo, no se proporciona el artículo, 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 dispensar 2.7 tazas, pero no 2.7 mL).
deviceCurrentlyDispensing: Los usuarios intentan dispensar un artículo, pero el dispositivo ya está dispensando.
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).

EXCLUSIONES de dispositivos

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

amountRemainingLow: El usuario expende un artículo o una cantidad desde el dispositivo, lo que lleva la cantidad restante a un nivel bajo. Eres responsable de definir qué se considera un nivel "bajo".
userNeedsToWait: Cuando el usuario debe esperar antes de que se pueda dispensar correctamente el artículo o la cantidad solicitados (por ejemplo, un grifo dispensará agua caliente, pero el usuario debe esperar a que el agua se caliente antes de que comience a dispensarla).