Questa pagina è stata tradotta dall'API Cloud Translation.

Eventi

Gli eventi sono asincroni e gestiti da Google Cloud Pub/Sub, in un unico argomento Project. Gli eventi forniscono aggiornamenti per tutti i dispositivi e le strutture; inoltre, la ricezione degli eventi è garantito purché il token di accesso non venga revocato dall'utente e i messaggi di evento non siano stati scaduto.

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 scoprire di più, consulta la documentazione di Google Cloud Pub/Sub di più su come funziona Pub/Sub. In particolare:

Apprendi le nozioni di base di Pub/Sub Guide illustrative.
Scopri come funziona l'autenticazione.
Scegli una libreria client fornita. oppure scrivine una personalizzata e utilizza Piattaforme API REST/HTTP o gRPC.

Iscrizione all'evento

Quando gli eventi sono abilitati per Project, ti verrà fornito un argomento specifico Project ID, che assume la connotazione di:

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

Per ricevere eventi, crea un comando pull o push dell'abbonamento in questione, a seconda del tuo caso d'uso. Sono supportate più sottoscrizioni all'argomento SDM. Consulta: Gestione degli abbonamenti per ulteriori informazioni informazioni.

Avvia eventi

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

Per un esempio, vedi Pagina Autorizza nella Guida rapida Guida.

Ordine evento

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

Per ulteriori informazioni, vedi Ordinare i messaggi.

ID utente

Se la tua implementazione si basa sugli utenti (anziché sulla struttura o sul dispositivo), utilizza 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 aggiunte 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 per un evento di relazione è il seguente:

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

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

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

Campi

Campo	Descrizione	Tipo di dati
`eventId`	L'identificatore univoco dell'evento.	`string` Esempio: "96305092-d82e-4e52-9115-29bfd0594bf0"
`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"

Consulta la sezione Eventi per ulteriori informazioni sulle diverse tipi di eventi e come funzionano.

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 un cambiamento nel valore di un campo trait, ad esempio la modifica della modalità di un termostato. Può anche rappresentare un'azione dei dispositivi che non modifica un campo trait, ad esempio premendo 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" : "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"
  ]
}

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

Un evento generato in risposta a un'azione del dispositivo che non modifica un campo trait ha anche un Payload con un oggetto resourceUpdate, ma con un oggetto events anziché un oggetto 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"
  ]
}

Questi tipi di eventi delle risorse sono definiti in tratti specifici. Ad esempio, L'evento di movimento è definito nel CameraMotion trait. Visualizza 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: "a556db20-2bab-4bd4-bb39-9c036a252a7e"
`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`

Consulta la sezione Eventi per ulteriori informazioni sulle diverse tipi di eventi e come funzionano.

Notifiche aggiornabili

Le notifiche basate sugli eventi relativi alle risorse possono essere implementate in un'app, ad esempio per Android o iOS. Per ridurre il numero di notifiche inviate, è stata attivata una funzione chiamata Potrebbero essere implementate notifiche aggiornabili, nel caso in cui le notifiche esistenti vengono aggiornati con nuove informazioni in base agli eventi successivi nello stesso evento .

Gli eventi selezionati supportano le notifiche aggiornabili e sono contrassegnati come Aggiornabile nella documentazione. Questi eventi hanno un campo aggiuntivo chiamato eventThreadId nei loro payload. Usa questa per collegare i singoli eventi allo scopo di aggiornare uno esistente che viene mostrata a un utente.

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

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

Questa logica di raggruppamento dei thread e di temporizzazione è gestita da Google ed è soggetta alle possono essere modificate in qualsiasi momento. developer deve aggiornare le notifiche in base sessioni e thread di eventi forniti dall'API SDM.

Stato del thread

Gli eventi che supportano le notifiche aggiornabili hanno anche un eventThreadState che indica lo stato del thread di eventi in quel momento. Questo 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 Pubblicazione di troppi messaggi di evento simili in un breve periodo di tempo.

Ad esempio, un messaggio potrebbe essere pubblicato in un argomento SDM per un evento Movimento iniziale. Altro i messaggi per Motion, dopodiché saranno esclusi dalla pubblicazione finché non passa un determinato periodo di tempo. Una volta trascorso questo periodo, di tempo, un messaggio per quel tipo di evento potrebbe essere pubblicato di nuovo.

Nell'app Google Home (GHA), gli eventi che sono stati i filtri applicati continueranno a essere visualizzati nella panoramica eventi di user. Tuttavia, tali eventi non generano una notifica dell'app (anche se quel tipo di notifica è attivata).

Ogni tipo di evento ha una propria logica di filtro, definita Google e soggetti a modifiche in qualsiasi momento. Questa logica di filtro degli eventi indipendenti dal thread di eventi e dalla logica di sessione.

Account di servizio

Gli account di servizio sono consigliati per gestire l'API SDM sottoscrizioni e messaggi di evento. Un account di servizio è utilizzato da un'applicazione una macchina virtuale, non una persona, e ha una propria chiave di account univoca.

Autorizzazione dell'account di servizio per gli utilizzi dell'API Pub/Sub 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 su come configurarlo, consulta Utilizzo di OAuth 2.0 per le versioni da server a server Applicazioni.

Autorizzazione

L'account di servizio deve essere autorizzato a essere utilizzato con API Pub/Sub:

Abilita Cloud Pub/Sub tramite Google Cloud 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 scarica la chiave dell'account di servizio nella macchina che utilizzerà l'API Pub/Sub.
Fornisci le credenziali di autenticazione (chiave dell'account di servizio) al tuo seguire le istruzioni nella pagina nella sezione o ricevere 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 Pub/Sub project.subscriptions API eseguire il pull e confermare i messaggi.

oauth2l

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

Se non disponi di Go sul sistema, scaricalo e installalo.
Dopo aver installato Go, installa oauth2l e aggiungi la relativa posizione su PATH variabile di ambiente:
```
go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
```

Utilizza oauth2l per ottenere un token di accesso per l'API, utilizzando l'appropriata Ambiti OAuth:

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...

Consulta il oauth2l README per ulteriori informazioni sull'utilizzo informazioni.

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 sul nella lingua che preferisci.

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 documentazione sul codice di errore API per l'elenco completo dei codici di errore dell'API.