IOTOWN에서 데이터 받기

외부 서비스에서 IOTOWN의 데이터를 실시간으로 전달 받는 방법을 설명합니다.

개요

IOTOWN에 수집된 데이터를 외부 서비스로 전달하는 방법은 두 가지입니다.

사전 준비

외부 서비스에서 데이터를 받으려면 수신 준비가 필요합니다.

방법 1: Webhook으로 받기

IOTOWN이 지정한 URL로 HTTP POST 또는 PUT 요청을 보냅니다.

Step 1: Webhook 액션 생성

파이프라인 > 액션 페이지에서 새 액션을 만듭니다.

페이로드 템플릿 (선택사항)

전송할 데이터 형식을 지정할 수 있습니다. 템플릿을 지정하지 않으면 다음 기본 형식으로 전송됩니다:

{
  "deviceId": "sensor-001",
  "data": {
    .....
  },
  "timestamp": "2025-01-28T12:00:00.000Z",
  "deviceTimestamp": "2025-01-28T11:59:50.000Z"
}

Step 2: 규칙 생성

파이프라인 > 규칙 페이지에서 새 규칙을 만듭니다.

Step 3: 수신 확인

외부 서비스에서 HTTP 요청 수신을 확인합니다.

방법 2: MQTT로 받기

IOTOWN이 MQTT 브로커로 메시지를 발행합니다. IOTOWN 내장 MQTT 브로커를 사용하거나 외부 MQTT 브로커를 사용할 수 있습니다.

Step 1: MQTT 커넥터 생성

파이프라인 > 액션 페이지 하단의 서비스 연동 설정 > MQTT 커넥터 관리로 이동하여 MQTT 커넥터를 생성합니다.

IOTOWN 내장 브로커를 사용할 경우, 다음과 같이 설정합니다.

Step 2: MQTT 액션 생성

파이프라인 > 액션 페이지에서 새 액션을 만듭니다.

페이로드 템플릿 (선택사항)

전송할 데이터 형식을 지정할 수 있습니다. 템플릿을 지정하지 않으면 다음 기본 형식으로 전송됩니다:

{
  "deviceId": "sensor-001",
  "data": {
    "temperature": 25.5,
    "humidity": 60
  },
  "timestamp": "2025-01-28T12:00:00.000Z",
  "deviceTimestamp": "2025-01-28T11:59:50.000Z"
}

Step 3: 규칙 생성

파이프라인 > 규칙 페이지에서 새 규칙을 만듭니다.

Step 4: 수신 확인

MQTT 클라이언트로 해당 브로커에 접속하고, 해당 토픽을 구독하여 메시지를 수신합니다.

페이로드 템플릿

Webhook과 MQTT 액션에서 전송할 데이터 형식을 직접 지정할 수 있습니다.

템플릿 예시

{
  "device": "{{device.name}}",
  "temperature": {{data.temperature}},
  "humidity": {{data.humidity}},
  "alert": "{{rule.name}}",
  "time": "{{timestamp_local}}"
}

사용 가능한 변수

파일 URL 처리

장치 데이터에 이미지/첨부파일이 포함되어 있으면 응답/페이로드에 /api/v1/files/... 형태의 상대 경로 URL이 들어옵니다. 두 가지 방식으로 다운로드할 수 있습니다.

방식 A — 액션으로 받은 서명된 URL 사용 (권장)

액션 페이로드의 URL은 IOTOWN이 자동으로 HMAC 서명한 일회용 링크입니다. 인증 헤더 없이 받은 URL 그대로 GET 하면 됩니다.

{
"deviceId": "camera-001",
"data": {
  "image": "/api/v1/files/iotown/data/<group>/<device>/20260427/abc123.jpg?exp=1714200000&sig=Xj7P..."
},
"timestamp": "2026-04-27T12:00:00.000Z"
}

수신자는 자신이 아는 IOTOWN 서버 도메인을 앞에 붙여서 GET 요청을 보냅니다.

방식 B — API Key로 직접 접근

만료된 URL 또는 데이터 조회 API(GET /api/v1/devices/.../data) 응답으로 받은 URL은 서명이 없습니다. 이 경우 ?exp=&sig= 부분을 제거하고 X-API-Key 헤더를 붙여 동일 경로로 요청하세요.

API Key 인증 시에는 본인 그룹의 파일만 조회 가능합니다(타 그룹 파일은 403).

파일 영구 보관

서명된 URL은 일정 시간(기본 1시간)이 지나면 만료됩니다. 영구 보관이 필요하면 수신 즉시 다운로드해서 저장하세요. 만료 후에도 같은 파일이 필요하면 방식 B(API Key)로 언제든 다시 가져올 수 있습니다.

만료 시간 변경

기본 만료는 1시간입니다. 관리 > 시스템 > 보안 > 서명된 파일 URL 메뉴에서 60초~7일 범위로 조정할 수 있습니다. 짧을수록 안전하고 길수록 수신 측에 여유가 생깁니다.

문제 해결

Webhook이 도달하지 않음

MQTT 메시지가 도달하지 않음

다음 단계