دليل نظام أمان المنزل الذكي

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

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

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

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

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

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

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

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

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

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

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

نموذج رد المزامنة

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

نماذج أوامر التنفيذ

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

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