action.devices.SYNC

이 인텐트는 지정된 사용자와 연결된 기기 목록 및 기능을 요청합니다.

계정 연결 중에 또는 사용자가 기기를 수동으로 다시 동기화할 때 트리거됩니다. fulfillment는 각 기기에 지원되는 특성 및 속성으로 응답해야 합니다.

SYNC 응답은 사용자와 관련된 모든 기기를 반환해야 합니다. 이 작업으로 특정 기기의 연결 가능 여부가 결정되지는 않습니다. 이는 QUERYEXECUTE 응답에서 처리됩니다.

자세한 내용은 식별 및 동기화를 참고하세요.

요청 형식

필드 유형 설명
requestId String

필수사항.

요청의 ID입니다.

inputs 배열

필수사항.

인텐트 요청과 일치하는 입력 목록

[item, ...] 객체

인텐트 요청과 연결된 유형 및 페이로드

intent

필수사항.

(상수 값: "action.devices.SYNC")

인텐트 요청 유형입니다.

SYNC 인텐트 요청

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

응답 형식

필드 유형 설명
requestId String

필수사항.

해당 요청의 ID

payload 객체

필수사항.

인텐트 응답 페이로드

agentUserId String

필수사항.

에이전트 플랫폼의 고유하고 변경할 수 없는 사용자 ID를 반영합니다. 문자열은 Google에 불투명하므로 상담사 측에 변경 불가능한 양식과 변경 가능한 양식이 있는 경우 변경 불가능한 양식 (예: 이메일 대신 계정 번호)을 사용합니다.

errorCode String

SYNC에 시스템 오류 발생

debugString String

사용자에게 표시되지는 않지만 개발 중에 기록되거나 사용될 수 있는 자세한 오류입니다.

devices 배열

필수사항.

사용자가 소유한 기기 목록입니다. 0대 이상의 기기가 반환됩니다 (기기 0대는 사용자가 기기를 보유하고 있지 않거나 모든 기기를 연결 해제했음을 의미함).

[item, ...] 객체

기기 메타데이터

id String

필수사항.

개발자의 클라우드에 있는 기기의 ID입니다. 이는 사용자와 개발자에게 고유해야 합니다. Google에서 공유 하는 경우 동일한 기기를 사용하여 여러 기기의 조회를 중복 삭제할 수 있기 때문입니다. 변경할 수 없습니다. 기기가 변경되면 어시스턴트는 새 기기로 취급합니다.

type String

필수사항.

기기의 하드웨어 유형입니다.

traits 배열

필수사항.

이 기기의 특성 목록입니다. 기기에서 지원하는 명령어, 속성, 상태를 정의합니다.

[item, ...] String

지원되는 특성의 이름입니다.

name 객체

필수사항.

이 기기의 이름입니다.

defaultNames 배열

사용자가 아닌 개발자가 제공한 이름 목록인 경우 제조업체 이름, SKU 등인 경우가 많습니다.

[item, ...] String

기기 기본 이름

name String

필수사항.

기기의 기본 이름으로, 일반적으로 사용자가 제공합니다. 어시스턴트는 응답에서 기기를 설명하는 데 사용하는 이름이기도 합니다.

nicknames 배열

사용자가 기기에 제공한 추가 이름입니다.

[item, ...] String

기기 닉네임

willReportState Boolean

필수사항.

기기의 실시간 상태 업데이트가 업데이트되는지를 나타냅니다. 보고 상태에 실시간 피드를 사용하려면 true, 폴링 모델을 사용하려면 false로 설정합니다.

notificationSupportedByAgent Boolean

(기본값: false)

기기에 알림이 사용 설정되어 있는지 나타냅니다.

roomHint String

사용자 집에 있는 기기의 현재 방을 제공하여 설정을 간소화합니다.

deviceInfo 객체

필요한 경우 일회성 로직에 사용할 기기를 설명하는 필드가 포함되어 있습니다 (예: '손상된 펌웨어 버전 X, 조명 Y의 색상을 조정해야 함' 또는 '보안 결함으로 모든 사용자에게 펌웨어 Z를 알려야 함').

manufacturer String

개발자가 다른 기기의 허브인 경우 특히 유용합니다. Google에서는 제조업체의 표준 목록을 제공할 수 있습니다. 예를 들어 TP-Link 및 Smartthings 모두 'osram'을 동일한 방식으로 설명하도록 할 수 있습니다.

model String

특정 기기의 모델 또는 SKU 식별자입니다.

hwVersion String

가능한 경우 하드웨어에 연결된 특정 버전 번호입니다.

swVersion String

소프트웨어/펌웨어에 연결된 구체적인 버전 번호입니다(가능한 경우).

attributes 객체

각 특성 스키마 참조에서 설명한 속성별 속성과 일치합니다.

customData 객체

개발자가 정의한 객체이며 향후 QUERY 및 EXECUTE 요청에 첨부됩니다. 기기당 최대 512바이트입니다. 이 객체를 사용하여 기기의 글로벌 리전과 같이 클라우드 서비스에 필요할 수 있는 기기에 관한 추가 정보를 저장합니다. 이 객체에는 몇 가지 제약 조건이 있습니다. 개인 식별 정보를 포함하되 이에 국한되지 않는 민감한 정보가 없습니다.

otherDeviceIds 배열

로컬 실행을 위해 클라우드 동기화 기기를 식별하는 데 사용되는 대체 ID 목록입니다.

[item, ...] 객체

대체 기기 ID입니다.

agentId String

상담사의 ID입니다. 일반적으로 이는 Actions 콘솔의 프로젝트 ID입니다.

deviceId String

필수사항.

에이전트에서 정의한 기기 ID입니다. 기기 ID는 고유해야 합니다.

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