Eventi

Gli eventi sono asincroni e vengono 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 finché il token di accesso non viene revocato dall'utente e i messaggi degli eventi non sono scaduti.

Attiva eventi

Gli eventi sono una funzionalità facoltativa dell'API SDM. Consulta Attiva eventi per scoprire come attivarli per il tuo Project.

Google Cloud Pub/Sub

Consulta la documentazione di Google Cloud Pub/Sub per scoprire di più sul funzionamento di Pub/Sub. In particolare:

Scopri le nozioni di base di Pub/Sub con le loro guide pratiche.
Scopri come funziona l'autenticazione.
Scegli una libreria client fornita o scrivi la tua e utilizza le superfici API REST/HTTP o gRPC.

Sottoscrizione agli eventi

Prima di gennaio 2025, se gli eventi erano attivati per il tuo Project, ti sarebbe stato fornito un argomento specifico per quell' Project ID, nel formato:

projects/gcp-project-name/subscriptions/topic-id

I progetti creati dopo gennaio 2025 devono ospitare autonomamente i propri argomenti Pub/Sub e dovrai fornire il tuo ID argomento. Per ulteriori informazioni, consulta Creare un argomento.

Per ricevere gli eventi, crea una sottoscrizione pull o push all'argomento, a seconda del tuo caso d'uso. Sono supportate più sottoscrizioni all'argomento SDM. Per ulteriori informazioni, consulta Gestire le sottoscrizioni.

Avviare gli eventi

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

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

Ordine degli eventi

Pub/Sub non garantisce la distribuzione ordinata degli eventi e l'ordine di ricezione degli eventi potrebbe non corrispondere all'ordine in cui 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 unico messaggio di evento.

Per ulteriori informazioni, consulta Ordinare i messaggi.

ID utente

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

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

Eventi di relazione

Gli eventi di relazione rappresentano un aggiornamento relazionale per 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:

DATA/ORA CREAZIONE
ELIMINATO
AGGIORNATA

Il payload di un evento di relazione è il seguente:

Payload

