OBCon Inc. : 마크다운

가이드에서 "https://www.obcon.biz/scada/" 등은 사용하고 계신 URL로 변경하여 접속 하여야 합니다.

사용자의 인증키 관리

SCADA에 관리자로 로그인하여 사용자의 인증키를 관리 한다.

"관리 > 사용자" 메뉴를 선택 한다. "Access Key/Secret 생성" 버튼을 선택하면 화면 하단에 Access Key와 Access Secret가 다시 생성되어 표시 된다.

Access Key : Open API를 사용하기 위한 아이디
Access Secret : Open API를 사용하기 위한 비밀번호
Open API 제어 : Open API 사용 권한을 관리

자신의 인증키 관리

SCADA에 로그인하여 내 정보 메뉴를 선택 한다. "Access Key/Secret 생성" 버튼을 선택하면 화면 하단에 Access Key와 Access Secret가 다시 생성되어 표시 된다.

Access Key : Open API를 사용하기 위한 아이디
Access Secret : Open API를 사용하기 위한 비밀번호

Open API 권한 관리

글로벌 관리자가 설정에서 사이트별로 OpenAPI 사용 여부를 관리 합니다. 신규로 Open API를 사용하는 사이트를 추가하는 경우에 글로벌 관리자에게 요청 하세요.

사용자 정보 중 "Open API 제어" 항목으로 권한 설정을 한다.
- 사용 불가 : Open API를 사용할 수 없다.
- 조회 권한 : Open API에서 조회 기능만 사용 한다.
- 제어 권한 : 모든 기능을 사용할 수 있다.
조회 권한이 있는 경우, 사용할 수 있는 기능
- Token 요청
- 장비 목록, 장비 상세
- 장비 데이터 조회, 최신 장비 데이터 조회
제어 권한이 있는 경우, 사용할 수 있는 기능
- 조회 권한으로 사용할 수 있는 모든 기능
- 장비 제어 요청

Open API 접속 정보

Open API를 사용하기 위해서는 다음 정보를 알고 있어야 한다.

Open API URL : 예) https://www.obcon.biz/scada/api/v1
Access Key : Open API를 사용하기 위한 아이디
Access Secret : Open API를 사용하기 위한 비밀번호

공통 사항

timestamp

타임스탬프로 1970-01-01 00:00:00 이후의 시간을 ms로 환산한 값이다. 13자리 숫자로 1/1000초 단위까지 표시 한다.

nonce

임의의 랜덤한 문자열

hmac

HMAC (Hash-based Message Authentication Code)-SHA256는 보안을 위해서 Open API 서비스로 전달하는 parameters를 사용한 일종의 해시코드 이다.

전달하는 데이터로 QueryString 형태로 변환한 후 Access Secret로 HMAC 처리를 한다. 전달하는 parameter가 없는 경우에는 해당 항목을 제외하고 QueryString을 생성 한다.

//--- Node.js 샘플
//--- params : 서버로 전달하는 데이터를 담은 object
//--- fields : hmac 생성에 사용할 변수 이름을 담은 배열
//--- accessSecret : Access Secret
function makeHmac(params, fields, accessSecret) {
    //--- QueryString 생성
    //---    field에 해당하는 값이 없는 경우 QueryString 생성에서 제외 한다.
    let query = [];
    for (let field of fields) {
        if ((params.hasOwnProperty(field)) && (params[field] != null)) {
            query.push(`${field}=${encodeURIComponent(params[field])}`);
        }
    }
    let queryString = query.join('&');
    
    //--- QueryString로 HMAC 생성
    return crypto.createHmac('sha256', accessSecret).update(queryString, 'utf-8').digest('hex');
}

주의) field에 해당하는 값이 있는 경우에만 QueryString에 추가 한다.

Token 요청

Request

Method : POST
Path : /services/getToken
Parameters

이름	타입	위치	필수	설명
accessKey	String	Body	필수	Access Key
duration	Integer	Body	옵션	Token의 유효 시간(초) Default 1800초 (30분)
timestamp	Integer	Body	필수	타임스탬프 (13자리 숫자)
nonce	String	Body	필수	임의의 랜덤한 문자열
hmac	String	Body	필수	HMA-SHA256

