Leitfaden für Smart-Home-Sicherheitssysteme

action.devices.types.SECURITYSYSTEM – Sicherheitssysteme können scharf oder unscharf geschaltet werden. Sie können auf verschiedenen Sicherheitsstufen scharf geschaltet werden (z. B. zu Hause und abwesend) und können Informationen zu bestimmten Sensoren senden, z. B. zu Sensoren, die eine Bewegung oder ein offenes Fenster erkennen.

Dieser Typ gibt an, dass das Gerät das Symbol für das Sicherheitssystem und einige zugehörige Synonyme und Aliasse erhält.

Gerätefunktionen

Details zur Implementierung finden Sie in der entsprechenden Dokumentation zu Trait. Dazu gehören z. B. Attribute und Statusangaben, die Ihr Dienst unterstützen sollte, und Informationen zum Erstellen von EXECUTE- und QUERY-Antworten.

Erforderliche Merkmale

Diese Merkmale und Befehle sind gegebenenfalls für Ihr Gerät erforderlich. Wenn Ihr Gerät diese Merkmale nicht unterstützt, geben Sie den Fehlercode functionNotSupported in einer QUERY- oder EXECUTE-Antwort ein. Weitere Informationen finden Sie unter Fehler und Ausnahmen.

Diese Traits werden empfohlen, sofern sie für Ihr Gerät relevant sind. Sie können jedoch alle verfügbaren Merkmale beliebig kombinieren, um die Funktionalität Ihrer vorhandenen Produkte bestmöglich zu berücksichtigen.

Qualitätsanforderungen

  • Latenz:muss kleiner oder gleich 2.000 ms sein.
  • Zuverlässigkeit:muss größer oder gleich 97% sein.

Beispielgerät: Einfaches Sicherheitssystem

Dieser Abschnitt enthält Beispiel-Intent-Nutzlasten, die basierend auf dem oben genannten Gerätetyp und den obigen Eigenschaften ein gemeinsames Sicherheitssystem darstellen. Wenn Sie in Ihrer Implementierung Traits hinzufügen oder entfernen, passen Sie Ihre Antworten entsprechend an.

Beispiel für SYNC-Antwort

Anfrage
{
  "requestId": "6894439706274654512",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}
Antwort
{
  "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"
        }
      }
    ]
  }
}

Beispielantwort für QUERY

Anfrage
{
  "requestId": "6894439706274654514",
  "inputs": [
    {
      "intent": "action.devices.QUERY",
      "payload": {
        "devices": [
          {
            "id": "123"
          }
        ]
      }
    }
  ]
}
Antwort
{
  "requestId": "6894439706274654514",
  "payload": {
    "devices": {
      "123": {
        "status": "SUCCESS",
        "online": true,
        "isArmed": true,
        "currentArmLevel": "home_key",
        "currentStatusReport": [
          {
            "blocking": false,
            "deviceTarget": "123",
            "priority": 0,
            "statusCode": "lowBattery"
          }
        ]
      }
    }
  }
}

Beispiele für EXECUTE-Befehle

ArmDisarm

Weitere Informationen zu den Befehlsparametern finden Sie in der Referenz zu action.devices.traits.ArmDisarm.

Anfrage
{
  "requestId": "6894439706274654516",
  "inputs": [
    {
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [
          {
            "devices": [
              {
                "id": "123"
              }
            ],
            "execution": [
              {
                "command": "action.devices.commands.ArmDisarm",
                "params": {
                  "arm": true,
                  "armLevel": "away_key"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
Antwort
{
  "requestId": "6894439706274654516",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "isArmed": true,
          "currentArmLevel": "away_key"
        }
      }
    ]
  }
}

Gerät ERRORS

Sehen Sie sich die vollständige Liste der Fehler und Ausnahmen an.

Ausnahmen für das Scharfschalten von Berichten

Wenn Sie versuchen, das System scharf oder unscharf zu schalten, können Sie über Ausnahmecodes, die Sie über das Trait StatusReport melden, zusätzlichen Kontext bereitstellen. Ausnahmen können als blockierend oder nicht blockierend gemeldet werden.

  • Ausnahmen, die nicht zu einer Blockierung führen, werden mit dem Status "SUCCESS" gemeldet. Dies bedeutet, dass durch die Ausnahme das Scharf- oder Unscharfschalten nicht verhindert wurde.
  • Blockierungen von Ausnahmen, die mit dem Status „EXCEPTIONS“ (AUSNAHMEN) gemeldet werden, geben an, dass das Scharf- oder Unscharfschalten aufgrund dieser Ausnahmen gestoppt wurde.

Zu den Ausnahmecodes, die häufig mit Sicherheitssystemen in Verbindung gebracht werden, gehören:

  • doorOpen: Eine Tür ist offen.
  • windowOpen: Ein Fenster ist geöffnet.
  • isOpen: Ein Sensor erkennt, dass etwas geöffnet ist, kann aber nicht feststellen, ob es sich um eine Tür oder ein Fenster handelt.

Beispiel: Ausnahme, die nicht zu einer Blockierung führt

Dieses Beispiel zeigt eine nicht blockierende Ausnahme, bei der das Sicherheitssystem scharf geschaltet ist, obwohl ein Fenster als offen gemeldet wurde.

Nutzer Stell das Sicherheitssystem auf hohe Sicherheit.
Google Assistant Ok, das Fenster vorne ist offen. Das Sicherheitssystem wird auf hohe Sicherheit scharf geschaltet.
Anfrage
{
  "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"
          }
        }]
      }]
    }
  }]
}
Antwort
{
  "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"
            }
          ]
        }
      }
    ]
  }
}

