Hướng dẫn về hệ thống an ninh nhà thông minh
action.devices.types.SECURITYSYSTEM – Hệ thống an ninh có thể đang bật và tắt. Chúng có thể được bật ở nhiều cấp độ an ninh (ví dụ: ở nhà và vắng nhà), cũng như 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à bí danh 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ề việc 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 phản hồi EXECUTE và QUERY.
Đặc điểm bắt buộc
Các đặc điểm và lệnh này là bắt buộc, nếu phù hợp với thiết bị của bạn. Nếu thiết bị của bạn không hỗ trợ những đặc điểm này, hãy nhập mã lỗi của functionNotSupported trong 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.
Đặc điểm được đề xuất
Bạn nên 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ể thoải mái kết hợp tất cả các đặc điểm có sẵn để phù hợp nhất với chức năng hiện tại của sản phẩm.
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 trình bày các tải trọng ý định mẫu đại diện cho một "Hệ thống bảo mật" chung dựa trên loại thiết bị và đặc điểm ở trên. Nếu bạn thêm hoặc xoá các đặc điểm trong quá trình triển khai, hãy sửa đổi câu trả lời của bạn sao 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ị ERRORS
Xem danh sách đầy đủ các lỗi và ngoại lệ.Báo cáo trường hợp ngoại lệ về chuông báo
Khi cố gắng bật hoặc tắt hệ thống, bạn có thể cung cấp thêm ngữ cảnh thông qua mã ngoại lệ mà bạn báo cáo thông qua trait StatusReport. Các 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 có trạng thái "thành công" cho biết ngoại lệ đó không ngăn việc bật hoặc tắt chuông báo động.
- Các trường hợp ngoại lệ chặn được báo cáo có trạng thái "EXCEPTIONS" cho biết rằng hành động bật hoặc tắt chuông báo động đã bị dừng do những ngoại lệ này.
Các mã ngoại lệ thường liên quan đến các hệ thống bảo mật bao gồm:
doorOpen: Một cánh cửa đang mở.windowOpen: Một cửa sổ đang mở ra.isOpen: Cảm biến phát hiện thấy có thứ gì đó đ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 tuần tự, trong đó hệ thống bảo mật được 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 an ninh cao. |
| Trợ lý Google | Được rồi, 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 trường hợp ngoại lệ
| User | Đặt hệ thống an ninh ở mức an ninh 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": "EXCEPTIONS",
"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 của bạn 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 hệ thống hay không khi có các trường hợp ngoại lệ đang hoạt động (ví dụ: khi cửa sổ hoặc cửa ra vào đang mở).
Trong trường hợp này, bạn có thể cần nhập cả mã PIN hoặc cụm mật khẩu, sau đó 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 cố gắng 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 phải được bật ngay cả khi cửa trước 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 | Tôi đang bật hệ thống an ninh. |
Ở lượt đầu tiên, bạn nên phản hồ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 mà Google gửi cho 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ụ: Mã PIN và thử thách xác nhận
Ví dụ này cho thấy một người dùng đang cố gắng kích hoạt hệ thống bảo mật và yêu cầu nhập mã PIN. Hệ thống phát hiện thấy cửa sổ trước và cửa sổ sau đang mở và yêu cầu người dùng xác nhận rằng cần tiếp tục bật chuông báo động.
| User | Bật chuông báo động để vắng nhà. |
| 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 để tắt chế độ này không? |
| User | Có. |
| Trợ lý Google | Được rồi, tôi đang tắt hệ thống an ninh |
Ở 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 gửi cho bạn một yêu cầu chứa mã PIN mà bạn 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ả cấp nhóm mục tiêu và báo cáo trạng thái hiện tại kèm theo các trường hợp ngoại lệ về việc 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 mà Google gửi cho bạn sẽ chỉ chứa kết quả ack,
chứ không chứa mã PIN đã cung cấp ở 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
}
}
]
}
}