Event API

Event API를 사용하기 위해서는 LG전자 담당자와 사전 협의가 필요합니다.

여러분의 서비스가 디바이스의 이벤트를 구독하거나 구독해제 할 수 있게 해주는 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 

API List

Method Summary
POST /event/{device-id} 특정 디바이스에 대해, 디바이스의 상태 변경에 대한 이벤트를 구독합니다.
DELETE /event/{device-id} 특정 디바이스에 대해, 디바이스의 상태 변경에 대한 이벤트 구독을 해제합니다. 

이벤트 구독

POST /event/{device-id}

Description

이 메서드는 여러분의 서비스가 디바이스의 이벤트를 구독하기 위한 API입니다.

이벤트는 디바이스 상태가 변경되는 경우 발생하며, 디바이스는 이벤트 구독을 요청한 서비스에 이벤트 메시지를 전달함으로써 변경된 상태 정보를 알려줍니다. 이 메서드의 목적은 디바이스의 실시간 상태 정보를 제공하기 위한 것은 아닙니다. 디바이스의 상태가 변경된 경우에만 상태 정보(변경 후 상태)를 제공합니다.

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

이 메서드 호출이 성공하면, device-id로 지정된 디바이스에 대해, 여러분의 서비스는 해당 디바이스 상태 변경 시 발생하는 이벤트 메시지를 받게 됩니다. 이벤트 메시지에는 디바이스 ID, 디바이스 타입 (가전 타입), 디바이스 상태가 포함되며, 상세 설명은 이벤트 메시지 정의를 참조하기 바랍니다.

 

Parameter

Header Parameters

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

Body Parameters

바디 파라미터로 다음과 같이 이벤트 구독 만료 기한을 입력합니다.

바디 파라미터 정보

Name

Type

Required

Description

Default

expire

object

optional

이벤트 구독 만료에 대한 다음 정보를 담은 오브젝트

-

 

unit

string

optional

이벤트 구독 만료 시간의 단위

  • 허용된 단위는 시간 (HOUR)입니다.

HOUR

 

timer

integer

optional

이벤트 구독 만료 시간

  • 최소값: 1
  • 최대값: 24
  • 기본값: 1

1

unit에 정의된 시간 단위로 timer에 정의된 시간만큼 이 메서드가 동작합니다. 즉, 이벤트 구독 이후 timer에 설정된 시간을 넘으면, 자동으로 디바이스로부터 이벤트 메시지를 받지 않습니다.

 

Result

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

성공

성공한 경우, 비어있는 값을 반환합니다.

실패

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

 

Example of Request

[POST] {{ENDPOINT_URL}}/event/{device-id}
 
## Header
{
    “Authorization”: "Bearer 3b565aa79ac4abaa37809a8b8b745499bd05bb3ef0ed75fe350ad2c696b4b956bddfa35e76c26a12ab33c643bed579dd",
    “x-country-code”: "KR",
    “x-message-id”: "0123456789012345678912",
    “x-service-id”: "470ae4c534ba143cad86e5c3",
    “x-service-key”: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzZXJ2aWNlSWQiOiI0NzBhZTRjNTM0YmExNDNjYWQ4NmU1YzMiLCJ0b2tlblNlZWQiOiI1Zjc2MWQwMDU2YmE4NWJkIiwidGltZSI6MTUxNjM0MTkzMn0.aznAEnUItCWc2UAFvoiIYDw0SCJDoY5xVCNnUyUJeiI",
    “content-type”: "application/json"
}
## Body
{
    “expire”: {
        “unit”: “HOUR”,
        “timer”: 1
    }
}

Example of Response

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

 

이벤트 해제

DELETE /event/{device-id}

Description

이 메서드는 여러분의 서비스가 디바이스의 이벤트를 구독하는 것을 해제하기 위한 API입니다. 

DELETE {Base_URL}/event/{device-id}

이 메서드 호출이 성공하면 device-id로 지정되는 디바이스에 대해, 여러분의 서비스는 해당 디바이스의 상태 변경에 대한 이벤트 메시지를 수신하지 않게 됩니다. 다시 이벤트 구독을 요청할 때까지 해당 디바이스로부터 이벤트 메시지를 받지 않습니다.

 

Parameter

Header Parameters

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

Body Parameters

None

 

Result

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

성공

성공한 경우, 비어있는 값을 반환합니다.

실패

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

 

Example of Request

[DELETE] {{ENDPOINT_URL}}/event/{device-id}
  
## Header
{
    “Authorization”: "Bearer 3b565aa79ac4abaa37809a8b8b745499bd05bb3ef0ed75fe350ad2c696b4b956bddfa35e76c26a12ab33c643bed579dd",
    “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”: {}
}

 

이벤트 메시지 정의

이벤트란 디바이스의 상태가 변경될 때 발생하는 메시지를 말하며, 이벤트 메시지의 정의는 아래 표를 따릅니다.

Name

Type

Description

event

object

이벤트에 대한 정보를 포함한 오브젝트

 

serviceId

string

서비스 아이디

 

deviceId

string

디바이스 아이디

 

deviceType

enum

디바이스 타입

 

report

object

변경된 디바이스의 상태

각 가전 타입 별 Device Profile의 상태 조회 결과를 참조하십시오.

 

pushType

enum

DEVICE_STATUS

 

userList

List

디바이스 이벤트를 등록한 사용자 리스트

Example

{
  "messageId": "W1FKFRBZRkiuFAfU9pb6kw",
  "timestamp": "2019-06-20T01:14:27.069000",
  "event": {
    "pushType": "DEVICE_STATUS",
    "serviceId": "6b2011e7ff026e984215522d",
    "deviceId": "HW1-69C3EDD9-1993-4442-B139-794CA5997ECA",
    "report": {
      {
        device status
      }
    },
    "deviceType": "DEVICE_WASHER",
    "userList": ["KR1910213944934"],
  }
}