Gli eventi sono asincroni e gestiti da Google Cloud Pub/Sub, in un singolo 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 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 il tuo Project.
Google Cloud Pub/Sub
Per saperne di più sul funzionamento di Pub/Sub, consulta la documentazione di Google Cloud Pub/Sub. In particolare:
- Apprendi le nozioni di base di Pub/Sub con le relative guide illustrative.
- Scopri come funziona l'autenticazione.
- Scegli una libreria client fornita oppure scrivine una personalizzata e utilizza le piattaforme API REST/HTTP o gRPC.
Iscrizione all'evento
Quando gli eventi sono abilitati per Project, ti verrà fornito un argomento specifico per quell'ID Project , sotto forma di:
projects/sdm-prod/topics/enterprise-project-id
Per ricevere eventi, crea una sottoscrizione pull o push per l'argomento in questione, a seconda del caso d'uso. Sono supportate più sottoscrizioni all'argomento SDM. Per ulteriori informazioni, consulta la pagina relativa alla gestione degli abbonamenti.
Avvia eventi
Per avviare eventi per la prima volta dopo la creazione dell'abbonamento 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.
Ad 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 degli eventi. Gli eventi possono anche arrivare singolarmente o combinati in un singolo messaggio di evento.
Per maggiori informazioni, consulta Ordinare i messaggi.
ID utente
Se l'implementazione è basata sugli utenti (anziché sulla struttura o sul dispositivo), utilizza il campo userID
del payload dell'evento 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 un dispositivo viene eliminato da una struttura.
Esistono tre tipi di eventi di relazione:
- CREATA
- ELIMINATO
- AGGIORNATA
Il payload per un evento di relazione è il seguente:
Payload
{ "eventId" : "3d498951-e011-453f-b4a4-8f0f3025490b", "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, mentre 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 ora il dispositivo autorizzato di userè correlato alla sua struttura autorizzata, il 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, il campo subject
è sempre
vuoto.
Campi
Campo | Descrizione | Tipo di dati |
---|---|---|
eventId |
L'identificatore univoco dell'evento. | string Esempio: "be318647-3e45-4b05-a382-1364b7950a4f" |
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 offuscato che rappresenta l'utente. | string Esempio: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi" |
Per ulteriori informazioni sui diversi tipi di eventi e sul loro funzionamento, consulta 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 se:
- Una stanza è stata eliminata
Eventi risorsa
Un evento di 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 del trait, ad esempio la pressione di un pulsante di un dispositivo.
Un evento generato in risposta a una modifica nel valore del campo trait contiene un oggetto traits
, simile a una chiamata GET del dispositivo:
Payload
{
"eventId" : "c5448841-a7fd-496b-9d28-afbd3b3c7d4d",
"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 di trait ha anche un payload con un oggetto resourceUpdate
, ma con un oggetto events
anziché un oggetto traits
:
Payload
{ "eventId" : "d955c5f3-ef8c-4785-95d0-8c9e1a235d53",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion
" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "Rj8TzS9Prbe9GlRwQmiOzC1Lco...", } } } "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 Movimento viene definito nel percorso CameraMotion . 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: "d955c5f3-ef8c-4785-95d0-8c9e1a235d53" |
timestamp |
L'ora in cui si è verificato l'evento. | string Esempio: "2019-01-01T00:00:01Z" |
resourceUpdate |
Un oggetto che fornisce informazioni dettagliate sull'aggiornamento della risorsa. | object |
userId |
Un identificatore univoco 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 dell'evento. | string Valori: "STARTED", "UPDATED", "ENDED" |
resourceGroup |
Un oggetto che indica 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 Eventi.
Notifiche aggiornabili
Le notifiche basate su eventi delle risorse possono essere implementate in un'app, ad esempio Android o iOS. Per ridurre il numero di notifiche inviate, è possibile implementare una funzionalità denominata notifiche aggiornabili, in cui le notifiche esistenti vengono aggiornate con nuove informazioni in base agli eventi successivi nello stesso thread di eventi.Alcuni eventi supportano le notifiche aggiornabili e sono contrassegnati con la dicitura
Aggiornabile eventThreadId
nei loro payload. Utilizza questo campo per collegare i singoli eventi allo scopo di aggiornare una notifica esistente visualizzata per un utente.
Un thread di un evento non è uguale a una sessione di evento. Il thread di eventi identifica lo stato aggiornato di un evento precedente nello stesso thread. La sessione di eventi identifica eventi separati che sono correlati tra loro e possono esserci più thread di eventi per una determinata sessione di evento.
Ai fini delle notifiche, i diversi tipi di eventi vengono raggruppati in thread diversi.
Questa logica di raggruppamento dei thread e di temporizzazione è gestita da Google ed è soggetta a modifiche in qualsiasi momento. Un developer deve aggiornare le notifiche in base ai thread di eventi e alle sessioni 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 ha i seguenti valori:
- AVVIATO: il primo evento nel thread di un evento.
- AGGIORNATO: un evento in un thread di eventi in corso. In un singolo thread possono esistere 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 quando è terminato.
Filtro degli eventi
In alcuni casi, gli eventi rilevati da un dispositivo potrebbero essere esclusi dalla pubblicazione in un argomento Pub/Sub SDM. Questo comportamento è chiamato filtro degli eventi. Lo scopo del filtro eventi è evitare di pubblicare troppi messaggi di evento simili in un breve lasso di tempo.
Ad esempio, un messaggio potrebbe essere pubblicato in un argomento SDM per un evento Movimento iniziale. Dopodiché, gli altri messaggi per Motion verranno esclusi dalla pubblicazione fino a quando non sarà trascorso un determinato periodo di tempo. Una volta trascorso questo periodo, è possibile che venga pubblicato di nuovo un messaggio evento per quel tipo di evento.
Nell'app Google Home (GHA), 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, definita da Google e soggetta a modifiche in qualsiasi momento. Questa logica di filtro degli eventi è indipendente dal thread di eventi e dalla logica di 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:
- developer richiede un token di accesso utilizzando una chiave di servizio.
- developer utilizza il token di accesso con le chiamate all'API.
Per scoprire di più su Google 2LO e sulla sua configurazione, consulta Utilizzo di OAuth 2.0 per applicazioni server-server.
Autorizzazione
L'account di servizio deve essere autorizzato a essere utilizzato con l'API Pub/Sub:
- Abilita l'API Cloud Pub/Sub in Google Cloud.
- 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.
- Fornisci le credenziali di autenticazione (chiave dell'account di servizio) nel codice dell'applicazione seguendo le istruzioni riportate nella pagina del passaggio precedente oppure ottieni un token di accesso manualmente utilizzando
oauth2l
se vuoi testare rapidamente l'accesso all'API. - Utilizza le credenziali dell'account di servizio o il token di accesso con l'API Pub/Sub
project.subscriptions
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.
- Se non disponi di Go sul sistema, scaricalo e installalo.
- Una volta installato Go, installa
oauth2l
e aggiungi la relativa posizione alla variabile di ambientePATH
:go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
- Utilizza
oauth2l
per ottenere un token di accesso per l'API, utilizzando gli ambiti OAuth appropriati:
Ad esempio, se la chiave di servizio si trova inoauth2l 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...
Per ulteriori informazioni sull'utilizzo, consulta il oauth2l
README.
Librerie client delle API di Google
Sono disponibili diverse librerie client per le API di Google che utilizzano OAuth 2.0. Per ulteriori informazioni sulla lingua che preferisci, consulta le librerie client delle API di Google.
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
Potrebbero essere restituiti i seguenti codici di errore in relazione a questa guida:
Messaggio di errore | RPC | Risoluzione dei problemi |
---|---|---|
L'immagine della fotocamera non è più disponibile per il download. | DEADLINE_EXCEEDED |
Le immagini dell'evento scadono 30 secondi dopo la pubblicazione dell'evento. Assicurati di scaricare l'immagine prima della scadenza. |
L'ID evento non appartiene alla videocamera. | FAILED_PRECONDITION |
Utilizza il valore eventID corretto restituito dall'evento della videocamera. |
Consulta la pagina Riferimento per i codici di errore API per l'elenco completo dei codici di errore delle API.