Este é o Centro para Desenvolvedores do Google Home, o novo destino para aprender a desenvolver ações de casa inteligente.

Esta página foi traduzida pela API Cloud Translation.

Esquema de traços de distribuição para casas inteligentes

action.devices.traits.Dispense: essa característica pertence a dispositivos que oferecem suporte à dispensação de uma quantidade especificada de um ou mais itens físicos.

Essa característica também oferece suporte à dispensação de uma predefinição, por exemplo, como uma "tigela de ração para gatos" para um comedouro para animais de estimação ou um "copo" para uma torneira.

ATRIBUTOS do dispositivo

Dispositivos com essa característica podem informar os seguintes atributos como parte da operação SYNC. Para saber mais sobre o processamento de intents SYNC, consulte Fulfillment de intents.

Atributos	Tipo	Descrição
`supportedDispenseItems`	Array	Contém informações sobre todos os itens que o dispositivo pode dispensar.
`[item, ...]`	Object	Item dispensável.
`item_name`	String	Obrigatório. Nome interno do item dispensado. Isso pode não ser fácil de usar e é compartilhado em todos os idiomas.
`item_name_synonyms`	Array	Obrigatório. Nomes de sinônimos para o dispensado em cada idioma com suporte.
`[item, ...]`	Object	Nomes de sinônimos para o item dispensado em um determinado idioma.
`synonyms`	Array	Obrigatório. Nomes de sinônimos para o item dispensado. Os sinônimos precisam incluir as formas singular e plural, se aplicável. A primeira string da lista precisa ser a forma plural do item nesse idioma.
`[item, ...]`	String	Nome do sinônimo
`lang`	String	Obrigatório. Código do idioma (ISO 639-1). Consulte os idiomas aceitos.
`supported_units`	Array	Obrigatório. Conjunto de unidades com suporte do dispositivo para esse item.
`[item, ...]`	String	Unidades aceitas. Valores aceitos: `CENTIMETERS` `CUPS` `DECILITERS` `FLUID_OUNCES` `GALLONS` `GRAMS` `KILOGRAMS` `LITERS` `MILLIGRAMS` `MILLILITERS` `MILLIMETERS` `NO_UNITS` `OUNCES` `PINCH` `PINTS` `PORTION` `POUNDS` `QUARTS` `TABLESPOONS` `TEASPOONS`
`default_portion`	Object	Obrigatório. Quantidade típica do item que pode ser dispensado.
`amount`	Número inteiro	Obrigatório. Valor dispensado.
`unit`	String	Obrigatório. Unidade dispensada.
`supportedDispensePresets`	Array	Predefinições compatíveis com o dispositivo.
`[item, ...]`	Object	Predefinição.
`preset_name`	String	Obrigatório. Nome interno da predefinição. Esse nome pode não ser amigável ao usuário e é compartilhado em todos os idiomas.
`preset_name_synonyms`	Array	Obrigatório. Nomes de sinônimos para a predefinição em cada idioma com suporte.
`[item, ...]`	Object	Nomes de sinônimos para a predefinição em um determinado idioma.
`synonyms`	Array	Obrigatório. Nomes de sinônimos para a predefinição. Os sinônimos precisam incluir as formas singular e plural, se aplicável.
`[item, ...]`	String	Nome do sinônimo
`lang`	String	Obrigatório. Código do idioma (ISO 639-1). Consulte os idiomas aceitos.

Exemplos

Dispenser de água compatível com unidades de líquidos com predefinições.

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

Dispenser de ração para animais de estimação sem predefinições.

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

ESTADOS DO DISPOSITIVO

As entidades com essa característica podem informar os seguintes estados como parte da operação QUERY. Para saber mais sobre o processamento de intents QUERY, consulte Fulfillment de intents.

Estados	Tipo	Descrição
`dispenseItems`	Array	Estados dos itens que o dispositivo pode dispensar.
`[item, ...]`	Object	Estado de um determinado item.
`itemName`	String	Nome do item do atributo `item_name`.
`amountRemaining`	Object	Quantidade do item restante no dispositivo. Se o dispositivo estiver dispensando, ele vai informar o valor restante ou o valor que será quando o dispositivo terminar a dispensação.
`amount`	Número	Valor restante
`unit`	String	Unidade do `amount` do atributo `supported_units`.
`amountLastDispensed`	Object	Quantidade do item que o dispositivo distribuiu mais recentemente. Se o dispositivo estiver dispensando, ele vai informar o valor dispensado antes do valor atual.
`amount`	Número	Valor restante
`unit`	String	Unidade do `amount` do atributo `supported_units`.
`isCurrentlyDispensing`	Booleano	Indica se o dispositivo está dispensando esse item.

