Bienvenue dans le centre Google Home pour les développeurs, la nouvelle destination pour apprendre à développer des actions pour la maison connectée. Remarque:Vous continuerez de créer des actions dans la console Actions.

Cette page a été traduite par l'API Cloud Translation.

Schéma de trait de distribution pour la maison connectée

action.devices.traits.Dispense : cette caractéristique appartient aux appareils qui permettent de distribuer une quantité spécifiée d'un ou de plusieurs articles physiques.

Cette caractéristique permet également de distribuer un préréglage, par exemple une "gamelle pour chat" pour un distributeur de nourriture pour animaux de compagnie ou un "verre" pour un robinet.

ATTRIBUTS de l'appareil

Les appareils dotés de cette caractéristique peuvent signaler les attributs suivants dans le cadre de l'opération SYNC. Pour en savoir plus sur la gestion des intents SYNC, consultez la section Traitement des intents.

Attributs	Type	Description
`supportedDispenseItems`	Array	Contient des informations sur tous les articles que l'appareil peut distribuer.
`[item, ...]`	Objet	Élément jetable.
`item_name`	String	Obligatoire. Nom interne de l'article distribué. Cette approche peut ne pas être conviviale et est commune dans toutes les langues.
`item_name_synonyms`	Array	Obligatoire. Noms des synonymes des produits distribués dans chaque langue compatible.
`[item, ...]`	Objet	Noms synonymes de l'article distribué dans une langue donnée.
`synonyms`	Array	Obligatoire. Noms synonymes de l'article distribué. Les synonymes doivent inclure les formes au singulier et au pluriel, le cas échéant. La première chaîne de cette liste doit être la forme au pluriel de l'élément dans cette langue.
`[item, ...]`	String	Synonyme
`lang`	String	Obligatoire. Code de langue (ISO 639-1) Consultez la liste des langues acceptées.
`supported_units`	Array	Obligatoire. Ensemble d'unités acceptées par l'appareil pour cet élément.
`[item, ...]`	String	Unités acceptées Valeurs acceptées : `CENTIMETERS` `CUPS` `DECILITERS` `FLUID_OUNCES` `GALLONS` `GRAMS` `KILOGRAMS` `LITERS` `MILLIGRAMS` `MILLILITERS` `MILLIMETERS` `NO_UNITS` `OUNCES` `PINCH` `PINTS` `PORTION` `POUNDS` `QUARTS` `TABLESPOONS` `TEASPOONS`
`default_portion`	Objet	Obligatoire. Quantité typique de l'article pouvant être distribuée.
`amount`	Entier	Obligatoire. Montant distribué.
`unit`	String	Obligatoire. Unité distribuée.
`supportedDispensePresets`	Array	Préréglages compatibles avec l'appareil.
`[item, ...]`	Objet	Préréglage.
`preset_name`	String	Obligatoire. Nom interne du préréglage. Ce nom peut ne pas être convivial et est partagé dans toutes les langues.
`preset_name_synonyms`	Array	Obligatoire. Noms synonymes du préréglage dans chaque langue prise en charge.
`[item, ...]`	Objet	Noms synonymes du préréglage dans une langue donnée.
`synonyms`	Array	Obligatoire. Noms synonymes du préréglage. Les synonymes doivent inclure les formes au singulier et au pluriel, le cas échéant.
`[item, ...]`	String	Synonyme
`lang`	String	Obligatoire. Code de langue (ISO 639-1) Consultez la liste des langues acceptées.

Exemples

Distributeur d'eau compatible avec les unités de liquides avec des préréglages.

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

Distributeur de nourriture pour animaux sans préréglages.

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

ÉTATS DE L'APPAREIL

Les entités avec cette caractéristique peuvent signaler les états suivants dans le cadre de l'opération QUERY. Pour en savoir plus sur la gestion des intents QUERY, consultez la section Traitement des intents.

États	Type	Description
`dispenseItems`	Array	États des articles que l'appareil peut distribuer.
`[item, ...]`	Objet	État d'un article donné.
`itemName`	String	Nom de l'élément de l'attribut `item_name`.
`amountRemaining`	Objet	Quantité restante de cet élément sur l'appareil. Si l'appareil est en train de distribuer du produit, le montant restant ou le montant qui sera distribué une fois la distribution terminée est indiqué.
`amount`	Number	Montant restant
`unit`	String	Unité pour le `amount` de l'attribut `supported_units`.
`amountLastDispensed`	Objet	Quantité de cet article distribué le plus récemment par l'appareil. Si l'appareil est en cours de distribution, la quantité d'eau distribuée avant la quantité actuelle doit être indiquée.
`amount`	Number	Montant restant
`unit`	String	Unité pour le `amount` de l'attribut `supported_units`.
`isCurrentlyDispensing`	Valeur booléenne	Indique si l'appareil distribue actuellement cet article.

