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

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

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

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

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

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

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

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

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

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

نموذج استجابة 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 حسنًا، النافذة الأمامية مفتوحة. يَتِمُّ الْآنَ تَفْعِيلُ جِهَازِ الْإِنْذَارْ فِي نِظَامِ الْأَمَانْ عَلَى مُسْتَوَى أَمَانْ عَالٍ.
طلب
{
    "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"
              }
            ]
          }
        }
      ]
    }
  }

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

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

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

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

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

المستخدم فعِّل نظام الأمان.
مساعد 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 تحدٍّ يتضمّن معلومات إضافية، بما في ذلك مستوى ARM المستهدف وتقرير الحالة الحالي الذي يتضمّن استثناءات الحظر.

الطلب 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
        }
      }
    ]
  }
}