action.devices.SYNC
Questo intent richiede l'elenco dei dispositivi associati all'utente specificato e delle sue funzionalità.
Si attiva durante il collegamento dell'account o quando un utente sincronizza manualmente i propri dispositivi. La distribuzione deve rispondere con le caratteristiche e gli attributi supportati per ogni dispositivo.
La tua risposta SYNC
dovrebbe restituire tutti i dispositivi associati all'utente.
Questa impostazione non determina se un particolare dispositivo è raggiungibile. Ciò viene gestito dalle risposte QUERY
e EXECUTE
.
Per maggiori dettagli, vedi Identificare e sincronizzare.
Formato della richiesta
Campi | Tipo | Descrizione |
---|---|---|
requestId |
Stringa |
Obbligatorio. ID della richiesta. |
inputs |
Array |
Obbligatorio. Elenco di input corrispondenti alla richiesta di intent. |
[item, ...] |
Oggetto |
Tipo e payload associati alla richiesta di intent. |
intent |
Obbligatorio. (Valore costante: Tipo di richiesta di intent. |
Esempi
Richiesta di sincronizzazione Intent
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [ { "intent": "action.devices.SYNC" } ] }
Formato della risposta
Campi | Tipo | Descrizione |
---|---|---|
requestId |
Stringa |
Obbligatorio. ID della richiesta corrispondente. |
payload |
Oggetto |
Obbligatorio. Payload della risposta dell'intent. |
agentUserId |
Stringa |
Obbligatorio. Indica l'ID utente univoco (e immutabile) sulla piattaforma dell'agente. La stringa è opaca per Google, quindi se è presente un modulo immutabile rispetto a un modulo modificabile per l'agente, utilizza il modulo immutabile (ad es. un numero di account anziché l'email). |
errorCode |
Stringa |
Per errori sistematici su SYNC |
debugString |
Stringa |
Errore dettagliato che non verrà mai presentato agli utenti, ma potrebbe essere registrato o utilizzato durante lo sviluppo. |
devices |
Array |
Obbligatorio. Elenco dei dispositivi di proprietà dell'utente. Vengono restituiti zero o più dispositivi (nessun dispositivo significa che l'utente non ha dispositivi o li ha disconnessi tutti). |
[item, ...] |
Oggetto |
Metadati del dispositivo. |
id |
Stringa |
Obbligatorio. L'ID del dispositivo nel cloud dello sviluppatore. Deve essere univoco per l'utente e per lo sviluppatore, poiché, in caso di condivisione, potremmo utilizzarlo per deduplicare più visualizzazioni dello stesso dispositivo. Deve essere immutabile per il dispositivo e, se cambia, l'assistente lo considera come un nuovo dispositivo. |
type |
Stringa |
Obbligatorio. Il tipo di dispositivo hardware. |
traits |
Array |
Obbligatorio. Elenco delle caratteristiche del dispositivo. Questo attributo definisce i comandi, gli attributi e gli stati supportati dal dispositivo. |
[item, ...] |
Stringa |
Nome della caratteristica supportata. |
name |
Oggetto |
Obbligatorio. Nomi del dispositivo. |
defaultNames |
Array |
Elenco di nomi forniti dallo sviluppatore anziché dall'utente, spesso con nomi di produttori, SKU e così via. |
[item, ...] |
Stringa |
Nome predefinito del dispositivo. |
name |
Stringa |
Obbligatorio. Nome principale del dispositivo, generalmente fornito dall'utente. Si tratta anche del nome che l'assistente preferirà per descrivere il dispositivo nelle risposte. |
nicknames |
Array |
Nomi aggiuntivi forniti dall'utente per il dispositivo. |
[item, ...] |
Stringa |
Nickname del dispositivo. |
willReportState |
Booleano |
Obbligatorio. Indica se lo stato del dispositivo verrà aggiornato dal feed in tempo reale. (vero per utilizzare il feed in tempo reale per lo stato dei rapporti e falso per utilizzare il modello di sondaggio). |
notificationSupportedByAgent |
Booleano |
(valore predefinito: Indica se le notifiche sono attivate per il dispositivo. |
roomHint |
Stringa |
Fornisce la stanza attuale del dispositivo nella casa dell'utente per semplificare la configurazione. |
deviceInfo |
Oggetto |
Se necessario, contiene i campi che descrivono il dispositivo per l'utilizzo in una logica che interessa una sola volta (ad esempio, "la versione del firmware X interrotta della spia Y richiede la regolazione del colore") oppure "il problema di sicurezza richiede la notifica di tutti gli utenti del firmware Z". |
manufacturer |
Stringa |
Utile in particolar modo quando lo sviluppatore è un hub per altri dispositivi. Google potrebbe fornire un elenco standard di produttori, in modo che ad esempio TP-Link e Smartthings descrivano nello stesso modo "osram". |
model |
Stringa |
Il modello o l'identificatore SKU del dispositivo specifico. |
hwVersion |
Stringa |
Il numero di versione specifico allegato all'hardware, se disponibile. |
swVersion |
Stringa |
Il numero di versione specifico allegato al software/firmware, se disponibile. |
attributes |
Oggetto |
Allineato con gli attributi per trattino descritti in ogni riferimento allo schema del tratto. |
customData |
Oggetto |
Oggetto definito dallo sviluppatore che verrà associato alle future richieste QUERY ed EXECUTE, massimo 512 byte per dispositivo. Utilizza questo oggetto per archiviare ulteriori informazioni sul dispositivo di cui il servizio cloud potrebbe avere bisogno, ad esempio l'area geografica globale del dispositivo. I dati in questo oggetto hanno alcuni vincoli: nessuna informazione sensibile, incluse, a titolo esemplificativo, le informazioni personali. |
otherDeviceIds |
Array |
Elenco di ID alternativi utilizzati per identificare un dispositivo sincronizzato con cloud per l'esecuzione locale. |
[item, ...] |
Oggetto |
ID dispositivo alternativo. |
agentId |
Stringa |
ID dell'agente. In genere, si tratta dell'ID progetto nella console di Actions. |
deviceId |
Stringa |
Obbligatorio. ID dispositivo definito dall'agente. L'ID dispositivo deve essere univoco. |
Esempi
Risposta dell'intento di SINCRONIZZAZIONE
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "agentUserId": "1836.15267389", "devices": [ { "id": "123", "type": "action.devices.types.OUTLET", "traits": [ "action.devices.traits.OnOff" ], "name": { "defaultNames": [ "My Outlet 1234" ], "name": "Night light", "nicknames": [ "wall plug" ] }, "willReportState": false, "roomHint": "kitchen", "deviceInfo": { "manufacturer": "lights-out-inc", "model": "hs1234", "hwVersion": "3.2", "swVersion": "11.4" }, "otherDeviceIds": [ { "deviceId": "local-device-id" } ], "customData": { "fooValue": 74, "barValue": true, "bazValue": "foo" } }, { "id": "456", "type": "action.devices.types.LIGHT", "traits": [ "action.devices.traits.OnOff", "action.devices.traits.Brightness", "action.devices.traits.ColorSetting" ], "name": { "defaultNames": [ "lights out inc. bulb A19 color hyperglow" ], "name": "lamp1", "nicknames": [ "reading lamp" ] }, "willReportState": false, "roomHint": "office", "attributes": { "colorModel": "rgb", "colorTemperatureRange": { "temperatureMinK": 2000, "temperatureMaxK": 9000 }, "commandOnlyColorSetting": false }, "deviceInfo": { "manufacturer": "lights out inc.", "model": "hg11", "hwVersion": "1.2", "swVersion": "5.4" }, "customData": { "fooValue": 12, "barValue": false, "bazValue": "bar" } } ] } }