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 QUERY
i EXECUTE
.
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: 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: 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" } } ] } }