Eventos

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

Nota: Si el dispositivo Device Access La 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. Para acceder de forma continua, debes usar el token de actualización en un plazo de 6 meses. Para obtener más ayuda con la autorización, consulta Vencimiento del token de actualización.

Habilitar eventos

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

Google Cloud Pub/Sub

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

• Aprender los conceptos básicos de Pub/Sub con sus Guías prácticas.
• Descubre cómo funciona Authentication.
• Elige una biblioteca cliente proporcionada. o escribir el tuyo propio y usar la Plataformas de la API de REST/HTTP o de gRPC.

Suscripción al evento

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

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

Para recibir eventos, crea una extracción o push a ese tema, según tu para tu caso de uso específico. Se admiten varias suscripciones al tema SDM. Consulta Administra 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.

Inicia eventos

Para iniciar eventos por primera vez después de crear 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 esto. llamada.

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

Orden del evento

Pub/Sub no garantiza la entrega ordenada de eventos, y es posible que el orden de recepción de los eventos corresponden al orden en el que ocurrieron los eventos. Usa el timestamp para facilitar la conciliación del orden de los eventos. Los eventos también pueden llegar de forma individual o combinada en un solo mensaje de evento.

Para obtener más información, consulta Cómo ordenar mensajes

IDs de usuario

Si tu implementación se basa en los usuarios (en lugar de en la estructura o el dispositivo), usa la 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 un dispositivo está agregado a una estructura, o cuando se borra un dispositivo de una estructura.

Hay 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" : "d93fe80c-dd14-4afb-80bd-b12dc7dca526",
  "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 el subject es el recurso con el que object tiene una relación. En la ejemplo anterior, un objeto user otorgó acceso a este dispositivo específico a una developery el dispositivo autorizado de userahora está relacionado con su de entrada, 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 es vacío.

Campos

Campo	Descripción	Tipo de datos
eventId	Es el identificador único del evento.	string Ejemplo: "96305092-d82e-4e52-9115-29bfd0594bf0"
timestamp	Indica la hora a la que ocurrió el evento.	string Ejemplo: “2019-01-01T00:00:01Z”
relationUpdate	Un objeto que detalla información sobre la actualización de 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 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 borró una sala

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 característica, como presionar un botón de dispositivo.

Cualquier cambio en un campo de rasgo genera un evento de recurso, a menos que se indique lo contrario en la documentación de referencia de la característica.

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

Carga útil

{
  "eventId" : "ba462282-5053-4e3c-bf38-612b802dfa53",
  "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 el persona documentación de la característica para comprender el formato de la carga útil de cualquier recurso de cambio de campo de característica para cada evento.

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

Carga útil

{
  "eventId" : "a556db20-2bab-4bd4-bb39-9c036a252a7e",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "MnCcivUK74q3Zq7CNUSsnYcAcM...",
      }
    }
  }
  "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 con rasgos específicos. Por ejemplo, el El evento de movimiento se define en el CameraMotion trait. 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	Es el identificador único del evento.	string Ejemplo: “a556db20-2bab-4bd4-bb39-9c036a252a7e”
timestamp	Indica la hora a 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	Es 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 recursos que pueden tener actualizaciones similares a este evento. El recurso del evento (del objeto resourceUpdate) siempre estará presente en este objeto.	object

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

Notificaciones actualizables

Las notificaciones basadas en eventos de recursos se pueden implementar en una app, por ejemplo, para Android o iOS. Para reducir la cantidad de notificaciones enviadas, una función llamada notificaciones actualizables, en donde las notificaciones existentes Se actualizan con información nueva basada en eventos posteriores del mismo evento. conversación.

Algunos eventos de la función son compatibles con notificaciones actualizables y están etiquetados como Actualizable  en la documentación. Estos eventos tienen un campo adicional llamado eventThreadId en sus cargas útiles. Usar esta para vincular eventos individuales con el fin de actualizar un evento una notificación de aplicación que se le mostró a un usuario.

Un subproceso de evento no es lo mismo que una sesión de evento. La conversación de eventos identifica el estado actualizado de un evento anterior en el mismo subproceso. El La sesión de eventos identifica eventos separados que se relacionan entre sí. 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 diferentes conversaciones.

Esta lógica de agrupación y sincronización de subprocesos está a cargo de Google y está sujeta a en cualquier momento. A developer debería actualizar las notificaciones según la sesiones y subprocesos de evento que proporciona la API de SDM.

Estado de subprocesos

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

• STARTED: Es el primer evento de una conversación de eventos.
• UPDATED: 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 de un subproceso de eventos, que puede ser un duplicado del último evento UPDATED, según el tipo de subproceso.

Este campo se puede utilizar para hacer un seguimiento del progreso de una conversación de evento y cuando tiene finalizado.

Filtrado de eventos

En algunos casos, es posible que los eventos detectados por un dispositivo no se publiquen. a un tema de Pub/Sub de SDM. Este comportamiento se llama filtrado de eventos. El propósito del filtrado de eventos es evitar Publicar demasiados mensajes de eventos similares en poco tiempo

Por ejemplo, se puede publicar un mensaje en un tema de SDM para un evento de movimiento inicial. Otra opción los mensajes para Motion que aparezcan después Se filtró de la publicación hasta que transcurra un período establecido. Cuando se cumpla ese período, transcurra el tiempo, se podrá volver a publicar un mensaje para ese tipo de evento.

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

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

Cuentas de servicio

Se recomiendan las cuentas de servicio para administrar la API de SDM suscripciones y mensajes de eventos. Las cuentas de servicio se usan en aplicaciones o en una máquina virtual, no una persona, y tiene su clave de cuenta única.

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

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

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

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

Autorización

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

1. Habilita el Cloud Pub/Sub API 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 asignarle solo la función de suscriptor de Pub/Sub. Asegúrate de descarga 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) a tu el código de la aplicación siguiendo las instrucciones de la página de la paso u obtén un token de acceso manualmente usando 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 el Pub/Sub project.subscriptions API para extraer y confirmar mensajes.

OAuth2l

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

1. Si no tienes Go en tu sistema, primero descárgalo y, luego, instálalo.
2. Una vez que Go esté instalado, instala oauth2l y agrega su ubicación a tu PATH. variable de entorno:

   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 el método Alcances de OAuth:

   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 información.

Bibliotecas cliente de la API de Google

Existen varias bibliotecas cliente disponibles para las APIs de Google que usan OAuth 2. Consulta Bibliotecas cliente de la API de Google para obtener más información sobre la el idioma que prefieras.

Cuando uses estas bibliotecas con Pub/Sub API, usa las siguientes cadenas 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 que se publica el evento. Asegúrate de descargar la imagen antes del vencimiento.
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 API para la lista completa de códigos de error de API.