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ể được bật và tắt. Hệ thống này có thể được bật ở nhiều mức an ninh (ví dụ: nhà và vắng nhà) và 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ị nhận được biểu tượng Hệ thống an ninh và một số từ đồng nghĩa và bí danh liên quan.

Khả năng của thiết bị

Hãy tham khảo tài liệu tương ứng về đặc điểm để 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 phản hồi EXECUTE và QUERY.

Đặc điểm bắt buộc

Bạn phải có các đặc điểm và lệnh này nếu thiết bị của bạn có áp dụng. Nếu thiết bị của bạn không hỗ trợ các đặc điểm này, hãy nhập mã lỗi functionNotSupported trong phản hồi QUERY hoặc EXECUTE. Xem phần Lỗi và trường hợp ngoại lệ để biết thêm thông tin.

Bạn nên có các đặc điểm này nếu thiết bị của bạn có áp dụng. Tuy nhiên, bạn có thể tự do 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 có của sản phẩm.

Thiết bị mẫu: 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 "Hệ thống an ninh" dựa trên loại thiết bị và các đặ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 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"
    }
  ]
}
Đáp
{
  "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"
          }
        ]
      }
    }
  ]
}
Đáp
{
  "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 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"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
Đáp
{
  "requestId": "6894439706274654516",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "isArmed": true,
          "currentArmLevel": "away_key"
        }
      }
    ]
  }
}

LỖI thiết bị

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

Báo cáo trường hợp ngoại lệ khi bật chuông báo động

Khi cố gắng bật hoặc tắt chuông báo động của hệ thống, bạn có thể cung cấp thêm ngữ cảnh thông qua mã trường hợp ngoại lệ mà bạn báo cáo thông qua đặc điểm StatusReport. Bạn có thể báo cáo trường hợp ngoại lệ là trường hợp ngoại lệ chặn hoặc không chặn.

  • Trường hợp ngoại lệ không chặn được báo cáo với trạng thái "SUCCESS" cho biết trường hợp ngoại lệ 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 với trạng thái "EXCEPTIONS" cho biết việc bật hoặc tắt chuông báo động đã bị dừng do các trường hợp ngoại lệ này.

Các mã trường hợp ngoại lệ thường liên kết với hệ thống an ninh bao gồm:

  • doorOpen: Cửa đang mở.
  • windowOpen: Cửa sổ đang mở.
  • isOpen: Cảm biến phát hiện thấy có gì đó đang mở (nhưng không biết đó là cửa hay cửa sổ).

Ví dụ: Trường hợp ngoại lệ không chặn

Ví dụ này cho thấy trường hợp ngoại lệ không chặn, trong đó hệ thống an ninh được bật ngay cả khi cửa sổ được báo cáo là đang mở.

Người dùng Đặ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.
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"
            }
          }]
        }]
      }
    }]
  }
Đáp
{
    "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ụ: Trường hợp ngoại lệ chặn

Người dùng Đặ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ở.
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 2
{
    "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 chuông báo động bằng 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 chuông báo động của hệ thống khi có các trường hợp ngoại lệ đang hoạt động hay không (ví dụ: khi cửa sổ hoặc cửa đang mở).

Tình huống này có thể yêu cầu cả mã PIN hoặc cụm mật khẩu, sau đó là xác nhận.

Ví dụ: Thử thách xác nhận

Ví dụ này cho thấy người dùng đang cố gắng bật chuông báo động của hệ thống an ninh, nhưng một 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 đang mở.

Người dùng Bật chuông báo động của 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 chuông báo động của hệ thống an ninh không?
Người dùng Có.
Trợ lý Google Được rồi, tôi đang bật chuông báo động của hệ thống an ninh.

Trong lượt đầu tiên, bạn nên phản hồi bằng 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âu trả lờ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 của Google gửi cho 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
            }
          }]
        }]
      }
    }]
  }
Đáp
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
      "commands": [
        {
          "ids": [
            "123"
          ],
          "status": "SUCCESS",
          "states": {
            "isArmed": true
          }
        }
      ]
    }
  }

Ví dụ: Thử thách xác nhận và mã PIN

Ví dụ này cho thấy người dùng đang cố gắng bật chuông báo động của hệ thống an ninh yêu cầu nhập mã PIN. Hệ thống phát hiện thấy cửa sổ phía trước và cửa sổ phía sau đang mở và yêu cầu người dùng xác nhận rằng việc bật chuông báo động sẽ tiếp tục.

Người dùng Bật chuông báo động khi vắng nhà.
Trợ lý Google Mã PIN của bạn là gì?
Người dùng 1234.
Trợ lý Google Có vẻ như cửa sổ phía trước và cửa sổ phía sau đang mở. Bạn có chắc chắn muốn tiếp tục bật chuông báo động của hệ thống an ninh khi vắng nhà không?
Người dùng Có.
Trợ lý Google Được rồi, tôi đang bật chuông báo động của hệ thống an ninh khi vắng nhà

Trong lượt đầu tiên, bạn nên phản hồi bằng 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
          }
        }]
      }]
    }
  }]
}
Đáp
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["456"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Sau đó, Google sẽ tiếp tục bằng một yêu cầu chứa mã PIN được cung cấp. Để hỗ trợ lượt thứ hai, bạn nên phản hồi bằng thử thách ackNeeded có thông tin bổ sung, bao gồm cả mức bật chuông báo động mục tiêu và báo cáo trạng thái hiện tại với các trường hợp 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"
          }
        }]
      }]
    }
  }]
}
Đáp
{
  "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 của Google gửi cho bạn sẽ chỉ chứa kết quả ack chứ không phải mã PIN được 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
          }
        }]
      }]
    }
  }]
}
Đáp
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "isArmed": true
        }
      }
    ]
  }
}