Giản đồ phân biệt đối xử trong nhà thông minh

action.devices.traits.Dispense – Đặc điểm này thuộc về các thiết bị hỗ trợ việc phân phối một hoặc nhiều mặt hàng thực tế theo số lượng đã chỉ định.

Đặc điểm này cũng hỗ trợ việc phân phối một giá trị đặt trước, chẳng hạn như "bát thức ăn cho mèo" cho một máy cho thú cưng ăn hoặc "ly" cho vòi nước.

ATTRIBUTE của thiết bị

Các thiết bị có đặc điểm này có thể báo cáo các thuộc tính sau đây trong quá trình thao tác SYNC. Để tìm hiểu thêm về cách xử lý ý định SYNC, hãy xem phần Thực hiện ý định.

Thuộc tính	Loại	Mô tả
supportedDispenseItems	Mảng	Chứa thông tin về tất cả các mặt hàng mà thiết bị có thể phân phối.
[item, ...]	Đối tượng	Mục có thể bỏ qua.
item_name	String	Bắt buộc. Tên nội bộ của mặt hàng được phân phối. Điều này có thể gây khó khăn cho người dùng và được chia sẻ trên tất cả ngôn ngữ.
item_name_synonyms	Mảng	Bắt buộc. Từ đồng nghĩa với tên phân phát bằng mỗi ngôn ngữ được hỗ trợ.
[item, ...]	Đối tượng	Từ đồng nghĩa với tên của mặt hàng được phân phối trong một ngôn ngữ nhất định.
synonyms	Mảng	Bắt buộc. Tên đồng nghĩa cho mặt hàng được phân phát. Từ đồng nghĩa phải bao gồm cả dạng số ít và số nhiều (nếu có). Chuỗi đầu tiên trong danh sách này phải là dạng số nhiều của mục đó bằng ngôn ngữ đó.
[item, ...]	String	Tên đồng nghĩa
lang	String	Bắt buộc. Mã ngôn ngữ (ISO 639-1). Xem các ngôn ngữ được hỗ trợ.
supported_units	Mảng	Bắt buộc. Tập hợp các đơn vị mà thiết bị hỗ trợ cho mặt hàng đó.
[item, ...]	String	Các đơn vị được hỗ trợ. Các giá trị được hỗ trợ: CENTIMETERS CUPS DECILITERS FLUID_OUNCES GALLONS GRAMS KILOGRAMS LITERS MILLIGRAMS MILLILITERS MILLIMETERS NO_UNITS OUNCES PINCH PINTS PORTION POUNDS QUARTS TABLESPOONS TEASPOONS
default_portion	Đối tượng	Bắt buộc. Lượng mặt hàng thông thường có thể được phân phát.
amount	Số nguyên	Bắt buộc. Số tiền đã phát.
unit	String	Bắt buộc. Đơn vị được phân phối.
supportedDispensePresets	Mảng	Các chế độ cài đặt trước mà thiết bị hỗ trợ.
[item, ...]	Đối tượng	Giá trị đặt trước.
preset_name	String	Bắt buộc. Tên nội bộ của giá trị đặt trước. Tên này có thể không thân thiện với người dùng và được dùng chung cho tất cả ngôn ngữ.
preset_name_synonyms	Mảng	Bắt buộc. Tên từ đồng nghĩa cho giá trị đặt trước trong mỗi ngôn ngữ được hỗ trợ.
[item, ...]	Đối tượng	Tên đồng nghĩa của giá trị đặt trước trong một ngôn ngữ đã cho.
synonyms	Mảng	Bắt buộc. Tên đồng nghĩa cho giá trị đặt trước. Từ đồng nghĩa phải bao gồm cả dạng số ít và số nhiều (nếu có).
[item, ...]	String	Tên đồng nghĩa
lang	String	Bắt buộc. Mã ngôn ngữ (ISO 639-1). Xem các ngôn ngữ được hỗ trợ.

Ví dụ

Máy nước hỗ trợ các đơn vị cho chất lỏng có chế độ cài đặt trước.

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

Máy cho thú cưng ăn không có chế độ cài đặt trước.

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

Trạng thái thiết bị

Các thực thể có đặc điểm này có thể báo cáo các trạng thái sau đây trong quá trình thực hiện thao tác QUERY. Để tìm hiểu thêm về cách xử lý ý định QUERY, hãy xem bài viết Thực hiện ý định.

Tiểu bang	Loại	Mô tả
dispenseItems	Mảng	Trạng thái của các mặt hàng mà thiết bị có thể phân phối.
[item, ...]	Đối tượng	Trạng thái của một mục nhất định.
itemName	String	Tên của mặt hàng trong thuộc tính item_name.
amountRemaining	Đối tượng	Số lượng mặt hàng đó còn lại trong thiết bị. Nếu thiết bị đang phân phối, giá trị này sẽ báo cáo lượng còn lại hoặc số tiền sau khi thiết bị phân phối xong.
amount	Number	Số tiền còn lại
unit	String	Đơn vị cho amount trong thuộc tính supported_units.
amountLastDispensed	Đối tượng	Lượng mặt hàng mà thiết bị đã phân phối gần đây nhất. Nếu thiết bị đang phân phối, thì thông tin này sẽ báo cáo lượng đã phân phối trước lượng hiện tại.
amount	Number	Số tiền còn lại
unit	String	Đơn vị cho amount từ thuộc tính supported_units.
isCurrentlyDispensing	Boolean	Cho biết liệu thiết bị có đang phân phối mặt hàng này hay không.