Exemplos

Quantas guloseimas para cães ainda restam no meu dispensador?

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

Quanta água resta no meu bebedouro?

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

Quanta ração para gatos eu dava antes?

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

A torneira ainda está liberando água?

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

amountRemaining e amountLastDispensed só precisam ser informados usando uma unidade de medida.

É possível fornecer vários itens na matriz dispenseItems. Cada nome de item precisa ser exclusivo e corresponder a um item no atributo supportedDispenseItems.

COMANDOS do dispositivo

Dispositivos com essa característica podem responder aos comandos a seguir como parte da operação EXECUTE. Para saber mais sobre o processamento de intents EXECUTE, consulte Fulfillment de intents.

`action.devices.commands.Dispense`

Dispensar itens.

Parâmetros

O payload contém uma das seguintes opções:

Dispensar por valor.

Parâmetros Tipo Descrição

Parâmetros	Tipo	Descrição
`item`	String	Nome do item a ser dispensado, do atributo `item_name`.
`amount`	Número	Obrigatório. Quantidade a ser dispensada.
`unit`	String	Obrigatório. Unidade do `amount`, do atributo `supported_units`.

item

String

Nome do item a ser dispensado, do atributo item_name.

amount

Número

Obrigatório.

Quantidade a ser dispensada.

unit

String

Obrigatório.

Unidade do amount, do atributo supported_units.

Dispensar por predefinição.

Parâmetros Tipo Descrição

Parâmetros	Tipo	Descrição
`presetName`	String	Obrigatório. Nome da predefinição a ser dispensada, do atributo `preset_name`.

presetName

String

Obrigatório.

Nome da predefinição a ser dispensada, do atributo preset_name.

Dispense sem parâmetros.

Parâmetros	Tipo	Descrição
Não há propriedades

Exemplos

Me dê uma xícara de água.

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

Encha o pratinho de água do gato.

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

Dispense água.

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

ERROS no dispositivo

Confira a lista completa de erros e exceções.

dispenseAmountRemainingExceeded: o usuário tentou dispensar um item ou valor de um dispositivo que não tem valor suficiente restante.
dispenseAmountAboveLimit: o usuário tentou dispensar um valor que está além dos limites do que pode ser solicitado em uma única consulta. Isso evita que uma quantidade excessiva seja dispensada acidentalmente (por exemplo, 500.000 xícaras de água).
dispenseAmountBelowLimit: o usuário tentou liberar um item ou uma quantidade do dispositivo que está abaixo da quantidade mínima que ele pode distribuir.
dispenseFractionalAmountNotSupported: o usuário tentou dispensar uma quantidade fracionária de um item que o dispositivo não pode dividir (por exemplo, itens contáveis, como petiscos para cães, não podem ser divididos pelo dispositivo).
genericDispenseNotSupported: o usuário tenta dispensar um dispositivo sem especificar um item ou predefinição, mas o dispositivo não oferece suporte a essa funcionalidade (por exemplo, uma ação de dispensação padrão).
dispenseUnitNotSupported: o usuário tenta dispensar de um dispositivo com uma unidade que não tem suporte para esse caso (por exemplo, o item não é fornecido, então supported_unit validation foi ignorado).
dispenseFractionalUnitNotSupported: o usuário tentou dispensar uma quantidade fracionária de um item que pode ser dividido, mas não para a unidade específica especificada (por exemplo, uma torneira pode dispensar 2,7 xícaras, mas não 2,7 ml).
deviceCurrentlyDispensing: os usuários tentam dispensar um item, mas o dispositivo já está dispensando.
deviceClogged: os usuários tentam dispensar um item, mas o dispositivo está entupido.
deviceBusy: os usuários tentam dispensar um item, mas o dispositivo está ocupado (genérico).

EXCEÇÕES de dispositivos

Essas exceções podem ser informadas como exceptionCode no objeto states da sua resposta:

amountRemainingLow: o usuário dispensa um item ou valor do dispositivo, diminuindo o valor restante. Você é responsável por definir o que constitui um nível "baixo".
userNeedsToWait: quando o usuário precisa esperar até que o item ou a quantidade solicitada possa ser dispensado. Por exemplo, uma torneira libera água quente, mas o usuário precisa esperar a água esquentar antes de começar a dispensar.