action.devices.SYNC

Mit diesem Intent wird die Liste der Geräte angefordert, die dem angegebenen Nutzer zugeordnet sind, sowie deren Funktionen.

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

Ihre SYNC-Antwort sollte alle Geräte zurückgeben, die mit dem Nutzer verknüpft sind. Dadurch wird nicht bestimmt, ob ein bestimmtes Gerät erreichbar ist. Dies wird durch die Antworten QUERY und EXECUTE abgedeckt.

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, die der Intent-Anfrage zugeordnet sind.

intent

Erforderlich.

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

Typ der Intent-Anfrage.

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.

Entspricht der eindeutigen (und unveränderlichen) Nutzer-ID auf der Plattform des Kundenservicemitarbeiters. Der String ist für Google nicht sichtbar. Wenn es auf der Agentenseite eine unveränderliche und eine veränderliche Form gibt, verwenden Sie die unveränderliche Form (z. B. eine Kontonummer anstelle einer E-Mail-Adresse).

errorCode String

Systematische Fehler bei SYNC

debugString String

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

devices Array

Erforderlich.

Liste der Geräte, die dem Nutzer gehören. Es werden null oder mehr Geräte zurückgegeben. „Null Geräte“ bedeutet, dass der Nutzer keine Geräte hat oder alle Geräte getrennt hat.

[item, ...] Objekt

Gerätemetadaten.

id String

Erforderlich.

Die ID des Geräts in der Cloud des Entwicklers. Diese ID muss für den Nutzer und den Entwickler eindeutig sein, da wir sie im Falle der Freigabe verwenden können, um mehrere Aufrufe desselben Geräts zu deduplizieren. Sie sollte für das Gerät unveränderlich sein. Wenn sie sich ändert, behandelt Assistant das Gerät als neues Gerät.

type String

Erforderlich.

Der Hardwaretyp des Geräts.

traits Array

Erforderlich.

Liste der Traits dieses Geräts. Hier werden die vom Gerät unterstützten Befehle, Attribute und Status definiert.

[item, ...] String

Name des unterstützten Merkmals.

name Objekt

Erforderlich.

Namen dieses Geräts.

defaultNames Array

Liste der Namen, die vom Entwickler und nicht vom Nutzer angegeben werden, 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. Das ist auch der Name, den Assistant bevorzugt verwendet, um das Gerät in Antworten zu beschreiben. Namen werden abgeschnitten, wenn sie das Limit von 60 Unicode-Codepunkten (Zeichen) überschreiten. Es werden keine Fehler ausgegeben. Entwickler sind dafür verantwortlich, lange Namen zu verarbeiten.

nicknames Array

Zusätzliche Namen, die der Nutzer für das Gerät angegeben hat.

[item, ...] String

Gerätealias

willReportState Boolesch

Erforderlich.

Gibt an, ob die Status dieses Geräts über den Echtzeit-Feed aktualisiert werden. „true“, um den Echtzeit-Feed für den Berichtsstatus zu verwenden, und „false“, um das Polling-Modell zu verwenden.

notificationSupportedByAgent Boolesch

(Standardeinstellung: false)

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

roomHint String

Gibt den aktuellen Raum des Geräts im Zuhause des Nutzers an, um die Einrichtung zu vereinfachen.

deviceInfo Objekt

Enthält Felder, die das Gerät für die einmalige Logik beschreiben, falls erforderlich (z.B. „Die fehlerhafte Firmware-Version X von Lampe Y erfordert eine Anpassung der Farbe“ oder „Eine Sicherheitslücke erfordert, dass alle Nutzer der Firmware Z benachrichtigt werden“).

manufacturer String

Das ist besonders nützlich, wenn das Gerät als Hub für andere Geräte dient. Google stellt möglicherweise eine Standardliste von Herstellern zur Verfügung, damit z.B. TP-Link und Smartthings „Osram“ auf dieselbe Weise beschreiben.

model String

Die Modell- oder SKU-Kennung des jeweiligen Geräts.

hwVersion String

Genaue Versionsnummer der Hardware, falls verfügbar.

swVersion String

Falls verfügbar, eine bestimmte Versionsnummer, die mit der Software/Firmware verknüpft ist.

attributes Objekt

Entspricht den Attributen pro Merkmal, die in jeder Merkmal-Schemareferenz beschrieben werden.

customData Objekt

Vom Entwickler definiertes Objekt, das an zukünftige QUERY- und EXECUTE-Anfragen angehängt wird. Maximal 512 Byte pro Gerät. Mit diesem Objekt können Sie zusätzliche Informationen zum Gerät speichern, die Ihr Cloud-Dienst möglicherweise benötigt, z. B. die globale Region des Geräts. Für Daten in diesem Objekt gelten einige Einschränkungen: Es dürfen keine sensiblen Informationen enthalten sein, einschließlich, aber nicht beschränkt auf personenbezogene Daten.

otherDeviceIds Array

Liste der alternativen 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 dies die Projekt-ID in der Actions Console.

deviceId String

Erforderlich.

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