Os eventos são assíncronos e gerenciados pelo Google Cloud Pub/Sub em um único tópico por Project. Os eventos fornecem atualizações para todos os dispositivos e estruturas, e o recebimento de eventos é garantido desde que o token de acesso não seja revogado pelo usuário e as mensagens de evento não tenham expirado.
Ativar eventos
Os eventos são um recurso opcional da API SDM. Consulte Ativar eventos para saber como ativar esse recurso para sua Project.
Google Cloud Pub/Sub
Consulte a documentação do Google Cloud Pub/Sub para saber mais sobre como ele funciona. Especificamente, faça o seguinte:
- Aprenda os conceitos básicos do Pub/Sub com os guias de instruções.
- Entenda como a autenticação funciona.
- Escolha uma biblioteca de cliente fornecida ou crie a sua própria e use as superfícies de API REST/HTTP ou gRPC.
Assinatura de eventos
Quando os eventos forem ativados para o Project, você vai receber um tópico específico para esse ID Project , no formato:
projects/sdm-prod/topics/enterprise-project-id
Para receber eventos, crie uma assinatura de pull ou push para esse tópico, dependendo do seu caso de uso. Várias assinaturas do tópico do SDM são aceitas. Consulte Gerenciar assinaturas para mais informações.
Iniciar eventos
Para iniciar eventos pela primeira vez depois que a assinatura do Pub/Sub for criada, faça uma
chamada de API
devices.list
como um acionador único. Os eventos de todas as estruturas e dispositivos serão publicados após essa
chamada.
Para conferir um exemplo, consulte a página Autorizar no Guia de início rápido.
Ordem dos eventos
O Pub/Sub não garante a entrega ordenada de eventos, e a ordem de recebimento de eventos pode não
corresponder à ordem em que os eventos realmente ocorreram. Use o campo timestamp
para ajudar na reconciliação da ordem de eventos. Os eventos também podem chegar individualmente ou combinados
em uma única mensagem de evento.
Para mais informações, consulte Como ordenar mensagens.
IDs de usuários
Se a implementação for baseada em usuários (em vez de estrutura ou dispositivo), use o campo userID
do payload do evento para correlacionar recursos e eventos. Esse campo é
um ID ofuscado que representa um usuário específico.
O userID
também está disponível no cabeçalho de resposta HTTP de cada chamada de API.
Eventos de relacionamento
Os eventos de relação representam uma atualização relacional de um recurso. Por exemplo, quando um dispositivo é adicionado a uma estrutura ou quando um dispositivo é excluído de uma estrutura.
Há três tipos de eventos de relação:
- CREATED
- EXCLUÍDO
- ATUALIZADO
O payload de um evento de relação é o seguinte:
Payload
{ "eventId" : "d5c0f0bd-de65-44fd-ac60-686c302e56eb", "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" }
Em um evento de relação, o object
é o recurso que acionou o evento, e o
subject
é o recurso com que o object
agora tem uma relação. No
exemplo acima, um user concedeu acesso a esse dispositivo específico a um
developer, e o dispositivo autorizado do useragora está relacionado à estrutura
autorizada, que aciona o evento.
Uma subject
só pode ser uma sala ou uma estrutura. Se o a developer não tiver
permissão para visualizar a estrutura do user, o subject
vai estar sempre
vazio.
Campos
Campo | Descrição | Tipo de dados |
---|---|---|
eventId |
O identificador exclusivo do evento. | string Exemplo: "64b87b46-1aec-42a4-8c01-997a407814df" |
timestamp |
O horário em que o evento ocorreu. | string Exemplo: "2019-01-01T00:00:01Z" |
relationUpdate |
Um objeto que detalha informações sobre a atualização da relação. | object |
userId |
Um identificador exclusivo e ofuscado que representa o usuário. | string Exemplo: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi" |
Consulte Eventos para mais informações sobre os diferentes tipos de eventos e como eles funcionam.
Exemplos
Os payloads de eventos são diferentes para cada tipo de evento de relação:
CREATED
Estrutura criada
"relationUpdate" : { "type" : "CREATED", "subject" : "", "object" : "enterprises/project-id/structures/structure-id" }
Dispositivo criado
"relationUpdate" : { "type" : "CREATED", "subject" : "enterprises/project-id/structures/structure-id", "object" : "enterprises/project-id/devices/device-id" }
Dispositivo criado
"relationUpdate" : { "type" : "CREATED", "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id", "object" : "enterprises/project-id/devices/device-id" }
ATUALIZADO
Dispositivo movido
"relationUpdate" : { "type" : "UPDATED", "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id", "object" : "enterprises/project-id/devices/device-id" }
EXCLUÍDO
Estrutura excluída
"relationUpdate" : { "type" : "DELETED", "subject" : "", "object" : "enterprises/project-id/structures/structure-id" }
Dispositivo excluído
"relationUpdate" : { "type" : "DELETED", "subject" : "enterprises/project-id/structures/structure-id", "object" : "enterprises/project-id/devices/device-id" }
Dispositivo excluído
"relationUpdate" : { "type" : "DELETED", "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id", "object" : "enterprises/project-id/devices/device-id" }
Os eventos de relação não são enviados quando:
- Uma sala é excluída
Eventos do recurso
Um evento de recurso representa uma atualização específica de um recurso. Ela pode ser uma resposta a uma mudança no valor de um campo de atributo, como mudar o modo de um termostato. Também pode representar uma ação do dispositivo que não muda um campo de atributo, como pressionar um botão do dispositivo.
Um evento gerado em resposta a uma mudança no valor do campo de atributo contém um
objeto traits
, semelhante a uma chamada GET do dispositivo:
Payload
{
"eventId" : "a88bc884-d2b8-42d6-adba-b7be92c232a3",
"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"
]
}
Use a documentação de cada trait para entender o formato de payload de qualquer evento de mudança de campo de recurso de trait.
Um evento gerado em resposta a uma ação do dispositivo que não muda um campo de atributo também tem um
payload com um objeto resourceUpdate
, mas com um objeto events
em vez de um objeto traits
:
Payload
{ "eventId" : "4f80de08-1b77-42a4-b33e-40876a2a1865",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion
" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "MWJ253hZMPAsJZJWbrGM4ThsKM...", } } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] }
Esses tipos de eventos de recurso são definidos em características específicas. Por exemplo, o evento de movimento é definido no traço CameraMotion . Consulte a documentação de cada atributo para entender o formato de payload desses tipos de eventos de recurso.
Campos
Campo | Descrição | Tipo de dados |
---|---|---|
eventId |
O identificador exclusivo do evento. | string Exemplo: "4f80de08-1b77-42a4-b33e-40876a2a1865" |
timestamp |
O horário em que o evento ocorreu. | string Exemplo: "2019-01-01T00:00:01Z" |
resourceUpdate |
Um objeto que detalha informações sobre a atualização do recurso. | object |
userId |
Um identificador exclusivo e ofuscado que representa o usuário. | string Exemplo: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi" |
eventThreadId |
O identificador exclusivo da linha de execução do evento. | string Exemplo: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59" |
eventThreadState |
O estado da linha de execução do evento. | string Valores: "STARTED", "UPDATED", "ENDED" |
resourceGroup |
Um objeto que indica recursos que podem ter atualizações semelhantes a esse evento. O recurso do próprio evento (do objeto resourceUpdate ) sempre estará presente nesse objeto. |
object |
Consulte Eventos para mais informações sobre os diferentes tipos de eventos e como eles funcionam.
Notificações atualizáveis
As notificações com base em eventos de recursos podem ser implementadas em um app, como Android ou iOS. Para reduzir o número de notificações enviadas, um recurso chamado notificações atualizáveis pode ser implementado, em que as notificações existentes são atualizadas com novas informações com base em eventos subsequentes na mesma linha de execução.Alguns eventos têm suporte a notificações atualizáveis e são marcados como
Atualizável eventThreadId
nos payloads. Use esse campo para vincular eventos individuais com o objetivo de atualizar uma notificação
existente que foi exibida para um usuário.
Uma linha de execução de evento não é a mesma coisa que uma sessão de evento. A linha de execução do evento identifica um status atualizado para um evento anterior na mesma linha de execução. A sessão de eventos identifica eventos separados que se relacionam entre si, e pode haver várias linhas de execução de eventos para uma determinada sessão de eventos.
Para fins de notificação, diferentes tipos de eventos são agrupados em diferentes linhas de execução.
Essa lógica de agrupamento e temporização de linhas de execução é processada pelo Google e está sujeita a mudanças a qualquer momento. A developer precisa atualizar as notificações com base nas linhas de execução e sessões de eventos fornecidas pela API SDM.
Estado da linha de execução
Os eventos que oferecem suporte a notificações atualizáveis também têm um campo eventThreadState
que indica o estado da linha de execução do evento naquele momento. Esse
campo tem os seguintes valores:
- STARTED: o primeiro evento em uma linha de execução de eventos.
- UPDATED: um evento em uma linha de execução de evento em andamento. Pode haver zero ou mais eventos com esse estado em uma única linha de execução.
- ENDED: o último evento em uma linha de execução, que pode ser uma cópia do último evento UPDATED, dependendo do tipo de linha de execução.
Esse campo pode ser usado para acompanhar o progresso de uma linha de execução de evento e quando ela terminou.
Filtragem de eventos
Em alguns casos, os eventos detectados por um dispositivo podem ser filtrados da publicação em um tópico do Pub/Sub do SDM. Esse comportamento é chamado de filtragem de eventos. O objetivo da filtragem de eventos é evitar a publicação de muitas mensagens de eventos semelhantes em um curto período.
Por exemplo, uma mensagem pode ser publicada em um tópico do SDM para um evento inicial de movimento. As outras mensagens para o Motion depois disso serão filtradas da publicação até que um período definido de tempo passe. Depois que esse período passa, uma mensagem de evento para esse tipo de evento pode ser publicada novamente.
No app Google Home (GHA, na sigla em inglês), os eventos que foram filtrados ainda vão aparecer no histórico de eventos do user. No entanto, esses eventos não geram uma notificação do app, mesmo que esse tipo de notificação esteja ativado.
Cada tipo de evento tem sua própria lógica de filtragem, que é definida pelo Google e está sujeita a mudanças a qualquer momento. Essa lógica de filtragem de eventos é independente da lógica de sessão e da linha de execução do evento.
Contas de serviço
As contas de serviço são recomendadas para gerenciar assinaturas da API SDM e mensagens de evento. Uma conta de serviço é usada por um aplicativo ou máquina virtual, não por uma pessoa, e tem uma chave de conta exclusiva.
A autorização da conta de serviço para a API Pub/Sub usa o OAuth de duas pernas (2LO, na sigla em inglês).
No fluxo de autorização de 2FA:
- O developer solicita um token de acesso usando uma chave de serviço.
- O developer usa o token de acesso com chamadas para a API.
Para saber mais sobre a autenticação de dois fatores do Google e como fazer a configuração, consulte Como usar o OAuth 2.0 para aplicativos de servidor para servidor.
Autorização
A conta de serviço precisa ser autorizada para uso com a API Pub/Sub:
- Ative a API Cloud Pub/Sub no Google Cloud.
- Crie uma conta de serviço e uma chave de conta de serviço, conforme descrito em Como criar uma conta de serviço. Recomendamos atribuir apenas o papel de Assinante do Pub/Sub. Faça o download da chave da conta de serviço para a máquina que vai usar a API Pub/Sub.
- Forneça suas credenciais de autenticação (chave da conta de serviço) ao
código do aplicativo seguindo as instruções na página da etapa
anterior ou receba um token de acesso manualmente usando
oauth2l
, se você quiser testar rapidamente o acesso à API. - Use as credenciais da conta de serviço ou o token de acesso com a
API
project.subscriptions
do Pub/Sub para extrair e confirmar mensagens.
oauth2l
O Google oauth2l
é uma ferramenta de linha de comando para OAuth escrita em Go. Instale-o para
Mac ou Linux usando Go.
- Se você não tiver o Go no seu sistema, faça o download e a instalação dele.
- Depois que o Go estiver instalado, instale o
oauth2l
e adicione o local dele à variável de ambientePATH
:go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
- Use
oauth2l
para receber um token de acesso para a API usando o escopo OAuth adequado:
Por exemplo, se a chave de serviço estiver localizada emoauth2l 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...
Consulte o README do oauth2l
(em inglês) para mais informações
sobre o uso.
Bibliotecas de cliente de APIs do Google
Há várias bibliotecas de cliente disponíveis para APIs do Google que usam o OAuth 2.0. Consulte Bibliotecas de cliente da API do Google para mais informações sobre a linguagem escolhida.
Ao usar essas bibliotecas com o Pub/Sub API, use as seguintes strings de escopo:
https://www.googleapis.com/auth/pubsub https://www.googleapis.com/auth/cloud-platform
Erros
Os seguintes códigos de erro podem ser retornados em relação a este guia:
Mensagem de erro | RPC | Solução de problemas |
---|---|---|
A imagem da câmera não está mais disponível para download. | DEADLINE_EXCEEDED |
As imagens de eventos expiram 30 segundos após a publicação do evento. Faça o download da imagem antes do prazo de validade. |
O ID do evento não pertence à câmera. | FAILED_PRECONDITION |
Use o eventID correto retornado pelo evento da câmera. |
Consulte a Referência de códigos de erro da API para conferir a lista completa de códigos de erro da API.