RESTful API Overview

Representational State Transfer (REST) is a type of software architecture style that consists of guidelines and best practices for interfaces provided by scalable Web services.

The four methods defined in the HTTP protocol define the CRUD for the resource.

HTTP Method	Meaning
POST	Create
GET	Select
PUT	Update
DELETE	Delete

Machbase is not a standard RESTful API, but rather a RESTful API that handles CRUD using only POST and GET methods.

That is, the POST method is used for data input and the rest is transmitted as a GET Method parameter to the SQL query so that all the operations can be performed.

Machbase 6.

5 RestAPI

Machbase에 웹서버를 내장하여 별도의 서버 구동 없이 Machbase에 직접 RestAPI를 수행하는 기능이다.

RestAPI 지원 Machbase Edition

7 RestAPI

MachBase supports convenient and fast Rest API functions through the web server built into the server.

Machbase Edition support embedded web server

All type of machbase editions are supported. (Edge / Fog / Cluster

(개발 중

)

RestAPI 지원 Table 종류

Tag Table / Log Table / Lookup Table / Volatile Table

Configuration 설정

machbase.conf 와 http.conf 두 가지 설정 파일이 존재한다.

machbase.conf : Rest API를 사용하기 위해 HTTP 서버를 사용할 지와 최대 메모리 사용량 등 HTTP Server에 대한 설정을 저장
http.conf : HTTP Web Server 자체에 대한 설정을 저장

설정 파일을 수정 하면 machbase 서버를 다시 시작해야 변경 내용이 적용된다.

버전별 .conf 파일의 위치

Edge / Fog 버전

$MACHBASE_HOME/conf/machbase.conf

$MACHBASE_HOME/

Location of version-specific .conf files

Edge/Fog version

$MACHBASE_HOME/conf/machbase.conf $MACHBASE_HOME/http/conf/http.conf

Cluster

버전

version

EACH

$EACH_BROKER_HOME/conf/machbase.conf (

Broker 별로 모두 수정)EACH

Modify by Broker) $EACH_BROKER_HOME/http/conf/http.conf (modify all per Broker

별로 모두 수정

)

각 .conf 파일 Property 설명

Added properties for embedded web server

machbase.conf (set as PROPERTY = VALUE

형태로 설정

)

AUTH

내장 웹 서버 사용 시 기본 인증을 사용할 지 여부

0 : 인증 사용 안함, 1 : 인증 사용함

Property	설명Description
HTTP_ENABLE	내장 웹 서버를 구동할 지 여부 0 : 구동 안함 Whether to run the embedded web server 0: not driven, 1: 구동 driven
HTTP_PORT_NO	내장 웹 서버 접속 Port 번호 Port 범위 Embedded web server connection port number Port range: 0 ~ 65535 Default : 5657
HTTP_MAX_MEM 하나의 Web Session에서 사용할 최대 메모리 Min : 1048576 MEM	Maximum memory used by one Web Session Min: 1048576 (1MB) Default : 536870912 536870912 (512MB)
HTTP_	AUTH	Whether to use Basic authentication when using the Embedded Web Server 0: Authentication not used, 1: Authentication enabled

http.conf (set in JSON

형식으로 설정

format)

Property	설명Description
document_rootroot	html file location based on $MACHBASE_HOME 기준의 html 파일 위치 Default : http/html ($MACHBASE_HOME/http/html)
max_request_size1회 요청의 최대 요청 byte 크기 제한size	Limit the maximum request byte size for one request
request_timeout_ms1회 요청의 최대 응답 대기 시간 ms	Maximum response latency for one request (millisecond)
enable_auth_domain_check	도메인 인증을 활성화 할지 여부 Whether to enable domain authentication Set to "yes" or "no" 값으로 설정value Default: "no"
reverse_proxy	요청 URL을 특정 URL로 변경 참고: https://brainbackdoor.tistory.com/113

각 .conf 파일 Sample

change request url to specific url

sample conf files

machbase.conf

Code Block

title	machbase.conf

#################################################################################
# Rest-API port
#################################################################################
HTTP_PORT_NO = 5657
   
#################################################################################
# Maximum memory per web session.
# Default Value# Default Value: 536870912 (512MB)
#################################################################################
HTTP_MAX_MEM = 536870912
   
#################################################################################
# Min Value# Min Value:     0
# Max Value# Max Value:     1
# Default Value# Default Value: 0
#
# Enable REST-API service.
#################################################################################
HTTP_ENABLE = 0
   
#################################################################################
# Min Value# Min Value:     0
# Max Value# Max Value:     1
# Default Value# Default Value: 0
#
# Enable Basic Authentication for RestAuthentication for Rest-API service
#################################################################################
HTTP_AUTH = 0

http.conf

Code Block

title	http.conf

{
    "document_root":"http/html/",
    "max_request_size":  "100000",
    "request_timeout_ms":  "10000",
    "enable_auth_domain_check":  "no",
    "reverse_proxy"  : [["/machbase/tables",  "http://127.0.0.1:55657/machbase"],
        ["/self_machbase_proxy",  "http://127.0.0.1:55657/machbase"],
        ["/dead_proxy",  "http://127.0.0.0/machbase"]]
}

