Hướng dẫn về hệ thống an ninh nhà thông minh
action.devices.types.SECURITYSYSTEM
– Bạn có thể bật và tắt chuông báo động của hệ thống an ninh. Các thiết bị này có thể được bật chuông báo động ở nhiều mức an ninh (ví dụ: ở nhà và vắng nhà), đồng thời có thể báo cáo thông tin về một số cảm biến, chẳng hạn như cảm biến phát hiện chuyển động hoặc cửa sổ đang mở.
Loại này cho biết thiết bị sẽ nhận được biểu tượng Hệ thống bảo mật cũng như một số từ đồng nghĩa và biệt hiệu có liên quan.
Khả năng của thiết bị
Hãy tham khảo tài liệu về đặc điểm tương ứng để biết thông tin chi tiết về cách triển khai, chẳng hạn như các thuộc tính và trạng thái mà dịch vụ của bạn cần hỗ trợ cũng như cách tạo các phản hồi EXECUTE và QUERY.
Trait bắt buộc
Những đặc điểm và lệnh này là bắt buộc, nếu áp dụng cho thiết bị của bạn. Nếu thiết bị của bạn không hỗ trợ các trait này, hãy nhập mã lỗi functionNotSupported
vào phản hồi QUERY hoặc EXECUTE. Hãy xem phần Lỗi và ngoại lệ để biết thêm thông tin.
Trait được đề xuất
Bạn nên sử dụng những đặc điểm này (nếu phù hợp với thiết bị của mình). Tuy nhiên, bạn có thể tuỳ ý kết hợp và so khớp từ tất cả các đặc điểm có sẵn sao cho phù hợp nhất với chức năng sản phẩm hiện có.
Yêu cầu về chất lượng
- Độ trễ: phải nhỏ hơn hoặc bằng 2000 mili giây.
- Độ tin cậy: phải lớn hơn hoặc bằng 97%.
Thiết bị ví dụ: Hệ thống an ninh đơn giản
Phần này chứa các tải trọng ý định mẫu đại diện cho một "Hệ thống bảo mật" phổ biến dựa trên loại thiết bị và đặc điểm nêu trên. Nếu bạn thêm hoặc xoá đặc điểm trong quá trình triển khai, hãy sửa đổi các phản hồi cho phù hợp để phản ánh những thay đổi đó.
Phản hồi SYNC mẫu
{ "requestId": "6894439706274654512", "inputs": [ { "intent": "action.devices.SYNC" } ] }
{ "requestId": "6894439706274654512", "payload": { "agentUserId": "user123", "devices": [ { "id": "123", "type": "action.devices.types.SECURITYSYSTEM", "traits": [ "action.devices.traits.StatusReport", "action.devices.traits.ArmDisarm" ], "name": { "name": "Simple security system" }, "willReportState": true, "attributes": { "availableArmLevels": { "levels": [ { "level_name": "home_key", "level_values": [ { "level_synonym": [ "Home and Guarding", "level 1", "home", "SL1" ], "lang": "en" } ] }, { "level_name": "away_key", "level_values": [ { "level_synonym": [ "Away and Guarding", "level 2", "away", "SL2" ], "lang": "en" } ] } ], "ordered": true } }, "deviceInfo": { "manufacturer": "smart-home-inc", "model": "hs1234", "hwVersion": "3.2", "swVersion": "11.4" } } ] } }
Phản hồi QUERY mẫu
{ "requestId": "6894439706274654514", "inputs": [ { "intent": "action.devices.QUERY", "payload": { "devices": [ { "id": "123" } ] } } ] }
{ "requestId": "6894439706274654514", "payload": { "devices": { "123": { "status": "SUCCESS", "online": true, "isArmed": true, "currentArmLevel": "home_key", "currentStatusReport": [ { "blocking": false, "deviceTarget": "123", "priority": 0, "statusCode": "lowBattery" } ] } } } }
Lệnh EXECUTE mẫu
ArmDisarm
Để biết thêm thông tin chi tiết về các tham số lệnh, hãy xem tài liệu tham khảo về
action.devices.traits.ArmDisarm
.
{ "requestId": "6894439706274654516", "inputs": [ { "intent": "action.devices.EXECUTE", "payload": { "commands": [ { "devices": [ { "id": "123" } ], "execution": [ { "command": "action.devices.commands.ArmDisarm", "params": { "arm": true, "armLevel": "away_key" } } ] } ] } } ] }
{ "requestId": "6894439706274654516", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "online": true, "isArmed": true, "currentArmLevel": "away_key" } } ] } }
Thiết bị LỖI
Xem danh sách toàn bộ lỗi và ngoại lệ.Báo cáo trường hợp ngoại lệ khi bật cảnh báo
Khi tìm cách tắt chuông báo động hoặc tắt chuông báo động cho hệ thống, bạn có thể cung cấp thêm bối cảnh thông qua mã ngoại lệ mà bạn báo cáo thông qua trait StatusReport. Các trường hợp ngoại lệ có thể được báo cáo là chặn hoặc không chặn.
- Các trường hợp ngoại lệ không chặn được báo cáo với trạng thái " THÀNH CÔNG" cho biết rằng trường hợp ngoại lệ này không ngăn việc bật hoặc tắt chuông báo động.
- Trường hợp ngoại lệ chặn được báo cáo có trạng thái "NGOẠI LỆ" cho biết rằng hoạt động bật hoặc tắt chuông báo động đã bị dừng do những trường hợp ngoại lệ này.
Sau đây là những mã ngoại lệ thường liên quan đến các hệ thống bảo mật:
doorOpen
: Một cánh cửa đang mở.windowOpen
: Một cửa sổ đang mở.isOpen
: Cảm biến phát hiện có vật nào đó đang mở (nhưng không biết đó là cửa ra vào hay cửa sổ).
Ví dụ: Ngoại lệ không chặn
Ví dụ này cho thấy một trường hợp ngoại lệ không chặn, trong đó hệ thống bảo mật đang bật ngay cả khi một cửa sổ được báo cáo là đang mở.
User | Đặt hệ thống an ninh ở mức bảo mật cao. |
Trợ lý Google | Ok, cửa sổ phía trước đang mở. Tôi đang bật hệ thống an ninh ở mức an ninh cao. |
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123" }], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true, "armLevel": "L2" } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "online": true, "isArmed": true, "currentArmLevel": "L2", "currentStatusReport": [ { "blocking": false, "priority": 0, "statusCode": "windowOpen", "deviceTarget": "sensor_id1" } ] } } ] } }
Ví dụ: Chặn ngoại lệ
User | Đặt hệ thống an ninh ở mức bảo mật cao. |
Trợ lý Google | Đã xảy ra lỗi khi điều khiển hệ thống an ninh. Cửa sổ phía trước đang mở. |
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123" }], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true, "armLevel": "L2" } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "online": true, "isArmed": false, "currentArmLevel": "L2", "currentStatusReport": [ { "blocking": true, "priority": 0, "statusCode": "windowOpen", "deviceTarget": "sensor_id1" } ] } } ] } }
Bật tính năng xác thực hai yếu tố
Nếu quy trình bật chuông báo động yêu cầu người dùng nhập mã PIN thông qua hộp thoại xác thực hai yếu tố, thì bạn phải xác nhận xem họ có muốn tiếp tục bật tính năng hệ thống khi có các ngoại lệ đang diễn ra (ví dụ: khi một cửa sổ hoặc cửa đang mở).
Trường hợp này có thể yêu cầu nhập cả mã PIN hoặc cụm mật khẩu, sau đó nhập xác nhận.
Ví dụ: Thử thách xác nhận
Ví dụ này cho thấy một người dùng đang cố bật hệ thống an ninh, nhưng cửa trước được phát hiện là đang mở. Người dùng xác nhận rằng hệ thống an ninh cần được bật ngay cả khi cửa trước đang mở.
User | Bật hệ thống an ninh. |
Trợ lý Google | Cửa trước đang mở. Bạn có chắc chắn muốn bật hệ thống an ninh không? |
User | Có. |
Trợ lý Google | Được rồi, tôi đang bật hệ thống an ninh. |
Trong lượt đầu tiên, bạn nên trả lời bằng một thử thách ackNeeded
.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123" }], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "ERROR", "errorCode": "challengeNeeded", "challengeNeeded": { "type": "ackNeeded" }, "states": { "isArmed": true, "currentArmLevel": "L2", "currentStatusReport": [ { "blocking": false, "priority": 0, "statusCode": "doorOpen", "deviceTarget": "456" } ] } } ] } }
Yêu cầu tiếp theo từ Google gửi đến bạn sẽ chứa kết quả ack
.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123" }], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true }, "challenge": { "ack": true } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "isArmed": true } } ] } }
Ví dụ: Xác nhận bằng mã PIN và xác nhận
Ví dụ này cho thấy một người dùng đang cố bật hệ thống bảo mật yêu cầu nhập mã PIN. Hệ thống phát hiện thấy cửa sổ trước và sau đang mở và yêu cầu người dùng xác nhận rằng sẽ tiếp tục bật chuông báo động.
User | Bật chuông báo động để vắng mặt. |
Trợ lý Google | Mã PIN của bạn là gì? |
User | 1234. |
Trợ lý Google | Có vẻ như cửa sổ trước và cửa sổ sau đang mở. Bạn có chắc chắn muốn tiếp tục bật hệ thống an ninh không? |
User | Có. |
Trợ lý Google | Được rồi, hãy bật hệ thống an ninh để mọi người rời đi |
Trong lượt đầu tiên, bạn nên trả lời bằng một thử thách pinNeeded
tiêu chuẩn.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123" }], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["456"], "status": "ERROR", "errorCode": "challengeNeeded", "challengeNeeded": { "type": "pinNeeded" } }] } }
Sau đó, Google sẽ gửi yêu cầu chứa mã PIN đã cung cấp. Để hỗ trợ lượt thứ hai, bạn nên phản hồi bằng thử thách ackNeeded
kèm theo thông tin bổ sung, bao gồm cấp nhóm mục tiêu và báo cáo trạng thái hiện tại có các ngoại lệ chặn.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [...], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true, "armLevel": "away" }, "challenge": { "pin": "1234" } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["456"], "status": "ERROR", "states": { "targetArmLevel": "away", "currentStatusReport": [{ "blocking": true, "priority": 1, "deviceTarget": "front_window_id", "statusCode": "deviceOpen" }, { "blocking": true, "priority": 1, "deviceTarget": "back_window_id", "statusCode": "deviceOpen" } ] }, "errorCode": "challengeNeeded", "challengeNeeded": { "type": "ackNeeded" } }] } }
Yêu cầu tiếp theo từ Google gửi đến bạn sẽ chỉ chứa kết quả ack
chứ không chứa mã PIN đã cung cấp trong lượt đầu tiên.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [...], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true, "armLevel": "away" }, "challenge": { "ack": true } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "isArmed": true } } ] } }