Eventos

Los eventos son asíncronos y los administra Google Cloud Pub/Sub en un solo tema por Project. Los eventos proporcionan actualizaciones para todos los dispositivos y estructuras, y se garantiza la recepción de eventos es siempre que el usuario no revoque el token de acceso y que los mensajes de eventos no hayan vencido.

Habilitar eventos

Los eventos son una función opcional de la API de SDM. Consulta Habilitar eventos para obtener información sobre cómo habilitarlos para tu Project.

Google Cloud Pub/Sub

Consulta la documentación de Google Cloud Pub/Sub para obtener más información sobre cómo funciona Pub/Sub. En particular:

Suscripción al evento

Antes de enero de 2025, si los eventos estaban habilitados para tu Project, se te habría proporcionado un tema específico para ese Project ID, de la siguiente manera:

projects/gcp-project-name/subscriptions/topic-id
 Los proyectos creados después de enero de 2025 deben alojar por sí mismos sus temas de Pub/Sub, y deberás proporcionar tu propio ID de tema. Consulta Crea un tema para obtener más información.

Para recibir eventos, crea una suscripción de extracción o inserción a ese tema, según tu caso de uso. Se admiten varias suscripciones al tema de SDM. Consulta Administra suscripciones para obtener más información.

Iniciar eventos

Para iniciar eventos por primera vez una vez que se haya creado la suscripción a Pub/Sub, realiza una devices.list llamada a la API como un activador único. Los eventos para todas las estructuras y dispositivos se publicarán después de esta llamada.

Para ver un ejemplo, consulta la página Autorizar en la Guía de inicio rápido.

Orden de eventos

Pub/Sub no garantiza la entrega ordenada de eventos, y el orden de recepción de eventos puede no corresponder al orden en que ocurrieron realmente los eventos. Usa el timestamp campo para ayudar a conciliar el orden de los eventos. Los eventos también pueden llegar de forma individual o combinados en un solo mensaje de evento.

Para obtener más información, consulta Ordena mensajes.

IDs de usuario

Si tu implementación se basa en usuarios (en lugar de estructuras o dispositivos), usa el userID campo de la carga útil del evento para correlacionar recursos y eventos. Este campo es un ID ofuscado que representa a un usuario específico.

El userID también está disponible en el encabezado de respuesta HTTP de cada llamada a la API.

Eventos de relación

Los eventos de relación representan una actualización relacional para un recurso. Por ejemplo, cuando se agrega un dispositivo a una estructura o cuando se borra un dispositivo de una estructura.

Existen tres tipos de eventos de relación:

  • CREATED
  • ELIMINADO
  • ACTUALIZADA

La carga útil de un evento de relación es la siguiente:

Carga útil

{
  "eventId" : "e4569d38-8013-46b4-ae24-62e40110f5a0",
  "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"
}

En un evento de relación, el object es el recurso que activó el evento, y el subject es el recurso con el que el object ahora tiene una relación. En el ejemplo anterior, un user ha otorgado acceso a este dispositivo específico a un developer, y el dispositivo autorizado de user's ahora está relacionado con su estructura autorizada, lo que activa el evento.

Un subject solo puede ser una habitación o una estructura. Si a developer no tiene permiso para ver la estructura de user, el subject siempre está vacío.

Campos

Campo Descripción Tipo de datos
eventId Identificador único para el evento. string
Ejemplo: "354536eb-5504-4869-b874-758502f8274a"
timestamp Hora en que ocurrió el evento. string
Ejemplo: "2019-01-01T00:00:01Z"
relationUpdate Objeto que detalla información sobre la actualización de la relación. object
userId Identificador único y ofuscado que representa al usuario. string
Ejemplo: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"

Consulta Eventos para obtener más información sobre los diferentes tipos y cómo funcionan.

Ejemplos

Las cargas útiles de eventos difieren para cada tipo de evento de relación:

CREATED

Se creó la estructura

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

Se creó el dispositivo

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

Se creó el dispositivo

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

ACTUALIZADA

Se movió el dispositivo

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

ELIMINADO

Se borró la estructura

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

Se borró el dispositivo

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

Se borró el dispositivo

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

Los eventos de relación no se envían cuando sucede lo siguiente:

  • Se borra una habitación.

