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ị có biểu tượng Hệ thống an ninh và một số từ đồng nghĩa và bí danh.

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

Tham khảo tài liệu về đặc điểm tương ứng cho 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 sẽ hỗ trợ cũng như cách tạo các phản hồi EXECUTE và QUERY.

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

Đây là những đặc điểm và lệnh bắt buộc, nếu phù hợp thiết bị. 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. Xem Lỗi và ngoại lệ để biết thêm thông tin.

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 hiện tại của mình chức năng 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 chứa 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 nêu trên. Nếu bạn thêm hoặc xoá các đặc điểm trong quá trình triển khai, 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

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 action.devices.traits.ArmDisarm tham chiếu.

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ị ERRORS

Xem toàn bộ danh sách lỗi và ngoại lệ.

Báo cáo trường hợp ngoại lệ về chuông báo

Khi tìm cách 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 đặc điểm 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 bằng thông báo "FAILED" trạng thái cho biết rằng ngoại lệ không ngăn được 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 bằng "EXCEPTIONS" trạng thái cho biết rằng việc bật chuông báo động 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) nếu đó là cửa ra vào hoặc cửa sổ).

Ví dụ: Ngoại lệ không chặn

Ví dụ này cho thấy một ngoại lệ không tuần tự trong đó hệ thống an ninh đượ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, từ 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 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 đang đ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"
            }
          }]
        }]
      }
    }]
  }
Phản hồ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 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ố bạn phải xác nhận xem họ có muốn tiếp tục bật tính năng báo động cho hệ thống hay không khi có các trường hợp ngoại lệ (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 tính năng bảo mật phải bật hệ thống 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 Được rồi, tôi đang bật chuông báo động 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.

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
            }
          }]
        }]
      }
    }]
  }
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 mà 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
            }
          }]
        }]
      }
    }]
  }
Câu trả lời
{
    "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 cần tiến hành 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 không bật hệ thống an ninh để tắt chế độ này?
User Có.
Trợ lý Google Được rồi, tôi đang bật chuông báo động hệ thống an ninh sang vắng nhà

Ở 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 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 một thử thách ackNeeded với 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 chặn ngoại lệ.

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 mà 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 ở 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
        }
      }
    ]
  }
}