action.devices.SYNC

Ta intencja wysyła prośbę o listę urządzeń powiązanych z danym użytkownikiem i ich możliwości.

Jest ona wywoływana podczas łączenia kont lub gdy użytkownik ręcznie synchronizuje urządzenia. Odpowiedź powinna zawierać obsługiwane cechy i atrybuty każdego urządzenia.

Odpowiedź SYNC powinna zawierać wszystkie urządzenia powiązane z użytkownikiem. Nie określa ona, czy dane urządzenie jest dostępne. Zajmują się tym QUERY i EXECUTE odpowiedzi.

Więcej informacji znajdziesz w artykule Identyfikowanie i synchronizowanie.

Format żądania

Pola Typ Opis
requestId String

Wymagane.

Identyfikator żądania.
inputs tablica

Wymagane.

Lista danych wejściowych pasujących do żądania intencji.
[item, ...] Obiekt

Typ i ładunek powiązane z żądaniem intencji.
intent

Wymagane.

(Wartość stała: "action.devices.SYNC")

Typ żądania intencji.
Przykłady

Żądanie intencji SYNC

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

Format odpowiedzi

Pola Typ Opis
requestId String

Wymagane.

Identyfikator odpowiedniego żądania.
payload Obiekt

Wymagane.

Ładunek odpowiedzi intencji.
agentUserId String

Wymagane.

Odzwierciedla unikalny (i niezmienny) identyfikator użytkownika na platformie agenta. Ten ciąg znaków jest nieprzezroczysty dla Google, więc jeśli po stronie agenta występuje niezmienna forma i forma zmienna, użyj formy niezmiennej (np. numeru konta zamiast adresu e-mail).
errorCode String

W przypadku systematycznych błędów w SYNC.
debugString String

Szczegółowy błąd, który nigdy nie będzie wyświetlany użytkownikom, ale może być rejestrowany lub używany podczas programowania.
devices tablica

Wymagane.

Lista urządzeń należących do użytkownika. Zwracana jest co najmniej 0 urządzeń (0 oznacza, że użytkownik nie ma urządzeń lub odłączył wszystkie).
[item, ...] Obiekt

Metadane urządzenia.
id String

Wymagane.

Identyfikator urządzenia w chmurze dewelopera. Musi być unikalny dla użytkownika i dewelopera, ponieważ w przypadku udostępniania możemy go używać do usuwania duplikatów wyświetleń tego samego urządzenia. Powinien być niezmienny dla urządzenia. Jeśli się zmieni, Asystent potraktuje go jako nowe urządzenie.
type String

Wymagane.

Typ sprzętu urządzenia.

Musi pasować do wzorca ^action.devices.types.[a-zA-z]+$.
traits tablica

Wymagane.

Lista cech tego urządzenia. Określa polecenia, atrybuty i stany obsługiwane przez urządzenie.
[item, ...] String

Nazwa obsługiwanej cechy.

Musi pasować do wzorca ^action.devices.traits.[a-zA-z]+$.
name Obiekt

Wymagane.

Nazwy tego urządzenia.
defaultNames tablica

Lista nazw podanych przez dewelopera, a nie użytkownika, często nazw producentów, jednostek SKU itp.
[item, ...] String

Domyślna nazwa urządzenia.
name String

Wymagane.

Główna nazwa urządzenia, zwykle podana przez użytkownika. Jest to też nazwa, której Asystent będzie używać do opisywania urządzenia w odpowiedziach. Nazwy zostaną obcięte, jeśli przekroczą limit 60 punktów kodowych Unicode (znaków), i nie zostaną zgłoszone żadne błędy. Deweloperzy są odpowiedzialni za obsługę długich nazw.
nicknames tablica

Dodatkowe nazwy urządzenia podane przez użytkownika.
[item, ...] String

Nazwa urządzenia.
willReportState Wartość logiczna

Wymagane.

Wskazuje, czy stany tego urządzenia będą aktualizowane przez kanał w czasie rzeczywistym. (Wartość true oznacza, że do raportowania stanu będzie używany kanał w czasie rzeczywistym, a wartość false – model sondowania).
notificationSupportedByAgent Wartość logiczna

(Domyślnie: false)

Wskazuje, czy powiadomienia są włączone na urządzeniu.
roomHint String

Upraszcza konfigurację, podając aktualny pokój urządzenia w domu użytkownika.
deviceInfo Obiekt

Zawiera pola opisujące urządzenie, które mogą być używane w logice jednorazowej (np. „uszkodzona wersja oprogramowania układowego X światła Y wymaga dostosowania koloru” lub „luka w zabezpieczeniach wymaga powiadomienia wszystkich użytkowników oprogramowania układowego Z”).
manufacturer String

Szczególnie przydatne, gdy deweloper jest hubem dla innych urządzeń. Google może udostępnić standardową listę producentów, aby np. TP-Link i Smartthings opisywały „osram” w ten sam sposób.
model String

Identyfikator modelu lub jednostki SKU danego urządzenia.
hwVersion String

Numer konkretnej wersji sprzętu, jeśli jest dostępny.
swVersion String

Numer konkretnej wersji oprogramowania, jeśli jest dostępny.
attributes Obiekt

Zgodne z atrybutami poszczególnych cech opisanymi w schemacie każdej cechy.
customData Obiekt

Obiekt zdefiniowany przez dewelopera, który będzie dołączany do przyszłych żądań QUERY i EXECUTE. Maksymalny rozmiar to 512 bajtów na urządzenie. Użyj tego obiektu do przechowywania dodatkowych informacji o urządzeniu, które mogą być potrzebne Twojej usłudze w chmurze, np. globalnego regionu urządzenia. Dane w tym obiekcie podlegają pewnym ograniczeniom: nie mogą zawierać informacji poufnych, w tym między innymi informacji umożliwiających identyfikację.
otherDeviceIds tablica

Lista alternatywnych identyfikatorów używanych do identyfikowania urządzenia zsynchronizowanego z chmurą na potrzeby lokalnego wykonania.
[item, ...] Obiekt

Alternatywny identyfikator urządzenia.
agentId String

Identyfikator agenta. Zwykle jest to identyfikator projektu w konsoli Actions.
deviceId String

Wymagane.

Identyfikator urządzenia zdefiniowany przez agenta. Identyfikator urządzenia musi być unikalny.
Przykłady

Odpowiedź intencji SYNC

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