راهنمای سیستم امنیتی خانه هوشمند

action.devices.types.SECURITYSYSTEM - سیستم های امنیتی را می توان مسلح و خلع سلاح کرد. آنها می توانند در سطوح امنیتی متعددی مسلح شوند (به عنوان مثال، خانه و خارج از خانه) و می توانند اطلاعات مربوط به سنسورهای خاص را گزارش کنند، مانند حسگری که حرکت را تشخیص می دهد یا یک پنجره باز.

این نوع نشان می‌دهد که دستگاه نماد سیستم امنیتی و برخی از مترادف‌ها و نام‌های مستعار مرتبط را دریافت می‌کند.

قابلیت های دستگاه

برای جزئیات پیاده‌سازی، مانند ویژگی‌ها و حالت‌هایی که سرویس شما باید از آنها پشتیبانی کند، و نحوه ایجاد پاسخ‌های EXECUTE و QUERY، به اسناد ویژگی مربوطه مراجعه کنید.

صفات مورد نیاز

این صفات و دستورات، در صورت وجود برای دستگاه شما، مورد نیاز هستند. اگر دستگاه شما از این ویژگی ها پشتیبانی نمی کند، کد خطای functionNotSupported را در پاسخ QUERY یا EXECUTE وارد کنید. برای اطلاعات بیشتر به خطاها و استثناها مراجعه کنید.

این ویژگی‌ها در صورت وجود برای دستگاه شما توصیه می‌شوند. با این حال، شما آزاد هستید که تمام ویژگی‌های موجود را با هم ترکیب کنید تا به بهترین نحو با عملکرد محصول موجود خود مطابقت داشته باشد.

الزامات کیفیت

  • تأخیر: باید کمتر یا مساوی 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

خلع سلاح

برای جزئیات بیشتر در مورد پارامترهای فرمان، به مرجع 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 : یک حسگر تشخیص می دهد که چیزی باز است (اما نمی داند در است یا پنجره).

مثال: استثنای غیر مسدود کننده

این مثال یک استثنا غیر مسدود کننده را نشان می دهد که در آن سیستم امنیتی مسلح است حتی اگر یک پنجره به عنوان باز گزارش شود.

کاربر سیستم امنیتی را روی امنیت بالا تنظیم کنید.
دستیار گوگل باشه جلو پنجره بازه مسلح کردن سیستم امنیتی به امنیت بالا
درخواست کنید 
{
    "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"
              }
            ]
          }
        }
      ]
    }
  }

مثال: استثنا مسدود کردن

کاربر سیستم امنیتی را روی امنیت بالا تنظیم کنید.
دستیار گوگل در کنترل سیستم امنیتی خطایی روی داد. جلو پنجره باز است.
درخواست کنید 
{
    "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"
              }
            ]
          }
        }
      ]
    }
  }

مسلح شدن با احراز هویت دو مرحله ای

اگر جریان تسلیح شما به کاربران نیاز دارد که یک پین را از طریق یک گفتگوی احراز هویت دو مرحله ای وارد کنند، باید تصدیق کنید که آیا آنها مایلند در صورت وجود استثنائات فعال (مثلاً زمانی که یک پنجره یا در باز است) به مسلح کردن سیستم ادامه دهند یا خیر .

این سناریو ممکن است به هر دو وارد کردن پین یا عبارت عبور نیاز داشته باشد و به دنبال آن یک تأیید باشد.

مثال: چالش قدردانی

این مثال کاربری را نشان می‌دهد که سعی می‌کند سیستم امنیتی را مسلح کند، اما درب ورودی باز است. کاربر تصدیق می کند که سیستم امنیتی باید مسلح باشد حتی اگر درب جلو باز است.

کاربر سیستم امنیتی را مسلح کنید.
دستیار گوگل درب ورودی باز است. آیا مطمئن هستید که می خواهید سیستم امنیتی را مسلح کنید؟
کاربر بله.
دستیار گوگل بسیار خوب، سیستم امنیتی را مسلح کنید.

در نوبت اول، باید با یک چالش 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
          }
        }
      ]
    }
  }

مثال: پین و چالش تایید

این مثال کاربری را نشان می دهد که تلاش می کند سیستم امنیتی را که به ورودی پین نیاز دارد مسلح کند. سیستم تشخیص می‌دهد که پنجره‌های جلو و عقب باز هستند و از کاربر می‌خواهد تأیید کند که مسلح کردن باید ادامه یابد.

کاربر بازو به دور.
دستیار گوگل پین شما چیست؟
کاربر 1234.
دستیار گوگل به نظر می رسد جلو پنجره و پشت پنجره باز هستند. آیا مطمئن هستید که می خواهید به مسلح کردن سیستم امنیتی برای دور کردن ادامه دهید؟
کاربر بله.
دستیار گوگل بسیار خوب، سیستم امنیتی را مسلح کنید

در نوبت اول، باید با یک چالش استاندارد 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 درخواستی حاوی پین ارائه شده را پیگیری می کند. به منظور حمایت از نوبت دوم، باید با یک چالش 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 است و نه پین ​​ارائه شده در نوبت اول.

درخواست 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
        }
      }
    ]
  }
}