Close

Overview

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

What is ThinQ Connect?

ThinQ Connect는 ThinQ 플랫폼이 파트너에게 제공하는 다양한 인터페이스 중 하나로, IoT 서비스를 직접 운영하고자 하는 파트너를 위해 제공되는 Server-to-Server 인터페이스입니다.

 

ss-concept-thinqEXT.png

Key Features (v2.0) 

여러분의 서비스는 ThinQ Connect API v2.0 API를 통해 ThinQ 플랫폼에 다음 작업을 요청할 수 있습니다. 

  • 사용자의 디바이스 목록을 조회합니다.
  • 단일 디바이스에 대해 
    • 프로파일 및 상태를 조회합니다.
    • 제어를 요청합니다.
    • 이벤트/푸쉬를 구독하거나 해지합니다. 
  • 복수의 디바이스에 대해 동시에 
    • 프로파일 및 상태를 조회합니다. 
    • 제어합니다. (단, 동일한 디바이스 타입에 대해서만 가능합니다.)
    • 이벤트/푸쉬를 구독하거나 해지합니다. 
  • 사용자의 디바이스 설정(추가/삭제/별명 변경 등)에 대한 푸쉬를 구독합니다.

ThinQ Connect API는 RESTful 형식으로 사용하기 쉽게 디자인되었습니다. 또한 API 요청 및 응답에는 LG 가전 제품의 속성을 모델링하여 json 포맷으로 정의한 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란?
    • 여러분의 서비스가 ThinQ 플랫폼의 개발 형상 서버들과 연동하는데 필요한 서비스 고유 정보로, 서비스 식별자(service_id, service_key)를 포함합니다.

3. 서비스 개발

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

LG Account (LG EMP) 연동 구현

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

사용자는 LG Account 계정을 통해 자신의 디바이스를 ThinQ 플랫폼에 등록합니다. 여러분의 서비스가 사용자의 디바이스 데이터를 이용하기 위해서, 사용자가 여러분의 서비스에 로그인할 때 EMP로부타 OAuth 2.0 토큰을 발급받도록 해야 합니다. 이를 위해 EMP는 OAuth 2.0 표준을 따르는 Open API를 제공합니다. 

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

  1. EMP API를 사용하여, EMP로부터 서비스 사용자의 OAuth 토큰을 발급받습니다.
  2. ThinQ Connect API를 호출할 때. API 요청 헤더 (Authorization)에 해당 사용자의 토큰 정보를 입력합니다. 

ThinQ Connect API 연동 구현

먼저, ThinQ Connect API 호출에 필요한 다음 값이 준비되었는지 확인하십시오. 모든 ThinQ Connect API는 요청 시 헤더에 다음 정보를 포함해야 합니다. 

헤더 파라미터

입력 값

설명
Authorization

EMP OAuth 토큰 정보

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

service_id 값

서비스 생성 후,LG 담당자에게 발급받은 DEV_SERVICE_CONFIG에 포함되어 있음.

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

service_key 값

서비스 생성 후,LG 담당자에게 발급받은 DEV_SERVICE_CONFIG에 포함되어 있음.

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

위 값이 모두 준비되었다면, API 문서를 참조하여 필요한 기능을 구현하십시오. 서비스 개발과 관련된 궁금한 점은 Tech Q&A 게시판을 통해 LG 담당자에게 문의할 수 있습니다.

4. 서비스 인증

개발이 완료되면 서비스 인증을 요청하십시오. LG 담당자가 인증을 완료하면 서비스 어드민에게 PRODUCT_SERVICE_CONFIG를 발급합니다. 인증과 관련된 궁금한 점은 Certification Q&A 게시판을 통해 문의할 수 있습니다. 

  • PRODUCT_SERVICE_CONFIG 란?
    • 여러분의 서비스가 ThinQ 플랫폼의 운영 형상 서버들과 연동할 수 있게 해주는 서비스 고유 정보입니다.
    • 배포 버전의 서비스에서는 이 값에 포함된 service_id/service_key로 ThinQ Connect API를 호출해야 합니다.