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.

Schema del tratto di erogazione per la smart home

action.devices.traits.Dispense: questo attributo appartiene ai dispositivi che supportano la dispensazione di una quantità specificata di uno o più articoli fisici.

Questa funzionalità supporta anche l'erogazione di un preset, ad esempio una "ciotola per gatti" per una mangiatoia per animali domestici o un "bicchiere" per un rubinetto.

ATTRIBUTI del dispositivo

I dispositivi con questa caratteristica possono segnalare i seguenti attributi nell'ambito dell'operazione SYNC. Per scoprire di più sulla gestione degli intent SYNC, consulta Adempimento degli intent.

Attributi	Tipo	Descrizione
`supportedDispenseItems`	Array	Contiene informazioni su tutti gli articoli che il dispositivo può erogare.
`[item, ...]`	Oggetto	Elemento non necessario.
`item_name`	String	Obbligatorio. Nome interno dell'articolo erogato. Questo approccio può non essere intuitivo ed è condiviso tra tutte le lingue.
`item_name_synonyms`	Array	Obbligatorio. Nomi dei sinonimi per il farmaco dispensato in ogni lingua supportata.
`[item, ...]`	Oggetto	Nomi dei sinonimi per l'articolo erogato in una determinata lingua.
`synonyms`	Array	Obbligatorio. Nomi sinonimi dell'articolo distribuito. I sinonimi devono includere sia le forme singolari che quelle plurali, se applicabili. La prima stringa in questo elenco deve essere la forma plurale dell'elemento nella lingua in questione.
`[item, ...]`	String	Nome sinonimo
`lang`	String	Obbligatorio. Codice lingua (ISO 639-1). Vedi le lingue supportate.
`supported_units`	Array	Obbligatorio. Insieme 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 può essere erogata.
`amount`	Intero	Obbligatorio. Importo erogato.
`unit`	String	Obbligatorio. Unità erogata.
`supportedDispensePresets`	Array	Preimpostazioni supportate dal dispositivo.
`[item, ...]`	Oggetto	Preset.
`preset_name`	String	Obbligatorio. Nome interno del preset. Questo nome può non essere user-friendly ed è condiviso in tutte le lingue.
`preset_name_synonyms`	Array	Obbligatorio. Nomi dei sinonimi per la preimpostazione in ogni lingua supportata.
`[item, ...]`	Oggetto	Nomi dei sinonimi per il preset in una determinata lingua.
`synonyms`	Array	Obbligatorio. Nomi dei sinonimi per il preset. I sinonimi devono includere sia la forma singolare che quella plurale, se applicabile.
`[item, ...]`	String	Nome sinonimo
`lang`	String	Obbligatorio. Codice lingua (ISO 639-1). Consulta le lingue supportate.

Esempi

Dispenser d'acqua che supporta le unità per i liquidi con preset.

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

Distributore di cibo per animali domestici senza preset.

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

STATI del dispositivo

Le entità con questo attributo possono segnalare i seguenti stati nell'ambito dell'operazione QUERY. Per scoprire di più sulla gestione degli intent QUERY, consulta Adempimento degli intent.

Stati	Tipo	Descrizione
`dispenseItems`	Array	Stati degli articoli che il dispositivo può erogare.
`[item, ...]`	Oggetto	Stato di un determinato elemento.
`itemName`	String	Nome dell'elemento dall'attributo `item_name`.
`amountRemaining`	Oggetto	Quantità dell'articolo rimanente nel dispositivo. Se il dispositivo sta attualmente erogando l'acqua, verrà indicata la quantità rimanente o quale sarà la quantità al termine dell'erogazione.
`amount`	Number	Importo rimanente
`unit`	String	Unità per `amount` dall'attributo `supported_units`.
`amountLastDispensed`	Oggetto	Quantità di quell'articolo erogata dal dispositivo più di recente. Se il dispositivo sta erogando, dovrebbe indicare l'importo erogato prima dell'importo di erogazione corrente.
`amount`	Number	Importo rimanente
`unit`	String	Unità per `amount` dall'attributo `supported_units`.
`isCurrentlyDispensing`	Valore booleano	Indica se il dispositivo sta erogando questo articolo.

