Device API

여러분의 서비스가 사용자의 디바이스에 대해, 디바이스 정보를 요청하고 제어하기 위한 API입니다.

기본 정보

Base URL

서버 형상	URL	비고
QA (DEV)	https://{region}-qa-ext.lgthinq.com	region KIC : Asia EIC : Europe AIC : North/South America
OP	https://{region}-ext.lgthinq.com

서버 형상

URL

비고

QA (DEV)

https://{region}-qa-ext.lgthinq.com

region

KIC : Asia
EIC : Europe
AIC : North/South America

https://{region}-ext.lgthinq.com

API List

Method & End Point	Summary
GET `/devices`	사용자의 디바이스 목록을 가져옵니다.
GET `/devices/profile/{device-id}`	특정 디바이스에 대해, 디바이스의 가전 타입에 해당하는 프로파일을 가져옵니다.
GET `/devices/{device-id}`	특정 디바이스에 대해, 디바이스의 상태 정보를 가져옵니다.
POST `/devices/{device-id}`	특정 디바이스를 제어합니다.

디바이스 목록 조회

GET /devices

Description

이 메서드는 여러분의 서비스를 이용하는 사용자가 LG ThinQ 플랫폼에 등록한 디바이스 목록을 얻어오기 위한 API입니다.

단, 사용자가 등록한 디바이스 중에서, 여러분의 서비스가 허용한 가전 타입의 디바이스만 조회됩니다. 예를 들어, 여러분의 서비스가 냉장고만을 대상으로 하는 경우, 사용자가 냉장고/세탁기/건조기 등 여러 디바이스를 등록했다 하더라도 냉장고에 해당하는 디바이스 목록만 가져옵니다.

GET {Base_URL}/devices

이 메서드는 다른 메서드들을 사용하기 전에 반드시 한 번은 호출되어야 합니다.

이 메서드가 반환해준 디바이스 목록에는 디바이스를 식별할 수 있는 device-id가 포함되어 있으며, 이 값으로 대상 디바이스를 지정하여 다른 메서드들을 호출할 수 있습니다. 따라서 이 메서드는 반드시 최초 1번은 호출되어야 하며, 디바이스 목록을 얻어온 후에는 매번 호출할 필요는 없습니다.

Parameter

Header Parameters

헤더 파라미터로 공통 헤더(Common Header)를 사용합니다.

Body Parameters

None

Result

이 메서드의 호출 결과는 다음과 같이 2가지 경우(성공, 실패)가 있습니다.

성공

성공한 경우, 여러분의 서비스가 허용한 가전 타입에 해당하는 사용자의 디바이스 목록이 다음과 같은 형식으로 반환됩니다.

Name		Type	Description
deviceId		string	디바이스를 식별할 수 있는 ID
deviceInfo		object	디바이스에 대한 다음 정보를 담은 오브젝트
	deviceType	enum	디바이스의 가전 타입 (Common Data Type > Device Type 에 정의된 값을 이용)
	modelName	string	디바이스의 모델 이름
	alias	string	디바이스 닉네임
	reportable	boolean	디바이스의 상태 변경 시 발생하는 event에 대해, 여러분의 서비스가 event를 구독 중인지 여부
	groupId	string	deviceType이 `DEVICE_WASHTOWER_WASHER`, `DEVICE_WASHTOWER_DRYER`인 경우에 전달됩니다. groupId

해당 사용자에 대해 LG ThinQ 플랫폼에 등록된 디바이스가 없을 경우 비어 있는 값이 반환됩니다.

실패

실패한 경우, Common Response에 정의된 응답 규약에 따라 에러 코드와 에러 메시지가 반환됩니다.

Example of Request

