Posting

Machbase의 최신 소식을 지금 만나보세요

[MACHBASE 기초] TAG TABLE 06 – RestAPI with curl

1. 개요

curl 프로그램을 사용하면 웹의 프로토콜 명령어를 command 상에서 수행할수 있습니다. Restful API과 curl을 통해 마크베이스에 저장된 데이터를 조작해 보겠습니다. 

2. 환경 셋팅

2-1. 디렉토리

edu_6_restAPI_curl 파일에는아래와 같은 스크립트가 저장되어 있습니다. 아래의 실습은 리눅스 환경을 기준으로 .sh 파일을 사용했습니다. 윈도우를 사용하시는 분들은 .bat 확장자 파일을 이용해 주세요.

Host:~/work/TagTutorial/edu_6_restAPI_curl$ ls
1_create_tag.sql 2_insert_meta.sql get_multi.sh get_multi_msec.sh get_single.sh post_nano.sh post_sec.sh select.sql tag_lists.sh time_range.sh
Host:~/work/TagTutorial/edu_6_restAPI_curl$

2-2. 마크베이스 서버 및 MWA 준비

이 튜토리얼은 Restful API를 활용합니다. 반드시 마크베이스 MWA를 먼저 동작시켜 주셔야 합니다. 현재 MWAserver는 192.168.0.148의 5001 포트로 연결되어 있습니다. 이 부분은 사용자마다 다를 수 있기 때문에 유의해 주세요.

Host:~/work/TagTutorial/edu_6_restAPI_curl$ machadmin -u

Host:~/work/TagTutorial/edu_6_restAPI_curl$ MWAserver start
SERVER STARTED, PID : 4846
 Connection URL : http://192.168.0.148:5001
Host:~/work/TagTutorial/edu_6_restAPI_curl$

2-3. Tag 테이블 생성

이전 튜토리얼과 같이 파일 1_create_tag.sql을 실행해 주세요. 그리고 2_insert_meta.sql 을 통해서 태그 메타 정보를 입력하실 수 있습니다. 이번에는 아래의 4개의 태그를 사용해 실습이 진행됩니다. 두개는 전력 사용량(TAG_ELEC1, TAG_ELEC2), 나머지 두개는 온도(TAG_TEMP1, TAG_TEMP2)를 나타내는 센서라고 가정하겠습니다.

INSERT INTO tag metadata VALUES ('TAG_ELEC1');
INSERT INTO tag metadata VALUES ('TAG_ELEC2');
INSERT INTO tag metadata VALUES ('TAG_TEMP1');
INSERT INTO tag metadata VALUES ('TAG_TEMP2');

2-4. CURL 설치

리눅스 우분투 혹은 레드헷 계열에서는 아래와 같이 curl을 설치해 주세요.

# ubuntu
sudo apt-get install curl

# redhat
sudo yum install curl

3. 실습

3-1. Rest API 문법

마크베이스는 아래와 같은 포맷으로 데이터를 입력할 수 있는 API를 제공합니다.

{
 "values":[
 [TAG_NAME, TAG_TIME, VALUE], # 태그명,시간,값을 입력한다. 
 [ .... ]....
 ], 
 "date_format":"Date Format" # date_format은 생략시 'YYYY-MM-DD HH24:MI:SS mmm:uuu:nnn' 로 설정된다.
}

3-2. 초단위 데이터 입력

튜토리얼에는 post_sec.sh 가 제공됩니다. 파일을 실행하면 초 단위로 데이터가 입력됩니다. (윈도우일 경우 post_sec.bat) 먼저, post_sec.sh (윈도우 : post_sec.bat) 파일에서 자신의 MWA가 설치된 주소(127.0.0.1)와 포트(5001)로 변경해 주세요.

  • 첫번째 명령어는 “TAG_ELEC1” 센서로 “100”을 “2018-01-10 01:11:11″에 1건 입력시킵니다.
  • 두번째 명령어는 “TAG_ELEC2”, “TAG_TEMP1”, “TAG_TEMP2″로 “2018-01-10 02:22:22” 시간에 200값을 입력시킵니다. 즉 3개의 데이터가 동시에 입력됩니다.