HMAC 생성시 fields
- accessKey, [duration], timestamp, nonce
- "[ ]"로 표시된 항목은 옵션 항목으로 없는 경우, 제외 하세요.

Response

data
- token : 권한을 얻기 위해 사용하는 JWT(JSON Web Token)

장비 목록

Request

Method : GET
Path : /devices
Parameters

이름	타입	위치	필수	설명
x-obcon-accessKey	String	Header	필수	Access Key
x-authorization	String	Header	필수	Bearer ${token}
fields	String	Query	옵션	all. 장비별로 장비 상세에서 반환하는 정보 반환
timestamp	Integer	Query	필수	타임스탬프 (13자리 숫자)
nonce	String	Query	필수	임의의 랜덤한 문자열
hmac	String	Query	필수	HMA-SHA256

x-authorization 값은 Token 앞에 반드시 "Bearer " 문자를 붙여 주세요.
HMAC 생성시 fields
- x-obcon-accessKey, [fields], timestamp, nonce
- "[ ]"로 표시된 항목은 옵션 항목으로 없는 경우, 제외 하세요.

Response

data
- size : 장비 갯수
- data : 장비 배열
  - deviceList 데이터 구조 참조
  - fields=all 인 경우 device 데이터 구조 참조

장비 상세

Request

Method : GET
Path : /devices/{record}
Parameters

이름	타입	위치	필수	설명
record	Integer	Path	필수	장비의 레코드 ID
x-obcon-accessKey	String	Header	필수	Access Key
x-authorization	String	Header	필수	Bearer ${token}
timestamp	Integer	Query	필수	타임스탬프 (13자리 숫자)
nonce	String	Query	필수	임의의 랜덤한 문자열
hmac	String	Query	필수	HMA-SHA256

x-authorization 값은 Token 앞에 반드시 "Bearer " 문자를 붙여 주세요.
HMAC 생성시 fields
- x-obcon-accessKey, timestamp, nonce

Response

data
- data : device 데이터 구조 참조

장비 데이터 조회

Request

Method : GET
Path : /devices/{record}/data
Parameters
- datetimeFrom <= 조회 대상 데이터 < datetimeTo

이름	타입	위치	필수	설명
record	Integer	Path	필수	장비의 레코드 ID
x-obcon-accessKey	String	Header	필수	Access Key
x-authorization	String	Header	필수	Bearer ${token}
datetimeFrom	String	Query	필수	조회 시작일시 (YYYYMMDDHHmmss)
datetimeTo	String	Query	필수	조회 종료일시 (YYYYMMDDHHmmss)
timestamp	Integer	Query	필수	타임스탬프 (13자리 숫자)
nonce	String	Query	필수	임의의 랜덤한 문자열
hmac	String	Query	필수	HMA-SHA256

x-authorization 값은 Token 앞에 반드시 "Bearer " 문자를 붙여 주세요.
HMAC 생성시 fields
- x-obcon-accessKey, datetimeFrom, datetimeTo, timestamp, nonce

Response

data
- hasNext : true인 경우 연속으로 조회할 데이터가 존재함
- datetimeFrom : 연속으로 조회할 때, 다음 조회에서 사용할 기간 (시작일시)
- datetimeTo : 연속으로 조회할 때, 다음 조회에서 사용할 기간 (종료일시)
- size : 데이터 갯수
- data : 데이터 목록
  - 정류기인 경우 devicedata1s 참조
  - 원격TB인 경우 devicedata2s 참조
  - 두께측정장비인 경우 devicedataAs 참조

여러 장비의 최신 장비 데이터 조회

Request

Method : GET
Path : /devices/latestData
Parameters

이름	타입	위치	필수	설명
x-obcon-accessKey	String	Header	필수	Access Key
x-authorization	String	Header	필수	Bearer ${token}
type	String	Query	옵션	장비 타입
timestamp	Integer	Query	필수	타임스탬프 (13자리 숫자)
nonce	String	Query	필수	임의의 랜덤한 문자열
hmac	String	Query	필수	HMA-SHA256