[GET] {{ENDPOINT_URL}}/devices
## Header
{
    "Authorization" : "Bearer 5a9a713f51a95c53d781addd1af0dfa4f6e1e7420a8bff3c5198308dac571aa9845832b8d29bbe1f04deec2d35229c6d",
    "x-country-code" : "KR",
    "x-message-id" : "0123456789012345678912",
    "x-service-id" : "470ae4c534ba143cad86e5c3",
    "x-service-key" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXJ2aWNlSWQiOiI0NzBhZTRjNTM0YmExNDNjYWQ4NmU1YzMiLCJ0b2tlblNlZWQiOiI1Zjc2MWQwMDU2YmE4NWJkIiwidGltZSI6MTUxNjM0MTkzMn0.aznAEnUItCWc2UAFvoiIYDw0SCJDoY5xVCNnUyUJeiI"
}

Example of Response

{
    "messageId" : " 0123456789012345678912" ,
    "timestamp" : " 2018-02-08T06:23:20.866279" ,
    "response" : [{
                    "deviceId": "0A36FC52-6281-4954-86D5-616A58CEA2C6",
                    "deviceInfo": {
                        "deviceType": "DEVICE_REFRIGERATOR",
                        "modelName": "S-TF",
                        "alias": "nickname",
                        "reportable": true
                    }
                }]
}

디바이스 프로파일 조회

GET /devices/profile/{device-id}

Description

이 메서드는 디바이스의 Device Profile을 조회하기 위한 API입니다.

Device Profile이란 LG 가전의 속성을 가전 유형 별로 표준화하여 기술한 정보로, LG ThinQ 플랫폼이 사용하는 디바이스 데이터입니다. 예를 들어, 냉장고에 대한 Device Profile은 온도/냉동 모드/절전 모드/도어 열림 등 냉장고의 상태를 설명하고 제어하기 위한 속성들을 정의합니다. 여러분은 이 프로파일을 바탕으로 디바이스의 상태를 해석하고 제어 명령을 생성할 수 있습니다.

GET {Base_URL}/devices/profile/{device-id}

이 메서드 호출이 성공하면, device-id로 지정된 디바이스에 대해, 해당 디바이스의 가전 타입에 대응되는 Device Profile이 JSON 형태로 반환됩니다.

Precondition

이 메서드를 사용하기 전에 반드시 1번은 디바이스 목록 조회(GET /devices) 메서드를 호출하여야 합니다. 이 메서드를 포함하여 특정 디바이스를 대상으로 수행되는 메서드의 경우, device-id 값을 얻기 위해 디바이스 목록 조회(GET /devices) 메서드를 최초 1회 먼저 시행해야 합니다.

Parameter

Header Parameters

헤더 파라미터로 공통 헤더(Common Header)를 사용합니다.

Body Parameters

None

Result

이 메서드의 호출 결과는 다음과 같이 2가지 경우(성공, 실패)가 있습니다.

성공

성공한 경우, 해당 디바이스의 가전 타입에 따라 Device Profile이 JSON 형태로 반환됩니다. 프로파일 내 각 속성의 의미는 다음을 참조하기 바랍니다.

가전 타입별 디바이스 프로파일
가전 타입	Device Profile
냉장고	Device Profile > Refrigerator
세탁기	Device Profile > Washer
건조기	Device Profile > Dryer
에어컨	Device Profile > Air Conditioner
공기청정기	Device Profile > Air Purifier
로봇청소기	Device Profile > Robot Cleaner
오븐	Device Profile > Oven
식기세척기	Device Profile > Dish Washer
스타일러	Device Profile > Styler
정수기	Device Profile > Water Purifier
제습기	Device Profile > Dehumidifier
실링 팬	Device Profile > Ceiling Fan

실패

실패한 경우, Common Response에 정의된 응답 규약에 따라 에러 코드와 에러 메시지가 반환됩니다.

Example of Request

[GET] {{ENDPOINT_URL}}/devices/profile/{device-id}
 
## Header
{
    "authorization" : "Bearer a6586272fc390566850bc5a837d32872f0c794498f651b5174244451700e2ea00ddb8dcc96902ea469aa765e589a221d",
    "x-country-code" : "KR",
     "x-message-id" : "0123456789012345678912",
    "x-service-id" : "470ae4c534ba143cad86e5c3",
    "x-service-key" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXJ2aWNlSWQiOiI0NzBhZTRjNTM0YmExNDNjYWQ4NmU1YzMiLCJ0b2tlblNlZWQiOiI1Zjc2MWQwMDU2YmE4NWJkIiwidGltZSI6MTUxNjM0MTkzMn0.aznAEnUItCWc2UAFvoiIYDw0SCJDoY5xVCNnUyUJeiI"
}