Beispiel: Blockierungsausnahme

Nutzer Stell das Sicherheitssystem auf hohe Sicherheit.
Google Assistant Beim Steuern des Sicherheitssystems ist ein Fehler aufgetreten. Das Fenster vorne ist offen.
Anfrage
{
  "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"
          }
        }]
      }]
    }
  }]
}
Antwort 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"
            }
          ]
        }
      }
    ]
  }
}

Aktivierung mit 2-Faktor-Authentifizierung

Wenn Nutzer bei der Scharfschaltung eine PIN über ein Dialogfeld für die 2-Faktor-Authentifizierung eingeben müssen, müssen Sie bestätigen, ob sie das System weiterhin scharf schalten möchten, wenn es aktive Ausnahmen gibt (z. B. wenn ein Fenster oder eine Tür geöffnet ist).

In diesem Fall ist möglicherweise sowohl die Eingabe der PIN als auch die Eingabe einer Passphrase erforderlich, gefolgt von einer Bestätigung.

Beispiel: Bestätigungsanfrage

Dieses Beispiel zeigt, wie ein Nutzer versucht, das Sicherheitssystem scharf zu schalten, aber eine Haustür wurde als offen erkannt. Der Nutzer bestätigt, dass das Sicherheitssystem scharf geschaltet sein soll, obwohl die Haustür geöffnet ist.

Nutzer Schalte das Sicherheitssystem scharf.
Google Assistant Die Eingangstür ist unverschlossen. Möchten Sie das Sicherheitssystem wirklich scharf schalten?
Nutzer Ja.
Google Assistant Ok, das Sicherheitssystem wird scharf geschaltet.

In der ersten Runde sollten Sie mit der ackNeeded-Aufgabe antworten.

Anfrage 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
          }
        }]
      }]
    }
  }]
}
Antwort 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"
            }
          ]
        }
      }
    ]
  }
}

Die anschließende Anfrage von Google an Sie enthält das Ergebnis ack.

Anfrage 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
          }
        }]
      }]
    }
  }]
}
Antwort
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "isArmed": true
        }
      }
    ]
  }
}

Beispiel: PIN und Bestätigungsaufforderung

Dieses Beispiel zeigt, wie ein Nutzer versucht, das Sicherheitssystem scharf zu schalten, für das eine PIN-Eingabe erforderlich ist. Das System erkennt, dass die vorderen und hinteren Fenster geöffnet sind, und fordert den Nutzer auf, zu bestätigen, dass die Scharfschaltung fortgesetzt werden soll.

Nutzer Scharf schalten auf weg.
Google Assistant Wie lautet Ihre PIN?
Nutzer 1234.
Google Assistant Es sieht so aus, als seien die vorderen und die hinteren Fenster offen. Möchten Sie das Sicherheitssystem wirklich auf „Abwesend“ scharf schalten?
Nutzer Ja.
Google Assistant Ok, das Sicherheitssystem wird auf „Abwesend“ scharf geschaltet

In der ersten Runde sollten Sie mit einer standardmäßigen pinNeeded-Aufgabe antworten.

Anfrage 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
          }
        }]
      }]
    }
  }]
}
Antwort
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["456"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Google sendet Ihnen dann eine Anfrage, die die angegebene PIN enthält. Damit die zweite Abzweigung funktioniert, sollten Sie mit einer ackNeeded-Aufgabe antworten. Geben Sie zusätzliche Informationen an, einschließlich der Zielverzweigungsebene und des aktuellen Statusberichts mit Blockierausnahmen.

Anfrage 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"
          }
        }]
      }]
    }
  }]
}
Antwort
{
  "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"
      }
    }]
  }
}

Die nachfolgende Anfrage von Google an Sie enthält nur das Ergebnis ack und nicht die in der ersten Runde angegebene PIN.

Anfrage 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
          }
        }]
      }]
    }
  }]
}
Antwort
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "isArmed": true
        }
      }
    ]
  }
}