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

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": "PENDING",
        "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
        }
      }
    ]
  }
}