Example of Response

{
    "messageId" : " c2d362a0-dd0f-11e6-a7c7-abfb76e3e664" ,
    "timestamp" : " 1284101485" ,
    "response" : {{ Device Profile }}
}

디바이스 상태 조회

GET /devices/{device-id}

Description

이 메서드는 디바이스의 현재 상태를 조회하기 위한 API입니다.

GET {Base_URL}/devices/{device-id}

이 메서드 호출이 성공하면, device-id로 지정된 디바이스의 현재 상태 정보를 반환받을 수 있습니다.

Precondition

Parameter

Header Parameters

헤더 파라미터로 공통 헤더(Common Header)를 사용합니다.

Body Parameters

None

Result

이 메서드의 호출 결과는 다음과 같이 2가지 경우(성공, 실패)가 있습니다.

성공

성공한 경우, 해당 디바이스의 현재 상태가 반환됩니다. 반환값은 Device Profile 을 기준으로 작성된 JSON 형태로 반환됩니다. 이는 가전 타입마다 구조가 다르므로, 다음 표를 참조하여 상태 정보의 의미를 확인하기 바랍니다.

디바이스 타입 별 상태조회 결과
가전 타입	상태 조회 결과
냉장고	상태 조회 결과
세탁기	상태 조회 결과
건조기	상태 조회 결과
에어컨	상태 조회 결과
공기청정기	상태 조회 결과
로봇청소기	상태 조회 결과
오븐	상태 조회 결과
식기세척기	상태 조회 결과
스타일러	상태 조회 결과
정수기	상태 조회 결과
제습기	상태 조회 결과
실링 팬	상태 조회 결과

실패

실패한 경우, Common Response에 정의된 응답 규약에 따라 에러 코드와 에러 메시지가 반환됩니다.

Example of Request

[GET] {{ENDPOINT_URL}}/devices/{device-id}
 
## Header
{
    "Authorization" : "Bearer 13d6800857e953e58c0a9f0cf4c1c298ecfa3012d1f9486a1925397a1f2a5d13ac6c898c9eaabda9c57ee8e8eca1006a",
    "x-country-code" : "KR",
    "x-message-id" : "0123456789012345678912",
    "x-service-id" : "470ae4c534ba143cad86e5c3",
    "x-service-key" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXJ2aWNlSWQiOiI0NzBhZTRjNTM0YmExNDNjYWQ4NmU1YzMiLCJ0b2tlblNlZWQiOiI1Zjc2MWQwMDU2YmE4NWJkIiwidGltZSI6MTUxNjM0MTkzMn0.aznAEnUItCWc2UAFvoiIYDw0SCJDoY5xVCNnUyUJeiI"
}

Example of Response

{
    "messageId" : " c2d362a0-dd0f-11e6-a7c7-abfb76e3e664" ,
    "timestamp" : " 1284101485" ,
    "response" : {{ Device Status }}
}

디바이스 제어

POST /devices/{device-id}

Description

이 메서드는 디바이스를 제어하기 위한 API입니다.

POST {Base_URL}/devices/{device-id}

이 메서드 호출이 성공하면, device-id 로 지정된 디바이스에 대해 제어 명령을 내립니다. 제어 명령은 Device Profile 을 바탕으로, 제어를 원하는 속성에 대해 기술한 name과 value 쌍의 정보로 구성되며, 이 메서드의 body 파라미터로 전달됩니다.

Precondition

이 메서드를 사용하기 전에 반드시 1번은 디바이스 목록 조회(GET /devices) 메서드를 호출하여야 합니다. 이 메서드를 포함하여 특정 디바이스를 대상으로 수행되는 메서드의 경우, device-id값을 얻기 위해 디바이스 목록 조회(GET /devices) 메서드를 최초 1회 먼저 시행해야 합니다.