x-authorization 값은 Token 앞에 반드시 "Bearer " 문자를 붙여 주세요.
HMAC 생성시 fields
- x-obcon-accessKey, [type], timestamp, nonce
- "[ ]"로 표시된 항목은 옵션 항목으로 없는 경우, 제외 하세요.

Response

data
- devices : 장비의 레코드 아이디 목록
- device_${장비의 레코드 아이디}
  - size : 데이터 갯수
  - data : 데이터 목록
    - 정류기인 경우 devicedata1s 참조
    - 원격TB인 경우 devicedata2s 참조
    - 두께측정장비인 경우 devicedataAs 참조

장비 제어 요청

Request

Method : PUT
Path : /devices/{record}/requestS
Parameters

이름	타입	위치	필수	설명
record	Integer	Path	필수	장비의 레코드 ID
x-obcon-accessKey	String	Header	필수	Access Key
x-authorization	String	Header	필수	Bearer ${token}
subCommand	String	Body	필수	설정 명령어
value	Float	Body	옵션
status	String	Body	옵션
gpsTime	String	Body	옵션	HHmmss
frequencyMode	String	Body	옵션	1. ELF, 2. ELCD, 3. LFCD
frequencySetting1	Float	Body	옵션	주파수 1 설정값 : 0 ~ 99
frequencySetting2	Float	Body	옵션	주파수 2 설정값 : 0 ~ 99
frequencySetting3	Float	Body	옵션	주파수 3 설정값 : 0 ~ 99
applyCycle	String	Body	옵션	주기 설정
networkCycle	Integer	Body	옵션	통신주기 : 1 ~ 60(분), 1 ~ 24(시)
dataCycle	Integer	Body	옵션	수집주기 : 1 ~ 60(분), 1 ~ 24(시)
timestamp	Integer	Body	필수	타임스탬프 (13자리 숫자)
nonce	String	Body	필수	임의의 랜덤한 문자열
hmac	String	Body	필수	HMA-SHA256

x-authorization 값은 Token 앞에 반드시 "Bearer " 문자를 붙여 주세요.
HMAC 생성시 fields
- x-obcon-accessKey, subCommand, [옵션 항목], timestamp, nonce
- "[ ]"로 표시된 항목은 옵션 항목으로 없는 경우, 제외 하세요.

Response

data
- requestId : 요청 아이디

subCommand에 따른 사용 옵션

장비 타입	인터페이스 버전	SubCommand	옵션	설명
정류기	1.00	0	value	DC 전압
		1	value	DC 전류
		2	value	방식전위
		3	value	On Time
		4	value	Off Time
		1	value	PCM 전압
		b	value	PCM 전류
		5	status	Mode - 정류기/인터럽트 선택 : 1. 인터럽트, 0. 정류기
		6	status	Mode - 자동/수동 선택 : 1. 수동, 0. 자동
		7	status	Mode - Remote/Local 선택 : 1. Remote, 0. Local
		8	status	동작 - 인터럽트 Start/Stop 선택 : 1. Start, 0. Stop
		9	status	Power - 파워 제어 선택 : 1. Off, 0. On
		c	status	PCM ELF 선택 : 1. On, 0. OFF
		d	status	PCM ELCD 선택 : 1. On, 0. OFF
		e	status	PCM LFCD 선택 : 1. On, 0. OFF
		f	status	정류기/PCM 선택 : 1. PCM, 0. 정류기
		g	status	PCM 상태 : 1. Start, 0. Stop
	1.01	h	gpsTime	HHmmss
		i	frequencyMode	1. ELF, 2. ELCD, 3. LFCD
			frequencySetting1	주파수 1 설정값 : 0 ~ 99
			frequencySetting2	주파수 2 설정값 : 0 ~ 99
			frequencySetting3	주파수 3 설정값 : 0 ~ 99
원격TB	1.00	a	applyCycle	주기 설정 0 : 통신주기(분)/수집주기(분) 1 :통신주기(시)/수집주기(분) 2 : 통신주기(시)/수집주기(시)
			networkCycle	통신주기 : 1 ~ 60 (분), 1 ~ 24 (시)
			dataCycle	수집 주기 : 1 ~ 60 (분), 1 ~ 24 (시)
