دليل نظام أمان المنزل المزوّد بأجهزة ذكية

action.devices.types.SECURITYSYSTEM - يمكن تفعيل أنظمة الأمان وإيقافها. يمكن تفعيل جهاز الإنذار على مستويات أمان متعدّدة (مثلاً في المنزل والخارج)، ويمكنه الإبلاغ عن معلومات حول أجهزة استشعار معيّنة، مثل جهاز استشعار يرصد حركة أو نافذة مفتوحة.

يشير هذا النوع إلى أنّ الجهاز يعرض رمز "نظام الأمان" وبعض المرادفات والأسماء المستعارة ذات الصلة.

إمكانات الجهاز

يمكنك الرجوع إلى وثائق السمات المقابلة لتفاصيل التنفيذ، مثل السمات والحالات التي يجب أن تدعمها خدمتك، وكيفية إنشاء استجابات EXECUTE وQUERY.

السمات المطلوبة

هذه السمات والأوامر مطلوبة، إذا كانت منطبقة على جهازك. إذا كان جهازك لا يتيح استخدام هذه السمات، أدخِل رمز الخطأ functionNotSupported في الاستجابة QUERY أو EXECUTE. يمكنك الاطّلاع على الأخطاء والاستثناءات لمعرفة مزيد من المعلومات.

يُنصح باستخدام هذه السمات إذا كانت مناسبة لجهازك. ومع ذلك، لك مطلق الحرية في مزج جميع السمات المتاحة ومطابقتها لمطابقة وظائف منتجك الحالية بأفضل شكل.

متطلبات الجودة

  • وقت الاستجابة: يجب أن يكون أقل من 2000 ملي ثانية أو يساويه.
  • الموثوقية: يجب أن تزيد عن 97% أو تساويها.

مثال على الجهاز: نظام أمان بسيط

يحتوي هذا القسم على أمثلة على حمولات النية التي تمثّل "نظام أمان" شائعًا استنادًا إلى نوع الجهاز والسمات الواردة أعلاه. في حال إضافة سمات أو إزالتها في عملية التنفيذ، عدِّل إجاباتك وفقًا لذلك لتعكس هذه التغييرات.

نموذج استجابة المزامنة

طلب
{
  "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. يمكن الإبلاغ عن الاستثناءات باعتبارها حظرًا أو لا تحظر.

  • تشير الاستثناءات التي لا تحظر التي تم الإبلاغ عنها بالحالة "تم بنجاح" إلى أنّ الاستثناء لم يمنع التفعيل أو الإيقاف.
  • تشير استثناءات الحظر التي تم الإبلاغ عنها بالحالة "استثناءات" إلى أنّ عملية الإيقاف أو الإيقاف قد تم إيقافها بسبب هذه الاستثناءات.

تتضمّن رموز الاستثناء المرتبطة عادةً بأنظمة الأمان ما يلي:

  • 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": "SUCCESS",
        "states": {
          "online": true,
          "isArmed": false,
          "currentArmLevel": "L2",
          "currentStatusReport": [
            {
              "blocking": true,
              "priority": 0,
              "statusCode": "windowOpen",
              "deviceTarget": "sensor_id1"
            }
          ]
        }
      }
    ]
  }
}

تفعيل ميزة "المصادقة الثنائية"

إذا كانت عملية التفعيل تتطلّب من المستخدمين إدخال رقم التعريف الشخصي من خلال مربّع حوار المصادقة الثنائية، عليك الموافقة على ما إذا كانوا يريدون مواصلة تفعيل النظام عند وجود استثناءات نشطة (على سبيل المثال، عندما يكون هناك نافذة أو باب مفتوح).

قد يتطلب هذا السيناريو كلاً من إدخال رقم التعريف الشخصي أو عبارة المرور، متبوعًا بإقرار.

مثال: تحدّي الإقرار

يعرض هذا المثال مستخدمًا يحاول تفعيل نظام الأمان، ولكن تم رصد فتح باب أمامي. يقرّ المستخدم بأنّه يجب تفعيل نظام الأمان على الرغم من فتح الباب الأمامي.

المستخدم تَفْعِيلْ جِهَازِ الْإِنْذَارْ فِي نِظَامِ الْأَمَانْ.
مساعد 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
        }
      }
    ]
  }
}

مثال: رقم التعريف الشخصي وتحدّي الإقرار

يعرض هذا المثال مستخدمًا يحاول تفعيل نظام الأمان يتطلب إدخال رقم التعريف الشخصي. يكتشف النظام أنّ النوافذ الأمامية والخلفية مفتوحة، ويطلب من المستخدم الإقرار بضرورة مواصلة عملية تفعيل جهاز الإنذار.

المستخدم تفعيل جهاز الإنذار وإبعاده
مساعد Google ما هو رقم تعريفك الشخصي؟
المستخدم 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 طلبًا يحتوي على رقم التعريف الشخصي الذي تم تقديمه. لإتاحة الدور الثاني، يجب الاستجابة باستخدام تحدٍّ 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
        }
      }
    ]
  }
}