curl -X POST -H "Content-Type: application/json" "http://127.0.0.1:5001/machiot-rest-api/" -d '{ "values":[["TAG_ELEC1","2018-01-10 01:11:11",100]], "date_format":"YYYY-MM-DD HH24:MI:SS" }'
curl -X POST -H "Content-Type: application/json" "http://127.0.0.1:5001/machiot-rest-api/" -d '{ "values":[["TAG_ELEC2","2018-01-10 02:22:22",200],["TAG_TEMP1","2018-01-10 01:11:11",11],["TAG_TEMP2","2018-01-10 02:22:22",22]], "date_format":"YYYY-MM-DD HH24:MI:SS" }'

아래와 같이 수행하면 4개의 태그에 대해 현재의 값을 데이터가 입력됩니다. 아래와 같이 Append Success라는 메시지가 나오면 성공적으로 입력된 것이다.

Host:~/work/TagTutorial/edu_6_restAPI_curl$ sh post_sec.sh 
{"ErrorCode": 0, "ErrorMessage": "", "Data": "{\"EXECUTE RESULT\":\"Append success\"}"}
{"ErrorCode": 0, "ErrorMessage": "", "Data": "{\"EXECUTE RESULT\":\"Append success\"}"}
Host:~/work/TagTutorial/edu_6_restAPI_curl$

제공된 select.sql을 통해 입력된 데이터를 확인해 보겠습니다. 각 태그에 대해 각각 1건씩, 총 네 건이 입력된 것을 볼 수 있다.

Host:~/work/TagTutorial/edu_5_restAPI_input$ machsql -f select.sql
Mach> select * from tag where name = 'TAG_ELEC1';
NAME TIME VALUE 
--------------------------------------------------------------------------------------------------
TAG_ELEC1 2018-01-10 01:11:11 000:000:000 100 
[1] row(s) selected.
Elapsed time: 0.001

Mach> select * from tag where name = 'TAG_ELEC2';
NAME TIME VALUE 
--------------------------------------------------------------------------------------------------
TAG_ELEC2 2018-01-10 02:22:22 000:000:000 200 
[1] row(s) selected.
Elapsed time: 0.001
Mach> select * from tag where name = 'TAG_TEMP1';
NAME TIME VALUE 
--------------------------------------------------------------------------------------------------
TAG_TEMP1 2018-01-10 01:11:11 000:000:000 11 
[1] row(s) selected.
Elapsed time: 0.001
style="background-color:#ddd; padding:10px;"

3-3. 나노 세컨드 단위 데이터 입력

이제 나노 세컨드 단위로 좀 더 세밀하게 데이터를 입력해 보겠습니다. 제공된 post_nano.sh 스크립트를 보면 다음과 같습니다. 마찬가지로 자신의 MWA가 설치된 주소(127.0.0.1)와 포트(5001)로 변경해 주세요. 위에서 사용된 post_sec.sh와 다른점은 입력되는 시간 포맷에 mmm:uuu:nnn 이 추가되었고, 입력되는 데이터에도 111:222:333 과 같은 스트링이 생겼습니다.

  • mmm : 밀리세컨드
  • uuu : 마이크로세컨드
  • nnn : 나노세컨드
curl -X POST -H "Content-Type: application/json" "http://127.0.0.1:5001/machiot-rest-api/" -d '{ "values":[["TAG_ELEC1","2018-01-10 01:11:11 111:222:333",100]], "date_format":"YYYY-MM-DD HH24:MI:SS mmm:uuu:nnn" }'
curl -X POST -H "Content-Type: application/json" "http://127.0.0.1:5001/machiot-rest-api/" -d '{ "values":[["TAG_ELEC2","2018-01-10 02:22:22 444:555:666",200],["TAG_TEMP1","2018-01-10 01:11:11 888:777:666",11],["TAG_TEMP2","2018-01-10 02:22:22 666:555:444",22]], "date_format":"YYYY-MM-DD HH24:MI:SS mmm:uuu:nnn" }'

post_nano.sh를 실행하면 “Append success”가 된 것을 확인할 수 있습니다.

Host:~/work/TagTutorial/edu_6_restAPI_curl$ sh post_nano.sh 
{"ErrorCode": 0, "ErrorMessage": "", "Data": "{\"EXECUTE RESULT\":\"Append success\"}"}
{"ErrorCode": 0, "ErrorMessage": "", "Data": "{\"EXECUTE RESULT\":\"Append success\"}"}
Host:~/work/TagTutorial/edu_6_restAPI_curl$

