Akıllı Ev Güvenlik Sistemi Kılavuzu

action.devices.types.SECURITYSYSTEM: Güvenlik sistemleri etkinleştirilebilir ve devre dışı bırakılabilir. Birden fazla güvenlik düzeyinde (ör. evde ve evde değil) etkinleştirilebilir ve hareket veya açık pencere algılayan sensörler gibi belirli sensörlerle ilgili bilgileri bildirebilirler.

Bu tür, cihazın Güvenlik Sistemi simgesini ve bazı ilgili eş anlamlı kelimeleri ve takma adları aldığını gösterir.

Cihaz özellikleri

Hizmetinizin desteklemesi gereken özellikler ve durumlar gibi uygulama ayrıntıları ve EXECUTE ile QUERY yanıtlarının nasıl oluşturulacağı hakkında bilgi edinmek için ilgili özellik dokümanlarına bakın.

Zorunlu özellikler

Cihazınız için geçerliyse bu özellikler ve komutlar gereklidir. Cihazınız bu özellikleri desteklemiyorsa bir QUERY veya EXECUTE yanıtına functionNotSupported hata kodunu girin. Daha fazla bilgi için Hatalar ve istisnalar bölümüne bakın.

Cihazınız için geçerliyse bu özellikler önerilir. Ancak mevcut ürün işlevinize en uygun şekilde tüm özellikleri bir araya getirebilirsiniz.

Kalite gereksinimleri

  • Gecikme: 2000 ms'den az veya eşit olmalıdır.
  • Güvenilirlik: %97'den büyük veya buna eşit olmalıdır.

Örnek cihaz: Basit güvenlik sistemi

Bu bölümde, yukarıdaki cihaz türüne ve özelliklere göre yaygın bir "Güvenlik Sistemi"ni temsil eden örnek intent yüklemeleri yer almaktadır. Uygulamanızda özellik ekler veya kaldırırsanız bu değişiklikleri yansıtacak şekilde yanıtlarınızı değiştirin.

Örnek SYNC yanıtı

İstek
{
  "requestId": "6894439706274654512",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}
Yanıt
{
  "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"
        }
      }
    ]
  }
}

Örnek QUERY yanıtı

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

Örnek EXECUTE komutları

ArmDisarm

Komut parametreleri hakkında daha fazla bilgi için action.devices.traits.ArmDisarm referansına bakın.

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

Cihaz HATALARI

Hataların ve istisnaların tam listesini inceleyin.

Silahlanma istisnalarını bildirme

Sistemi etkinleştirmeye veya devre dışı bırakmaya çalışırken StatusReport özelliği aracılığıyla bildirdiğiniz istisna kodları aracılığıyla ek bağlam sağlayabilirsiniz. İstisnalar, engelleyen veya engellemeyen olarak bildirilebilir.

  • "SUCCESS" durumuyla raporlanan engellemeyen istisnalar, istisnanın arming veya disarming işlemini engellemediğini gösterir.
  • "EXCEPTIONS" durumuyla bildirilen engelleme istisnaları, silahlandırmanın veya silahsızlandırmanın bu istisnalar nedeniyle durdurulduğunu gösterir.

Güvenlik sistemleriyle sıklıkla ilişkilendirilen istisna kodları şunlardır:

  • doorOpen: Bir kapı açık.
  • windowOpen: Bir pencere açıktır.
  • isOpen: Bir sensör, açık bir şey algılar (ancak bunun kapı mı yoksa pencere mi olduğunu bilmez).

Örnek: Engellemeyen istisna

Bu örnekte, bir pencere açık olarak bildirilmesine rağmen güvenlik sisteminin etkinleştirildiği engellenmeyen bir istisna gösterilmektedir.

Kullanıcı Güvenlik sistemini yüksek güvenliğe ayarlayın.
Google Asistan Tamam, ön pencere açık. Güvenlik sistemini yüksek güvenlik modunda etkinleştiriyorum.
İstek
{
    "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"
            }
          }]
        }]
      }
    }]
  }
Yanıt
{
    "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"
              }
            ]
          }
        }
      ]
    }
  }

Örnek: Engelleme istisnası

Kullanıcı Güvenlik sistemini yüksek güvenliğe ayarlayın.
Google Asistan Güvenlik sistemi kontrol edilirken hata oluştu. Ön pencere açık.
İstek
{
    "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"
            }
          }]
        }]
      }
    }]
  }
Yanıt 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"
              }
            ]
          }
        }
      ]
    }
  }

İki faktörlü kimlik doğrulamayı etkinleştirme

Etkinleştirme akışınızda kullanıcıların iki faktörlü kimlik doğrulama iletişim kutusu aracılığıyla PIN girmesi gerekiyorsa etkin istisnalar (ör. açık bir pencere veya kapı) olduğunda sistemi etkinleştirmeye devam etmek isteyip istemediklerini onaylamanız gerekir.

Bu senaryoda, PIN veya şifre girişinin hemen ardından onay gerekebilir.

Örnek: Onay istemi

Bu örnekte, bir kullanıcının güvenlik sistemini etkinleştirmeye çalıştığı ancak ön kapının açık olduğu algılandığı gösterilmektedir. Kullanıcı, ön kapı açık olsa bile güvenlik sisteminin etkinleştirilmesi gerektiğini kabul eder.

Kullanıcı Güvenlik sistemini etkinleştirin.
Google Asistan Ön kapı açık. Güvenlik sistemini etkinleştirmek istediğinizden emin misiniz?
Kullanıcı Evet.
Google Asistan Tamam, güvenlik sistemini etkinleştiriyorum.

İlk turda ackNeeded meydan okuması ile yanıt vermelisiniz.

İstek 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
            }
          }]
        }]
      }
    }]
  }
Yanıt 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'ın size göndereceği sonraki istek, ack sonucunu içerir.

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

Örnek: PIN ve onay istemi

Bu örnekte, PIN girişi gerektiren güvenlik sistemini etkinleştirmeye çalışan bir kullanıcı gösterilmektedir. Sistem, ön ve arka camların açık olduğunu algılar ve kullanıcıdan, arming işleminin devam etmesini onaylamasını ister.

Kullanıcı Dışarıda modunda etkinleştirin.
Google Asistan PIN'iniz nedir?
Kullanıcı 1234.
Google Asistan Ön ve arka pencereler açık Güvenlik sistemini uzaktan etkinleştirmeye devam etmek istediğinizden emin misiniz?
Kullanıcı Evet.
Google Asistan Tamam, güvenlik sistemini evde değil moduna geçiriyorum.

İlk turda standart bir pinNeeded meydan okuması ile yanıt vermeniz gerekir.

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

Ardından Google, sağlanan PIN'i içeren bir istek gönderir. İkinci turu desteklemek için, hedef kol seviyesi ve engelleme istisnaları içeren mevcut durum raporu da dahil olmak üzere ek bilgiler içeren bir ackNeeded istemiyle yanıt vermeniz gerekir.

İstek 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"
          }
        }]
      }]
    }
  }]
}
Yanıt
{
  "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'ın size göndereceği sonraki istek, ilk turda sağlanan PIN'i değil, yalnızca ack sonucunu içerir.

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