RestAPI 사용

DDL / DML / Append

수행 가능

REST API Usage

Code Block

기본Basic 요청request 형식format
 

http://addr:port/machbase?q=query&f=dateformat
 
응답 형식Response DDL / Append / DML (except Selectexcept Select)

{"error_code":0,  "error_message"  :"Message",  "data":[]}
 
응답 형식Response DML (Select)

{"error_code":0,  "error_message"  :"Message",  "columns":[Columns],  "data":[Data]}

DDL Sample

Code Block

## Request of 테이블creating 생성a 요청table
curl -G G "http://127.0.0.1:5657/machbase"  --data-urlencode 'q=create table test_table (name varchar(20), time datetime, value double)'
  

## 정상Normal 응답response
{"error_code":0,  "error_message"  :"No Error",  "data":[]}
  

## 테이블Request 삭제of 요청dropping curla -G table
curl -G "http://127.0.0.1:5657/machbase"  --data-urlencode 'q=drop table test_table'
   
## 정상Normal 응답response
{"error_code":0,  "error_message"  :"No Error",  "data":[]}

DML Sample

Code Block

## Request 로그Log 테이블 입력(Insert) 요청table data insert
curl -G "http://127.0.0.1:5657/machbase" --data-urlencode 'q=insert into test_table values ("test", "1999-01-01 00:00:00", 0)'
   
## 정상 응답Response
{"error_code":0, "error_message" :"No Error", "data":[]}
   
## 로그Request 테이블Log 조회table 요청select
curl -G "http://127.0.0.1:5657/machbase" --data-urlencode 'q=select * from test_table'
   
## 정상 응답Response
{"error_code":0, "error_message": "", "columns" : [{"name":"NAME", "type":5, "length":20},{"name":"TIME", "type":6, "length":8},{"name":"VALUE", "type":20, "length":8}],"data" :[{"NAME":"test", "TIME":"1999-01-01 00:00:00 000:000:000", "VALUE":0.000}]}

Append Sample

Code Block

## Append some 로그data 테이블 입력(Append) 요청to log table
curl -X POST -H "Content-Type: application/json" "http://127.0.0.1:5657/machbase" -d '{"name":"test_table", "date_format":"YYYY-MM-DD","values":[["test", "1999-01-01 00:00:01", 1], ["test", "1999-01-01 00:00:02", 2], ["test", "1999-01-01 00:00:03", 3]]}'
   
## 정상 응답Response
{"error_code":0, "error_message" :"No Error", "data":[], "append_success":3, "append_failure":0}


In the case of Binary

Append

Binary Append의 경우 Binary 데이터를 Base64로 인코딩 후 전송하면 서버에서 디코딩 후 저장하게 된다.

출력 시에는 바이너리 데이터가 Base64로 인코딩되어 반환된다.

입력 : Binary Data >> Base64 Encoding >> HTTP

 Append, if binary data is encoded in Base64 and transmitted, the server will decode it and store it. When outputting, binary data is returned after being encoded in Base64.

Input : Binary Data >> Base64 Encoding >> HTTP(POST) >> Base64 Decoding Decoding >> Append(BLOB Binary)

출력 Output : BLOB Binary Binary >> Base64 Base64 Encoding >> HTTP (GET) >> Base64 Decoding Decoding >> Save or View Binary

Binary Append Sample

Code Block

## 00Example ~of FF까지의sending 256바이트binary 바이너리data. 데이터를data Base64로should 인코딩be 후encoded 입력by /Base64.
출력  
예##  Request ##append 로그to 테이블 입력(Append) 요청log table
curl  -X POST -H "Content-Type: application/json" "http://127.0.0.1:5657/machbase" -d '{"name":"test_table", "date_format":"YYYY-MM-DD","values":[["AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t/g4eLj5OXm5+jp6uvs7e7v8PHy8/T19vf4+fr7/P3+/w=="]]}'
   
## 정상 응답Result
{"error_code":0, "error_message" :"No Error", "data":[], "append_success":1, "append_failure":0}
   
## Get 로그data 테이블from 출력log 요청table
curl -G "http://127.0.0.1:5657/machbase" --data-urlencode 'q=select * from test_table';
   
## The Base64 데이터 출력encoded data are displaied
{"error_code" :0, "error_message": "No Error", "columns" : [{"name":"V1", "type":57, "length":67108864}],"data" :[{"V1":"AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t/g4eLj5OXm5+jp6uvs7e7v8PHy8/T19vf4+fr7/P3+/w=="}]}
   
