Giản đồ đặc điểm phân phối trong nhà thông minh

action.devices.traits.Dispense – Đặc điểm này thuộc về các thiết bị hỗ trợ phân phối một lượng cụ thể của một hoặc nhiều vật phẩm.

Đặ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 đựng thức ăn cho mèo" cho máy cho thú cưng ăn hoặc "ly" cho vòi nước.

THUỘC TÍNH 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 SYNC. Để tìm hiểu thêm về cách xử lý ý định SYNC, vui lòng xem phần Thực hiện ý định.

Thuộc tính	Loại	Nội dung mô tả
supportedDispenseItems	Mảng	Chứa thông tin về tất cả các vật phẩm mà thiết bị có thể phân phối.
[item, ...]	Đối tượng	Vật phẩm cần thiết.
item_name	Chuỗi	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ể không thân thiện với người dùng và được chia sẻ cho tất cả các ngôn ngữ.
item_name_synonyms	Mảng	Bắt buộc. Từ đồng nghĩa của tên được phân phối trong mỗi ngôn ngữ được hỗ trợ.
[item, ...]	Đối tượng	Từ đồng nghĩa của tên món ăn được phân phối trong một ngôn ngữ cụ thể.
synonyms	Mảng	Bắt buộc. Tên từ đồng nghĩa của mặt hàng được phân phối. 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 ở dạng số nhiều của mục bằng ngôn ngữ đó.
[item, ...]	Chuỗi	Tên từ đồng nghĩa
lang	Chuỗi	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ị thiết bị hỗ trợ cho mục đó.
[item, ...]	Chuỗi	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ối.
amount	Số nguyên	Bắt buộc. Số tiền đã phân phối.
unit	Chuỗi	Bắt buộc. Thiết bị phân phối.
supportedDispensePresets	Mảng	Thiết bị hỗ trợ giá trị đặt trước.
[item, ...]	Đối tượng	Giá trị đặt trước.
preset_name	Chuỗi	Bắt buộc. Tên nội bộ cho 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ả cá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 từ đồng nghĩa của giá trị đặt trước trong một ngôn ngữ cụ thể.
synonyms	Mảng	Bắt buộc. Tên từ đồng nghĩa của 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, ...]	Chuỗi	Tên từ đồng nghĩa
lang	Chuỗi	Bắt buộc. Mã ngôn ngữ (ISO 639-1). Xem các ngôn ngữ được hỗ trợ.

Ví dụ

Bình nước uống hỗ trợ các đơn vị chất lỏng có sẵn các chế độ cài đặt sẵn.

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

Hộp đựng thức ăn cho thú cưng không có giá trị đặ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 của 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 trong thao tác QUERY. Để tìm hiểu thêm về cách xử lý ý định QUERY, vui lòng xem phần Thực hiện ý định.

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

Ví dụ

Còn bao nhiêu thức ăn cho chó trong hộp của tôi?

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

Máy làm lạnh nước của tôi còn bao nhiêu nước?

{
  "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 vẫn đang cấp nước phải 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ặt hàng phải là duy nhất và tương ứng với một mặt hàng trong thuộc tính supportedDispenseItems.

Lệnh trên thiết bị

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

action.devices.commands.Dispense

Phân phối các vật phẩm.

Thông số

Gói dữ liệu có một trong các nội dung sau:

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

Thông số	Loại	Mô tả
item	Chuỗi	Tên của mặt hàng cần phân phối, từ thuộc tính item_name.
amount	Number	Bắt buộc. Lượng phân phối.
unit	Chuỗi	Bắt buộc. Đơn vị của 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	Chuỗi	Bắt buộc. Tên của giá trị đặ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	Nội dung mô tả
Không có thuộc tính nào

Ví dụ

Cho tôi 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"
  }
}

Phân phối nước.

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

Thiết bị ERRORS

Xem danh sách đầy đủ lỗi và trường hợp ngoại lệ.

• dispenseAmountRemainingExceeded: Người dùng đã cố gắng phân phối một mặt hàng hoặc số tiền từ một thiết bị không còn đủ số lượng mặt hàng.
• dispenseAmountAboveLimit: Người dùng đã cố gắng phân bổ một số tiền vượt quá giới hạn của những gì họ có thể yêu cầu trong một truy vấn. Điều này để tránh trường hợp vô tình phân phối 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 vật phẩm hoặc một lượng từ thiết bị thấp hơn 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ỏ một mục mà thiết bị không thể phân tách (ví dụ: các mục có thể phân chia như thức ăn cho chó nhưng thiết bị có thể không chia hết được).
• genericDispenseNotSupported: Người dùng cố gắng phân phối từ một thiết bị mà không chỉ định mục hoặc giá trị đặt trước, nhưng thiết bị không hỗ trợ chức năng đó (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ặt hàng 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 nhỏ của một mục có thể chia nhỏ được nhưng không cho đơn vị cụ thể được chỉ định (ví dụ: vòi nước có thể xả được 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át một món 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).

NGOẠI LỆ thiết bị

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

• amountRemainingLow – Người dùng phân phối một mặt hàng hoặc một số lượng từ thiết bị, khiến số lượng còn lại xuống một cấp thấp. Bạn có trách nhiệm xác định các yếu tố tạo nên cấp độ "thấp".
• userNeedsToWait – Khi người dùng phải đợi trước khi có thể phân phối thành công mặt hàng hoặc số lượng theo 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 phải chờ nước nóng lên trước khi bắt đầu phân phối).