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.

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

Yêu cầu
{
  "requestId": "6894439706274654512",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}
Câu trả lời
{
  "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

Yêu cầu
{
  "requestId": "6894439706274654514",
  "inputs": [
    {
      "intent": "action.devices.QUERY",
      "payload": {
        "devices": [
          {
            "id": "123"
          }
        ]
      }
    }
  ]
}
Câu trả lời
{
  "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.

Yêu cầu
{
  "requestId": "6894439706274654516",
  "inputs": [
    {
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [
          {
            "devices": [
              {
                "id": "123"
              }
            ],
            "execution": [
              {
                "command": "action.devices.commands.ArmDisarm",
                "params": {
                  "arm": true,
                  "armLevel": "away_key"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
Câu trả lời
{
  "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.
Yêu cầu
{
  "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"
          }
        }]
      }]
    }
  }]
}
Câu trả lời
{
  "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ở.
Yêu cầu
{
  "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"
          }
        }]
      }]
    }
  }]
}
Cách phản hồi 2
{
  "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.

Yêu cầu 1
{
  "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
          }
        }]
      }]
    }
  }]
}
Cách phản hồi 2
{
  "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.

Yêu cầu 2
{
  "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
          }
        }]
      }]
    }
  }]
}
Câu trả lời
{
  "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.

Yêu cầu 1
{
  "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
          }
        }]
      }]
    }
  }]
}
Câu trả lời
{
  "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.

Yêu cầu 2
{
  "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"
          }
        }]
      }]
    }
  }]
}
Câu trả lời
{
  "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.

Yêu cầu 3
{
  "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
          }
        }]
      }]
    }
  }]
}
Câu trả lời
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "isArmed": true
        }
      }
    ]
  }
}