Мероприятия

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

Информация о мероприятиях

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

Google Cloud Pub/Sub

Подробнее о том, как работает Pub/Sub, можно узнать из документации по Google Cloud Pub/Sub. В их числе:

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

Подписка на события

До января 2025 г., если для вашего Projectбыли включены события, вы получали размещенную в Google тему, связанную с этим Project , в следующем формате:

projects/sdm-prod/topics/enterprise-project-id

Теперь все проекты должны самостоятельно размещать свои темы издатель-подписчик в собственном облачном проекте Google Cloud (обязательно для новых проектов с января 2025 года и для всех существующих проектов до 30 ноября 2026 года) в следующем формате:

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

Если в вашем project уже используется тема, размещенная в вашем облачном проекте Google Cloud, никаких действий не требуется. Перенос конфигурации темы Pub/Sub не аннулирует существующие токены доступа пользователей или разрешения OAuth. Для тем и подписок, размещенных на собственных серверах, действуют стандартные тарифы Google Cloud Pub/Sub (включая бесплатный план – 10 ГБ в месяц). Подробнее о том, как создать тему…

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

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

Чтобы инициировать события в первый раз после создания подписки издатель-подписчик, выполните вызов API devices.list в качестве однократного триггера. После этого вызова будут публиковаться события для всех структур и устройств.

Пример можно найти на странице Авторизация в кратком руководстве по началу работы.

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

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

Подробнее о порядке сообщений…

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

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

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

События, связанные с отношениями

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

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

• CREATED
• УДАЛЕНО
• ОБНОВЛЕНО

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

{
  "eventId" : "768e4eea-b61d-428b-8926-c67e2abaddf9",
  "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. В приведенном выше примере пользователь a 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"
}

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

• Удалена комната

События, связанные с ресурсами

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

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

{
  "eventId" : "ae3f760e-9e1f-4c14-b911-28482e86e56d",
  "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" : "aecdfca3-25ec-4738-bdbf-d24c4a209d93",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "jE1ZfUIAp6z2anjwTJp5E8QxvC...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

Эти типы событий ресурсов определены в определенных чертах. Например, событие Motion определено в типаже CameraMotion . Чтобы узнать формат полезной нагрузки для этих типов событий ресурсов, ознакомьтесь с документацией по каждому признаку.

Поля

Подробнее о событиях…

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

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

Цепочка мероприятия – это не то же самое, что сеанс мероприятия. Цепочка событий содержит обновленный статус предыдущего события в той же цепочке. Сеанс события позволяет идентифицировать отдельные события, связанные друг с другом. В рамках одного сеанса может быть несколько цепочек событий.

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

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

Состояние цепочки

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

• STARTED – первое событие в цепочке.
• UPDATED – событие в цепочке событий. В одном потоке может быть ноль или более событий с таким статусом.
• ENDED – последнее событие в цепочке, которое может быть копией последнего события UPDATED в зависимости от типа цепочки.

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

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

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

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

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

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

Сервисные аккаунты

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

Для авторизации сервисного аккаунта в Pub/Sub API используется двусторонняя аутентификация OAuth (2LO).

При двухэтапной авторизации:

• developer запрашивает токен доступа с помощью сервисного ключа.
• developer использует токен доступа при вызовах API.

Подробнее о том, как использовать OAuth 2.0 для серверных приложений…

Авторизация

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

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

oauth2l

Google oauth2l – это инструмент командной строки для OAuth, написанный на языке Go. Установите его для macOS или 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, доступно несколько клиентских библиотек. Дополнительную информацию о выбранном языке можно найти в статье Клиентские библиотеки Google API.

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

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

Ошибки

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

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