## machsql을Can 통한check HEXdata Dumpusing 값machsql
확인
select to_hex(v1) from test from test_table;
to_hex(v1)                                                                      
------------------------------------------------------------------------------------
000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F2021222324252627
28292A2B2C2D2E2F303132333435363738393A3B3C3D3E3F404142434445464748494A4B4C4D4E4F
505152535455565758595A5B5C5D5E5F606162636465666768696A6B6C6D6E6F7071727374757677
78797A7B7C7D7E7F808182838485868788898A8B8C8D8E8F909192939495969798999A9B9C9D9E9F
A0A1A2A3A4A5A6A7A8A9AAABACADAEAFB0B1B2B3B4B5B6B7B8B9BABBBCBDBEBFC0C1C2C3C4C5C6C7
C8C9CACBCCCDCECFD0D1D2D3D4D5D6D7D8D9DADBDCDDDEDFE0E1E2E3E4E5E6E7E8E9EAEBECEDEEEF
F0F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF                                                
[1] row(s) selected.

Using HTTP

_AUTH

Auth Property

사용Request Header에

This is an option to set authentication as a normal user by including the string 'Authorization: Basic Base64String'

문자열을 포함하여 정상 유저임을 인증하도록 설정하는 옵션이다.Base64 문자열은 ID@Host:Password 구조로 작성한다. (단, Host명은 정확하지 않아도 된다. ID, Password는 Machbase의 유저 정보를 입력해야 한다.)
Code Block

title	인증을 위한 Basic Base64String 생성 방법

##

 in the Request Header. Base64 string is written in ID@Host:Password structure. (However, the host name does not need to be correct. ID and password must be entered in Machbase user information.)

How to create a Basic Base64String for authorize

Base64String 사용

Code Block
## In case of ID: sys, Password Password: manager 일, 경우의creating 생성a 예Base64String echo -n "sys@localhost:manager" \| base64 ## 생성된Result Base64String c3lzQGxvY2FsaG9zdDptYW5hZ2Vy
Code Block
title

Using Auth Sample (HTTP_AUTH = 1

인 경우

)

##

Code Block

## Request Authorization을of 넣지result 않은without 요청의authorization 예clause
curl -G G "http://127.0.0.1:5657/machbase"  --data-urlencode 'q=select * from v$stmt'
   
## 에러Error 발생occurred
{"error_code":3118,  "error_message"  :"There is No Authorization Header.",  "data":[]}
   
## RequestAdding Header에 'Authorization:Base64String' 추가한at 요청의the request 예header
curl -H H "Authorization: Basic c3lzQGxvY2FsaG9zdDptYW5hZ2Vy"    -G G "http://127.0.0.1:5657/machbase"  --data-urlencode 'q=select * from v$stmt'
  

## 정상Normal 응답response
{"error_code":0,  "error_message":  "No Error",  "columns"  : [{"name":"ID",  "type":8,  "length":4},{"name":"SESS_ID",  "type":8,  "length":4},{"name":"STATE",  "type":5,  "length":64},{"name":"RECORD_SIZE",  "type":8,  "length":4},{"name":"QUERY",  "type":5,  "length":32767}],"data"  :[{"ID":0,  "SESS_ID":52,  "STATE":"Fetch prepared",  "RECORD_SIZE":0,  "QUERY":"select * from v$stmt"}]}

출력 소수점 Scale 지정 (s 옵션)

응답 데이터의 소수점을 몇자리까지 출력할 지 지정

0 ~ 9 값으로 설정 (범위 값이 아닐 경우 3으로 동작)

Code Blocktitle소수점 5자리까지 출력

Changing floating point precision with s option

Specify how many decimal places of response data to output Set to a value from 0 to 9 (If it is not a range value, it operates as 3)

Sample (s=5)

Code Block

## 소수점display 5자리까지result 출력5 decimal places
curl -G "http://127.0.0.1:5657/machbase" --data-urlencode 'q=select * from test_table' --data-urlencode 's=5';
   
## 정상Normal 응답response
{"error_code" :0, "error_message": "", "columns" : [{"name":"C1", "type":16, "length":4},{"name":"C2", "type":20, "length":8}],"data" :[{"C1":12345.00000, "C2":1234.01235}]}

데이터

Changing data Fetch

모드 변경

mode (m

옵션

option)

응답 data에 column 이름을 항상 붙여서 표시할 지 결정

Decide whether to always display column names in response data (0:

표시

 display, 1:

표시 안함)
Code Blocktitle

 do not display)

Default Fetch mode Sample (m=0)

Code Block

#### Request fetch modefetch mode (m=0)
요청
curl -G "http://127.0.0.1:5657/machbase" --data-urlencode 'q=select * from tag limit 2' --data-urlencode 'm=0';
   
## 정상Normal 응답response (ColumnConatains Name을Column Name 포함한in 결과result 출력data)
{"error_code" :0, "error_message": "", "columns" : [{"name":"NAME", "type":5, "length":20},{"name":"TIME", "type":6, "length":8},{"name":"VALUE", "type":20, "length":8}],
"data" :[{"NAME":"tag1", "TIME":"2001-09-09 10:46:40 000:000:000", "VALUE":1000000000.000}, {"NAME":"tag1", "TIME":"2001-09-09 10:46:41 000:000:000", "VALUE":1000000001.000}]}

Code Block

title

Advanced Fetch mode Sample (m=1)

## fetch mode

Code Block

## Request fetch mode (m=1) 요청
curl -G "http://127.0.0.1:5657/machbase" --data-urlencode 'q=select * from tag limit 2' --data-urlencode 'm=1';
   
