Мероприятия

События происходят асинхронно и управляются системой Google Cloud Pub/Sub в рамках одной темы на каждый элемент. ProjectСобытия обеспечивают обновления для всех устройств и структур, и получение событий гарантировано до тех пор, пока токен доступа не будет отозван пользователем и сообщения о событиях не истекут.

Включить события

События — это необязательная функция API SDM. См. Включить события чтобы узнать, как их включить для вас Project.

Google Cloud Pub/Sub

Для получения более подробной информации о работе Pub/Sub обратитесь к документации Google Cloud Pub/Sub . В частности:

• Изучите основы Pub/Sub с помощью их руководств .
• Разберитесь, как работает аутентификация .
• Выберите предоставленную клиентскую библиотеку или напишите свою собственную и используйте API REST/HTTP или gRPC .

Подписка на мероприятие

До января 2025 года, если для вас были включены события. ProjectВам бы предоставили тему, специально посвященную этому вопросу. Project Идентификационный номер в следующем виде:

projects/gcp-project-name/subscriptions/topic-id

Для получения событий создайте подписку на эту тему с возможностью получения или отправки данных , в зависимости от ваших потребностей. Поддерживается несколько подписок на тему SDM. Дополнительную информацию см. в разделе «Управление подписками» .

Инициировать события

Для запуска событий в первый раз после создания подписки Pub/Sub выполните одноразовый вызов API devices.list . После этого вызова будут опубликованы события для всех структур и устройств.

Пример можно увидеть на странице «Авторизация» в кратком руководстве пользователя.

порядок событий

Система Pub/Sub не гарантирует упорядоченную доставку событий, и порядок получения событий может не соответствовать порядку их фактического возникновения. Используйте поле timestamp для уточнения порядка событий. События также могут поступать по отдельности или объединяться в одно сообщение.

Для получения более подробной информации см. раздел «Сообщения заказа» .

Идентификаторы пользователей

Если ваша реализация основана на пользователях (а не на структуре или устройстве), используйте поле userID из полезной нагрузки события для сопоставления ресурсов и событий. Это поле представляет собой зашифрованный идентификатор, обозначающий конкретного пользователя.

Идентификатор userID также доступен в заголовке HTTP-ответа каждого вызова API.

События взаимосвязи

События, связанные с реляцией, представляют собой обновление информации о ресурсе. Например, когда устройство добавляется в структуру или когда устройство удаляется из структуры.

Существует три типа событий, связанных с отношениями:

• СОЗДАННЫЙ
• УДАЛЕНО
• ОБНОВЛЕНО

Полезная нагрузка для события, связанного с отношением, выглядит следующим образом:

