مرحبًا بك في "مركز مطوّري برامج Google Home"، وجهتك الجديدة لتعلّم كيفية تطوير إجراءات منزلية ذكية. ملاحظة: ستواصل إنشاء الإجراءات في وحدة تحكم الإجراءات.
تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

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

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

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

هذه السمات والأوامر مطلوبة، إذا كانت منطبقة على جهازك.

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

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

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

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

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

نموذج استجابة 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

إيقاف جهاز الإنذار

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

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

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

  • 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"
          }
        }]
      }]
    }
  }]
}
الرد الثاني
{
  "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"
            }
          ]
        }
      }
    ]
  }
}

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

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

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

مثال: اختبار الإقرار باستلام الشكر

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

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