## 정상Normal 응답response (ColumnColumn Names are Name이not 생략된included 결과in 출력results)
{"error_code" :0, "error_message": "", "columns" : [{"name":"NAME", "type":5, "length":20},{"name":"TIME", "type":6, "length":8},{"name":"VALUE", "type":20, "length":8}],
"data" :[["tag1", "2001-09-09 10:46:40 000:000:000", 1000000000.000], ["tag1", "2001-09-09 10:46:41 000:000:000", 1000000001.000]]}

NULL 값의 처리

DML의 처리 중 Insert나 Append 시 NULL 값은 그대로 null로 입력하면 된다.
Code Block

title	Append 시 NULL 값을 포함한 JSON Sample

Handling of NULL values
When inserting or appending during DML processing, a NULL value can be entered as null as it is.

JSON Sample for appending null values

Select 시의 NULL 값 포함 결과 Sample

Code Block
[["data1", "data2", "data3"],["data11", "data12", "data13"],["data21", "data22", "data23"],[null,null,null]]
Code Block
title

Sample result containing null values from SELECT

Code Block

[{"C1":null, "C2":null, "C3":null, "C4":null, "C5":null, "C6":null, "C7":null, "C8":null, "C9":null, "C10":null, "C11":null, "C12":null}]":null, "C5":null, "C6":null, "C7":null, "C8":null, "C9":null, "C10":null, "C11":null, "C12":null}]

RestAPI for Tag Table Usage

Machbase provides Historian-like RestAPI access to Tag Table.

The default request format is http://ipaddr:port/machiot/ or http://ipaddr:port/machiot-rest-api/

In addition, the following parameters can be handed over to the URL.

Parameter

Description

Sample

f

or

DateFormat

Set Date Format

XXX?f=YYYY/MM/DD

XXX?DateFormat=YYYY/MM/DD

s

or

Scale

Set Scale

XXX?s=12

XXX?Scale=12

m

or

FetchMode

Set Fetch Mode

XXX?m=1

XXX?FetchMode=1

Raw data processing function

Raw Value Append API

This API is a function of appending a large amount of data into a given table.

URL

http://ipaddr:port/machiot/datapoints/raw/{Table}

http://ipaddr:port/machiot/v1/datapoints/raw/{Table}

HTTP method : POST
Table : Target tag table to be input

Usage

Code Block

language	js

Request
curl  -X POST -H "Content-Type: application/json" "http://127.0.0.1:${ITF_HTTP_PORT}/machiot-rest-api/datapoints/raw/tag" 
-d '{"date_format":"YYYY-MM-DD HH24:MI:SS",
     "values":
       [ 
          ["tag1", "1999-01-01 00:00:00", 0], 
          ["tag1", "1999-01-01 00:00:01", 1], 
          ["tag1", "1999-01-01 00:00:02", 2]
        ]
     }';
Response
{
   "error_code":0, 
   "error_message" :"No Error",
   "timezone":"+0900", 
   "data":[], 
   "append_success":3, 
   "append_failure":0
}

Raw Value Select API

This API is a function of obtaining data from a given table.

It supports the method of directly specifying all URLs, and also supports the method of passing them to the factor of the GET method.

Each directory name may be designated as a factor in the URL below.

URL

http://ipaddr:port/machiot/datapoints/raw/{Table}/{TagNames}/{Start}/{End}/{Direction}/{Count}/{Offset}

http://ipaddr:port/machiot/v1/datapoints/raw/{Table}/{TagNames}/{Start}/{End}/{Direction}/{Count}/{Offset}

HTTP method : GET
Table : Target tag table to be selected
TagNames : Target tag name to be selected
- This tag name can be divided into a comma and multiple tag results can be obtained in one series.
Start : Indicates the starting time value of the data to be selected.
End : Indicates the last time value of the data to be selected.
- Time format: Both space-free and space-support forms are supported as shown below. (If tested with curl, additional forms can be used)
  - Basic form (space supported, up to nanoseconds)
    - YYYY-MM-DD HH:MI:SS, millis
    - YYYY-MM-DD HH:MI:SS milliSec:microSec:nanoSec
  - Additional Form (space not supported, Use uppercase T instead of space and support up to milliseconds)
    - YYYY-MM-DDTHH:MI:SS,millis
- Example
  - "2020-12-12"
  - "2020-12-12 03:22:22"
  - "2020-12-12 03:22:22 222:333:444"
  - "2020-12-12T03:22:22"
  - "2020-12-12T03:22:22,234"
Direction (Omitable)
- 0 (Default): Output in the order entered
- 1 : Output in the direction of time decrease
- 2 : Output in the direction of time increase
Count (Omitable)
- 0 (Default): Output all data
- Else : Output a given number of records
Offset (Omitable)
- 0 (Default) : Do not skip over
- Else : Skip over a given value

Usage

Code Block

language	js

