คู่มือระบบรักษาความปลอดภัยสมาร์ทโฮม
action.devices.types.SECURITYSYSTEM - เปิดและปิดระบบรักษาความปลอดภัยได้ อุปกรณ์เหล่านี้สามารถเปิดระบบรักษาความปลอดภัยได้หลายระดับ (เช่น อยู่บ้านและไม่อยู่บ้าน) และสามารถรายงานข้อมูลเกี่ยวกับเซ็นเซอร์บางตัว เช่น เซ็นเซอร์ที่ตรวจจับการเคลื่อนไหวหรือหน้าต่างที่เปิดอยู่
ประเภทนี้ระบุว่าอุปกรณ์ได้รับไอคอนระบบรักษาความปลอดภัย รวมถึงคำพ้องความหมายและนามแฝงที่เกี่ยวข้อง
ความสามารถของอุปกรณ์
โปรดดูรายละเอียดการใช้งานในเอกสารประกอบของลักษณะที่เกี่ยวข้อง เช่น แอตทริบิวต์และสถานะที่บริการควรรองรับ และวิธีสร้างการตอบกลับ EXECUTE และ QUERY
ลักษณะที่จำเป็น
คุณต้องใช้ลักษณะและคำสั่งเหล่านี้ หากอุปกรณ์ของคุณรองรับ หากอุปกรณ์ไม่รองรับลักษณะเหล่านี้ ให้ป้อนรหัสข้อผิดพลาดของ functionNotSupported ในการตอบกลับ QUERY หรือ EXECUTE ดูข้อมูลเพิ่มเติมที่ข้อผิดพลาดและข้อยกเว้น
ลักษณะที่แนะนำ
เราขอแนะนำให้ใช้ลักษณะเหล่านี้หากอุปกรณ์ของคุณมี อย่างไรก็ตาม คุณผสมและจับคู่จากลักษณะทั้งหมดที่มีอยู่เพื่อให้ตรงกับฟังก์ชันการทำงานของผลิตภัณฑ์ที่มีอยู่มากที่สุดได้
ข้อกำหนดด้านคุณภาพ
- เวลาในการตอบสนอง: ต้องน้อยกว่าหรือเท่ากับ 2000ms
- ความน่าเชื่อถือ: ต้องมากกว่าหรือเท่ากับ 97%
ตัวอย่างอุปกรณ์: ระบบรักษาความปลอดภัยแบบง่าย
ส่วนนี้มีตัวอย่างเพย์โหลด Intent ที่แสดง "ระบบรักษาความปลอดภัย" ทั่วไปตามประเภทอุปกรณ์และลักษณะข้างต้น หากคุณเพิ่มหรือนําลักษณะในการนําไปใช้ออก ให้แก้ไขคําตอบให้สอดคล้องกับการเปลี่ยนแปลงเหล่านั้น
ตัวอย่างการตอบกลับ 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 คุณรายงานข้อยกเว้นได้ว่าเป็นบล็อกหรือไม่บล็อก
- ข้อยกเว้นที่ไม่บล็อกที่รายงานโดยมีสถานะ "สําเร็จ" บ่งชี้ว่าข้อยกเว้นไม่ได้ป้องกันไม่ให้ระบบเปิดหรือปิดระบบ
- ข้อยกเว้นการบล็อกที่รายงานโดยมีสถานะเป็น "ข้อยกเว้น" บ่งบอกว่าระบบหยุดการเปิดหรือปิดระบบเนื่องจากข้อยกเว้นเหล่านี้
รหัสข้อยกเว้นที่มักเชื่อมโยงกับระบบรักษาความปลอดภัย ได้แก่
doorOpen: ประตูเปิดอยู่windowOpen: หน้าต่างเปิดอยู่isOpen: เซ็นเซอร์ตรวจพบว่ามีสิ่งของเปิดอยู่ (แต่ไม่ทราบว่าเป็นประตูหรือหน้าต่าง)
ตัวอย่าง: ข้อยกเว้นแบบไม่บล็อก
ตัวอย่างนี้แสดงข้อยกเว้นที่ไม่บล็อกซึ่งระบบรักษาความปลอดภัยเปิดอยู่แม้ว่าจะมีการรายงานว่าหน้าต่างเปิดอยู่
| ผู้ใช้ | ตั้งค่าระบบรักษาความปลอดภัยเป็นระดับสูง |
| Google Assistant | โอเค หน้าต่างด้านหน้าเปิดอยู่ กำลังเปิดใช้งานระบบรักษาความปลอดภัยเป็นระดับสูง |
{
"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 Assistant | เกิดข้อผิดพลาดในการควบคุมระบบรักษาความปลอดภัย หน้าต่างด้านหน้าเปิดอยู่ |
{
"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": "EXCEPTIONS",
"states": {
"online": true,
"isArmed": false,
"currentArmLevel": "L2",
"currentStatusReport": [
{
"blocking": true,
"priority": 0,
"statusCode": "windowOpen",
"deviceTarget": "sensor_id1"
}
]
}
}
]
}
}การเปิดระบบด้วยการตรวจสอบสิทธิ์แบบ 2 ปัจจัย
หากขั้นตอนการเปิดระบบกำหนดให้ผู้ใช้ป้อน PIN ผ่านกล่องโต้ตอบการตรวจสอบสิทธิ์แบบ 2 ปัจจัย คุณต้องรับทราบว่าผู้ใช้ต้องการเปิดระบบต่อไปหรือไม่เมื่อมีข้อยกเว้นที่ใช้งานอยู่ (เช่น เมื่อหน้าต่างหรือประตูเปิดอยู่)
สถานการณ์นี้อาจกำหนดให้ต้องป้อนทั้ง PIN หรือรหัสผ่าน ทั้ง 2 อย่าง ตามด้วยการรับทราบ
ตัวอย่าง: การยืนยันการยอมรับ
ตัวอย่างนี้แสดงผู้ใช้ที่พยายามเปิดระบบรักษาความปลอดภัย แต่ระบบตรวจพบว่าประตูหน้าเปิดอยู่ ผู้ใช้รับทราบว่าระบบรักษาความปลอดภัยควรเปิดใช้งานแม้ว่าประตูหน้าจะเปิดอยู่ก็ตาม
| ผู้ใช้ | เปิดใช้งานระบบรักษาความปลอดภัย |
| Google Assistant | ประตูหน้าเปิดอยู่ค่ะ คุณแน่ใจไหมว่าต้องการเปิดระบบรักษาความปลอดภัย |
| ผู้ใช้ | ได้ |
| Google Assistant | โอเค กำลังเปิดใช้งานระบบรักษาความปลอดภัย |
ในเทิร์นแรก คุณควรตอบกลับด้วยภารกิจ ackNeeded
{
"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": [
"123"
],
"status": "ERROR",
"errorCode": "challengeNeeded",
"challengeNeeded": {
"type": "ackNeeded"
},
"states": {
"isArmed": true,
"currentArmLevel": "L2",
"currentStatusReport": [
{
"blocking": false,
"priority": 0,
"statusCode": "doorOpen",
"deviceTarget": "456"
}
]
}
}
]
}
}คำขอที่ Google ส่งให้คุณในภายหลังจะมีผลการค้นหา ack
{
"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 ระบบตรวจพบว่าหน้าต่างด้านหน้าและด้านหลังเปิดอยู่ และขอให้ผู้ใช้ยืนยันว่าควรเปิดระบบต่อ
| ผู้ใช้ | เปิดระบบเป็น "ไม่อยู่บ้าน" |
| Google Assistant | โปรดระบุ PIN |
| ผู้ใช้ | 1234 |
| Google Assistant | ดูเหมือนว่าหน้าต่างด้านหน้าและหน้าต่างด้านหลังจะเปิดอยู่ คุณแน่ใจไหมว่าต้องการเดินหน้าเปิดระบบรักษาความปลอดภัยเป็น "ไม่อยู่บ้าน" |
| ผู้ใช้ | ได้ |
| Google Assistant | โอเค กำลังเปิดใช้งานระบบรักษาความปลอดภัยเป็น "ไม่อยู่บ้าน" |
ในเทิร์นแรก คุณควรตอบกลับด้วยpinNeededภารกิจมาตรฐาน
{ "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 ที่ระบุ หากต้องการรองรับการอุทธรณ์รอบที่ 2 คุณควรตอบกลับด้วยการอุทธรณ์ ackNeeded พร้อมข้อมูลเพิ่มเติม ซึ่งรวมถึงระดับกลุ่มเป้าหมายและรายงานสถานะปัจจุบันพร้อมข้อยกเว้นการบล็อก
{ "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 ที่ระบุไว้ในรอบแรก
{ "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 } } ] } }