Esta página foi traduzida pela API Cloud Translation.

Esquema de características de distribuição inteligente de casas

action.devices.traits.Dispense: essa característica pertence a dispositivos compatíveis com a liberação de uma quantidade especificada de um ou mais itens físicos.

Essa característica também oferece suporte à distribuiçã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 "vidro" 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 como processar intents SYNC, consulte fulfillment de intent.

Atributos	Tipo	Descrição
`supportedDispenseItems`	Array	Contém informações sobre todos os itens que o dispositivo pode distribuir.
`[item, ...]`	Object	Item dispensável.
`item_name`	String	Obrigatório. Nome interno do item dispensado. Ele não é muito fácil de usar e é compartilhado em todos os idiomas.
`item_name_synonyms`	Array	Obrigatório. Sinônimos para os dispensados em cada idioma compatível.
`[item, ...]`	Object	Sinônimos para o item dispensado em um determinado idioma.
`synonyms`	Array	Obrigatório. Nomes de sinônimos do item dispensado. Os sinomamas devem incluir formas singular e plural, se aplicável. A primeira string dessa lista precisa ser a forma plural do item nesse idioma.
`[item, ...]`	String	Nome de sinônimo
`lang`	String	Obrigatório. Código do idioma (ISO 639-1). Consulte os idiomas compatíveis.
`supported_units`	Array	Obrigatório. Conjunto de unidades compatíveis com o dispositivo para o item.
`[item, ...]`	String	Unidades aceitas. Os valores suportados são: `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. Valor típico do item que pode ser distribuído.
`amount`	Número inteiro	Obrigatório. Valor liberado
`unit`	String	Obrigatório. Unidade liberada.
`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 não é fácil de usar e é compartilhado em todos os idiomas.
`preset_name_synonyms`	Array	Obrigatório. Nomes de sinônimos da predefinição em cada idioma com suporte.
`[item, ...]`	Object	São nomes de sinônimos da predefinição em um determinado idioma.
`synonyms`	Array	Obrigatório. Nomes de sinônimos da predefinição. Os sinônimos precisam incluir os formatos singular e plural, se aplicável.
`[item, ...]`	String	Nome de sinônimo
`lang`	String	Obrigatório. Código do idioma (ISO 639-1). Consulte os idiomas compatíveis.

Exemplos

Sistema de distribuição de água com suporte a unidades para 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"
          ]
        }
      ]
    }
  ]
}

Contador de alimentos 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"
      }
    }
  ]
}

STATES do dispositivo

Entidades com essa característica podem relatar os estados a seguir como parte da operação QUERY. Para saber mais sobre como processar intents QUERY, consulte fulfillment de intent.

Estados	Tipo	Descrição
`dispenseItems`	Array	Estados dos itens que o dispositivo pode distribuir.
`[item, ...]`	Object	Estado de um determinado item.
`itemName`	String	Nome do item do atributo `item_name`.
`amountRemaining`	Object	Valor desse item restante no dispositivo. Se o dispositivo estiver dispensando no momento, isso informará a quantidade restante ou quanto será o valor após o dispositivo ser dispensado.
`amount`	Número	Valor restante
`unit`	String	Unidade para a `amount` do atributo `supported_units`.
`amountLastDispensed`	Object	Quantidade do item dispensado mais recentemente pelo dispositivo. Se o dispositivo estiver liberando ele no momento, deverá informar a quantidade antes da liberação atual.
`amount`	Número	Valor restante
`unit`	String	Unidade para a `amount` do atributo `supported_units`.
`isCurrentlyDispensing`	Booleano	Indica se o dispositivo está liberando este item no momento.

Exemplos

Quantos petiscos os cachorros vão ter no meu dispenser?

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

Quanto falta de água no refrigerador de água?

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

Quantos alimentos para gatos eu dei 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 informadas usando uma unidade de medida.

Vários itens podem ser fornecidos 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 seguintes comandos como parte da operação EXECUTE. Para saber mais sobre como processar intents EXECUTE, consulte fulfillment de intent.

`action.devices.commands.Dispense`

Distribua itens.

Parâmetros

O payload contém um dos seguintes itens:

Distribua por quantidade.

Parâmetros Tipo Descrição

Parâmetros	Tipo	Descrição
`item`	String	Nome do item a ser descartado, do atributo `item_name`.
`amount`	Número	Obrigatório. Valor a ser distribuído.
`unit`	String	Obrigatório. Unidade para a `amount` do atributo `supported_units`.

item

String

Nome do item a ser descartado, do atributo item_name.

amount

Número

Obrigatório.

Valor a ser distribuído.

unit

String

Obrigatório.

Unidade para a amount do atributo supported_units.

Dispense por padrã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 parâmetros.

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

Exemplos

Me dê um copo de água.

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

Preencha o pote de água do gato.

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

Água de distribuição.

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

Dispositivo ERRORS

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

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

EXCEÇÕES DE DISPOSITIVOS

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

amountRemainingLow: o usuário dispensa um item ou valor do dispositivo, o que reduz o valor restante. Você é responsável por definir o que constitui um nível "baixo".
userNeedsToWait: quando o usuário precisa esperar antes que o item ou o valor solicitado seja liberado (por exemplo, uma torneira libera água quente, mas o usuário precisa esperar o aquecimento da água antes de começar a receber).