Ví dụ

Bộ phân phối thức ăn cho chó của tôi còn bao nhiêu khẩu phần?

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

Còn bao nhiêu nước trong bình nước nóng của tôi?

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

Trước đây, tôi đã cho mèo ăn bao nhiêu thức ăn?

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

Vòi nước có còn chảy nước không?

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

Bạn chỉ cần báo cáo amountRemaining và amountLastDispensed bằng một đơn vị đo lường.

Bạn có thể cung cấp nhiều mục trong mảng dispenseItems. Mỗi tên mục phải là duy nhất và phải tương ứng với một mục trong thuộc tính supportedDispenseItems.

LỆNH thiết bị

Các thiết bị có đặc điểm này có thể phản hồi các lệnh sau đây trong quá trình hoạt động EXECUTE. Để tìm hiểu thêm về cách xử lý ý định EXECUTE, hãy xem phần Thực hiện ý định.

action.devices.commands.Dispense

Phân phối mặt hàng.

Thông số

Trọng tải chứa một trong những nội dung sau:

Phân phối theo số lượng.

Thông số	Loại	Mô tả
item	String	Tên của mặt hàng được phân phối, từ thuộc tính item_name.
amount	Number	Bắt buộc. Số lượng phân phối.
unit	String	Bắt buộc. Đơn vị cho amount, từ thuộc tính supported_units.

Phân phối theo giá trị đặt trước.

Thông số	Loại	Mô tả
presetName	String	Bắt buộc. Tên của chế độ cài đặt trước để phân phối, từ thuộc tính preset_name.

Phân phối mà không có tham số.

Thông số	Loại	Mô tả
Không có thuộc tính nào

Ví dụ

Cho tôi uống 1 cốc nước.

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

Đổ đầy bát nước cho mèo.

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

Cung cấp nước.

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

LỖI thiết bị

Xem danh sách đầy đủ các lỗi và ngoại lệ.

• dispenseAmountRemainingExceeded: Người dùng đã cố gắng phân phối một mặt hàng hoặc số lượng từ một thiết bị không còn đủ số lượng.
• dispenseAmountAboveLimit: Người dùng đã cố phân phối số lượng vượt quá giới hạn những gì họ có thể yêu cầu trong một truy vấn. Việc này là để tránh vô tình cấp quá nhiều nước (ví dụ: 500.000 cốc nước).
• dispenseAmountBelowLimit: Người dùng đã cố gắng phân phối một mặt hàng hoặc số lượng từ thiết bị, nhưng thiết bị đó có số lượng dưới mức tối thiểu mà thiết bị có thể phân phối.
• dispenseFractionalAmountNotSupported: Người dùng đã cố gắng phân phối một lượng nhỏ của một mặt hàng mà thiết bị không thể chia (ví dụ: thiết bị có thể không chia được các mặt hàng có thể đếm được như thức ăn cho chó).
• genericDispenseNotSupported: Người dùng cố gắng phân phối từ một thiết bị mà không chỉ định một mặt hàng hoặc chế độ cài đặt trước, nhưng thiết bị không hỗ trợ chức năng như vậy (ví dụ: thao tác phân phối mặc định).
• dispenseUnitNotSupported: Người dùng cố gắng phân phối từ một thiết bị có đơn vị không được hỗ trợ cho trường hợp đó (ví dụ: mục không được cung cấp nên supported_unit validation đã bị bỏ qua).
• dispenseFractionalUnitNotSupported: Người dùng đã cố gắng phân phối một lượng phân đoạn của một mục có thể được chia nhưng không phải cho đơn vị cụ thể được chỉ định (ví dụ: vòi nước có thể phân phối 2,7 cốc nhưng không phải 2,7 mL).
• deviceCurrentlyDispensing: Người dùng cố gắng phân phối một mặt hàng nhưng thiết bị đã phân phối.
• deviceClogged: Người dùng cố gắng phân phối một mặt hàng nhưng thiết bị bị tắc.
• deviceBusy: Người dùng cố gắng phân phối một mặt hàng nhưng thiết bị đang bận (chung).

TRƯỜNG HỢP NGOẠI LỆ về thiết bị

Bạn có thể báo cáo các trường hợp ngoại lệ này dưới dạng exceptionCode trong đối tượng states của phản hồi:

• amountRemainingLow – Người dùng phân phát một mặt hàng hoặc một lượng pin từ thiết bị, đưa lượng vật phẩm còn lại xuống mức thấp. Bạn có trách nhiệm xác định những yếu tố cấu thành một cấp độ "thấp".
• userNeedsToWait – Khi người dùng phải chờ trước khi có thể phân phối thành công mặt hàng hoặc số lượng đã yêu cầu (ví dụ: vòi nước sẽ phân phối nước nóng nhưng người dùng cần chờ nước nóng lên trước khi bắt đầu phân phối).