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

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

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

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

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

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

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

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

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

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

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

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

مثال على استجابة 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. يمكن الإبلاغ عن الاستثناءات على أنّها مسموح بها أو غير مسموح بها.

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

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

  • 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
        }
      }
    ]
  }
}

إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0‏ ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0‏. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers‏. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.

تاريخ التعديل الأخير: 2025-05-17 (حسب التوقيت العالمي المتفَّق عليه)