Request (Directly specifying all URL)
curl -X GET  "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/v1/datapoints/raw/tag/tag-1/2001-09-09T00:00:00,000/2001-09-09T01:20:00,000/0/5/0"
Request
{
  "error_code": 0,
  "error_message": "",
  "columns": [
    {
      "name": "NAME",
      "type": 5,
      "length": 20
    },
    {
      "name": "TIME",
      "type": 6,
      "length": 31
    },
    {
      "name": "VALUE",
      "type": 20,
      "length": 17
    }
  ],
  "timezone": "+0900",
  "data": [
    {
      "NAME": "tag-1",
      "TIME": "2001-09-09 01:00:01 000:000:000",
      "VALUE": 8001
    },
    {
      "NAME": "tag-1",
      "TIME": "2001-09-09 01:01:41 000:000:000",
      "VALUE": 8101
    },
    {
      "NAME": "tag-1",
      "TIME": "2001-09-09 01:03:21 000:000:000",
      "VALUE": 8201
    },
    {
      "NAME": "tag-1",
      "TIME": "2001-09-09 01:05:01 000:000:000",
      "VALUE": 8301
    },
    {
      "NAME": "tag-1",
      "TIME": "2001-09-09 01:06:41 000:000:000",
      "VALUE": 8401
    },
    {
      "NAME": "tag-1",
      "TIME": "2001-09-09 01:08:21 000:000:000",
      "VALUE": 8501
    }
  ]
}

Request (Passing factors)
curl -X GET  "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/v1/datapoints/raw?Table=tag&TagNames=tag-1&Start=2001-09-09T00:00:00,000&End=2001-09-09T01:20:00,000&Direction=0&Count=5&Offset=0"
Response
{
  "error_code": 0,
  "error_message": "",
  "columns": [
    {
      "name": "NAME",
      "type": 5,
      "length": 20
    },
    {
      "name": "TIME",
      "type": 6,
      "length": 31
    },
    {
      "name": "VALUE",
      "type": 20,
      "length": 17
    }
  ],
  "timezone": "+0900",
  "data": [
    {
      "NAME": "tag-1",
      "TIME": "2001-09-09 01:00:01 000:000:000",
      "VALUE": 8001
    },
    {
      "NAME": "tag-1",
      "TIME": "2001-09-09 01:01:41 000:000:000",
      "VALUE": 8101
    },
    {
      "NAME": "tag-1",
      "TIME": "2001-09-09 01:03:21 000:000:000",
      "VALUE": 8201
    },
    {
      "NAME": "tag-1",
      "TIME": "2001-09-09 01:05:01 000:000:000",
      "VALUE": 8301
    },
    {
      "NAME": "tag-1",
      "TIME": "2001-09-09 01:06:41 000:000:000",
      "VALUE": 8401
    }
  ]
}
 
Request (When specifying multiple tags (tag-1, tag-2, tag-3))
curl -X GET  "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/v1/datapoints/raw/tag/tag-1,tag-2,tag-3/2001-09-09T00:00:00,000/2001-09-09T01:20:00,000/0/0/0";
Response
[
  {
    "NAME": "tag-1",
    "TIME": "2001-09-09 01:00:01 000:000:000",
    "VALUE": 8001
  },
  {
    "NAME": "tag-1",
    "TIME": "2001-09-09 01:01:41 000:000:000",
    "VALUE": 8101
  },
  {
    "NAME": "tag-2",
    "TIME": "2001-09-09 01:00:02 000:000:000",
    "VALUE": 8002
  },
  {
    "NAME": "tag-2",
    "TIME": "2001-09-09 01:01:42 000:000:000",
    "VALUE": 8102
  },
  {
    "NAME": "tag-3",
    "TIME": "2001-09-09 01:00:03 000:000:000",
    "VALUE": 8003
  },
  {
    "NAME": "tag-3",
    "TIME": "2001-09-09 01:01:43 000:000:000",
    "VALUE": 8103
  },
  {
    "NAME": "tag-3",
    "TIME": "2001-09-09 01:03:23 000:000:000",
    "VALUE": 8203
  } 
]

All Tag-based Raw Value Delete API

This API deletes all data prior to a specific time for all entered tags.

This function can be usefully used to remove data that is no longer needed after disk capacity is insufficient or backup is completed.

URL

http://ipaddr:port/machiot/datapoints/raw/{Table}/{BeforeTime}

http://ipaddr:port/machiot/v1/datapoints/raw/{Table}/{BeforeTime}

HTTP method : DELETE
Table : Target tag table to be deleted
BeforeTime : Indicates time value which all data before it will deleted

Usage

Code Block

language	js

Request
curl -X DELETE  "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/v1/datapoints/raw/tag/2001-09-09T01:20:00,000";
Response
{
  "error_code": 0,
  "error_message": "No Error",
  "timezone": "+0900",
  "effect_rows": "1201",
  "data": []
}

Specific Tag-based Raw Value deletion API

This API deletes all data prior to a specific time for a specific tag.

This function can be usefully used to remove data that is no longer needed after disk capacity is insufficient or backup is completed.

URL

http://ipaddr:port/machiot/datapoints/raw/{Table}/{TagNames}/{BeforeTime}

http://ipaddr:port/machiot/v1/datapoints/raw/{Table}/{TagNames}/{BeforeTime}

