Eventi

Gli eventi sono asincroni e gestiti da Google Cloud Pub/Sub, in un unico argomento per Project. Gli eventi forniscono aggiornamenti per tutti i dispositivi e le strutture e la ricezione degli eventi è garantita a condizione che il token di accesso non venga revocato dall'utente e che i messaggi di evento non siano scaduti.

Attiva eventi

Gli eventi sono una funzionalità facoltativa dell'API SDM. Consulta Attivare gli eventi per scoprire come attivarli per la tua Project.

Google Cloud Pub/Sub

Per saperne di più sul funzionamento di Pub/Sub, consulta la documentazione di Google Cloud Pub/Sub. In particolare:

Iscrizione all'evento

Quando sono abilitati eventi per Project, ti verrà fornito un argomento specifico per quell' Project ID, sotto forma di:

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

Per ricevere eventi, crea una sottoscrizione pull o push per quell'argomento, a seconda del caso d'uso. Sono supportate più sottoscrizioni all'argomento SDM. Per ulteriori informazioni, consulta Gestione degli abbonamenti.

Avviare eventi

Per avviare gli eventi per la prima volta dopo la creazione della sottoscrizione Pub/Sub, effettua una chiamata API devices.list come trigger una tantum. Gli eventi per tutte le strutture e i dispositivi verranno pubblicati dopo questa chiamata.

Per un esempio, consulta la pagina Autorizza nella Guida rapida.

Ordine evento

Pub/Sub non garantisce la consegna ordinata degli eventi e l'ordine di ricezione degli eventi potrebbe non corrispondere all'ordine in cui gli eventi si sono effettivamente verificati. Utilizza il campo timestamp per facilitare la riconciliazione dell'ordine dell'evento. Gli eventi possono anche arrivare singolarmente o combinati in un singolo messaggio evento.

Per maggiori informazioni, consulta Ordinare messaggi.

ID utente

Se l'implementazione si basa sugli utenti (anziché sulla struttura o sul dispositivo), utilizza il campo userID del payload degli eventi per correlare risorse ed eventi. Questo campo è un ID offuscato che rappresenta un utente specifico.

userID è disponibile anche nell'intestazione della risposta HTTP di ogni chiamata API.

Eventi di relazione

Gli eventi di relazione rappresentano un aggiornamento relazionale di una risorsa. ad esempio quando un dispositivo viene aggiunto a una struttura o quando viene eliminato da una struttura.

Esistono tre tipi di eventi correlati:

  • CREATED
  • ELIMINATO
  • AGGIORNATA

Il payload per un evento di relazione è il seguente:

Payload

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

In un evento di relazione, object è la risorsa che ha attivato l'evento e subject è la risorsa con cui object ha ora una relazione. Nell'esempio precedente, user ha concesso l'accesso a questo dispositivo specifico a un developere il dispositivo autorizzato di userè ora correlato alla sua struttura autorizzata, che attiva l'evento.

Un subject può essere solo una stanza o una struttura. Se a developer non dispone dell'autorizzazione per visualizzare la struttura di user, subject è sempre vuoto.

Campi

Campo Descrizione Tipo di dati
eventId L'identificatore univoco dell'evento. string
Esempio: "1362476b-4ac4-4608-a8be-4c8cf4101426"
timestamp L'ora in cui si è verificato l'evento. string
Esempio: "2019-01-01T00:00:01Z"
relationUpdate Un oggetto che descrive in dettaglio le informazioni sull'aggiornamento della relazione. object
userId Un identificatore univoco e offuscato che rappresenta l'utente. string
Esempio: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"

Per ulteriori informazioni sui diversi tipi di eventi e sul loro funzionamento, consulta la sezione Eventi.

Esempi

I payload degli eventi sono diversi per ogni tipo di evento di relazione:

DATA/ORA CREAZIONE

Struttura creata

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

Dispositivo creato

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

Dispositivo creato

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

AGGIORNATA

Dispositivo spostato