Eventos de recursos

Un evento de recurso representa una actualización específica de un recurso. Puede ser en respuesta a un cambio en el valor de un campo de trait, como cambiar el modo de un termostato. También puede representar una acción del dispositivo que no cambia un campo de trait, como presionar un botón del dispositivo.

Un evento generado en respuesta a un cambio en el valor del campo de trait contiene un traits objeto, similar a una llamada GET del dispositivo:

Carga útil

{
  "eventId" : "0efe7b28-4cfd-4f69-90e4-50ee9ee79acc",
  "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"
  ]
}

Usa la documentación de trait individual para comprender el formato de carga útil de cualquier evento de recurso de cambio de campo de trait.

Un evento generado en respuesta a una acción del dispositivo que no cambia un campo de trait también tiene una carga útil con un objeto resourceUpdate, pero con un objeto events en lugar de un objeto traits:

Carga útil

{
  "eventId" : "1b3afcc8-a274-4836-9f9a-b8235aa4b0e0",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "5IWtUlKhUJ02ni3zMynroMi1bt...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

Estos tipos de eventos de recursos se definen en traits específicos. Por ejemplo, el evento Motion se define en el trait CameraMotion. Consulta la documentación de cada trait para comprender el formato de carga útil de estos tipos de eventos de recursos.

Campos

Campo Descripción Tipo de datos
eventId Identificador único para el evento. string
Ejemplo: "1b3afcc8-a274-4836-9f9a-b8235aa4b0e0"
timestamp Hora en que ocurrió el evento. string
Ejemplo: "2019-01-01T00:00:01Z"
resourceUpdate Objeto que detalla información sobre la actualización del recurso. object
userId Identificador único y ofuscado que representa al usuario. string
Ejemplo: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
eventThreadId Identificador único del subproceso del evento. string
Ejemplo: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
eventThreadState Estado del subproceso del evento. string
Valores: "STARTED", "UPDATED", "ENDED"
resourceGroup Objeto que indica los recursos que podrían tener actualizaciones similares a este evento. El recurso del evento en sí (del objeto resourceUpdate) siempre estará presente en este objeto. object

Consulta Eventos para obtener más información sobre los diferentes tipos y cómo funcionan.

Notificaciones actualizables

Las notificaciones basadas en eventos de recursos se pueden implementar en una app, como para Android o iOS. Para reducir la cantidad de notificaciones enviadas, se puede implementar una función llamada notificaciones actualizables, en la que las notificaciones existentes se actualizan con información nueva basada en eventos posteriores en el mismo subproceso de eventos.

Selecciona la compatibilidad con la función de eventos para las notificaciones actualizables y se etiquetan como Updateable  en la documentación. Estos eventos tienen un campo adicional llamado eventThreadId en sus cargas útiles. Usa este campo para vincular eventos individuales con el fin de actualizar una notificación existente que se haya mostrado a un usuario.

Un subproceso de eventos no es lo mismo que una sesión de eventos. El subproceso de eventos identifica un estado actualizado para un evento anterior en el mismo subproceso. La sesión de eventos identifica eventos separados que se relacionan entre sí, y puede haber varios subprocesos de eventos para una sesión de eventos determinada.

Para fines de notificación, los diferentes tipos de eventos se agrupan en diferentes subprocesos.

Google controla esta lógica de agrupación y sincronización de subprocesos, y está sujeta a cambios en cualquier momento. A developer debe actualizar las notificaciones en función de los subprocesos y las sesiones de eventos que proporciona la API de SDM.

Estado de subprocesos

Los eventos que admiten notificaciones actualizables también tienen un campo eventThreadState que indica el estado del subproceso de eventos en ese momento. Este campo tiene los siguientes valores:

  • STARTED: Es el primer evento en un subproceso de eventos.
  • UPDATED: Es un evento en un subproceso de eventos en curso. Puede haber cero o más eventos con este estado en un solo subproceso.
  • ENDED: Es el último evento en un subproceso de eventos, que puede ser un duplicado del último evento UPDATED, según el tipo de subproceso.

Este campo se puede usar para hacer un seguimiento del progreso de un subproceso de eventos y cuándo finalizó.

Filtrado de eventos

En algunos casos, los eventos detectados por un dispositivo se pueden filtrar para que no se publiquen en un tema de Pub/Sub de SDM. Este comportamiento se llama filtrado de eventos. El propósito del filtrado de eventos es evitar la publicación de demasiados mensajes de eventos similares en un período breve.

Por ejemplo, se puede publicar un mensaje en un tema de SDM para un evento Motion inicial. Los otros mensajes de Motion después de eso se filtrarán para que no se publiquen hasta que pase un período determinado. Una vez que pase ese período, se podrá volver a publicar un mensaje de evento para ese tipo de evento.

En la app de Google Home (GHA), los eventos que se filtraron seguirán apareciendo en el user's historial de eventos. Sin embargo, esos eventos no generan una notificación de la app (incluso si ese tipo de notificación está habilitado).

Cada tipo de evento tiene su propia lógica de filtrado de eventos, que define Google y está sujeta a cambios en cualquier momento. Esta lógica de filtrado de eventos es independiente de la lógica de subproceso y sesión de eventos.

Cuentas de servicio

Se recomiendan las cuentas de servicio para administrar las suscripciones a la API de SDM y los mensajes de eventos. Una cuenta de servicio la usa una aplicación o una máquina virtual, no una persona, y tiene su propia clave de cuenta única.

La autorización de la cuenta de servicio para la API de Pub/Sub usa OAuth de dos segmentos (2LO).

En el flujo de autorización de 2LO, sucede lo siguiente:

  • El developer solicita un token de acceso con una clave de servicio.
  • El developer usa el token de acceso con llamadas a la API.

Para obtener más información sobre Google 2LO y cómo configurarlo, consulta Uso de OAuth 2.0 para aplicaciones de servidor a servidor.

Autorización

La cuenta de servicio debe estar autorizada para usarse con la API de Pub/Sub:

  1. Habilita la API de Cloud Pub/Sub en Google Cloud.
  2. Crea una cuenta de servicio y una clave de cuenta de servicio como se describe en Crea una cuenta de servicio. Te recomendamos que solo le otorgues el rol de Suscriptor de Pub/Sub. Asegúrate de descargar la clave de la cuenta de servicio en la máquina que usará la API de Pub/Sub.
  3. Proporciona tus credenciales de autenticación (clave de cuenta de servicio) al código de tu aplicación siguiendo las instrucciones de la página del paso anterior o, si deseas probar rápidamente el acceso a la API, obtén un token de acceso de forma manual con oauth2l, si quieres probar rápidamente el acceso a la API.
  4. Usa las credenciales de la cuenta de servicio o el token de acceso con la API project.subscriptions de Pub/Sub para extraer y confirmar mensajes.

oauth2l

Google oauth2l es una herramienta de línea de comandos para OAuth escrita en Go. Instálala para Mac o Linux con Go.

  1. Si no tienes Go en tu sistema, primero descárgalo e instálalo.
  2. Una vez que se instale Go, instala oauth2l y agrega su ubicación a tu variable de entorno PATH: 
    go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
  3. Usa oauth2l para obtener un token de acceso para la API con los permisos de OAuth adecuados: 
    oauth2l fetch --credentials path-to-service-key.json --scope https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform
     Por ejemplo, si la clave de servicio se encuentra en ~/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...

Consulta el archivo oauth2l README para obtener más información sobre el uso.

Bibliotecas cliente de la API de Google

Hay varias bibliotecas cliente disponibles para las APIs de Google que utilizan OAuth 2.0. Consulta Bibliotecas cliente de la API de Google para obtener más información sobre el lenguaje que elijas.

Cuando uses estas bibliotecas con el Pub/Sub API, usa las siguientes cadenas de permisos:

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

Errores

Es posible que se muestren los siguientes códigos de error relacionados con esta guía:

Mensaje de error RPC Solución de problemas
La imagen de la cámara ya no está disponible para descargarla. DEADLINE_EXCEEDED Las imágenes de eventos vencen 30 segundos después de que se publica el evento. Asegúrate de descargar la imagen antes del vencimiento.
El ID del evento no pertenece a la cámara. FAILED_PRECONDITION Usa el eventID correcto que devuelve el evento de la cámara.

Consulta la Referencia de códigos de error de la API para ver la lista completa de códigos de error.