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 la recepción de eventos está garantizada, siempre y cuando el usuario no revoque el token de acceso y los mensajes de evento no hayan vencido.

Nota: Si tu Device Access integración se basa en eventos de Pub/Sub y rara vez realiza llamadas a la API, se revocará la autorización de usersi vence el token de actualización. Si quieres acceder de forma continua, debes usar el token de actualización para actualizar el token de acceso en un plazo de 6 meses. Para obtener más ayuda con la autorización, consulta Cómo actualizar el vencimiento del token.

Habilitar eventos

Los eventos son una función opcional de la API de SDM. Consulta Cómo 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 su funcionamiento. En particular, considera lo siguiente:

• Aprende los conceptos básicos de Pub/Sub con sus guías prácticas.
• Comprende cómo funciona Authentication.
• Elige una biblioteca cliente proporcionada o escribe una propia y usa las plataformas de API de REST/HTTP o de la API de gRPC.

Suscripción a eventos

Cuando se habiliten los eventos para tu Project, se te proporcionará un tema específico para ese ID de Project , en el formato siguiente:

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

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

No se admite la publicación de mensajes en un tema de SDM. Usa traits para obtener el estado actual de los recursos o enviar comandos.

Iniciar eventos

Para iniciar eventos por primera vez una vez que se creó la suscripción a Pub/Sub, realiza una llamada a la API devices.list como activador único. Los eventos de todas las estructuras y los 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 del evento

Pub/Sub no garantiza la entrega ordenada de los eventos, y es posible que el orden de recepción de los eventos no coincida con el orden en que los eventos ocurrieron en realidad. Usa el campo timestamp para ayudar a conciliar el orden de los eventos. Los eventos también pueden llegar de forma individual o combinarse 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 los usuarios (en lugar de la estructura o el dispositivo), usa el campo userID 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:

• CREADO
• ELIMINADO
• ACTUALIZADA

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

Carga útil

{
  "eventId" : "eed9763a-8735-45d9-81d9-e0621c130eb1",
  "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, object es el recurso que activó el evento, y subject es el recurso con el que object ahora tiene una relación. En el ejemplo anterior, user le otorgó acceso a este dispositivo específico a un developer, y el dispositivo autorizado de userahora está relacionado con su estructura autorizada, que activa el evento.

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

Campos

Campo	Descripción	Tipo de datos
eventId	El identificador único del evento.	string Ejemplo: “1362476b-4ac4-4608-a8be-4c8cf4101426”
timestamp	Es la hora en la que ocurrió el evento.	string Ejemplo: “2019-01-01T00:00:01Z”
relationUpdate	Un objeto que detalla información sobre la actualización de la relación.	object
userId	Es un 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 de eventos 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 en los siguientes casos:

• 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 de dispositivo.

Cualquier cambio en el campo del trait genera un evento de recurso, a menos que se indique lo contrario en la documentación de referencia del trait.

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

Carga útil

{
  "eventId" : "5b98a768-6771-4d4d-836d-58cce3a62cca",
  "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 las características individuales para comprender el formato de la carga útil de cualquier evento de recurso de cambio de campo de la característica.

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" : "3426d266-406b-48f3-9595-5192229a39a0",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "8XZ1cQ76Becovj551YfM9ZnuwB...",
      }
    }
  }
  "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 características específicas. Por ejemplo, el evento Motion se define en la característica CameraMotion . Consulta la documentación de cada característica para comprender el formato de la carga útil para estos tipos de eventos de recursos.

Campos

Campo	Descripción	Tipo de datos
eventId	El identificador único del evento.	string Ejemplo: “3426d266-406b-48f3-9595-5192229a39a0”
timestamp	Es la hora en la que ocurrió el evento.	string Ejemplo: “2019-01-01T00:00:01Z”
resourceUpdate	Un objeto que detalla información sobre la actualización del recurso.	object
userId	Es un identificador único y ofuscado que representa al usuario.	string Ejemplo: “AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi”
eventThreadId	El identificador único del subproceso del evento.	string Ejemplo: “d67cd3f7-86a7-425e-8bb3-462f92ec9f59”
eventThreadState	Es el estado del subproceso del evento.	string Valores: “STARTED”, “UPDATED”, “ENDED”
resourceGroup	Un 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 de eventos 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.

Algunos eventos admiten notificaciones actualizables y están etiquetados como Actualizables  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 le mostró a un usuario.

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

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

Google controla esta lógica de agrupación y sincronización de subprocesos, que está sujeta a cambios en cualquier momento. Un developer debe actualizar las notificaciones en función de los subprocesos y las sesiones de eventos proporcionados por 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 del evento en ese momento. Este campo tiene los siguientes valores:

• STARTED: Es el primer evento de una conversación de eventos.
• ACTUALIZADO: Un evento en un subproceso de un evento en curso. Puede haber cero o más eventos con este estado en un solo subproceso.
• ENDED: Es el último evento de 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 realizar un seguimiento del progreso de un subproceso de un evento y su finalización.

Filtrado de eventos

En algunos casos, es posible que los eventos que detecta un dispositivo no se publiquen en un tema de Pub/Sub de SDM. Este comportamiento se denomina filtrado de eventos. El propósito del filtrado de eventos es evitar publicar demasiados mensajes de eventos similares en un período breve.

Por ejemplo, es posible que un mensaje se publique en un tema de SDM para un evento de movimiento inicial. Los demás mensajes relacionados con Motion después de eso dejarán de publicarse hasta que transcurra un período determinado. Una vez transcurrido ese período, es posible que se vuelva a publicar un mensaje para ese tipo de evento.

En la app de Google Home (GHA), los eventos que se hayan filtrado seguirán apareciendo en el historial de eventos de user. 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 del subproceso de eventos y de la lógica de la sesión.

Cuentas de servicio

Se recomiendan las cuentas de servicio para administrar mensajes de eventos y suscripciones a las APIs de SDM. Una aplicación o máquina virtual, no una persona, usa una cuenta de servicio, 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 2LO:

• developer solicita un token de acceso mediante una clave de servicio.
• 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 Usa OAuth 2.0 para aplicaciones de servidor a servidor.

Autorización

La cuenta de servicio debe estar autorizada para usar 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. Recomendamos asignarle solo la función 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. Sigue las instrucciones de la página del paso anterior para proporcionar tus credenciales de autenticación (clave de la cuenta de servicio) al código de tu aplicación, o bien obtén un token de acceso de forma manual con oauth2l si deseas 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 de project.subscriptions de Pub/Sub para extraer y confirmar los 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 el sistema, descárgalo e instálalo primero.
2. Una vez que Go esté instalado, instala oauth2l y agrega su ubicación a la variable de entorno PATH:

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

3. Usa oauth2l a fin de obtener un token de acceso para la API con los permisos de OAuth apropiados:

   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 tu 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 README de oauth2l para obtener más información de uso.

Bibliotecas cliente de la API de Google

Hay varias bibliotecas cliente disponibles para las APIs de Google que usan 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 Pub/Sub API, utiliza las siguientes strings de alcance:

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 en relación con esta guía:

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

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