Te damos la bienvenida al Centro para desarrolladores de Google Home, el nuevo destino para aprender a desarrollar acciones de casa inteligente. Nota: Seguirás compilando acciones en la Consola de Actions.

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

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

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`.

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

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

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).