두께측정장비	1.00	a	applyCycle	주기 설정 3 : 통신주기(분)/수집주기(분) 5 :통신주기(시)/수집주기(분) 6 : 통신주기(시)/수집주기(시)
			networkCycle	통신주기 : 1 ~ 60 (분), 1 ~ 24 (시)
			dataCycle	수집 주기 : 1 ~ 60 (분), 1 ~ 24 (시)

정류기 1.01 버전에서는 1.00 버전의 인터페이스도 사용할 수 있다.

장비 제어 결과 요청

Request

Method : GET
Path : /devices/{record}/responseA
Parameters

이름	타입	위치	필수	설명
record	Integer	Path	필수	장비의 레코드 ID
x-obcon-accessKey	String	Header	필수	Access Key
x-authorization	String	Header	필수	Bearer ${token}
subCommand	String	Query	필수	requestS 요청시 보낸 subCommand
requestId	Integer	Query	필수	S 요청시 받은 아이디
timestamp	Integer	Query	필수	타임스탬프 (13자리 숫자)
nonce	String	Query	필수	임의의 랜덤한 문자열
hmac	String	Query	필수	HMA-SHA256

x-authorization 값은 Token 앞에 반드시 "Bearer " 문자를 붙여 주세요.
HMAC 생성시 fields
- x-obcon-accessKey, subCommand, requestId, timestamp, nonce

Response

data
- datetime : 장비로부터 응답을 받은 시간 (YYYY-MM-DD HH:mm:ss)
- code : -1. 장비로부터 받은 응답이 없음, 오류 코드 (0. 정상 적용, 1. 적용 실패, 2. 패킷 이상, 99. 기타)

Open API 응답 (JSON 데이터)

code :응답 코드 (숫자 또는 숫자 배열)
- 0 : 정상
- 0이 아닌 숫자 : 오류 코드
message : 응답 메시지 (문자열 또는 문자열 배열)
data : 반환 데이터 object
- 요청에 따라 반환 데이터가 다름
error 오류 관련 데이터 object (Reserved)

응답 데이터 구조

deviceList 데이터 구조

이름	타입	설명
id	Integer	레코드 ID
name	String	장비 이름
type	String	장비 타입 1. 정류기, 2. 원격TB, A. 두께측정장비
deviceKey	String	장비 아이디
interfaceVersion	String	인터페이스 버전 1.00. 1.01. 1.02
installDate	String	설치일 (YYYY-MM-DD)
statusUse	String	활성 여부 Active, Inactive

device 데이터 구조