결과가 제대로 들어갔는지 select.sql을 통해서 확인해 보겠습니다.

Host:~/work/TagTutorial/edu_6_restAPI_curl$ is -f select.sql 
Mach> select * from tag where name = 'TAG_ELEC1';
NAME TIME VALUE 
--------------------------------------------------------------------------------------------------
TAG_ELEC1 2018-01-10 01:11:11 000:000:000 100 
TAG_ELEC1 2018-01-10 01:11:11 111:222:333 100 
[2] row(s) selected.
Elapsed time: 0.001
Mach> select * from tag where name = 'TAG_ELEC2';
NAME TIME VALUE 
--------------------------------------------------------------------------------------------------
TAG_ELEC2 2018-01-10 02:22:22 000:000:000 200 
TAG_ELEC2 2018-01-10 02:22:22 444:555:666 200 
[2] row(s) selected.
Elapsed time: 0.000
Mach> select * from tag where name = 'TAG_TEMP1';
NAME TIME VALUE 
--------------------------------------------------------------------------------------------------
TAG_TEMP1 2018-01-10 01:11:11 000:000:000 11 
TAG_TEMP1 2018-01-10 01:11:11 888:777:666 11 
[2] row(s) selected.
Elapsed time: 0.000
Mach> select * from tag where name = 'TAG_TEMP2';
NAME TIME VALUE 
--------------------------------------------------------------------------------------------------
TAG_TEMP2 2018-01-10 02:22:22 000:000:000 22 
TAG_TEMP2 2018-01-10 02:22:22 666:555:444 22 
[2] row(s) selected.
Elapsed time: 0.000

3-4. GET를 통한 태그 데이터 추출

이번에는  Restful API를 통해서 태그 데이터를 추출해 보겠습니다. Rest API 구문은 다음과 같이 구성됩니다.

{MWA URL}/machiot-rest-api/datapoints/raw/{TagName}/{Start}/{End}/{Direction}/{Count}/{Offset}/
  • TagName : Tag Name. 복수의 Tag 지원(,로 구분하여 사용)
  • Start, End : 기간, YYYY-MM-DD HH24:MI:SS 또는 YYYY-MM-DD 또는 YYYY-MM-DD HH24:MI:SS,mmm (mmm: millisecond, 생략시 start는 000, End는 999이며, 마이크로와 나노도 모두 999임) 실제 스트링으로 지정할 때는 날짜와 시간 사이에 T를 넣어서 빈공간을 없애준다.
  • Direction : 0(ascending), 추후 지원 (시간이 증가하는 방향)
  • Count : LIMIT, 0이면 전체
  • Offset : offset (기본값 = 0)

3-5. 단일 태그 데이터 가져오기

주어진 예제에서 가장 간단한 get_single.sh를 보면, 아래와 같이 TAG_ELEC1에 대해서 데이터를 가져오고 있습니다. (주의할 점은 시간 지정시 대문자 T가 들어가는 것을 잊지 말아야 합니다.)

curl -G "http://192.168.0.148:5001/machiot-rest-api/v1/datapoints/raw/TAG_ELEC1/2018-01-01T00:00:00/2018-01-31T00:00:00"

다음과 같이 총 2건의 TAG_ELEC1에 대한 데이터가 출력됩니다. (읽기 쉽게 줄바꿈을 넣어서 표시함)  

Host:~/work/TagTutorial/edu_6_restAPI_curl$ sh get_single.sh 
{"ErrorCode": 0, "ErrorMessage": "", 
 "Data": [{"DataType": "DOUBLE", 
 "ErrorCode": 0, 
 "TagName": "TAG_ELEC1", 
 "CalculationMode": "raw", 
 "Samples": [{"TimeStamp": "2018-01-10 01:11:11 000:000:000", "Value": 100.0, "Quality": 1}, 
 {"TimeStamp": "2018-01-10 01:11:11 111:222:333", "Value": 100.0, "Quality": 1}]}]}

Host:~/work/TagTutorial/edu_6_restAPI_curl$

3-6. 다중 태그 데이터 가져오기

get_multi.sh는 다수의 태그에 대한 데이터를 가져옵니다. 태그들은 태그명 사이를 컴마( , )로 구분해 주세요.