"relationUpdate" : {
  "type" : "UPDATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

ELIMINATO

Struttura eliminata

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

Dispositivo eliminato

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

Dispositivo eliminato

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

Gli eventi di relazione non vengono inviati quando:

  • È stata eliminata una stanza

Eventi risorsa

Un evento della risorsa rappresenta un aggiornamento specifico di una risorsa. Può essere in risposta a una modifica nel valore di un campo trait, ad esempio la modifica della modalità di un termostato. Può anche rappresentare un'azione del dispositivo che non modifica un campo dei trait, ad esempio la pressione di un pulsante del dispositivo.

Un evento generato in risposta a una modifica nel campo del valore del trait contiene un oggetto traits, simile a una chiamata GET di dispositivo:

Payload

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

Utilizza la documentazione relativa ai singoli trait per comprendere il formato del payload per qualsiasi evento di risorsa di modifica dei campi dei trait.

Un evento generato in risposta a un'azione del dispositivo che non modifica un campo dei trait ha anche un payload con un oggetto resourceUpdate, ma con un oggetto events anziché un oggetto traits:

Payload

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

Questi tipi di eventi delle risorse sono definiti in tratti specifici. Ad esempio, l'evento di movimento viene definito nel tratto FotocameraMotion . Consulta la documentazione di ogni trait per comprendere il formato del payload per questi tipi di eventi delle risorse.

Campi

Campo Descrizione Tipo di dati
eventId L'identificatore univoco dell'evento. string
Esempio: "3426d266-406b-48f3-9595-5192229a39a0"
timestamp L'ora in cui si è verificato l'evento. string
Esempio: "2019-01-01T00:00:01Z"
resourceUpdate Un oggetto che descrive in dettaglio le informazioni sull'aggiornamento della risorsa. object
userId Un identificatore univoco e offuscato che rappresenta l'utente. string
Esempio: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
eventThreadId L'identificatore univoco del thread di eventi. string
Esempio: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
eventThreadState Lo stato del thread di eventi. string
Valori: "STARTED", "UPDATED", "ENDED"
resourceGroup Un oggetto che indica le risorse che potrebbero avere aggiornamenti simili a questo evento. La risorsa dell'evento stesso (dall'oggetto resourceUpdate) sarà sempre presente in questo oggetto. object

Per ulteriori informazioni sui diversi tipi di eventi e sul loro funzionamento, consulta la sezione Eventi.

Notifiche aggiornabili

Le notifiche basate sugli eventi delle risorse possono essere implementate in un'app, ad esempio per Android o iOS. Per ridurre il numero di notifiche inviate, potrebbe essere implementata una funzionalità chiamata notifiche aggiornabili, in cui le notifiche esistenti vengono aggiornate con nuove informazioni in base agli eventi successivi nello stesso thread di eventi.

Seleziona il supporto delle funzionalità di eventi per le notifiche aggiornabili e sono contrassegnati come Aggiornabili  nella documentazione. Questi eventi hanno un campo aggiuntivo chiamato eventThreadId nei loro payload. Utilizza questo campo per collegare singoli eventi allo scopo di aggiornare una notifica esistente che è stata mostrata per un utente.

Un thread di eventi non corrisponde a una sessione di eventi. Il thread di evento identifica uno stato aggiornato per un evento precedente nello stesso thread. La sessione evento identifica eventi separati correlati tra loro e possono esserci più thread di eventi per una determinata sessione di evento.

A scopo di notifica, diversi tipi di eventi vengono raggruppati in thread diversi.

Questa logica di raggruppamento e tempistica dei thread è gestita da Google ed è soggetta a modifiche in qualsiasi momento. developer deve aggiornare le notifiche in base alle sessioni e ai thread degli eventi forniti dall'API SDM.

Stato del thread

Gli eventi che supportano le notifiche aggiornabili hanno anche un campo eventThreadState che indica lo stato del thread di eventi in quel momento. Questo campo contiene i seguenti valori:

  • AVVIATO: il primo evento in un thread di eventi.
  • AGGIORNATO: un evento in un thread di eventi in corso. In un singolo thread possono esserci zero o più eventi con questo stato.
  • ENDED: l'ultimo evento in un thread di eventi, che potrebbe essere un duplicato dell'ultimo evento UPDATED, a seconda del tipo di thread.

Questo campo può essere utilizzato per monitorare l'avanzamento di un thread di eventi e la sua fine.

Filtro degli eventi

In alcuni casi, gli eventi rilevati da un dispositivo potrebbero essere esclusi dalla pubblicazione in un argomento SDM Pub/Sub. Questo comportamento è chiamato filtro degli eventi. Lo scopo del filtro degli eventi è evitare di pubblicare troppi messaggi di eventi simili in un breve periodo di tempo.

