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 hệ thống an ninh. Bạn có thể đặt hệ thống ở nhiều mức độ bảo mật (ví dụ: ở nhà và vắng nhà) và hệ thống 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 bảo mật và một số từ đồng nghĩa cũng như tên thay thế có liên quan.

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

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 phải 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ó những đặc điểm và lệnh này (nếu có) trên thiết bị của mình. 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. Hãy xem phần Lỗi và trường hợp 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 thiết bị của bạn có hỗ trợ. Tuy nhiên, bạn có thể tự do kết hợp các đặc điểm có sẵn để phù hợp nhất với chức năng sản phẩm hiện có.

Ví dụ về thiết bị: 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 ở 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á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"
    }
  ]
}
Phản hồ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 mẫu của hàm QUERY

Yêu cầu
{
  "requestId": "6894439706274654514",
  "inputs": [
    {
      "intent": "action.devices.QUERY",
      "payload": {
        "devices": [
          {
            "id": "123"
          }
        ]
      }
    }
  ]
}
Phản hồi
{
  "requestId": "6894439706274654514",
  "payload": {
    "devices": {
      "123": {
        "status": "SUCCESS",
        "online": true,
        "isArmed": true,
        "currentArmLevel": "home_key",
        "currentStatusReport": [
          {
            "blocking": false,
            "deviceTarget": "123",
            "priority": 0,
            "statusCode": "lowBattery"
          }
        ]
      }
    }
  }
}

Ví dụ về các lệnh EXECUTE

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"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
Phản hồi
{
  "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 chế độ báo động

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. Bạn có thể báo cáo các trường hợp ngoại lệ là chặn hoặc không chặn.

  • Ngoại lệ không chặn được báo cáo với trạng thái "SUCCESS" cho biết ngoại lệ không ngăn chặn quá trình kích hoạt hoặc vô hiệu hoá.
  • Ngoại lệ chặn được báo cáo với trạng thái "EXCEPTIONS" cho biết rằng quá trình kích hoạt hoặc huỷ kích hoạt đã bị dừng do những ngoại lệ này.

Các mã ngoại lệ thường liên quan đến hệ thống bảo mật bao gồm:

  • doorOpen: Cửa đang mở.
  • windowOpen: Một cửa sổ đang mở.
  • 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 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 an ninh được bật chuông báo động ngay cả khi một 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ổ 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"
            }
          }]
        }]
      }
    }]
  }
Phản hồ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ụ: 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ổ 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"
              }
            ]
          }
        }
      ]
    }
  }

Tăng cường bảo mật bằng tính năng xác thực hai yếu tố

Nếu quy trình bật chế độ bảo vệ 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 chế độ bảo vệ 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ở).

Trường hợp này có thể yêu cầu cả việc nhập mã PIN hoặc cụm mật khẩu, sau đó là bước 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ố gắng bật hệ thống an ninh, nhưng hệ thống phát hiện thấy cửa trước đang mở. Người dùng xác nhận rằng hệ thống an ninh sẽ được bật ngay cả khi cửa trước đang mở.

Người dùng 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?
Người dùng 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 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
            }
          }]
        }]
      }
    }]
  }
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 đế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
            }
          }]
        }]
      }
    }]
  }
Phản hồi
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
      "commands": [
        {
          "ids": [
            "123"
          ],
          "status": "SUCCESS",
          "states": {
            "isArmed": true
          }
        }
      ]
    }
  }

Ví dụ: Thử thách về mã PIN và 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 an ninh và cần 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 nên tiếp tục bật chế độ bảo vệ.

Người dùng Bật chuông báo động ở chế độ 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ổ trước và cửa sổ sau đang mở. Bạn có chắc chắn muốn tiếp tục bật chế độ vắng nhà cho hệ thống an ninh không?
Người dùng Có.
Trợ lý Google Được thôi, tôi sẽ bật hệ thống an ninh ở chế độ vắng nhà

Trong lượt đầu tiên, bạn nên phản hồ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
          }
        }]
      }]
    }
  }]
}
Phản hồ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 kèm theo 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 kèm theo thông tin bổ sung, bao gồm cả cấp độ cánh tay mục tiêu và báo cáo trạng thái hiện tại có 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"
          }
        }]
      }]
    }
  }]
}
Phản hồ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 của Google gửi đến 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
          }
        }]
      }]
    }
  }]
}
Phản hồi
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "isArmed": true
        }
      }
    ]
  }
}