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 é desde que o token de acesso não seja revogado pelo usuário e as mensagens de evento não tenham sido expirou.
Ativar eventos
Os eventos são um recurso opcional da API SDM. Consulte Ativar eventos para saber como ativar esses recursos no seu Project.
Google Cloud Pub/Sub
Consulte a documentação do Google Cloud Pub/Sub para saber sobre como o Pub/Sub funciona. Especificamente, faça o seguinte:
- Aprenda os conceitos básicos do Pub/Sub com os Guias de instruções.
- Entenda como funciona a autenticação.
- Escolha uma Biblioteca de cliente fornecida. ou escrever a sua e usar o Plataformas da API REST/HTTP ou gRPC.
Inscrição no evento
Quando os eventos estiverem ativados para sua Project, você vai receber um tema específico para essa Project na forma de:
projects/sdm-prod/topics/enterprise-project-id
Para receber eventos, crie um objeto pull ou push para esse tópico, dependendo das suas caso de uso de negócios. Há suporte para várias assinaturas no tópico do SDM. Consulte Como gerenciar assinaturas para saber mais informações imprecisas ou inadequadas.
Iniciar eventos
Para iniciar eventos pela primeira vez após a criação da assinatura do Pub/Sub, faça uma
devices.list
chamada de API como um acionador único. Eventos de todas as estruturas e dispositivos serão publicados depois disso
chamada.
Para ver um exemplo, consulte Página Autorizar no início rápido Guia.
Ordem do evento
O Pub/Sub não garante a entrega ordenada de eventos, e a ordem de recebimento dos eventos não pode
correspondem à ordem em que os eventos realmente ocorreram. Usar a timestamp
para ajudar na reconciliação da ordem do evento. Os eventos também podem ser entregues 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 nos usuários (e não na estrutura ou no dispositivo), use o
userID
do payload do evento para correlacionar recursos e eventos. Este 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 relação
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:
- CRIADO
- EXCLUÍDO
- ATUALIZADO
O payload de um evento de relação é o seguinte:
Payload
{ "eventId" : "06f4651c-8fc0-4525-9138-1662ffe268b3", "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, object
é o recurso que acionou o evento e a
subject
é o recurso com que object
agora tem uma relação. Na
exemplo acima, um user concedeu acesso a este dispositivo específico para um
developer, e o dispositivo autorizado de useragora está relacionado ao
que aciona o evento.
Um subject
só pode ser um cômodo ou uma estrutura. Se a developer não tiver
permissão para visualizar a estrutura de user, o subject
estará sempre
vazio.
Campos
Campo | Descrição | Tipo de dados |
---|---|---|
eventId |
O identificador exclusivo do evento. | string Exemplo: "6c0031ac-b979-4622-858b-e2a4e38655ef" |
timestamp |
A hora 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 evento 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 foi excluída
Eventos do recurso
Um evento de recurso representa uma atualização específica de um recurso. Ela pode ser em resposta a uma mudança no valor de um campo de características, como a mudança do modo de um termostato. Também pode representar uma ação do dispositivo que não muda um campo de características, como pressionar um botão do dispositivo.
Um evento gerado em resposta a uma alteração no valor do campo de característica contém um
Objeto traits
, semelhante a uma chamada GET de dispositivo:
Payload
{
"eventId" : "172f8070-f7c7-42f7-9110-760c6049fc30",
"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 o indivíduo documentação de características para compreender o formato do payload de qualquer recurso de alteração de campos de características evento.
Um evento gerado em resposta a uma ação do dispositivo que não altera um campo de características também tem um
payload com um objeto resourceUpdate
, mas com um objeto events
.
em vez de um objeto traits
:
Payload
{ "eventId" : "dccde63e-29b8-49d7-ae64-198450bae2bf",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion
" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "Bw3CN4TTI2FtYtTsvRypvsfSXu...", } } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] }
Esses tipos de eventos de recursos são definidos em características específicas. Por exemplo, o O evento de movimento é definido CameraMotion trait. Consulte a documentação de cada característica para entender o formato de payload para esses tipos de eventos de recursos.
Campos
Campo | Descrição | Tipo de dados |
---|---|---|
eventId |
O identificador exclusivo do evento. | string Exemplo: "dccde63e-29b8-49d7-ae64-198450bae2bf" |
timestamp |
A hora em que o evento ocorreu. | string Exemplo: "2019-01-01T00:00:01Z" |
resourceUpdate |
Um objeto que detalha informações sobre a atualização de recursos. | object |
userId |
Um identificador exclusivo e ofuscado que representa o usuário. | string Exemplo: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi" |
eventThreadId |
O identificador exclusivo da sequência de eventos. | string Exemplo: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59" |
eventThreadState |
O estado da sequência de eventos. | 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
Notificações baseadas em eventos de recursos podem ser implementadas em um app, por exemplo, Android ou iOS. Para reduzir o número de notificações enviadas, um recurso chamado notificações atualizáveis podem ser implementadas, quando as notificações existentes são atualizadas com novas informações com base em eventos subsequentes do mesmo evento fioSelecionar o suporte do recurso de eventos para notificações atualizáveis e estão marcados como
Atualizável eventThreadId
nos payloads. Usar
para vincular eventos individuais com a finalidade de atualizar um
notificação que foi exibida a um usuário.
Uma sequência de eventos não é a mesma coisa que uma sessão de evento. A conversa do evento identifica o status atualizado de um evento anterior na mesma linha de execução. A event session identifica eventos separados que se relacionam entre si, e pode haver vários segmentos de eventos para uma determinada sessão de evento.
Para fins de notificação, diferentes tipos de eventos são agrupados em diferentes fios
Essa lógica de agrupamento e tempo é processada pelo Google e está sujeita a mudar a qualquer momento. O developer precisa atualizar as notificações com base no sequências de eventos e sessões fornecidas pela API SDM.
Estado da linha de execução
Os eventos compatíveis com notificações atualizáveis também têm um eventThreadState
.
campo que indica o estado da sequência de eventos naquele momento. Isso
tem os seguintes valores:
- STARTED: o primeiro evento em uma sequência de eventos.
- UPDATED: um evento em uma sequência de eventos em andamento. Pode haver zero ou mais eventos com esse estado em uma única linha de execução.
- ENDED — o último evento em uma sequência de eventos, que pode ser uma cópia do último evento UPDATED, dependendo do tipo de sequência.
Este campo pode ser usado para acompanhar o progresso de uma sequência de eventos e quando ela tem acabou.
Filtragem de eventos
Em alguns casos, os eventos detectados por um dispositivo podem ser filtrados da publicação a um tópico do Pub/Sub do SDM. Esse comportamento é chamada de filtragem de eventos. O objetivo da filtragem de eventos é evitar publicar 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 de movimento inicial. Outra opção para Motion. Depois disso, serão filtrados da publicação até que um determinado período passe. Uma vez que esse período de tempo, uma mensagem de evento para esse tipo de evento pode ser publicada novamente.
No app Google Home (GHA), os eventos que aconteceram filtrados ainda aparecem no histórico de eventos de user. No entanto, como não geram uma notificação de app (mesmo que esse tipo seja ativado).
Cada tipo de evento tem sua própria lógica de filtragem de eventos, que é definida pelo Google e sujeitos a alterações a qualquer momento. Essa lógica de filtragem de eventos independente da linha de execução do evento e da lógica da sessão.
Contas de serviço
As contas de serviço são recomendadas para gerenciar a API SDM inscrições e mensagens de eventos. Uma conta de serviço é usada por um aplicativo ou máquina virtual, não uma pessoa, e tem sua própria chave de conta exclusiva.
A autorização de conta de serviço para usos da API Pub/Sub OAuth de duas etapas (2LO).
No fluxo de autorização de 2LO:
- 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 o Google 2LO e como configurá-lo, acesse Uso do OAuth 2.0 para servidor para servidor Aplicativos.
Autorização
A conta de serviço deve ter autorização para uso com o API Pub/Sub:
- Ative o Cloud Pub/Sub API 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 conceder apenas o papel Assinante do Pub/Sub. Não se esqueça de faça o download da chave da conta de serviço na máquina que usará o a API Pub/Sub.
- Forneça suas credenciais de autenticação (chave da conta de serviço) à sua
o código do aplicativo seguindo as instruções na página da versão anterior
ou receba um token de acesso manualmente usando
oauth2l
, se você querem testar rapidamente o acesso à API. - Use as credenciais da conta de serviço ou o token de acesso com a
Pub/Sub
project.subscriptions
API para receber e confirmar mensagens.
OAuth 2
O Google oauth2l
é uma ferramenta de linha de comando para OAuth escrita em Go. Instalar por
Mac ou Linux usando Go.
- Se você não tem o Go no seu sistema, faça o download e instale-o primeiro.
- Depois que o Go for instalado, instale o
oauth2l
e adicione o local dele ao seuPATH
variável de ambiente: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 Escopos do OAuth:
Por exemplo, se a chave de serviço estiveroauth2l 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 uso
informações imprecisas ou inadequadas.
Bibliotecas de cliente de APIs do Google
Várias bibliotecas de cliente disponíveis para as APIs do Google que utilizam o OAuth 2.0. Consulte Bibliotecas de cliente das APIs do Google para mais informações sobre idioma de sua escolha.
Ao usar essas bibliotecas com o Pub/Sub API, use o 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 do evento expiram 30 segundos após a publicação. Faça o download da imagem antes que ela expire. |
O ID do evento não pertence à câmera. | FAILED_PRECONDITION |
Use a eventID correta retornada pelo evento da câmera. |
Consulte a Referência do código de erro da API para a lista completa de códigos de erro da API.