HTTP method : DELETE
Table : Target tag table to be deleted
TagNames : Target tag names to be deleted. You can specify multiple tags separated by a comma.
BeforeTime : Indicates time value which all data before it will deleted

Usage

Code Block

language	js

Request 
curl -X DELETE  "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/v1/datapoints/raw/tag/tag-2,tag-3/2001-09-09T01:20:00,000";
Response
{
  "error_code": 0,
  "error_message": "No Error",
  "timezone": "+0900",
  "effect_rows": "32",
  "data": []
}

Statistical data processing function

Statistical Data Select API

This API is a function that quickly obtains statistical results for stored data.

URL

http://ipaddr:port/machiot/datapoints/calculated/{Table}/{TagNames}/{Start}/{End}/{CalculationMode}/{Count}/{IntervalType}/{IntervalValue}

http://ipaddr:port/machiot/v1/datapoints/calculated/{Table}/{TagNames}/{Start}/{End}/{CalculationMode}/{Count}/{IntervalType}/{IntervalValue}

HTTP method : GET
Table : Target tag table to be selected
TagNames : Target tag names to be selected. You can specify multiple tags separated by a comma.
- If multiple tags are specified, the total operation result for those tags is output. (If you want to get statistical results for each tag, you have to call it tag by tag)
Start, End : Specify the time range in which data is to be obtained (Lookup Raw Value Select API)
Count : Number of result
CalculationMode : Target statistical function to be obtained. You can specify multiple statistical functions separated by a comma. (The function name must be the same as below)
- min : Minimum value
- max : Maximum value
- sum : Sum of values
- count : Count of values
- avg : Average of values
IntervalType : Desired time unit type of values
- sec : Per second
- min : Per minute
- hour : Per hour
IntervalValue : Desired time unit of IntervalType
- A value greater than 0 is specified as a minor number of 60.
- Mainly 5, 10, 15, and 30 are designated.

Usage

Code Block

language	js

Request (single statistical function)
curl -X GET  "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/v1/datapoints/calculated/tag/tag-1/2001-09-09T00:00:00,000/2001-09-09T01:20:00,000/sum/5/min/5"
Response
{
  "error_code": 0,
  "error_message": "",
  "columns": [
    {
      "name": "time",
      "type": 6,
      "length": 31
    },
    {
      "name": "sum",
      "type": 20,
      "length": 17
    }
  ],
  "timezone": "+0900",
  "data": [
    {
      "time": "2001-09-09 01:00:00 000:000:000",
      "sum": 24303
    },
    {
      "time": "2001-09-09 01:05:00 000:000:000",
      "sum": 25203
    },
    {
      "time": "2001-09-09 01:10:00 000:000:000",
      "sum": 26103
    },
    {
      "time": "2001-09-09 01:15:00 000:000:000",
      "sum": 27003
    },
    {
      "time": "2001-09-09 01:20:00 000:000:000",
      "sum": 9201
    }
  ]
}
Request (multiple statistical function)
curl -X GET  "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/v1/datapoints/calculated/tag/tag-1/2001-09-09T00:00:00,000/2001-09-09T01:20:00,000/sum,min,max/5/min/5"
{
  "error_code": 0,
  "error_message": "",
  "columns": [
    {
      "name": "time",
      "type": 6,
      "length": 31
    },
    {
      "name": "sum",
      "type": 20,
      "length": 17
    },
    {
      "name": "min",
      "type": 20,
      "length": 17
    },
    {
      "name": "max",
      "type": 20,
      "length": 17
    }
  ],
  "timezone": "+0900",
  "data": [
    {
      "time": "2001-09-09 01:00:00 000:000:000",
      "sum": 24303,
      "min": 8001,
      "max": 8201
    },
    {
      "time": "2001-09-09 01:05:00 000:000:000",
      "sum": 25203,
      "min": 8301,
      "max": 8501
    },
    {
      "time": "2001-09-09 01:10:00 000:000:000",
      "sum": 26103,
      "min": 8601,
      "max": 8801
    },
    {
      "time": "2001-09-09 01:15:00 000:000:000",
      "sum": 27003,
      "min": 8901,
      "max": 9101
    },
    {
      "time": "2001-09-09 01:20:00 000:000:000",
      "sum": 9201,
      "min": 9201,
      "max": 9201
    }
  ]
}

Tag metadata processing function

The schema of the table used in this section was created as follows.

Code Block

language	js

curl -X GET "http://127.0.0.1:${ITF_HTTP_PORT}/machbase" --data-urlencode 'q=create tagdata table TAG (name_multi varchar(20) primary key, time_multi datetime basetime, value_multi double summarized, value2_multi short, value3_multi varchar(10)) metadata (myshortmeta short, baseip ipv4);';

Tag Information INSERT API

This API is used to register tags to be used.

Enter data as many as the number of metadata columns added when creating a table with the Tag ID.

URL

http://ipaddr:port/machiot/tags/list/{TableName}

http://ipaddr:port/machiot/v1/tags/list/{TableName}

HTTP method : POST
TableName : Target tag table to be input.

Usage

