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: "action.devices.SYNC")

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: false)

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