이름	타입	설명
id	Integer	레코드 ID
name	String	장비 이름
type	String	장비 타입 1. 정류기, 2. 원격TB, A. 두께측정장비
deviceKey	String	장비 아이디
location	String	위치
latitude	Float	위도
longitude	Float	경도
networkMode	String	통신 모드
dataMode	String	데이터 모드
networkCycle	Integer	통신주기
networkCycleUnit	String	통신주기 단위
dataCycle	Integer	수집주기
dataCycleUnit	String	수집주기 단위
peakNetworkCycle	Integer	피크타임 통신주기(분)
peakDataCycle	Integer	피크타임 수집주기(분)
peakTimeStart1	Integer	피크타임 시작 1
peakTimeEnd1	Integer	피크타임 종료 1
peakTimeStart2	Integer	피크타임 시작 2
peakTimeEnd2	Integer	피크타임 종료 2
ac	Float	AC 측정값
ac1	Float	AC 1 측정값
ac2	Float	AC 2 측정값
preventPotential	Float	방식 전위
preventPotential2	Float	방식 전위 2
batteryVoltage	Float	배터리 전압
temperature	Float	장치 온도
sensitivity	Float	수신 감도
sensitivityRsrp	Integer	수신감도 RSRP
sensitivitySnr	Float	수신감도 SNR
sensitivityRsrq	Integer	수신감도 RSRQ
pressure	Float	압력
pressure2	Float	압력 2
gasConcentration1	Integer	가스농도 1
gasConcentration2	Integer	가스농도 2
dcVoltage	Float	DC 전압
dcElectric	Float	DC 전류
onTime	Float	인터럽트 On time
offTime	Float	인터럽트 Off time
rectifierStatus	String	문열림: 0. 닫힘, 1. 열림
rtuStatus	String	RTU 전원: 0. 정상, 1. 정전
powerStatus	String	정류기 전원: 0. 정상, 1. 정전
interruptRectifier	String	정류기/인터럽트: 0. 정류기, 1. 인터럽트
operateMode	String	자동/수동: 0. 자동, 1. 수동
controlMode	String	로컬/리모트: 0. 로컬, 1. 리모트
operateStatus	String	Stop/Start: 0. Stop, 1. Start
statusDatetime	String	상태 변경일자
interfaceVersion	String	인터페이스 버전
installDate	String	설치일
pipeControl	String	배관연결: 0. 배관연결 해제, 1. 배관연결
waterSensorControl	String	제어값: 0. 수위센서 Off, 1. 수위센서 On
acVoltage	Float	AC 전압
acElectric	Float	AC 전류
deviceMode	String	정류기/PCM: 0. 정류기, 1. PCM
elf	String	ELF: 0. OFF, 1. ON
elcd	String	ELCD: 0. OFF, 1. ON
lfcd	String	LFCD: 0. OFF, 1. ON
pcmOperateStatus	String	PCM 상태: 0. Stop, 1. Start
usePreventPotential	String	전위 사용 여부: 0. 사용 않음, 1. 사용
gpsStatus	String	GPS 상태: 0. Not Ready, 1. Ready
gpsTime	String	GPS 시간: HHmmss
frequencyMode	String	주파수 설정 모드: 1. ELF, 2. ELCD, 3. LFCD
frequencySetting1	Float	주파수 1 설정값
frequencySetting2	Float	주파수 2 설정값
frequencySetting3	Float	주파수 3 설정값
statusUse	String	활성 여부
humidity	Integer	습도
electric	Float	전류
ai1	Float	Analog Input 1
ai2	Float	Analog Input 2
ai3	Float	Analog Input 3
ai4	Float	Analog Input 4
ai5	Float	Analog Input 5
ai6	Float	Analog Input 6
ai7	Float	Analog Input 7
ai8	Float	Analog Input 8
ai9	Float	Analog Input 9
ai10	Float	Analog Input 10
ai11	Float	Analog Input 11
ai12	Float	Analog Input 12
ai13	Float	Analog Input 13
di1	String	Digital Input 1
di2	String	Digital Input 2
di3	String	Digital Input 3
di4	String	Digital Input 4
di5	String	Digital Input 5
labels	String	이름과 단위

device의 labels 데이터 구조

생략

devicedata1s 데이터 구조

이름	타입	설명
id	Integer	레코드 ID
siteKey	String	사이트 키
type	String	장비 타입 1. 정류기
deviceKey	String	장비 아이디
statusDatetime	String	발생일자: YYYYMMDDHHmmss
dcVoltage	Float	DC 전압
dcElectric	Float	DC 전류
preventPotential	Float	방식 전위
onTime	Float	인터럽트 On time
offTime	Float	인터럽트 Off time
batteryVoltage	Float	배터리 전압
temperature	Float	장치 온도
acVoltage	Float	AC 전압
acElectric	Float	AC 전류
acVoltageControl	Float	AC 전압 (제어)
acElectricControl	Float	AC 전류 (제어)
rectifierStatus	String	문열림: 0. 닫힘, 1. 열림
rtuStatus	String	RTU 전원: 0. 정상, 1. 정전
deviceMode	String	정류기/PCM: 0. 정류기, 1. PCM
elf	String	ELF: 0. OFF, 1. ON
elcd	String	ELCD: 0. OFF, 1. ON
lfcd	String	LFCD: 0. OFF, 1. ON
powerStatus	String	정류기 전원: 0. 정상, 1. 정전
interruptRectifier	String	정류기/인터럽트: 0. 정류기, 1. 인터럽트
operateMode	String	자동/수동: 0. 자동, 1. 수동
controlMode	String	로컬/리모트: 0. 로컬, 1. 리모트
operateStatus	String	Stop/Start: 0. Stop, 1. Start
pcmOperateStatus	String	PCM 상태: 0. Stop, 1. Start
gpsStatus	String	GPS 상태: 0. Not Ready, 1. Ready
gpsTime	String	GPS 시간: HHmmss
interfaceVersion	String	인터페이스 버전
customData	String	Custom data