curl -G "http://192.168.0.148:5001/machiot-rest-api/v1/datapoints/raw/TAG_TEMP1,TAG_TEMP2/2018-01-01T00:00:00/2018-01-31T00:00:00"

다음과 같이 청 2건의 TAG_ELEC1에 대한 데이터가 출력됩니다. (읽기 쉽게 줄바꿈을 넣어서 표시함)

Host:~/work/TagTutorial/edu_6_restAPI_curl$ sh get_multi.sh 
{"ErrorCode": 0, 
 "ErrorMessage": "", 
 "Data": [{"DataType": "DOUBLE", 
 "ErrorCode": 0, 
 "TagName": "TAG_TEMP1", 
 "CalculationMode": "raw", 
 "Samples": [{"TimeStamp": "2018-01-10 01:11:11 000:000:000", "Value": 11.0, "Quality": 1}, 
 {"TimeStamp": "2018-01-10 01:11:11 888:777:666", "Value": 11.0, "Quality": 1}]}, 
 {"DataType": "DOUBLE", 
 "ErrorCode": 0, 
 "TagName": "TAG_TEMP2", 
 "CalculationMode": "raw", 
 "Samples": [{"TimeStamp": "2018-01-10 02:22:22 000:000:000", "Value": 22.0, "Quality": 1}, 
 {"TimeStamp": "2018-01-10 02:22:22 666:555:444", "Value": 22.0, "Quality": 1}]}]}

Host:~/work/TagTutorial/edu_6_restAPI_curl$

3-7. 밀리세컨드 범위의 다중 태그 데이터 가져오기

get_multi_msec.sh는 다수의 태그 대해서 지정되는 시간 범위를 Mili Second로 지정합니다. 스크립트에서 시간을 지정해 준 부분(2018-01-10T01:11:11,888/2018-01-10T02:22:22,100)을 자세히 봐 주세요. 초단위 뒤에 컴마( , )와 숫자가 추가되어 있습니다. 이것은 1시 11분 11초 888밀리 세컨드보다 크고, 2시 22분 22초 100 밀리 세컨드보다 작은 태그 데이터를 가져오라는 의미 입니다.

curl -G "http://192.168.0.148:5001/machiot-rest-api/v1/datapoints/raw/TAG_TEMP1,TAG_TEMP2/2018-01-10T01:11:11,888/2018-01-10T02:22:22,100"

실행하면 다음과 같이 데이터를 가져옵니다.. (읽기 쉽게 줄바꿈을 넣어서 표시함)

Host:~/work/TagTutorial/edu_6_restAPI_curl$ sh get_multi_msec.sh 
{"ErrorCode": 0, 
 "ErrorMessage": "", 
 "Data": [{"DataType": "DOUBLE", 
 "ErrorCode": 0, 
 "TagName": "TAG_TEMP1", 
 "CalculationMode": "raw", 
 "Samples": [{"TimeStamp": "2018-01-10 01:11:11 888:777:666", "Value": 11.0, "Quality": 1}]}, 
 {"DataType": "DOUBLE", 
 "ErrorCode": 0, 
 "TagName": "TAG_TEMP2", 
 "CalculationMode": "raw", 
 "Samples": [{"TimeStamp": "2018-01-10 02:22:22 000:000:000", "Value": 22.0, "Quality": 1}]}]}

Host:~/work/TagTutorial/edu_6_restAPI_curl$

현재 마크베이스 Rest API에서는 마이크로와 나노에 대해서는 시간 범위를 지정하는 것을 제공하지 않습니다. 유의해 주세요.

3-8. GET를 통한 기타 태그 정보  추출

이번에는  Restful API를 통해서 태그의 부가 정보를  추출해 보겠습니다. 다음의 URL은 마크베이스에 존재하는 모든 태그 리스트를 가져오는 명령입니다.

curl -G "http://192.168.0.148:5001/machiot-rest-api/tags/list"

수행하면, 다음과 같이 데이터를 가져온다. (읽기 쉽게 줄바꿈을 넣어서 표시함)

Host:~/work/TagTutorial/edu_6_restAPI_curl$ sh tag_lists.sh 
{"ErrorCode": 0, 
 "ErrorMessage": "", 
 "Data": [{"NAME": "TAG_ELEC1"}, 
 {"NAME": "TAG_ELEC2"}, 
 {"NAME": "TAG_TEMP1"}, 
 {"NAME": "TAG_TEMP2"}]}
