Ti diamo il benvenuto nel Centro sviluppatori Google Home, la nuova destinazione per scoprire come sviluppare azioni per la smart home. Nota: continuerai a creare azioni nella console di Actions.

Questa pagina è stata tradotta dall'API Cloud Translation.

Switch to English

Schema delle funzionalità di domotica smart

action.devices.traits.Dispense: questo tratto appartiene ai dispositivi che supportano l'erogazione di una o più quantità specifiche di uno o più articoli fisici.

Questa caratteristica supporta anche l'erogazione di una preimpostazione, ad esempio come "ciotola per gatti" per un alimentatore per animali domestici o come "vetro" per un rubinetto.

ATTRIBUTE dispositivo

I dispositivi con questo trattino potrebbero segnalare i seguenti attributi come parte dell'operazione SYNC. Per saperne di più sulla gestione degli intent SYNC, consulta la sezione fulfillment di intent.

Attributi	Tipo	Descrizione
`supportedDispenseItems`	Array	Contiene informazioni su tutti gli elementi che il dispositivo può erogare.
`[item, ...]`	Oggetto	Articolo dispensabile.
`item_name`	String	Obbligatorio. Nome interno dell'articolo erogatore. Questa opzione può essere ottimizzata per gli utenti e viene condivisa in tutte le lingue.
`item_name_synonyms`	Array	Obbligatorio. Sinonimi di nomi assegnati in ogni lingua supportata.
`[item, ...]`	Oggetto	Sinonimi di nomi di articoli distribuiti in una determinata lingua.
`synonyms`	Array	Obbligatorio. Nomi dei sinonimi dell'articolo erogatore. Le sinomi devono includere forme singolari e plurali, se applicabili. La prima stringa di questo elenco deve essere la forma plurale dell'elemento in quella lingua.
`[item, ...]`	String	Nome sinonimo
`lang`	String	Obbligatorio. Codice lingua (ISO 639-1). Scopri le lingue supportate.
`supported_units`	Array	Obbligatorio. Set di unità supportate dal dispositivo per l'elemento.
`[item, ...]`	String	Unità supportate. Valori supportati: `CENTIMETERS` `CUPS` `DECILITERS` `FLUID_OUNCES` `GALLONS` `GRAMS` `KILOGRAMS` `LITERS` `MILLIGRAMS` `MILLILITERS` `MILLIMETERS` `NO_UNITS` `OUNCES` `PINCH` `PINTS` `PORTION` `POUNDS` `QUARTS` `TABLESPOONS` `TEASPOONS`
`default_portion`	Oggetto	Obbligatorio. Quantità tipica dell'articolo che potrebbe essere erogato.
`amount`	Intero	Obbligatorio. Importo erogato.
`unit`	String	Obbligatorio. Unità di erogazione.
`supportedDispensePresets`	Array	Preimpostazioni supportate dal dispositivo.
`[item, ...]`	Oggetto	Preimpostato.
`preset_name`	String	Obbligatorio. Nome interno della preimpostazione. Questo nome non è facile da usare e viene condiviso in tutte le lingue.
`preset_name_synonyms`	Array	Obbligatorio. Nomi dei sinonimi per la preimpostazione in ogni lingua supportata.
`[item, ...]`	Oggetto	Nomi di sinonimi per la preimpostazione in una determinata lingua.
`synonyms`	Array	Obbligatorio. Nomi di sinonimi per la preimpostazione. I sinonimi devono includere forme singolari e plurali, se applicabili.
`[item, ...]`	String	Nome sinonimo
`lang`	String	Obbligatorio. Codice lingua (ISO 639-1). Scopri le lingue supportate.

Esempi

Erogatore di acqua che supporta le unità per i liquidi con preimpostazioni.