Code Block

language	js

Request
curl -X POST -H "Content-Type: application/json" "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/tags/list/tag" -d
       '{
        "values":[
            ["tag3", 0, "127.0.0.0"],
            ["tag4", 1, "127.0.0.1"],
            ["tag4", 1, "127.0.0.1"],
            ["tag5", 2, "127.0.0.2"]
         ]
        }';
Response 
{
  "error_code": 0,
  "error_message": "No Error",
  "timezone": "+0900",
  "data": [],
  "append_success": 3,
  "append_failure": 1
}
#tag4의 중복 입력으로 에러 1건, 나머지 3건 성공

Tag Information SELECT API

URL

http://ipaddr:port/machiot/tags/list/{Table}/{TagName}

http://ipaddr:port/machiot/v1/tags/list/{Table}/{TagName}

HTTP method : GET
Table : Target tag table to be selected
- Print a list of all tag names if only table name is specified
TagName : Target tag name to be selected
- Print the tag details

Usage

Code Block

language	js

Request (select all tag names)
curl -X GET  "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/tags/list/tag"
Response 
{
  "error_code": 0,
  "error_message": "",
  "columns": [
    {
      "name": "name_multi",
      "type": 5,
      "length": 20
    }
  ],
  "timezone": "+0900",
  "data": [
    {
      "name_multi": "tag0"
    },
    {
      "name_multi": "tag1"
    },
    {
      "name_multi": "tag3"
    },
    {
      "name_multi": "tag4"
    },
    {
      "name_multi": "tag5"
    }
  ]
}

Tag Information UPDATE API

This API supports modification of additional tag information.

Both PUT and PATCH are supported, and the value of the JSON format used at the time of input must be the same as the column name of the table.

Since multiple column names are supported, values of two or more columns can be changed at once.

URL

http://ipaddr:port/machiot/tags/list/{Table}/{TagName}

http://ipaddr:port/machiot/v1/tags/list/{Table}/{TagName}

HTTP method : PUT / PATCH
Table : Target tag table to be updated
TagName : Target tag name to be updated

Usage

Code Block

language	js

Request (PUT)
curl -X PUT -H "Content-Type: application/json" "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/tags/list/tag/tag0" -d  '{"baseip":"192.168.0.1"}';
Response
{ 
   "error_code":0, 
   "error_message" :"No Error", 
   "timezone":"+0900", 
   "effect_rows":"1",
   "data":[]
}
 
Request (PATCH)
curl -X PATCH -H "Content-Type: application/json" "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/tags/list/tag/tag3" -d  '{"baseip":"255.255.255.0", "myshortmeta":9999 }';
Response
{ 
   "error_code":0, 
   "error_message" :"No Error", 
   "timezone":"+0900", 
   "effect_rows":"1",
   "data":[]
}

Tag Information DELETE API

This API deletes the specified tag. However, if raw data is present in the tag, deletion fails.

In order to delete a tag in which raw data exists, this function must be called after performing the deletion of raw data for that tag.

URL

http://ipaddr:port/machiot/tags/list/{Table}/{TagNames}

http://ipaddr:port/machiot/v1/tags/list/{Table}/{TagNames}

HTTP method : DELETE
Table: Target tag table to be deleted
TagName: Target tag name to be deleted

Usage

Code Block

language	js

Request (Try to delete tag with raw data)
curl -X DELETE -H "Content-Type: application/json" "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/tags/list/tag/tag0";
Response (Error)
{ 
   "error_code":2324, 
   "error_message" :"Cannot delete tagmeta. there exist data with deleted_tag key.", 
   "timezone":"+0900", 
   "data":[]
}


Request (Try to delete tag without raw data)
curl -X DELETE -H "Content-Type: application/json" "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/tags/list/tag/tag4";
Response (Success)
{ 
   "error_code":0, 
   "error_message" :"No Error", 
   "timezone":"+0900", 
   "effect_rows":"1", 
   "data":[]
}

Other function

Time range lookup API

This API obtains an overall time range (minimum and maximum) for data of the specified table and tag.

URL

http://ipaddr:port/machiot/tags/range/{Table}/{TagName}

http://ipaddr:port/machiot/v1/tags/range/{Table}/{TagName}

HTTP method : GET
Table : Target tag table to be selected
TagName : Target tag name to be selected
- If not specified, return the whole tag time range (the tag name will be returned to ALL).

Usage

Code Block

language	js

Request (Whole tag range)
curl -X GET  "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/tags/range/tag"
Response 
{
  "error_code": 0,
  "error_message": "",
  "columns": [
    {
      "name": "name",
      "type": 5,
      "length": 3
    },
    {
      "name": "min",
      "type": 6,
      "length": 31
    },
    {
      "name": "max",
      "type": 6,
      "length": 31
    }
  ],
  "timezone": "+0900",
  "data": [
    {
      "name": "ALL",
      "min": "2001-09-09 01:00:00 000:000:000",
      "max": "2032-09-09 10:46:49 000:000:000"
    }
  ]
}
 
