Aktion.Geräte.SYNC

Dieser Intent fordert die Liste der Geräte an, die dem jeweiligen Nutzer und seinen Funktionen zugeordnet sind.

Sie wird während der Kontoverknüpfung oder wenn ein Nutzer seine Geräte manuell neu synchronisiert, ausgelöst. Die Auftragsausführung sollte mit den unterstützten Merkmalen und Attributen für jedes Gerät antworten.

In Ihrer SYNC-Antwort sollten alle mit dem Nutzer verknüpften Geräte zurückgegeben werden. Damit wird nicht bestimmt, ob ein bestimmtes Gerät erreichbar ist. Dies wird von den Antworten QUERY und EXECUTE verarbeitet.

Weitere Informationen finden Sie unter Identifizieren und synchronisieren.

Anfrageformat

Felder Typ Beschreibung
requestId String

Erforderlich.

ID der Anfrage.

inputs Array

Erforderlich.

Liste der Eingaben, die der Intent-Anfrage entsprechen.

[item, ...] Objekt

Typ und Nutzlast der Intent-Anfrage.

intent

Erforderlich.

(Konstante Wert: "action.devices.SYNC")

Intent-Anfragetyp.

Beispiele

SYNC-Intent-Anfrage

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}

Antwortformat

Felder Typ Beschreibung
requestId String

Erforderlich.

ID der entsprechenden Anfrage.

payload Objekt

Erforderlich.

Nutzlast der Intent-Antwort.

agentUserId String

Erforderlich.

Gibt die eindeutige (und unveränderliche) Nutzer-ID auf der Plattform des Agents an. Der String ist für Google nicht transparent. Wenn also auf der Seite des Agents ein unveränderliches Formular gegenüber einem änderbaren Formular besteht, verwenden Sie das unveränderliche Formular (z. B. eine Kontonummer statt einer E-Mail-Adresse).

errorCode String

Bei systematischen Fehlern in SYNC

debugString String

Detaillierter Fehler, der Nutzern nicht angezeigt, aber während der Entwicklung protokolliert oder verwendet werden kann.

devices Array

Erforderlich.

Liste der Geräte, die dem Nutzer gehören. Es werden keine oder mehr Geräte zurückgegeben. Das bedeutet, dass der Nutzer keine oder keine Verbindung hat.

[item, ...] Objekt

Gerätemetadaten.

id String

Erforderlich.

Die ID des Geräts in der Cloud des Entwicklers. Dieser Name muss sowohl für den Nutzer als auch für den Entwickler eindeutig sein. Im Fall einer gemeinsamen Nutzung kann dies dazu verwendet werden, mehrere Ansichten desselben Geräts zu entfernen. Sie sollte für das Gerät nicht geändert werden. Wenn sich das Gerät ändert, behandelt Assistant es als neues Gerät.

type String

Erforderlich.

Der Hardwaretyp des Geräts.

traits Array

Erforderlich.

Liste der Merkmale dieses Geräts. Definiert die Befehle, Attribute und Status, die das Gerät unterstützt.

[item, ...] String

Name des unterstützten Attributs.

name Objekt

Erforderlich.

Die Namen dieses Geräts.

defaultNames Array

Liste der vom Entwickler bereitgestellten Namen und nicht des Nutzers, häufig Herstellernamen, Artikelnummern usw.

[item, ...] String

Standardname des Geräts.

name String

Erforderlich.

Primärer Name des Geräts, der in der Regel vom Nutzer angegeben wird. Dies ist auch der Name, mit dem Assistant das Gerät in den Antworten beschreiben soll.

nicknames Array

Zusätzliche Namen, die vom Nutzer für das Gerät angegeben wurden.

[item, ...] String

Gerätealias.

willReportState Boolesch

Erforderlich.

Gibt an, ob die Status dieses Geräts durch den Echtzeitfeed aktualisiert werden. (True, um den Echtzeitfeed für den Berichtsstatus zu verwenden; und False, um das Abfragemodell zu verwenden.)

notificationSupportedByAgent Boolesch

(Standard: false)

Gibt an, ob Benachrichtigungen für das Gerät aktiviert sind.

roomHint String

Stellt den aktuellen Raum des Geräts im Zuhause des Nutzers bereit, um die Einrichtung zu vereinfachen

deviceInfo Objekt

Enthält Felder, in denen das Gerät bei Bedarf in einer einmaligen Logik beschrieben wird (z.B. „fehlerhafte Firmwareversion X von Y erfordert Anpassung der Farbe“ oder „Sicherheitsfehler erfordert, dass alle Nutzer von der Firmware Z benachrichtigt werden“).

manufacturer String

Das ist besonders nützlich, wenn der Entwickler ein Hub für andere Geräte ist. Google kann hier eine Standardliste der Hersteller bereitstellen, damit beispielsweise TP-Link und Smartthings "Osram" auf die gleiche Weise beschreiben.

model String

Die Modell- oder Artikelnummer des jeweiligen Geräts.

hwVersion String

Die spezifische Versionsnummer, die an die Hardware angehängt ist, sofern verfügbar.

swVersion String

Die spezifische Versionsnummer, die an die Software bzw. Firmware angehängt ist, sofern verfügbar.

attributes Objekt

Entspricht den Attributen, die in den einzelnen Merkmalen des Eigenschaftsattributs beschrieben sind.

customData Objekt

Vom Entwickler definiertes Objekt, das an künftige QUERY- und EXECUTE-Anfragen angehängt wird (maximal 512 Byte pro Gerät). Verwenden Sie dieses Objekt, um zusätzliche Informationen zu dem Gerät zu speichern, das Ihr Cloud-Dienst benötigt, z. B. die globale Region des Geräts. Für Daten in diesem Objekt gelten einige Einschränkungen: Es sind keine vertraulichen Informationen, einschließlich, aber nicht beschränkt auf personenbezogene Daten.

otherDeviceIds Array

Liste alternativer IDs, die zur Identifizierung eines mit der Cloud synchronisierten Geräts für die lokale Ausführung verwendet werden.

[item, ...] Objekt

Alternative Geräte-ID.

agentId String

Die ID des Agents. In der Regel ist das die Projekt-ID in der Actions Console.

deviceId String

Erforderlich.

Vom Agent definierte Geräte-ID. Die Geräte-ID muss eindeutig sein.

Beispiele

SYNC-Intent-Antwort

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