{
  "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 per animali domestici senza preimpostazioni.

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

STATO dispositivo

Le entità con questa caratteristica possono segnalare i seguenti stati nell'ambito dell'operazione QUERY, Per saperne di più sulla gestione degli intent QUERY, consulta la sezione fulfillment di intent.

Stati	Tipo	Descrizione
`dispenseItems`	Array	Stati degli articoli che il dispositivo può erogare.
`[item, ...]`	Oggetto	Lo stato di un determinato articolo.
`itemName`	String	Nome dell'articolo dall'attributo `item_name`.
`amountRemaining`	Oggetto	Importo rimanente dell'articolo nel dispositivo. Se il dispositivo sta erogando un prodotto, viene registrato l'importo rimanente o l'importo che verrà erogato al termine dell'erogazione.
`amount`	Number	Importo rimanente
`unit`	String	Unità di misura per `amount` dall'attributo `supported_units`.
`amountLastDispensed`	Oggetto	Quantità dell'articolo erogato il dispositivo più di recente. Se il dispositivo sta erogando prodotti, è necessario segnalare l'importo erogato prima di quello attuale.
`amount`	Number	Importo rimanente
`unit`	String	Unità di misura per `amount` dall'attributo `supported_units`.
`isCurrentlyDispensing`	Booleano	Indica se il dispositivo sta erogando questo articolo.

Esempi

Quanti croccantini rimangono nel dispenser?

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

Quanta acqua rimane nel mio refrigeratore?

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

Quanti alimenti per gatti ho dato prima?

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

Il rubinetto eroga ancora acqua?

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

amountRemaining e amountLastDispensed devono essere segnalati solo utilizzando un'unità di misura.

È possibile specificare più elementi nell'array di dispenseItems. Il nome di ogni articolo deve essere univoco e corrispondere a un articolo dell'attributo supportedDispenseItems.

COMANDI dispositivo

I dispositivi con questo trattino potrebbero rispondere ai seguenti comandi nell'ambito dell'operazione EXECUTE. Per saperne di più sulla gestione degli intent EXECUTE, consulta la sezione fulfillment di intent.

`action.devices.commands.Dispense`

Erogazione di articoli.

Parametri

Il payload contiene uno dei seguenti valori:

Eroga in base all'importo.

Parametri Tipo Descrizione

Parametri	Tipo	Descrizione
`item`	String	Nome dell'articolo da erogare dall'attributo `item_name`.
`amount`	Number	Obbligatorio. Importo da erogare.
`unit`	String	Obbligatorio. Unità di misura per `amount`, dall'attributo `supported_units`.

item

String

Nome dell'articolo da erogare dall'attributo item_name.

amount

Number

Obbligatorio.

Importo da erogare.

unit

String

Obbligatorio.

Unità di misura per amount, dall'attributo supported_units.

Eroga per preimpostazione.

Parametri Tipo Descrizione

Parametri	Tipo	Descrizione
`presetName`	String	Obbligatorio. Nome della preimpostazione da erogare dall'attributo `preset_name`.

presetName

String

Obbligatorio.

Nome della preimpostazione da erogare dall'attributo preset_name.

Dosatore senza parametri.

Parametri	Tipo	Descrizione
Nessuna proprietà

Esempi

Dammi 1 tazza d'acqua.

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

Riempi la ciotola del gatto.

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

Erogazione di acqua.

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

ERRORI del dispositivo

Consulta l'elenco completo degli errori e delle eccezioni.

dispenseAmountRemainingExceeded: l'utente ha tentato di erogare un elemento o un importo da un dispositivo che non dispone di importo sufficiente.
dispenseAmountAboveLimit: l'utente ha tentato di erogare un'importo superiore ai limiti di ciò che può chiedere in una singola query. Questo per evitare di erogare accidentalmente una quantità eccessiva (ad esempio, 500.000 tazze d'acqua).
dispenseAmountBelowLimit: l'utente ha tentato di erogare dal dispositivo un importo o un importo inferiore all'importo minimo che può erogare.
dispenseFractionalAmountNotSupported: l'utente ha tentato di erogare una quantità frazionata di un elemento che il dispositivo non può dividere (ad esempio, gli elementi conteggiabili come i cibo per cani potrebbero non essere divisibili per il dispositivo).
genericDispenseNotSupported: l'utente cerca di erogare un dispositivo da un dispositivo senza specificare un elemento o un preset, ma il dispositivo non supporta questa funzionalità (ad esempio, un'azione di erogazione predefinita).
dispenseUnitNotSupported: l'utente cerca di erogare da un dispositivo con un'unità non supportata per il caso (ad esempio, l'articolo non è fornito, pertanto supported_unit validation è stato ignorato).
dispenseFractionalUnitNotSupported: l'utente ha tentato di erogare una quantità frazionata di un articolo che può essere suddiviso, ma non per l'unità specificata (ad esempio, un rubinetto potrebbe essere in grado di erogare 2,7 tazze ma non 2,7 ml).
deviceCurrentlyDispensing: l'utente tenta di erogare un articolo, ma il dispositivo lo sta già facendo.
deviceClogged: l'utente tenta di erogare un articolo, ma il dispositivo è intasato.
deviceBusy: l'utente cerca di erogare un articolo, ma il dispositivo è occupato (generico).

ECCEZIONI DEL Dispositivo

Queste eccezioni possono essere segnalate come exceptionCode nell'oggetto states della risposta:

amountRemainingLow: l'utente eroga un dispositivo o un importo dal dispositivo e, in questo modo, porta la quantità rimanente a un livello basso. Sei responsabile della definizione di ciò che costituisce un livello "basso".
userNeedsToWait - Quando l'utente deve attendere prima di poter erogare correttamente l'articolo o l'importo richiesto (ad esempio, un rubinetto eroga acqua calda, ma l'utente deve attendere che l'acqua si riscaldi prima che inizi l'erogazione).