Мероприятия

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

Enable events

События — это необязательная функция API SDM. См. Enable events to learn how to enable them for your Project.

Google Cloud Pub/Sub

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

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

Event subscription

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

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

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

Initiate events

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

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

Event order

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

For more information, see Ordering messages .

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

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

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

Relation events

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

There are three types of relation events:

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

The payload for a relation event is as follows:

{
  "eventId" : "e87a6458-575e-45f2-b57f-80d2929d55a7",
  "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 has granted access to this specific device to a developer, and the userАвторизованное устройство теперь связано с его авторизованной структурой, что и запускает событие.

A subject can only be a room or a structure. If a developer does not have permission to view the user's structure, the subject is always empty.

Поля

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

Примеры

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

"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"
}

Relation events are not sent when:

• A room is deleted

Resource events

Событие ресурса представляет собой обновление, специфичное для ресурса. Оно может происходить в ответ на изменение значения поля характеристики, например, на изменение режима работы термостата. It can also represent a device action that doesn't change a trait field such as pressing a device button.

An event generated in response to a change in the value of trait field contains a traits object, similar to a device GET call:

{
  "eventId" : "13186bf3-ee54-4ccb-8ea4-52d28e1d9a53",
  "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"
  ]
}

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

An event generated in response to a device action that doesn't change a trait field also has a payload with a resourceUpdate object, but with an events object instead of a traits object:

{
  "eventId" : "747ad1c4-22b5-460d-a568-bc3e97abb04d",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "g5chgCCqiULgbIj_18dPCsMAvz...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

Поля

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

Updateable notifications

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

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

For notification purposes, different types of events are grouped into different threads.

This thread grouping and timing logic is handled by Google and is subject to change at any time. A developer should update notifications based on the event threads and sessions provided by the SDM API.

Thread state

Events that support updateable notifications also have an eventThreadState field that indicates the state of the event thread at that point in time. This field has the following values:

• STARTED — The first event in an event thread.
• UPDATED — An event in an ongoing event thread. There can be zero or more events with this state in a single thread.
• ЗАВЕРШЕНО — Последнее событие в потоке событий, которое может быть дубликатом последнего события ОБНОВЛЕНО, в зависимости от типа потока.

This field can be used to track the progress of an event thread and when it has ended.

Event filtering

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

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

In the Google Home App (GHA), events that were filtered will still show in the user's event history. However, such events don't generate an app notification (even if that notification type is enabled).

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

Service accounts

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

Service account authorization for the Pub/Sub API uses Two-legged OAuth (2LO).

In the 2LO authorization flow:

• Он developer requests an access token using a service key.
• Он developer uses the access token with calls to the API.

To learn more about Google 2LO and how to get set up, see Using OAuth 2.0 for Server to Server Applications .

Авторизация

The service account should be authorized for use with the Pub/Sub API:

1. Enable the Cloud Pub/Sub API in Google Cloud.
2. Создайте учетную запись службы и ключ учетной записи службы, как описано в разделе «Создание учетной записи службы» . Мы рекомендуем присвоить ей только роль подписчика Pub/Sub . Убедитесь, что ключ учетной записи службы загружен на компьютер, который будет использовать API Pub/Sub.
3. Предоставьте свои учетные данные для аутентификации (ключ учетной записи службы) коду вашего приложения, следуя инструкциям на странице предыдущего шага, или получите токен доступа вручную с помощью oauth2l , если хотите быстро протестировать доступ к API.
4. Use service account credentials or the access token with the Pub/Sub project.subscriptions API to pull and acknowledge messages.

oauth2l

Google oauth2l is a command line tool for OAuth written in Go. Install it for Mac or Linux using Go.

1. If you do not have Go on your system, download and install it first .
2. Once Go is installed, install oauth2l and add its location to your PATH environment variable:

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

3. Use oauth2l to get an access token for the API, using the appropriate OAuth scope(s):

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

   For example, if your service key is located at ~/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...

See the oauth2l README for more usage information.

Google API Client Libraries

There are several client libraries available for Google APIs that utilize OAuth 2.0. See Google API Client Libraries for more information on the language of your choice.

When using these libraries with the Pub/Sub API, use the following scope string(s):

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

Ошибки

The following error code(s) may be returned in relation to this guide:

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