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

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

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

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

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

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

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

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

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