Exemples

Combien de friandises pour chien restent-elles dans mon distributeur ?

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

Combien d'eau reste-t-il dans mon distributeur d'eau ?

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

Quelle quantité de nourriture pour chats donnais-je auparavant ?

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

Le robinet distribue-t-il toujours de l'eau ?

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

amountRemaining et amountLastDispensed ne doivent être indiqués qu'avec une seule unité de mesure.

Vous pouvez fournir plusieurs éléments dans le tableau dispenseItems. Chaque nom d'élément doit être unique et correspondre à un élément de l'attribut supportedDispenseItems.

COMMANDES DE L'APPAREIL

Les appareils dotés de cette caractéristique peuvent répondre aux commandes suivantes dans le cadre de l'opération EXECUTE. Pour en savoir plus sur la gestion des intents EXECUTE, consultez la section Traitement des intents.

`action.devices.commands.Dispense`

Distribuer des articles.

Paramètres

La charge utile contient l'un des éléments suivants :

Distribuez le montant.

Paramètres Type Description

Paramètres	Type	Description
`item`	String	Nom de l'article à distribuer, issu de l'attribut `item_name`.
`amount`	Number	Obligatoire. Montant à distribuer.
`unit`	String	Obligatoire. Unité pour le `amount`, à partir de l'attribut `supported_units`.

item

String

Nom de l'article à distribuer, issu de l'attribut item_name.

amount

Number

Obligatoire.

Montant à distribuer.

unit

String

Obligatoire.

Unité pour le amount, à partir de l'attribut supported_units.

Distribution par préréglage.

Paramètres Type Description

Paramètres	Type	Description
`presetName`	String	Obligatoire. Nom du préréglage à distribuer, à partir de l'attribut `preset_name`.

presetName

String

Obligatoire.

Nom du préréglage à distribuer, à partir de l'attribut preset_name.

Distribution sans paramètres.

Paramètres	Type	Description
Aucune propriété

Exemples

Donnez-moi un verre d'eau.

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

Remplissez le bol d'eau du chat.

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

Versez de l'eau.

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

ERREURS de l'appareil

Consultez la liste complète des erreurs et exceptions.

dispenseAmountRemainingExceeded: l'utilisateur a tenté de distribuer un élément ou une quantité à partir d'un appareil dont la quantité restante est insuffisante.
dispenseAmountAboveLimit : l'utilisateur a essayé de distribuer une quantité qui dépasse les limites de ce qu'il peut demander dans une seule requête. Cela permet d'éviter de distribuer accidentellement une quantité excessive (par exemple, 500 000 tasses d'eau).
dispenseAmountBelowLimit: l'utilisateur a essayé de distribuer un article ou une quantité depuis l'appareil dont la quantité est inférieure à la quantité minimale qu'il peut distribuer.
dispenseFractionalAmountNotSupported: l'utilisateur a tenté de distribuer une quantité fractionnaire d'un élément que l'appareil ne peut pas diviser (par exemple, les éléments dénombrables tels que les friandises pour chien ne peuvent pas être divisibles par l'appareil).
genericDispenseNotSupported : l'utilisateur tente de distribuer un produit à partir d'un appareil sans spécifier d'article ni de préréglage, mais l'appareil n'est pas compatible avec cette fonctionnalité (par exemple, une action de distribution par défaut).
dispenseUnitNotSupported : l'utilisateur tente de distribuer un article à partir d'un appareil avec une unité non compatible dans ce cas (par exemple, l'article n'est pas fourni, donc supported_unit validation a été ignoré).
dispenseFractionalUnitNotSupported : l'utilisateur a essayé de distribuer une quantité fractionnaire d'un élément pouvant être divisé, mais pas pour l'unité spécifique spécifiée (par exemple, un robinet peut distribuer 2,7 tasses, mais pas 2,7 mL).
deviceCurrentlyDispensing: l'utilisateur tente de distribuer un article, mais l'appareil est déjà en train de le faire.
deviceClogged: l'utilisateur tente de distribuer un article, mais l'appareil est bloqué.
deviceBusy : l'utilisateur tente de distribuer un article, mais l'appareil est occupé (générique).

EXCEPTIONS concernant les appareils

Ces exceptions peuvent être signalées en tant que exceptionCode dans l'objet states de votre réponse :

amountRemainingLow : l'utilisateur distribue un élément ou une quantité à partir de l'appareil, ce qui ramène la quantité restante à un niveau faible. Vous êtes responsable de définir ce qui constitue un niveau "faible".
userNeedsToWait : lorsque l'utilisateur doit attendre avant que l'objet ou la quantité demandés puissent être distribués (par exemple, un robinet distribue de l'eau chaude, mais l'utilisateur doit attendre que l'eau chauffe avant de commencer à verser de l'eau).