Esempi

Quanti bocconcini per cani sono rimasti nel mio dispenser?

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

Quanta acqua è rimasta nel mio refrigeratore d'acqua?

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

Quanto cibo 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 sta ancora erogando acqua?

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

amountRemaining e amountLastDispensed devono essere registrati solo utilizzando una unità di misura.

È possibile fornire più elementi all'interno dell'array dispenseItems. Ogni nome dell'elemento deve essere univoco e deve corrispondere a un elemento nell'attributo supportedDispenseItems.

COMANDI dispositivo

I dispositivi con questa caratteristica possono rispondere ai seguenti comandi nell'ambito dell'operazione EXECUTE. Per scoprire di più sulla gestione degli intent EXECUTE, consulta Adempimento degli intent.

`action.devices.commands.Dispense`

Distribuire gli articoli.

Parametri

Il payload contiene uno dei seguenti elementi:

Dispensa 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à 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à per amount, dall'attributo supported_units.

Erogazione in base al preset.

Parametri Tipo Descrizione

Parametri	Tipo	Descrizione
`presetName`	String	Obbligatorio. Nome del valore preimpostato da distribuire, dall'attributo `preset_name`.

presetName

String

Obbligatorio.

Nome del valore preimpostato da distribuire, dall'attributo preset_name.

Dispensa senza parametri.

Parametri	Tipo	Descrizione
Nessuna proprietà

Esempi

Dammi un bicchiere d'acqua.

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

Riempi la ciotola dell'acqua del gatto.

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

Versa l'acqua.

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

ERRORI dispositivo

Consulta l'elenco completo di errori ed eccezioni.

dispenseAmountRemainingExceeded: l'utente ha tentato di erogare un articolo o un importo da un dispositivo che non ha un importo sufficiente rimanente.
dispenseAmountAboveLimit: l'utente ha provato a erogare un importo superiore ai limiti di ciò che può chiedere in una singola query. Questo serve a evitare di erogare accidentalmente una quantità eccessiva (ad esempio 500.000 tazze di acqua).
dispenseAmountBelowLimit: l'utente ha provato a erogare un articolo o un importo dal dispositivo inferiore all'importo minimo che può erogare.
dispenseFractionalAmountNotSupported: l'utente ha provato a dispensare una quantità frazionaria di un articolo che il dispositivo non può suddividere (ad esempio, gli articoli conteggiabili come le crocchette per cani potrebbero non essere divisibile dal dispositivo).
genericDispenseNotSupported: l'utente tenta di erogare un prodotto da un dispositivo senza specificare un articolo o una preimpostazione, ma il dispositivo non supporta questa funzionalità (ad esempio un'azione di erogazione predefinita).
dispenseUnitNotSupported: l'utente tenta di erogare da un dispositivo con un'unità non supportata per quel caso (ad esempio, l'articolo non è stato fornito, quindi supported_unit validation è stato ignorato).
dispenseFractionalUnitNotSupported: l'utente ha tentato di erogare una quantità frazionaria di un articolo che può essere suddiviso, ma non per l'unità specifica 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 è già in funzione.
deviceClogged: gli utenti tentano di erogare un articolo, ma il dispositivo è intasato.
deviceBusy: l'utente tenta 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 articolo o un importo dal dispositivo, portando l'importo rimanente a un livello basso. È tua responsabilità definire cosa costituisce un livello "basso".
userNeedsToWait - Quando l'utente deve attendere prima che l'articolo o la quantità richiesta possa essere erogata correttamente (ad esempio, un rubinetto eroga acqua calda, ma l'utente deve attendere che l'acqua si riscaldi prima che inizi l'erogazione).