歡迎使用 Google Home 開發人員中心,探索全新功能,瞭解如何開發智慧住宅動作。注意:請繼續在「動作」控制台中建立動作。
透過集合功能整理內容 你可以依據偏好儲存及分類內容。

智慧型住宅分散型點心結構定義

action.devices.traits.Dispense - 此屬性所屬的裝置可分配指定數量的一或多個實體項目。

此外,這項特性也支援配置預設食材,例如當做寵物餵食器的「貓食碗」或水龍頭的「玻璃」

裝置屬性

具有此特性的裝置可能會在 SYNC 作業中回報下列屬性。如要進一步瞭解如何處理 SYNC 意圖,請參閱意圖執行要求一文。

屬性 類型 說明
supportedDispenseItems 陣列

包含裝置可供應的所有商品相關資訊。

[item, ...] 物件

可出貨商品。

item_name 字串

必填。

已售商品的內部名稱。這項功能不容易理解,並且與所有語言共用。

item_name_synonyms 陣列

必填。

以各個支援語言分配的同義詞名稱。

[item, ...] 物件

特定語言的銷售項目的同義詞名稱。

synonyms 陣列

必填。

已分配項目的同義詞名稱。這類話應包括單數與複數形式 (如果適用的話)。此清單的第一個字串必須是該語言的項目的複數形式。

[item, ...] 字串

同義詞名稱

lang 字串

必填。

語言代碼 (ISO 639-1)。詳情請參閱支援的語言

supported_units 陣列

必填。

裝置支援的商品單位組合。

[item, ...] 字串

支援的單位。

支援的值:

CENTIMETERS
CUPS
DECILITERS
FLUID_OUNCES
GALLONS
GRAMS
KILOGRAMS
LITERS
MILLIGRAMS
MILLILITERS
MILLIMETERS
NO_UNITS
OUNCES
PINCH
PINTS
PORTION
POUNDS
QUARTS
TABLESPOONS
TEASPOONS
default_portion 物件

必填。

可折抵的商品一般數量。

amount 整數

必填。

已提領的金額。

unit 字串

必填。

分配單位。

supportedDispensePresets 陣列

裝置支援的預設設定。

[item, ...] 物件

預設。

preset_name 字串

必填。

預設設定的內部名稱。此名稱不容易使用,且適用於所有語言。

preset_name_synonyms 陣列

必填。

各個支援語言的預設設定同義詞名稱。

[item, ...] 物件

特定語言的預設同義詞名稱。

synonyms 陣列

必填。

預設設定的同義詞名稱。同義詞應包括單數與複數形式 (如適用)。

[item, ...] 字串

同義詞名稱

lang 字串

必填。

語言代碼 (ISO 639-1)。詳情請參閱支援的語言

範例

抽油器,可配備液位和液相的液位。

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

寵物食物分配器沒有預設設定

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

裝置狀態:STATE

具有此特性的裝置可能會在 QUERY 作業中回報下列狀態。如要進一步瞭解如何處理 QUERY 意圖,請參閱意圖執行要求一文。

類型 說明
dispenseItems 陣列

裝置可供應的商品項目狀態。

[item, ...] 物件

特定項目的狀態。

itemName 字串

來自 item_name 屬性的項目名稱。

amountRemaining 物件

該項目在裝置中剩餘的金額。如果裝置目前正在分配,這會回報剩餘金額,或是裝置在配銷後的總金額。

amount Number

剩餘金額

unit 字串

supported_units 屬性中的 amount 單位。

amountLastDispensed 物件

裝置最近自費支付的商品數量。如果裝置目前正在分配款項,則應回報裝置在目前配銷金額之前已配置的金額。

amount Number

剩餘金額

unit 字串

supported_units 屬性中的 amount 單位。

isCurrentlyDispensing 布林

指出裝置是否正在供應這項商品。

範例

我的調酒桶中還有幾隻狗零食?

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

我的冷水器還剩多少錢?

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

我先前提供的貓食有多少?

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

水龍頭是否仍在供應水?

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

您只需要使用一個測量單位回報 amountRemainingamountLastDispensed

您可以在 dispenseItems 陣列中提供多個項目。每個項目的名稱都不得重複,且必須對應至 supportedDispenseItems 屬性中的某個項目。

裝置指令

具有此特性的裝置可能會在 EXECUTE 作業中回應下列指令。如要進一步瞭解如何處理 EXECUTE 意圖,請參閱意圖執行要求一文。

action.devices.commands.Dispense

供應多種商品。

參數

酬載包含下列其中一個值:

依金額分配。

參數 類型 說明
item 字串

要供應的商品名稱,來自 item_name 屬性。

amount Number

必填。

要抵銷的金額。

unit 字串

必填。

supported_units 屬性中的 amount 單位。

依預設而定。

參數 類型 說明
presetName 字串

必填。

來自「preset_name」屬性的預設設定名稱。

不含參數的分配。

參數 類型 說明

沒有任何資源

範例

給我 1 杯水。

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

填充貓咪水碗

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

污水。

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

裝置錯誤:ERRORS

請參閱錯誤和例外狀況的完整清單。
  • dispenseAmountRemainingExceeded:使用者嘗試從的裝置餘額不足,嘗試分配某個項目或金額。
  • dispenseAmountAboveLimit:使用者嘗試超出某個查詢所要求的範圍限制。這是為了避免意外量過量 (例如 500,000 杯水)。
  • dispenseAmountBelowLimit:使用者嘗試從裝置分配一個項目或金額,但低於最低限度的裝置數量。
  • dispenseFractionalAmountNotSupported:使用者嘗試分配一定比例的項目,且裝置無法分割 (例如,裝置可能無法分割小狗等可計算的項目)。
  • genericDispenseNotSupported:使用者嘗試在裝置中指定 (例如指定項目或預設),但裝置不支援這類功能,例如預設的分散動作。
  • dispenseUnitNotSupported:使用者嘗試從不支援該單位的單位發行裝置 (例如未提供此項目,因此被略過 supported_unit validation)。
  • dispenseFractionalUnitNotSupported:使用者嘗試分配一定比例的項目,但該項目可以分割,但無法指定的特定單位 (例如,水龍頭可能會供應 2.7 杯,但不能供應 2.7 毫升)。
  • deviceCurrentlyDispensing:使用者嘗試供應某個項目,但裝置已經在供應中。
  • deviceClogged:使用者嘗試散佈項目,但裝置已損毀。
  • deviceBusy:使用者嘗試散佈項目,但裝置忙碌 (一般)。

裝置排除

您可以在回應的 states 物件中將下列例外狀況回報為 exceptionCode

  • amountRemainingLow - 使用者從裝置分配項目或金額,導致剩餘的金額偏低。您必須負責定義「低」層級的要素。
  • userNeedsToWait - 使用者必須等待要求的項目或金額成功供應 (比方說,水龍頭會供應熱水,但使用者必須等待水溫上升才能開始分配)。