{
  "eventId" : "a304e204-ebf9-4c6b-8db5-4cb6a412cf0a",
  "timestamp" : "2019-01-01T00:00:01Z",
  "relationUpdate" : {
    "type" : "CREATED",
    "subject" : "enterprises/project-id/structures/structure-id",
    "object" : "enterprises/project-id/devices/device-id"
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
}

В событии, связанном с отношением, object является ресурс, который инициировал событие, а subject — ресурс, с которым у object теперь есть отношение. В приведенном выше примере... user предоставил доступ к этому конкретному устройству developerи userАвторизованное устройство теперь связано с его авторизованной структурой, что и запускает событие.

subject может быть только комната или сооружение. Если a developer не имеет разрешения на просмотр userВ структуре этого выражения subject всегда пуст.

Поля

Более подробную информацию о различных типах мероприятий и порядке их проведения можно найти в разделе «Мероприятия» .

Примеры

Содержимое событий различается для каждого типа событий, связанных с отношениями:

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

"relationUpdate" : {
  "type" : "UPDATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

События, связанные с отношениями, не отправляются в следующих случаях:

• Комната удалена

Ресурсные события

Событие ресурса представляет собой обновление, специфичное для ресурса. Оно может происходить в ответ на изменение значения поля характеристики, например, на изменение режима работы термостата. Это также может представлять собой действие устройства, которое не изменяет поле характеристики, например, нажатие кнопки устройства.

Событие, генерируемое в ответ на изменение значения поля trait, содержит объект traits , аналогично вызову GET для устройства:

{
  "eventId" : "61549c49-5c57-482a-904f-9f09242c0d24",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "traits" : {
      "sdm.devices.traits.ThermostatMode" : {
        "mode" : "COOL"
      }
    }
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

Используйте документацию по отдельным характеристикам , чтобы понять формат полезной нагрузки для любого события изменения поля характеристики.

Событие, сгенерированное в ответ на действие устройства, которое не изменяет поле характеристики, также содержит полезную нагрузку с объектом resourceUpdate , но с объектом events вместо объекта traits :

{
  "eventId" : "eccd6c8c-0bb4-4d2d-b42f-dca6e8cd3fd9",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "KAb53OE5RwOsHepm_hbkNdd2Jh...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

Эти типы ресурсных событий определяются в конкретных характеристиках. Например, событие «Движение» определяется в CameraMotion Характеристика. Для понимания формата полезной нагрузки для событий, связанных с ресурсами, см. документацию по каждой характеристике.

Поля

Более подробную информацию о различных типах мероприятий и порядке их проведения можно найти в разделе «Мероприятия» .

Обновляемые уведомления

Некоторые события поддерживают обновляемые уведомления и помечены в документации как «Обновляемые» . В их полезной нагрузке есть дополнительное поле eventThreadId . Используйте это поле для связывания отдельных событий с целью обновления существующего уведомления, которое было показано пользователю.

Поток событий — это не то же самое, что сессия событий. Поток событий определяет обновленный статус предыдущего события в том же потоке. Сессия событий определяет отдельные события, которые связаны друг с другом, и для одной сессии событий может быть несколько потоков событий.

В целях оповещения различные типы событий группируются в разные потоки.

Логика группировки потоков и синхронизации обрабатывается компанией Google и может быть изменена в любое время. developer Уведомления следует обновлять на основе потоков событий и сессий, предоставляемых API SDM.

состояние потока

События, поддерживающие обновляемые уведомления, также имеют поле eventThreadState , которое указывает состояние потока события в данный момент времени. Это поле может принимать следующие значения:

• НАЧАЛО — Первое событие в ветке событий.
• ОБНОВЛЕНО — Событие в текущем потоке событий. В одном потоке может быть ноль или более событий с таким состоянием.
• ЗАВЕРШЕНО — Последнее событие в потоке событий, которое может быть дубликатом последнего события ОБНОВЛЕНО, в зависимости от типа потока.

Это поле можно использовать для отслеживания хода выполнения потока событий и момента его завершения.

Фильтрация событий

В некоторых случаях события, обнаруженные устройством, могут быть отфильтрованы и не опубликованы в теме SDM Pub/Sub. Такое поведение называется фильтрацией событий . Цель фильтрации событий — избежать публикации слишком большого количества похожих сообщений о событиях за короткий промежуток времени.

Например, сообщение может быть опубликовано в тему SDM для первоначального события Motion. Другие сообщения для Motion после этого будут отфильтрованы и не будут опубликованы до истечения заданного периода времени. По истечении этого периода времени сообщение о событии данного типа может быть опубликовано снова.

В приложении Google Home (GHA) отфильтрованные события по-прежнему будут отображаться. userИстория событий. Однако такие события не генерируют уведомление приложения (даже если этот тип уведомления включен).

Для каждого типа событий существует своя собственная логика фильтрации событий, которая определяется Google и может быть изменена в любое время. Эта логика фильтрации событий не зависит от логики потока событий и сессии.

Служебные счета

Для управления подписками на API SDM и сообщениями о событиях рекомендуется использовать служебные учетные записи. Служебная учетная запись используется приложением или виртуальной машиной, а не человеком, и имеет свой собственный уникальный ключ.

Для авторизации учетной записи службы в API Pub/Sub используется двухэтапная OAuth (2LO).

В процессе авторизации 2LO:

• Он developer Запрашивает токен доступа, используя ключ службы.
• Он developer Использует токен доступа при вызовах API.

Чтобы узнать больше о Google 2LO и о том, как его настроить, см. раздел «Использование OAuth 2.0 для приложений, работающих между серверами» .

Авторизация

Учетная запись службы должна быть авторизована для использования с API Pub/Sub:

1. Включите API Cloud Pub/Sub в Google Cloud.
2. Создайте учетную запись службы и ключ учетной записи службы, как описано в разделе «Создание учетной записи службы» . Мы рекомендуем присвоить ей только роль подписчика Pub/Sub . Убедитесь, что ключ учетной записи службы загружен на компьютер, который будет использовать API Pub/Sub.
3. Предоставьте свои учетные данные для аутентификации (ключ учетной записи службы) коду вашего приложения, следуя инструкциям на странице предыдущего шага, или получите токен доступа вручную с помощью oauth2l , если хотите быстро протестировать доступ к API.
4. Используйте учетные данные сервисной учетной записи или токен доступа к API проекта Pub/Sub project.subscriptions для получения и подтверждения сообщений.

oauth2l

Google oauth2l — это инструмент командной строки для аутентификации OAuth, написанный на Go. Установите его для Mac или Linux, используя Go.

1. Если у вас нет Go на компьютере, сначала скачайте и установите его .
2. После установки Go установите oauth2l и добавьте его путь к переменной среды PATH :

   go install github.com/google/oauth2l@latest
   export PATH=$PATH:~/go/bin

3. Используйте oauth2l для получения токена доступа к API, используя соответствующие области действия OAuth:

   oauth2l fetch --credentials path-to-service-key.json --scope https://www.googleapis.com/auth/pubsub
   https://www.googleapis.com/auth/cloud-platform

   Например, если ваш сервисный ключ находится по адресу ~/myServiceKey-eb0a5f900ee3.json :

   oauth2l fetch --credentials ~/myServiceKey-eb0a5f900ee3.json --scope https://www.googleapis.com/auth/pubsub
   https://www.googleapis.com/auth/cloud-platform
   ya29.c.Elo4BmHXK5...

Дополнительную информацию об использовании см. в файле README oauth2l .

Клиентские библиотеки API Google

Для API Google, использующих OAuth 2.0, доступно несколько клиентских библиотек. Дополнительную информацию о выбранном вами языке программирования см. в разделе «Клиентские библиотеки API Google» .

При использовании этих библиотек с Pub/Sub APIИспользуйте следующие строки области видимости:

https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform

Ошибки

В связи с данным руководством могут быть возвращены следующие коды ошибок:

Полный список кодов ошибок API см. в Справочнике кодов ошибок API.