Close

Overview

여러분의 서비스가 LG ThinQ 플랫폼에 연결된 LG 가전의 정보를 얻고 제어하려면 어떻게 해야 할까요? LG ThinQ 플랫폼은 파트너의 IoT 서비스를 위한 인터페이스로 ThinQ Connect API를 제공합니다. 

What is ThinQ Connect?

ThinQ Connect는 LG ThinQ 플랫폼이 파트너에게 제공하는 다양한 인터페이스 중 하나로, IoT 서비스를 직접 운영하고자 하는 파트너를 위해 제공되는 Server-to-Server 인터페이스입니다. ThinQ Connect API (Application Programming Interface)는 RESTful API로 디자인되었으며, 다음 기능을 제공합니다.

  • LG 가전 제품 제어
  • LG 가전 제품 상태 조회
  • LG 가전 제품의 푸쉬 메시지 구독

Basic Concept

ss-concept-thinqEXT.png

 

ThinQ Connect API의 호출 및 응답에는 LG 가전 제품의 속성을 모델링하여 json 포맷으로 정의한 Device Profile이 사용됩니다. 이 프로파일에는 디바이스의 상태를 기술하거나 디바이스를 제어할 수 있는 속성들이 정의되어 있습니다. Device Profile은 가전 유형별로 제공되며, 같은 유형의 가전이라도 제품 별로 다소 차이가 있을 수 있습니다.

여러분의 IoT 서비스는 ThinQ Connect API를 호출하여 다음과 같은 일들을 할 수 있습니다.

  • LG ThinQ 플랫폼에 등록된 사용자의 가전 리스트를 조회합니다.
  • 특정 가전의 Device Profile을 조회합니다.
  • 프로파일의 속성 값을 읽어, 해당 가전의 상태 정보를 얻습니다.
  • 프로파일의 속성 값을 변경하여, 해당 가전으로 제어 명령을 내립니다.
  • 해당 가전이 발송하는 푸쉬 메시지를 구독하고, 유용한 알림을 사용자에게 전달합니다.

Terms and Definitions

ThinQ Connect API에서 공통적으로 사용되는 용어의 정의는 다음과 같습니다.

Terms

Description

ThinQ Connect

LG 가전과 연동하는 IoT 서비스를 직접 운영하는 파트너를 위해 LG ThinQ 플랫폼이 제공하는 인터페이스로서, 파트너의 IoT 서비스가 LG ThinQ 플랫폼에 연결된 수많은 LG 가전 제품들과 통신할 수 있도록 해주는 Server-to-Server 클라우드 인터페이스입니다.

ThinQ Connect API

ThinQ Connect가 제공하는 API (Application Programming Interface)로, RESTful 패턴으로 사용하기 쉽게 설계되었으며, 다음 기능을 제공합니다.

  • LG 가전의 Device Profile 조회
  • LG 가전 제어
  • LG 가전 상태 조회
  • LG 가전의 푸쉬 메시지 구독

Device Profile

LG 가전 제품의 속성을 모델링한 json 포맷의 파일입니다. 각 가전 제품이 발송할 수 있는 알림 메시지 ("세탁이 완료되었습니다.", "부품을 교체해 주십시오." 등)와 가전의 상태를 기술하거나 제어할 수 있는 속성들이 정의되어 있습니다. 

ThinQ Connect API의 호출 파라미터 및 응답 결과에서 LG 가전의 데이터를 전달하기 위해 사용됩니다.

  • Device Profile을 속성 값을 읽어 디바이스의 현재 상태 정보를 알 수 있습니다.
  • Device Profile의 속성 값을 변경하여 디바이스로 제어 명령을 내릴 수 있습니다.

파트너 서버

파트너가 자체 IoT 서비스를 운영하고 있는 서버입니다. 예를 들면, 통신사, 건설사, AI 음성 서비스(Alexa, Clova, Google Assistant) 등의 서버가 될 수 있습니다. 

서비스

파트너 서버에서 운영되는 파트너의 IoT 서비스를 말하며 ThinQ Connect API를 사용하여 개발됩니다.

파트너십이 이루어지면 LG는 서비스를 생성하여 서비스 고유값 (SERVICE_CONFIG)을 발급합니다. 파트너는 이 값을 ThinQ Connec API 요청 헤더에 입력하여 API 사용 허가를 얻고 서비스를 개발합니다. 

사용자 (END-User)

파트너 서비스의 사용자이자, LG 가전을 사용하는 고객입니다.

  • 서비스 사용자 & LG 가전 사용자 

디바이스

사용자가 LG ThinQ 플랫폼에 등록한 "LG 가전"을 의미합니다.

  • 디바이스 등록은 사용자가 직접 LG ThinQ 앱을 통해 해야 합니다.  

SERVICE_CONFIG

  • Service ID
  • Service Key 

ThinQ 플랫폼이 파트너의 서비스를 식별하여 ThinQ Connect API 사용을 허가해주기 위한 서비스 고유 정보입니다.

  • SERVICE_CONFIG에는 service_id와 service_key가 포함됩니다.
  • 파트너가 서비스 생성을 요청하면, LG 담당자가 서비스를 생성한 후 파트너의 서비스 어드민에게 이 값들을 알려줍니다.
  • 파트너는 서비스를 개발할 때, ThinQ Connect API의 요청 헤더에 이 값을 입력해야 합니다.  
    • 헤더 x-service-id에 service_id를 입력합니다.
    • 헤더 x-service-key에 service_key를 입력합니다.
  • 서비스 개발 단계에서는 DEV_SERVICE_CONFIG를 발급받아 사용해야 하고, 서비스 배포 시에는 PRODUCT_SERVICE_CONFIG를 발급받아 사용해야 합니다.