Request (Specific tag name range)
curl -X GET  "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/tags/range/tag/tag-1"
Response 
{
  "error_code": 0,
  "error_message": "",
  "columns": [
    {
      "name": "name",
      "type": 5,
      "length": 20
    },
    {
      "name": "min",
      "type": 6,
      "length": 31
    },
    {
      "name": "max",
      "type": 6,
      "length": 31
    }
  ],
  "timezone": "+0900",
  "data": [
    {
      "name": "tag-1",
      "min": "2001-09-09 01:00:01 000:000:000",
      "max": "2001-09-21 12:31:41 000:000:000"
    }
  ]
}

Record count API

This API obtains the number of records present in the specified table or tag.

URL

http://ipaddr:port/machiot/tags/count/{Table}/{TagNames}

혹은

http://ipaddr:port/machiot/tags/cnt/{Table}/{TagNames}

http://ipaddr:port/machiot/v1/tags/count/{Table}/{TagNames}

혹은

http://ipaddr:port/machiot/v1/tags/cnt/{Table}/{TagNames}

HTTP method : GET
Table : Target tag table to be counted
TagName : Target tag name to be counted
- If not specified, output the total number of records in the table.

Usage

Code Block

language	js

Request (Total number of records in the table)
curl -X GET  "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/tags/count/tag"
Response 
{
  "error_code": 0,
  "error_message": "",
  "columns": [
    {
      "name": "count",
      "type": 12,
      "length": 20
    }
  ],
  "timezone": "+0900",
  "data": [
    {
      "count": 1000001
    }
  ]
}


Request (Total number of records of specified tag)
curl -X GET  "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/tags/count/tag/tag-1";
{
  "error_code": 0,
  "error_message": "",
  "columns": [
    {
      "name": "count",
      "type": 12,
      "length": 20
    }
  ],
  "timezone": "+0900",
  "data": [
    {
      "count": 10000
    }
  ]
}

Disk usage API

This API approximates the disk usage in use by the specified table or tag.

URL

http://ipaddr:port/machiot/tags/disksize/{Table}/{TagNames}

http://ipaddr:port/machiot/v1/tags/disksize/{Table}/{TagNames}

HTTP method : GET
Table : Target tag table to be measured
TagName : Target tag name to be measured
- If not specified, output the total disk usage for that table.

Usage

Code Block

language	js

Request (Total disk usage for table)
curl -X GET  "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/tags/disksize/tag/"
Response
{
  "error_code": 0,
  "error_message": "",
  "columns": [
    {
      "name": "disksize",
      "type": 12,
      "length": 20
    }
  ],
  "timezone": "+0900",
  "data": [
    {
      "disksize": 276904448
    }
  ]
}

Request (Total disk usage of specified tag)
curl -X  GET  "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/tags/disksize/tag/tag-1"
Response
{
  "error_code": 0,
  "error_message": "",
  "columns": [
    {
      "name": "disksize",
      "type": 12,
      "length": 20
    }
  ],
  "timezone": "+0900",
  "data": [
    {
      "disksize": 240000
    }
  ]
}

Rollup request API

This API requests compulsory execution for a specific rollup table. Through this, it is forced to calculate statistical values that have not yet been calculated.

If you call this API, you can wait for seconds to minutes depending on the situation, so you should use it carefully.

URL

http://ipaddr:port/machiot//rollup/{Table}

http://ipaddr:port/machiot/v1//rollup/{Table}

HTTP method : GET
Table : Target table to be execute rollup

Usage

Code Block

language	js

Request
curl -X HTTP GET  "http://127.0.0.1:${ITF_HTTP_PORT}/machiot/tags/rollup/tag"
Response 
{
  "error_code": 0,
  "error_message": "No Error",
  "timezone": "+0900",
  "data": []
}

Page Comparison

Versions Compared

Old Version 2

New Version Current

Key

RESTful API Overview

목차

Machbase 6.

RestAPI 지원 Machbase Edition

7 RestAPI

Machbase Edition support embedded web server

RestAPI 지원 Table 종류

Configuration 설정

버전별 .conf 파일의 위치

Edge / Fog 버전

Location of version-specific .conf files

Edge/Fog version

Cluster

version

Added properties for embedded web server

sample conf files

DDL / DML / Append

REST API Usage

Append Sample

Binary Append Sample

Using HTTP

Auth Property

출력 소수점 Scale 지정 (s 옵션)

Changing floating point precision with s option

Changing data Fetch

mode (m

option)

NULL 값의 처리

RestAPI for Tag Table Usage

Raw data processing function

Raw Value Append API

URL

Usage

Raw Value Select API

URL

Usage

All Tag-based Raw Value Delete API

URL

Usage

Specific Tag-based Raw Value deletion API

URL

Usage

Statistical data processing function

Statistical Data Select API

URL

Usage

Tag metadata processing function

Tag Information INSERT API

URL

Usage

Tag Information SELECT API

URL

Usage

Tag Information UPDATE API

URL

Usage

Tag Information DELETE API

URL

Usage

Other function

Time range lookup API

URL

Usage

Record count API

URL

Usage

Disk usage API

URL

Usage

Rollup request API

URL

Usage