action.devices.SYNC

Ten zamiar żąda listy urządzeń powiązanych z danym użytkownikiem i ich możliwości.

Jest wyzwalany podczas łączenia kont lub gdy użytkownik ręcznie ponownie synchronizuje urządzenia. Usługa realizacji powinna odpowiadać obsługiwanymi cechami i atrybutami każdego urządzenia.

Odpowiedź SYNC powinna zawierać wszystkie urządzenia powiązane z użytkownikiem. Nie określa to, czy dane urządzenie jest osiągalne. Odpowiadają za to odpowiedzi QUERYEXECUTE.

Więcej informacji znajdziesz w artykule Identyfikowanie i synchronizowanie.

Format żądania

Pola Typ Opis
requestId String

Wymagany.

Identyfikator żądania.

inputs Tablica

Wymagany.

Lista danych wejściowych pasujących do żądania intencji.

[item, ...] Obiekt

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

intent

Wymagany.

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

Typ żądania intencji.

Przykłady

Żądanie dotyczące zamiaru SYNC

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

Format odpowiedzi

Pola Typ Opis
requestId String

Wymagany.

Identyfikator odpowiedniego żądania.

payload Obiekt

Wymagany.

Ładunek odpowiedzi na intencję.

agentUserId String

Wymagany.

Zawiera unikalny (i niezmienny) identyfikator użytkownika na platformie agenta. Ciąg znaków jest dla Google nieprzejrzysty, więc jeśli po stronie agenta występuje forma niezmienna i 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

Wymagany.

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

[item, ...] Obiekt

metadane urządzenia,

id String

Wymagany.

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 wielu wyświetleń tego samego urządzenia. Powinien być niezmienny dla urządzenia. Jeśli się zmieni, Asystent będzie traktować urządzenie jako nowe.

type String

Wymagany.

Typ sprzętu urządzenia.

traits Tablica

Wymagany.

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

[item, ...] String

Nazwa obsługiwanego atrybutu.

name Obiekt

Wymagany.

Nazwy tego urządzenia.

defaultNames Tablica

Lista nazw podanych przez dewelopera, a nie przez użytkownika, często są to nazwy producentów, numery SKU itp.

[item, ...] String

Domyślna nazwa urządzenia.

name String

Wymagany.

Główna nazwa urządzenia, zwykle podawana 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 odpowiadają za obsługę długich nazw.

nicknames Tablica

Dodatkowe nazwy urządzenia podane przez użytkownika.

[item, ...] String

Nazwa urządzenia.

willReportState Wartość logiczna

Wymagany.

Wskazuje, czy stany tego urządzenia będą aktualizowane przez kanał danych w czasie rzeczywistym. (wartość true, aby używać kanału danych w czasie rzeczywistym do raportowania stanu, a wartość false, aby używać modelu odpytywania).

notificationSupportedByAgent Wartość logiczna

(Domyślnie: false)

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

roomHint String

Podaje aktualne pomieszczenie, w którym znajduje się urządzenie w domu użytkownika, aby uprościć konfigurację.

deviceInfo Obiekt

Zawiera pola opisujące urządzenie, które w razie potrzeby można wykorzystać w logice jednorazowej (np. „uszkodzona wersja oprogramowania X urządzenia Y wymaga dostosowania koloru” lub „błąd zabezpieczeń wymaga powiadomienia wszystkich użytkowników oprogramowania Z”).

manufacturer String

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

model String

Identyfikator modelu lub SKU konkretnego urządzenia.

hwVersion String

Konkretny numer wersji przypisany do sprzętu, jeśli jest dostępny.

swVersion String

Konkretny numer wersji oprogramowania, jeśli jest dostępny.

attributes Obiekt

Zgodne z atrybutami poszczególnych cech opisanymi w dokumentacji schematu każdej cechy.

customData Obiekt

Obiekt zdefiniowany przez dewelopera, który zostanie dołączony do przyszłych żądań QUERY i EXECUTE. Maksymalny rozmiar to 512 bajtów na urządzenie. Użyj tego obiektu, aby przechowywać dodatkowe informacje o urządzeniu, które mogą być potrzebne Twojej usłudze w chmurze, np. region globalny urządzenia. Dane w tym obiekcie podlegają pewnym ograniczeniom: nie mogą zawierać informacji poufnych, w tym danych umożliwiających identyfikację.

otherDeviceIds Tablica

Lista alternatywnych identyfikatorów używanych do identyfikowania urządzenia zsynchronizowanego z chmurą na potrzeby lokalnego wykonywania.

[item, ...] Obiekt

Alternatywny identyfikator urządzenia.

agentId String

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

deviceId String

Wymagany.

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

Przykłady

Odpowiedź na zamiar 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"
        }
      }
    ]
  }
}