devicedata2s 데이터 구조

이름	타입	설명
id	Integer	레코드 ID
siteKey	String	사이트 키
type	String	장비 타입 2. 원격TB
deviceKey	String	장비 아이디
statusDatetime	String	발생일자: YYYYMMDDHHmmss
ac	Float	AC 측정값
preventPotential	Float	방식 전위
batteryVoltage	Float	배터리 전압
sensitivity	Float	수신 감도
dataMode	String	데이터 모드 0. 통신주기(분)/수집주기(분), 1. 통신주기(시)/수집주기(분) 2. 통신주기(시)/수집주기(시)
dataCycle	Integer	수집주기
networkCycle	Integer	통신주기
temperature	Float	장치 온도
humidity	Integer	습도

devicedataAs 데이터 구조

이름	타입	설명
id	Integer	레코드 ID
siteKey	String	사이트 키
type	String	장비 타입 A. 두께측정장비
deviceKey	String	장비 아이디
statusDatetime	String	발생일자: YYYYMMDDHHmmss
dataMode	String	데이터 모드 3. 통신주기(분)/수집주기(분), 5. 통신주기(시)/수집주기(분) 6. 통신주기(시)/수집주기(시)
dataCycle	Integer	수집주기
networkCycle	Integer	통신주기
ai1	Float	Analog Input 1
ai2	Float	Analog Input 2
ai3	Float	Analog Input 3
ai4	Float	Analog Input 4
ai5	Float	Analog Input 5
ai6	Float	Analog Input 6
ai7	Float	Analog Input 7
ai8	Float	Analog Input 8
ai9	Float	Analog Input 9
ai10	Float	Analog Input 10
ai11	Float	Analog Input 11
ai12	Float	Analog Input 12
ai13	Float	Analog Input 13
batteryVoltage	Float	배터리 전압
sensitivity	Float	수신 감도

Open API 이력 관리

현재의 인터페이스 정의서에 따르면 requestS 요청에 따른 responseA 응답을 서비스에서 정확하게 확인할 수 없습니다. 따라서 다음과 같이 보완을 하였으나 정확한 응답은 아닐 수 있습니다. 정확한 확인이 필요하면 장비의 값을 읽어 추가 확인하시기 바랍니다.

Open API 이력 관리를 통한 응답 보완

requestS 요청이 발생하면 Open API 이력에 해당 요청을 저장하고 동일한 장비에서 동일한 요청에 대한 응답이 오면 Open API 이력을 업데이트 합니다. requestA 요청이 발생하면 Open API 이력 테이블에 있는 응답을 반환 합니다.
동일한 장비에서 동일한 요청(subCommand)이 여러번 발생할 수 있기 때문에 정확한 응답을 반환하지 못할 가능성이 있습니다.

설정 파일에서 권한 설정

//--- 모든 사이트(고객사)에게 Open API 허용시
//---     true이면 모든 사이트가 Open API를 사용할 수 있습니다.
conf.openAPI.useAll = true;

//--- 특정 사이트(고객사)에만 Open API 허용시
//---     Open API의 사용이 허용된 사이트의 ID 배열
conf.openAPI.sites = [];

Open API

사용자의 인증키 관리

자신의 인증키 관리

Open API 권한 관리

Open API 접속 정보

공통 사항

timestamp

nonce

hmac

Token 요청

장비 목록

장비 상세

장비 데이터 조회

최신 장비 데이터 조회

여러 장비의 최신 장비 데이터 조회

장비 제어 요청

장비 제어 결과 요청

Open API 응답 (JSON 데이터)

응답 데이터 구조

deviceList 데이터 구조

device 데이터 구조

device의 labels 데이터 구조

devicedata1s 데이터 구조

devicedata2s 데이터 구조

devicedataAs 데이터 구조

Open API 이력 관리

설정 파일에서 권한 설정

관련 사이트