{
  "eventId" : "465db104-bacc-41df-88ec-2a9b1888c998",
  "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, il object è la risorsa che ha attivato l'evento e il subject è la risorsa con cui il object ha ora una relazione. Nell' esempio sopra, un user ha concesso l'accesso a questo dispositivo specifico a un developer, e il dispositivo autorizzato di user' è ora correlato alla sua struttura autorizzata, il che attiva l'evento.

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

Campi

Campo	Descrizione	Tipo di dati
`eventId`	L'identificatore univoco dell'evento.	`string` Esempio: "d31091a1-4e8a-4600-87e1-943f93ad5ad0"
`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 offuscato univoco che rappresenta l'utente.	`string` Esempio: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"

Per saperne di più sui diversi tipi di eventi e sul loro funzionamento, consulta la pagina Eventi.

Esempi

I payload degli eventi variano a seconda del 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:

Viene eliminata una stanza

Eventi risorsa

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

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

Payload

{
  "eventId" : "98d6b069-a607-4fea-8512-ce78b8d61458",
  "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 dei singoli tratti per comprendere il formato del payload per qualsiasi evento risorsa di modifica del campo di tratto.

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

Payload

{
  "eventId" : "50ae838d-42fd-48b7-b46b-4c24f97787a5",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "fmLARdlpNMN9IiXyXjElNP1ZiI...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

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

Campi

Campo	Descrizione	Tipo di dati
`eventId`	L'identificatore univoco dell'evento.	`string` Esempio: "50ae838d-42fd-48b7-b46b-4c24f97787a5"
`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 offuscato univoco che rappresenta l'utente.	`string` Esempio: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
`eventThreadId`	L'identificatore univoco del thread dell'evento.	`string` Esempio: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
`eventThreadState`	Lo stato del thread dell'evento.	`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 saperne di più sui diversi tipi di eventi e sul loro funzionamento, consulta la pagina Eventi.

Notifiche aggiornabili

Le notifiche basate sugli eventi risorsa possono essere implementate in un'app, ad esempio per Android o iOS. Per ridurre il numero di notifiche inviate, è possibile implementare 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 gli eventi che supportano le notifiche aggiornabili e che sono contrassegnati come Aggiornabili nella documentazione. Questi eventi hanno un campo aggiuntivo denominato eventThreadId nei payload. Utilizza questo campo per collegare i singoli eventi allo scopo di aggiornare una notifica esistente visualizzata per un utente.

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

Ai fini delle notifiche, i diversi tipi di eventi vengono raggruppati in thread diversi.

Questa logica di raggruppamento e temporizzazione dei thread viene gestita da Google ed è soggetta a modifiche in qualsiasi momento. Un developer dovrebbe aggiornare le notifiche in base ai thread e alle sessioni di 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 dell'evento in quel momento. Questo campo ha i seguenti valori:

STARTED: il primo evento in un thread di eventi.
UPDATED: 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 può 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 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 di movimento iniziale. Gli altri messaggi per Motion verranno esclusi dalla pubblicazione fino a quando non sarà trascorso un periodo di tempo prestabilito. Una volta trascorso questo periodo di tempo, un messaggio di evento per quel tipo di evento potrebbe essere pubblicato di nuovo.

Nell'app Google Home, gli eventi che sono stati filtrati verranno comunque visualizzati nella cronologia eventi di user. Tuttavia, questi eventi non generano una notifica dell'app (anche se il tipo di notifica è attivato).

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 dalla logica di thread e sessione degli eventi.

Service account

I service account sono consigliati per la gestione delle sottoscrizioni all'API SDM e dei messaggi degli eventi. Un service account viene utilizzato da un'applicazione o da una macchina virtuale, non da una persona, e ha una propria chiave account univoca.

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

Nel flusso di autorizzazione 2LO:

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

Per scoprire di più su Google 2LO e su come configurarlo, consulta Utilizzo di OAuth 2.0 per applicazioni da server a server a server.

Autorizzazione

Il service account deve essere autorizzato per l'utilizzo con l'API Pub/Sub:

Attiva l'API Cloud Pub/Sub in Google Cloud.
Crea un service account e una chiave del service account come descritto in Creare un service account. Ti consigliamo di assegnare solo il ruolo Sottoscrittore Pub/Sub. Assicurati di scaricare la chiave del service account sulla macchina che utilizzerà l'API Pub/Sub.
Fornisci le credenziali di autenticazione (chiave del service account) al codice dell'applicazione seguendo le istruzioni riportate nella pagina del passaggio precedente oppure ottieni manualmente un token di accesso utilizzando oauth2l, se vuoi testare rapidamente l'accesso all'API.
Utilizza le credenziali del service account o il token di accesso con l' APIproject.subscriptions di Pub/Sub per eseguire il pull e inviare un ACK per i messaggi.

oauth2l

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

Se non hai Go sul tuo sistema, scaricalo e installalo.
Una volta installato Go, installa oauth2l e aggiungi la sua posizione alla variabile di ambiente PATH:
```
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:

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 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 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 di tua scelta, consulta Librerie client delle API di Google.

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

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

Errori

I seguenti codici di errore potrebbero essere restituiti in relazione a questa guida:

Messaggio di errore	RPC	Risoluzione dei problemi
L'immagine della videocamera non è più disponibile per il download.	`DEADLINE_EXCEEDED`	Le immagini degli eventi 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 l'`eventID` corretto restituito dall'evento della videocamera.

Per l'elenco completo dei codici di errore dell'API, consulta il riferimento ai codici di errore dell'API.

Eventi Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Attiva eventi

Google Cloud Pub/Sub

Sottoscrizione agli eventi

Avviare gli eventi

Ordine degli eventi

ID utente

Eventi di relazione

Payload

Campi

Esempi

DATA/ORA CREAZIONE

Struttura creata

Dispositivo creato

Dispositivo creato

AGGIORNATA

Dispositivo spostato

ELIMINATO

Struttura eliminata

Dispositivo eliminato

Dispositivo eliminato

Eventi risorsa

Payload

Payload

Campi

Notifiche aggiornabili

Stato del thread

Filtro degli eventi

Service account

Autorizzazione

oauth2l

Librerie client delle API di Google

Errori

Eventi