智慧型住宅保全系統指南

action.devices.types.SECURITYSYSTEM：保全系統可啟動及解除。這類攝影機可在多層安全等級 (例如在家和外出) 下啟動，並回報特定感應器的相關資訊，例如可偵測動作或未開啟窗戶的感應器。

這個類型表示裝置會得到保全系統圖示 同義詞和別名

裝置功能

請參閱 導入詳細資料，例如服務應支援的屬性和狀態，以及 建立「EXECUTE」和「QUERY」回應。

必要特性

您必須具有這些特徵和指令 (如果有的話) 裝置。如果您的裝置不支援這些特徵，請輸入 在 QUERY 或 EXECUTE 回應中使用 functionNotSupported。詳情請見 詳情請參閱錯誤和例外狀況。

建議您採用這些特性 (如果裝置適用的話)。 不過，您可以自由搭配運用所有可用的特徵，完美搭配 產品功能。

品質規定

  • 延遲時間：必須小於或等於 2000 毫秒。
  • 可靠性：必須大於或等於 97%。

裝置範例：簡易型安全防護系統

本節包含代表常見「保全系統」的意圖酬載範例 根據上述裝置類型和特徵建立廣告如果您在實作中新增或移除特徵， 請據此修改回應。

SYNC 回應範例

要求
，瞭解如何調查及移除這項存取權。 
{
  "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"
        }
      }
    ]
  }
}

QUERY 回應範例

要求
，瞭解如何調查及移除這項存取權。 
{
  "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"
          }
        ]
      }
    }
  }
}

EXECUTE 指令範例

ArmDisarm

如要進一步瞭解指令參數 請參閱 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"
        }
      }
    ]
  }
}

裝置錯誤

查看完整清單 錯誤和例外狀況。

回報啟動例外狀況

當您試圖啟動或解除系統時，可以提供額外的 例外狀況代碼 透過 StatusReport 特徵回報 例外狀況可以回報為封鎖或非封鎖。

  • 報告含有「成功」的非封鎖例外狀況狀態表示 例外狀況並未妨礙啟動或解除
  • 傳回「EXCEPTIONS」的封鎖例外狀況狀態表示正在啟動 或解除警報狀態

與安全系統相關的例外狀況代碼包括：

  • doorOpen：有一扇門開著。
  • windowOpen：視窗已開啟。
  • isOpen：感應器偵測到東西處於開啟狀態 (但不知情) 例如門、窗口)。
，瞭解如何調查及移除這項存取權。

示例：非封鎖的例外狀況

此範例顯示一個非阻塞例外狀況，其中保全系統 會啟動。

使用者 將保全系統設為「高安全性」
Google 助理 好的，前窗 已開啟。正在將保全系統啟動到高安全性狀態
要求
，瞭解如何調查及移除這項存取權。 
{
    "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"
              }
            ]
          }
        }
      ]
    }
  }

範例：封鎖例外狀況

使用者 將保全系統設為「高安全性」
Google 助理 發生錯誤 並控管保全系統前門已開啟。
要求
，瞭解如何調查及移除這項存取權。 
{
    "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"
            }
          }]
        }]
      }
    }]
  }
回覆 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"
              }
            ]
          }
        }
      ]
    }
  }

使用雙重驗證啟動系統

如果啟動流程需要使用者透過 「雙重驗證」對話方塊 您必須確認，當其啟動狀態時，是否要繼續啟動系統 例外狀況 (例如窗戶或門開啟時)。

這類情況可能需要「同時」輸入 PIN 碼或通關密語，接著加上確認訊息。

例如：認可驗證問題

這個範例顯示使用者嘗試啟動保全系統 偵測到前門已開啟使用者確認 系統應該先啟動系統，

使用者 啟動保全系統
Google 助理 前門已開啟。 確定要啟動保全系統嗎？
使用者 是。
Google 助理 好的，啟動 和安全性系統

第一次回合，您應該透過 ackNeeded 挑戰回應。

要求 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
            }
          }]
        }]
      }
    }]
  }
回覆 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"
              }
            ]
          }
        }
      ]
    }
  }

Google 後續傳送給您的要求會包含 ack 結果。

要求 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
            }
          }]
        }]
      }
    }]
  }
回應
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
      "commands": [
        {
          "ids": [
            "123"
          ],
          "status": "SUCCESS",
          "states": {
            "isArmed": true
          }
        }
      ]
    }
  }

例如：PIN 碼和確認驗證問題

這個範例顯示使用者嘗試啟動需要 PIN 碼的保全系統。 系統偵測到正面和後側視窗已開啟，並要求使用者確認 啟動的 Pod

使用者 主動出擊，
Google 助理 請提供你的 PIN 碼
使用者 1234。
Google 助理 這看起來像 前視窗和後車窗已開啟確定要繼續嗎 要啟動保全系統嗎？
使用者 是。
Google 助理 好的，啟動 保全系統

第一次回合，您應以標準的 pinNeeded 挑戰做出回應。

要求 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
          }
        }]
      }]
    }
  }]
}
回應
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["456"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

接著，Google 會再傳送要求您提供 PIN 碼的要求。為了提供支援 第二次輪到，您應該以 ackNeeded 挑戰回應，並加上 包括目標實驗組層級，以及目前的狀態報表 封鎖例外狀況

要求 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"
          }
        }]
      }]
    }
  }]
}
回應
{
  "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"
      }
    }]
  }
}

Google 後續傳送給您的要求中只會包含 ack 結果， 而不是一開始的 PIN 碼

要求 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
          }
        }]
      }]
    }
  }]
}
回應
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "isArmed": true
        }
      }
    ]
  }
}