Witamy w Google Home Developer Center – nowym miejscu, z którego dowiesz się, jak tworzyć inteligentne działania domowe. Uwaga: nadal będziesz tworzyć działania w konsoli Actions.
Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

action.devices.SYNC

Ta intencja wymaga listy urządzeń powiązanych z danym użytkownikiem i jego możliwościami.

Jest ona wyzwalana podczas łączenia kont lub gdy użytkownik ponownie zsynchronizuje swoje urządzenia. Usługa powinna spełniać określone cechy i atrybuty dostępne na każdym urządzeniu.

Odpowiedź SYNC powinna zwrócić wszystkie urządzenia powiązane z użytkownikiem. Nie określa to, czy dane urządzenie jest osiągalne. Jest ona obsługiwana przez odpowiedzi QUERY i EXECUTE.

Więcej informacji znajdziesz w artykule Identyfikacja i synchronizacja.

Format żądania

Pola Typ Opis
requestId Ciąg

Wymagane.

Identyfikator żądania.

inputs Tablica

Wymagane.

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

[item, ...] Obiekt

Typ i ładunek powiązany 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 Ciąg

Wymagane.

Identyfikator odpowiedniego żądania.

payload Obiekt

Wymagane.

Ładunek odpowiedzi na intencję.

agentUserId Ciąg

Wymagane.

Odzwierciedla unikalny (i niezmienny) identyfikator użytkownika na platformie agenta. Ciąg jest niewidoczny dla Google, więc jeśli masz postać stałego formularza, musisz go zmienić na stabilny (np. numer konta zamiast adresu e-mail).

errorCode Ciąg

W przypadku błędów systemowych w systemie SYNC

debugString Ciąg

Szczegółowy błąd, który nigdy nie pojawia się użytkownikom, ale może zostać zarejestrowany lub użyty podczas programowania.

devices Tablica

Wymagane.

Lista urządzeń należących do użytkownika. Nie zwróci się więcej niż 1 urządzenie (zero urządzeń oznacza, że użytkownik nie ma urządzeń lub wszystkie zostały odłączone).

[item, ...] Obiekt

Metadane urządzenia.

id Ciąg

Wymagane.

Identyfikator urządzenia w chmurze dewelopera. Musi to być unikalna nazwa dla użytkownika i dewelopera – tak jak w przypadku udostępniania. Pozwala to usunąć duplikaty wielu wyświetleń na tym samym urządzeniu. Urządzenie nie może się zmienić. Jeśli się zmieni, Asystent będzie je traktować jako nowe urządzenie.

type Ciąg

Wymagane.

Typ urządzenia.

traits Tablica

Wymagane.

Lista cech używanych przez to urządzenie. Określa to polecenia, atrybuty i stany obsługiwane przez urządzenie.

[item, ...] Ciąg

Nazwa obsługiwanej cechy.

name Obiekt

Wymagane.

Nazwy tego urządzenia.

defaultNames Tablica

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

[item, ...] Ciąg

Domyślna nazwa urządzenia.

name Ciąg

Wymagane.

Główna nazwa urządzenia, którą określa użytkownik. Będzie to też nazwa, której Asystent będzie używać do opisywania urządzenia w odpowiedziach.

nicknames Tablica

Dodatkowe nazwy podane przez użytkownika dla urządzenia.

[item, ...] Ciąg

Nazwa urządzenia.

willReportState Wartość logiczna

Wymagane.

Wskazuje, czy stany urządzenia będą aktualizowane przez kanał w czasie rzeczywistym. (prawda: do przesyłania raportów używa się kanału Czas rzeczywisty, a fałsz – do używania modelu ankiety)

notificationSupportedByAgent Wartość logiczna

(Domyślnie: false)

Określa, czy powiadomienia są włączone na urządzeniu.

roomHint Ciąg

Zapewnia bieżący pokój urządzenia w domu użytkownika, aby uprościć konfigurację.

deviceInfo Obiekt

Zawiera pola opisujące urządzenie do jednorazowego użycia logiki (np. „zepsute oprogramowanie w wersji X światła Y wymaga dostosowania koloru” lub „brak luk w zabezpieczeniach wymaga powiadomienia wszystkich użytkowników oprogramowania układowego Z”).

manufacturer Ciąg

Szczególnie przydatne, gdy deweloper pełni w nim rolę innego urządzenia. Google może udostępnić standardową listę producentów, aby np. linki TP-Link i Smartthings pisaliśmy tak samo jak „osram”.

model Ciąg

Identyfikator modelu lub kod SKU konkretnego urządzenia.

hwVersion Ciąg

Konkretny numer wersji podłączony do sprzętu, jeśli jest dostępny.

swVersion Ciąg

Konkretny numer wersji dołączony do oprogramowania lub oprogramowania układowego (jeśli jest dostępny).

attributes Obiekt

jest dopasowywany do atrybutów określonych w każdym odniesieniu do schematu cech.

customData Obiekt

Obiekt zdefiniowany przez dewelopera, który zostanie dołączony do przyszłych żądań QUERY i ExECUTE. Maksymalnie 512 bajtów na urządzenie. Służy do przechowywania dodatkowych informacji o urządzeniu, którego może potrzebować Twoja usługa w chmurze, np. o globalnym regionie urządzenia. Dane w tym obiekcie mają kilka ograniczeń: brak 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 w chmurze do wykonywania lokalnie.

[item, ...] Obiekt

Alternatywny identyfikator urządzenia.

agentId Ciąg

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

deviceId Ciąg

Wymagane.

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

Przykłady

Odpowiedź dotycząca 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"
        }
      }
    ]
  }
}