Host:~/work/TagTutorial/edu_6_restAPI_curl$

3-9. 임의 태그의 시간 범위 얻기

아래는 마크베이스에서 제공하는 DB 전체에 대한 시간의 최소, 최대 범위를 얻거나, 혹은 임의의 태그에 대한 시간 범위를 얻을 때 활용되는 API에 대한 설명이다. 실제로 차트를 그리는 경우 미리 정보를 얻어서 해당 데이터 출력에 대한 개략적이 크기를 유추하는데 도움이 됩니다.

  • TagName : Tag Name (현재 복수의 Tag Name은 지원하지 않음)
  • TagName이 없는 경우는 전체 Data를 대상으로 시간범위를 구함
{MWA URL}/machiot-rest-api/tags/range/
{MWA URL}/machiot-rest-api/tags/range/{TagName}

time_range.sh 스크립트는 다음과 같습니다.

curl -G "http://192.168.0.148:5001/machiot-rest-api/tags/range/" # 전체 시간 범위 구함
curl -G "http://192.168.0.148:5001/machiot-rest-api/tags/range/TAG_ELEC1" # 각 태그의 시간 범위 구함
curl -G "http://192.168.0.148:5001/machiot-rest-api/tags/range/TAG_ELEC2"
curl -G "http://192.168.0.148:5001/machiot-rest-api/tags/range/TAG_TEMP1"
curl -G "http://192.168.0.148:5001/machiot-rest-api/tags/range/TAG_TEMP2"

수행하면, 다음과 같이 태그가 저장된 시간 범위를 쉽게 얻을 수 있습니다.

Host:~/work/TagTutorial/edu_6_restAPI_curl$ sh time_range.sh 
{"ErrorCode": 0, "ErrorMessage": "", "Data": [{"MAX": "2018-01-10 02:22:22 666:555:444", "MIN": "2018-01-10 01:11:11 000:000:000"}]} # DB 전체 시간 범위
{"ErrorCode": 0, "ErrorMessage": "", "Data": [{"MAX": "2018-01-10 01:11:11 111:222:333", "MIN": "2018-01-10 01:11:11 000:000:000"}]} # TAG_ELEC1의 시간 범위 
{"ErrorCode": 0, "ErrorMessage": "", "Data": [{"MAX": "2018-01-10 02:22:22 444:555:666", "MIN": "2018-01-10 02:22:22 000:000:000"}]} # TAG_ELEC2의 시간 범위 
{"ErrorCode": 0, "ErrorMessage": "", "Data": [{"MAX": "2018-01-10 01:11:11 888:777:666", "MIN": "2018-01-10 01:11:11 000:000:000"}]} # TAG_TEMP1의 시간 범위 
{"ErrorCode": 0, "ErrorMessage": "", "Data": [{"MAX": "2018-01-10 02:22:22 666:555:444", "MIN": "2018-01-10 02:22:22 000:000:000"}]} # TAG_TEMP2의 시간 범위 
Host:~/work/TagTutorial/edu_6_restAPI_curl$

4. 마치며

이상으로 실제 curl을 통해서 태그 데이터를 입력 및 얻고, 관련 정보를 추출해 봤습니다. RestAPI를 잘 활용하면 자신들이 가진 별도의 차트를 웹 상에서 그리는 데  큰 도움이 될 것입니다. 실제 마크베이스의 Tag Analyzer도 이러한 RestAPI를 통해서 구현되었습니다.

연관 포스트

C언어로 Binary data를 Machbase에 넣기

1.개요 Data를 다루다 보면 numeric, varchar 형 데이터뿐만 아니라 JPG, PNG, MP3와 같은 Binary data도 database에 저장해야 할 때가 존재한다. 그러나 일반 data들과는 달리 Binary

[MACHBASE 연동] Android studio에서 JDBC 연결하기

마크베이스 기술지원본부 이현민 1. 개요 수많은 데이터들이 많은 환경에서 생성되고 있는 오늘날, 우리 현대인들의 동반자인 스마트폰 또한 데이터생성의 주체로써 또는 전달자로서 알게 모르게 그 구실을