DEV_SERVICE_CONFIG

ThinQ 플랫폼의 개발 형상 서버 (DV)들과 연동시켜주는 SERVICE_CONFIG입니다. 서비스를 배포하기 전 개발 단계에서 사용합니다.

PRODUCT_SERVICE_CONFIG

ThinQ 플랫폼의 운영 형상 서버 (OP)들과 연동시켜주는 SERVICE_CONFIG입니다. 서비스 배포 시에는 이 값을 사용해야 합니다.

How to Develop your Service? 

파트너십을 맺은 후 서비스를 배포하기까지의 과정은 다음과 같습니다. 

Development Process
파트너십 요청
서비스 생성 요청
서비스 개발
서비스 인증

1. 파트너십 요청

ThinQ Connect API 정보는 공개되어 있지만, 이를 사용하려면 LG전자와 파트너십을 맺은 후 서비스 키를 요청하고 발급받아야 합니다.

LG전자와 파트너십을 논의하고 서비스 개발을 시작하고 싶다면, 파트너십을 요청하세요. 파트너십 요청이 승인되면, 별도의 요청없이 개발자 사이트를 이용할 수 있는 권한 요청이 자동으로 접수됩니다. 권한이 승인되면 My Service 페이지에서 ThinQ Connect API를 사용할 수 있는 서비스 키를 요청하고 발급 받을 수 있습니다. 

2. 서비스 생성

서비스 생성을 요청하십시오. 서비스 생성이 완료되면 LG 담당자가 서비스 어드민에게 DEV_SERVICE_CONFIG를 발급합니다.

  • 서비스 어드민
    • 파트너사의 임직원으로 각 서비스별로 1명씩 지정됩니다. (기본적으로 서비스 생성을 요청한 사람을 서비스 어드민으로 지정하며, 향후 변경할 수 있습니다.) 
  • DEV_SERVICE_CONFIG
    • 서비스 고유값(service_id, service_key)으로, 서비스를 식별하여 ThinQ 플랫폼의 개발 형상 서버들과 연동할 수 있게 해줍니다.

3. 서비스 개발

서비스를 개발하는 과정은 크게 2가지로 볼 수 있습니다.

LG Account (LG EMP) 연동 구현

LG Account란 LG 서비스 사용자를 위해 제공되는 LG의 통합 계정으로, LG EMP(Enterprise Membership Platform)에서 관리합니다.  

사용자는 LG Account 계정을 통해 자신의 디바이스를 LG ThinQ 플랫폼에 등록합니다. 이 디바이스 데이터를 이용하기 위해서는 여러분의 서비스도 사용자의 LG Account 계정과 연동해야 합니다. 이를 위해 LG EMP는 OAuth 표준을 따르는 Open API를 제공합니다. 

다음과 같이 구현하십시오.

  1. LG EMP가 제공하는 API를 사용하여, LG EMP로부터 서비스 사용자의 OAuth 토큰을 발급받습니다.
    • LG EMP API에 대한 가이드는 이 사이트에 게시되어 있지 않으며, 파트너십 협약이 이루어진 파트너에게 별도로 제공됩니다.
  2. ThinQ Connect API를 호출할 때. API 요청 헤더에 해당 사용자의 토큰 정보를 입력합니다. 
    • 헤더 Authorization에 EMP로부터 발급받은 해당 사용자의 OAuth 토큰을 입력합니다.

ThinQ Connect API 연동 구현

앞에서 설명한 대로, ThinQ Connect API를 호출할 때는 API 요청 헤더에 다음을 입력해야 합니다. 

헤더 파라미터

입력 값

설명
Authorization

EMP OAuth 토큰 정보

LG ThinQ 플랫폼은 이 정보로 사용자를 식별하여,  누구의 디바이스 정보를 제공해야 하는지를 판단하고, 여러분의 서비스가 해당 사용자의 정보를 이용하도록 승인 받았는지를 확인합니다.
x-service-id

LG 담당자에게 발급받은 SERVICE_CONFIG 중, service_id 값

LG ThinQ 플랫폼은 이 정보로 여러분의 서비스를 식별하고, 허가받은 서비스인지를 확인합니다.
x-service-key

LG 담당자에게 발급받은 SERVICE_CONFIG 중, service_key 값

LG ThinQ 플랫폼은 이 정보로 여러분의 서비스를 식별하고, 허가받은 서비스인지를 확인합니다.

ThinQ Connect API를 사용하여 다음과 같은 기능들을 개발할 수 있습니다.

  • 서비스 사용자가 LG ThinQ 플랫폼에 등록한 디바이스 리스트 조회
  • 각 디바이스의 Device Profile 조회
  • 각 디바이스의 상태 조회
  • 각 디바이스로 제어 명령 전달
  • 각 디바이스로부터 푸쉬 메시지를 구독하고 사용자에게 유용한 알림을 전달

4. 서비스 인증

서비스 개발이 완료되면 서비스 인증을 요청하십시오. LG 담당자가 인증을 완료하면 서비스 어드민에게 PRODUCT_SERVICE_CONFIG를 발급해주며, 이 값을 이용하여 서비스를 배포할 수 있습니다.

  • PRODUCT_SERVICE_CONFIG
    • 서비스 고유값(service_id, service_key)으로, 서비스를 식별하여 ThinQ 플랫폼의 운영 형상 서버들과 연동할 수 있게 해줍니다.
    • 배포 버전의 서비스에서는 이 값으로 ThinQ Connect API를 호출해야합니다.