Ti diamo il benvenuto nel Centro sviluppatori Google Home, la nuova destinazione per imparare a sviluppare azioni per la smart home. Nota:continuerai a creare azioni nella Console Actions.
Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Schema trattino smart Home

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

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

ATTRIBUTE del dispositivo

I dispositivi con questa caratteristica potrebbero segnalare i seguenti attributi come parte dell'operazione SYNC. Per scoprire di più sulla gestione degli intent SYNC, consulta Soddisfazione degli intent.

Attributi Tipo Descrizione
supportedDispenseItems Array

Contiene informazioni su tutti gli articoli che il dispositivo può erogare.

[item, ...] Oggetto

Dosatore.

item_name Stringa

Obbligatorio.

Nome interno dell'articolo erogato. Questa classe non è facile da usare e viene condivisa in tutte le lingue.

item_name_synonyms Array

Obbligatorio.

Sinonimi che indicano l'erogazione in ogni lingua supportata.

[item, ...] Oggetto

Sinonimi di nomi dell'articolo erogato in una determinata lingua.

synonyms Array

Obbligatorio.

Nomi di sinonimi dell'articolo erogato. Le sinomi dovrebbero includere sia la forma singolare che quella plurale, se applicabile. La prima stringa dell'elenco deve essere la forma al plurale dell'elemento in quella lingua.

[item, ...] Stringa

Nome del sinonimo

lang Stringa

Obbligatorio.

Codice lingua (ISO 639-1). Scopri le lingue supportate.

supported_units Array

Obbligatorio.

Insieme di unità supportate dal dispositivo per quell'elemento.

[item, ...] Stringa

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

amount Intero

Obbligatorio.

Importo erogato.

unit Stringa

Obbligatorio.

Unità erogata.

supportedDispensePresets Array

Preimpostazioni supportate dal dispositivo.

[item, ...] Oggetto

Predefinito.

preset_name Stringa

Obbligatorio.

Nome interno della preimpostazione. Questo nome non è facile da usare ed è condiviso in tutte le lingue.

preset_name_synonyms Array

Obbligatorio.

Nomi di 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 al plurale e al singolare, se applicabili.

[item, ...] Stringa

Nome del sinonimo

lang Stringa

Obbligatorio.

Codice lingua (ISO 639-1). Scopri le lingue supportate.

Esempi

Distributore d'acqua che supporta le unità per 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"
          ]
        }
      ]
    }
  ]
}

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

STATEs dispositivo

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

Stati Tipo Descrizione
dispenseItems Array

Stati degli articoli che il dispositivo può erogare.

[item, ...] Oggetto

Stato di un determinato elemento.

itemName Stringa

Nome dell'articolo dall'attributo item_name.

amountRemaining Oggetto

Importo rimanente dell'articolo sul dispositivo. Se il dispositivo sta erogando energia, indica l'importo rimanente o l'importo una volta che il dispositivo sta per erogare.

amount Number

Importo rimanente

unit Stringa

Unità per amount dall'attributo supported_units.

amountLastDispensed Oggetto

La quantità dell'articolo erogato dal dispositivo più di recente. Se il dispositivo sta erogando corrente, questo dovrebbe riportare l'importo erogato prima di quello attualmente in corso.

amount Number

Importo rimanente

unit Stringa

Unità per amount dall'attributo supported_units.

isCurrentlyDispensing Booleano

Indica se il dispositivo sta erogando questo articolo.

Esempi

Quanti cibo 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
    }
  ]
}

Quanto acqua resiste nel mio refrigeratore?

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

Quanti 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 eroga acqua ancora?

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

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

È possibile fornire più elementi nell'array dispenseItems. Ogni nome di articolo deve essere univoco e deve corrispondere a un articolo nell'attributo supportedDispenseItems.

comandi del 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 Soddisfazione degli intent.

action.devices.commands.Dispense

Dispensa articoli.

Parametri

Il payload contiene uno dei seguenti valori:

Dosa in base all'importo.

Parametri Tipo Descrizione
item Stringa

Nome dell'articolo da erogare, dall'attributo item_name.

amount Number

Obbligatorio.

Importo da erogare.

unit Stringa

Obbligatorio.

Unità per amount, dall'attributo supported_units.

Eroga per preimpostazione.

Parametri Tipo Descrizione
presetName Stringa

Obbligatorio.

Nome della preimpostazione da erogare, dall'attributo preset_name.

Dispensa senza parametri.

Parametri Tipo Descrizione

Nessuna proprietà

Esempi

Dammi una tazza di 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"
  }
}

Erogare 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 articolo o un importo da un dispositivo che non dispone di un importo sufficiente.
  • dispenseAmountAboveLimit: l'utente ha tentato di distribuire un importo che supera i limiti di ciò che può richiedere in una singola query. Questo consente di evitare accidentalmente erogare una quantità eccessiva (ad esempio, 500.000 tazze di acqua).
  • dispenseAmountBelowLimit: l'utente ha tentato di erogare sul dispositivo un articolo o una quantità inferiore all'importo minimo che può erogare.
  • dispenseFractionalAmountNotSupported: l'utente ha tentato di erogare una quantità frazionata di un articolo che il dispositivo non può dividere (ad esempio, elementi conteggiabili come i cibo per cani potrebbero non essere divisibili per il dispositivo).
  • genericDispenseNotSupported: l'utente cerca di erogare da un dispositivo senza specificare un elemento o una preimpostazione, ma il dispositivo non supporta tale funzionalità (ad esempio, un'azione di erogazione predefinita).
  • dispenseUnitNotSupported: l'utente cerca di erogare da un dispositivo con un'unità non supportata per quel caso (ad esempio, l'articolo non è fornito, quindi 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: gli utenti cercano di erogare un articolo, ma il dispositivo sta già erogando un prodotto.
  • deviceClogged: l'utente cerca di distribuire un articolo, ma il dispositivo è intasato.
  • deviceBusy: l'utente cerca di erogare un articolo, ma il dispositivo è occupato (generico).

ECCEZIONI DISPOSITIVO

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

  • amountRemainingLow: l'utente eroga un articolo o un importo dal dispositivo, il che comporta il raggiungimento di un livello inferiore per l'importo rimanente. Sei responsabile della definizione di ciò che costituisce un livello "basso".
  • userNeedsToWait: quando l'utente deve attendere prima di poter erogare l'articolo o l'importo richiesto, ad esempio, un rubinetto eroga acqua calda, ma l'utente deve attendere che l'acqua si riscaldi prima di iniziare l'erogazione.