Parameter

Header Parameters

헤더 파라미터로 공통 헤더를 사용합니다.

제어 요청 시 Common Header의 x-conditional-control 값을 true로 설정하면, 먼저 디바이스 상태를 조회하고 제어가 가능한 상태에서만 제어 명령을 실행시킬 수 있습니다.

Body Parameters

해당 기기에 대한 제어 명령을 입력합니다. 제어 명령이란 Device Profile 을 바탕으로 제어를 원하는 속성애 대해 name과 value 쌍으로 표현한 정보입니다.

Configuration of Control Command
Name	Type	Required	Description
name	string	mandatory	Device profile에서 resource 속성 이름을 사용합니다.
value	string	mandatory	Device profile에서 resource 속성 내부의 값을 사용합니다.

예를 들어, 냉장고에 대해 냉장실의 온도를 섭씨 0도로 제어하라는 명령은 다음과 같습니다.

# 냉장실 섭씨 0도 제어 명령 예
{ 
	"temperature": {
		"targetTemperature": 0,
		"locationName": "FRIDGE",
		"unit": "C"
	}
}

각 가전 별 제어 명령의 예시는 다음을 참조하십시오.

Control Command Examples by Device Type
가전 타입	제어 명령
냉장고	제어 명령
세탁기	제어 명령
건조기	제어 명령
에어컨	제어 명령
공기청정기	제어 명령
로봇청소기	제어 명령
오븐	제어 명령
식기세척기	-
스타일러	제어 명령
정수기	-
제습기	제어 명령
실링 팬	제어 명령

Result

이 메서드의 호출 결과는 다음과 같이 2가지 경우(성공, 실패)가 있습니다.

성공

제어명령이 기기에 정상적으로 전달되었을 경우, HTTP 200 OK 가 반환됩니다.

실패

실패한 경우, Common Response에 정의된 응답 규약에 따라 에러 코드와 에러 메시지가 반환됩니다.

Example of Request

[POST] {{ENDPOINT_URL}}/device/{device-id}
 
## Header
{
    "Authorization" : "Bearer 13d6800857e953e58c0a9f0cf4c1c298ecfa3012d1f9486a1925397a1f2a5d13ac6c898c9eaabda9c57ee8e8eca1006a",
    "x-country-code" : "KR",
    "x-message-id" : "0123456789012345678912",
    "x-service-id" : "470ae4c534ba143cad86e5c3",
    "x-service-key" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXJ2aWNlSWQiOiI0NzBhZTRjNTM0YmExNDNjYWQ4NmU1YzMiLCJ0b2tlblNlZWQiOiI1Zjc2MWQwMDU2YmE4NWJkIiwidGltZSI6MTUxNjM0MTkzMn0.aznAEnUItCWc2UAFvoiIYDw0SCJDoY5xVCNnUyUJeiI",
    " content-type" : "application/json"
}
## Body
{
    "temperature" : {
        "targetTemperature" : 0,
        "locationName" : " FRIDGE" ,
        "unit" : " C"   
    }
}

Example of Response

{
    "messageId" : " c2d362a0-dd0f-11e6-a7c7-abfb76e3e664" ,
    "timestamp" : " 1284101485" ,
    "response" : {}
}

[Action Required: Windows XP OS users] End of Support for 3DES Cipher

Device API

기본 정보

Base URL

API List

디바이스 목록 조회

Description

Parameter

Header Parameters

Body Parameters

Result

성공

실패

Example of Request

Example of Response

디바이스 프로파일 조회

Description

Precondition

Parameter

Header Parameters

Body Parameters

Result

성공

실패

Example of Request

Example of Response

디바이스 상태 조회

Description

Precondition

Parameter

Header Parameters

Body Parameters

Result

성공

실패

Example of Request

Example of Response

디바이스 제어

Description

Precondition

Parameter

Header Parameters

Body Parameters

Result

성공

실패

Example of Request

Example of Response