Eventos

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:

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" : "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"
}

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: "96305092-d82e-4e52-9115-29bfd0594bf0"
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"
}

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" : "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"
  ]
}

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" : "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"
  ]
}

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: "a556db20-2bab-4bd4-bb39-9c036a252a7e"
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 fio

Selecionar o suporte do recurso de eventos para notificações atualizáveis e estão marcados como Atualizável  na documentação. Esses eventos têm um campo extra chamado 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 aplicativo (mesmo que esse tipo de notificação 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 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, consulte 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:

  1. Ative o Cloud Pub/Sub API no Google Cloud.
  2. 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.
  3. 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.
  4. Use as credenciais da conta de serviço ou o token de acesso com o 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.

  1. Se você não tem o Go no seu sistema, faça o download e instale-o primeiro.
  2. Depois que o Go for instalado, instale o oauth2l e adicione o local dele ao seu PATH variável de ambiente: 
    go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
  3. Use oauth2l para receber um token de acesso para a API, usando o Escopos do OAuth: 
    oauth2l fetch --credentials path-to-service-key.json --scope https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform
    Por exemplo, se a chave de serviço estiver ~/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 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 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.