Ad esempio, un messaggio potrebbe essere pubblicato in un argomento SDM per un evento Movimento iniziale. Gli altri messaggi per l'azione successivi verranno esclusi dalla pubblicazione fino al termine di un determinato periodo di tempo. Una volta trascorso questo periodo, un messaggio per quel tipo di evento può essere pubblicato di nuovo.

Nell'app Google Home, gli eventi filtrati continueranno a essere visualizzati nella panoramica eventi di user. Tuttavia, questi eventi non generano una notifica dell'app (anche se quel tipo di notifica è abilitato).

Ogni tipo di evento ha una propria logica di filtro degli eventi, che è definita da Google e soggetta a modifiche in qualsiasi momento. Questa logica di filtro degli eventi dipende dal thread di eventi e dalla logica della sessione.

Account di servizio

Gli account di servizio sono consigliati per gestire le iscrizioni e i messaggi di evento dell'API SDM. Un account di servizio viene utilizzato da un'applicazione o da una macchina virtuale, non da una persona, e ha una propria chiave di account univoca.

L'autorizzazione dell'account di servizio per l'API Pub/Sub utilizza OAuth a due vie (2LO).

Nel flusso di autorizzazione 2LO:

  • L'oggetto developer richiede un token di accesso utilizzando una chiave di servizio.
  • L' developer utilizza il token di accesso con le chiamate all'API.

Per scoprire di più su Google 2LO e su come eseguire la configurazione, consulta Utilizzo di OAuth 2.0 per applicazioni server-server.

Autorizzazione

L'account di servizio deve essere autorizzato per l'utilizzo con l'API Pub/Sub:

  1. Abilita l'API Cloud Pub/Sub in Google Cloud.
  2. Crea un account di servizio e una chiave dell'account di servizio come descritto in Creazione di un account di servizio. Ti consigliamo di assegnargli solo il ruolo Sottoscrittore Pub/Sub. Assicurati di scaricare la chiave dell'account di servizio nella macchina che utilizzerà l'API Pub/Sub.
  3. Fornisci le credenziali di autenticazione (chiave dell'account di servizio) al codice dell'applicazione seguendo le istruzioni riportate nella pagina del passaggio precedente oppure richiedi un token di accesso manualmente utilizzando oauth2l, se vuoi testare rapidamente l'accesso all'API.
  4. Utilizza le credenziali dell'account di servizio o il token di accesso con l'API project.subscriptions Pub/Sub per eseguire il pull e la conferma dei messaggi.

Oauth2L

Google oauth2l è uno strumento a riga di comando per OAuth scritto in Go. Installalo per Mac o Linux utilizzando Go.

  1. Se non hai Go sul tuo sistema, scaricalo e installalo prima.
  2. Dopo aver installato Go, installa oauth2l e aggiungi il relativo percorso alla variabile di ambiente PATH: 
    go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
  3. Utilizza oauth2l per ottenere un token di accesso per l'API, utilizzando gli ambiti OAuth appropriati: 
    oauth2l fetch --credentials path-to-service-key.json --scope https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform
    Ad esempio, se la tua chiave di servizio si trova in ~/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...

Per ulteriori informazioni sull'utilizzo, consulta il file README di oauth2l.

Librerie client delle API di Google

Sono disponibili diverse librerie client per le API di Google che utilizzano OAuth 2.0. Consulta le librerie client delle API di Google per ulteriori informazioni sulla lingua scelta.

Quando utilizzi queste librerie con Pub/Sub API, usa le seguenti stringhe di ambito:

https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform

Errori

In relazione a questa guida, è possibile che vengano restituiti i seguenti codici di errore:

Messaggio di errore RPC Risoluzione dei problemi
L'immagine della fotocamera non è più disponibile per il download. DEADLINE_EXCEEDED Le immagini degli eventi scadono 30 secondi dopo la loro pubblicazione. Assicurati di scaricare l'immagine prima della scadenza.
L'ID evento non appartiene alla videocamera. FAILED_PRECONDITION Usa il valore eventID corretto restituito dall'evento della videocamera.

Consulta la pagina Riferimento sui codici di errore API per l'elenco completo dei codici di errore API.