OmniThings API 使用文件

TSDBase 服務介紹

TSDBase(Time Series Database) API 提供 POST 方法,以 Json 格式的內容儲存與讀取資料,透過 OmniThings 服務可自定 schema,並賦予不同 SID 於不同 schema 之個別存取權限,提供軟體開發者一個能夠自由定義資料結構 ,可靠並具低延遲及高擴充性的儲存平台。


專有名詞

SID

每個應用在 ASUSCloud Platform 都需要有一個獨立的 SID(Security ID),每一個 SID 會對應到一把 Program Key。

Attribute

為 TSDBase 最小單元,可有不同資料型態。

Entry

為 attribute 的集合,attribute name 不可重複。

Key Schema

描述 entry 唯一值是由哪些 attribute 組成,具有順序性,建議第一項 attribute 之資料型態為 DateTime,可加速查詢速度。

Schema

描述 entry 的attribute 組成 ,組成內需包含 key schema。當進行資料查詢時,必須送出至少一項 key schema 內的 attribute 為查詢條件。

Service

每個用戶在系統內專屬的資料集代號,若將 Service 比喻為系統配發的資料庫,而 Schema 則為用戶於資料庫內建立的資料表。


認證

TSDBase API 呼叫,需於產生 Authorization 字串,於 header 內送出,以驗證 SID 是否擁有存取權限。

組成說明

參數說明
signature_method字串 "HMAC-SHA1"
nonce亂數字串,應用產生,並帶入 signature
timestamp長整數(long),應用產生,並帶入 signature
signature
  • 將 nonce, signature_method, timestamp 組為下列字串
    nonce=3JERMeEJAM72GPN5RVWq&signature_method=HMAC-SHA1&timestamp=1455615083120
  • 進行 url encode
  • 以 SID 對應的 Program key 進行 HMAC-SHA1

範例

nonce="uX5ggmuo61YMhMYVgyDk",signature_method="HMAC-SHA1",timestamp="1454139872740",signature="MIn%2BzkKTqXuDWrQ3zqat53WaYOc%3D"

HMAC-SHA1 Implements

Java  JavaScript  .NET Framework  Python

Sample Code

Java  JavaScript  C# 

API

資料型態

型態說明
DateTime 時間字串,格式 yyyy-MM-dd HH:mm:ss
HASH 數值字串,僅允許作為 KEY 使用
RANGE 有限長度字串,僅允許作為 KEY 使用
Number 數值字串,僅允許作為 Attribute 使用
String 有限長度字串
Boolean 布林值,true|false,僅允許作為 Attribute 使用
Integer 4bytes 整數,範圍 -2147483648 ~ 2147483647
Unsigned Integer 4bytes 無號整數,範圍 0 ~ 2147483647
Long 長整數,範圍 -9223372036854775807 ~ 9223372036854775807
Unsigned Long 8bytes 無號長整數,範圍 0 ~ 9223372036854775807
Double 浮點數,範圍 -1.7976931348623158E+308 ~ 1.7976931348623158+308,僅允許作為 Attribute 使用
Unsigned Double 無號浮點數,範圍 0 ~ 1.7976931348623158E+308,僅允許作為 Attribute 使用

How to Use?

TSDBase 提供 http/https 呼叫API,呼叫方式: https://hsinchu.omnithings.io/tsdbase/entry,由 request header X-Omni-Action 指定操作動作。

使用流程:

  • 透過 X-Omni-Action: PutEntries 存放資料。
  • 透過 X-Omni-Action: Query 讀取資料。


API Request Header

名稱必要性說明
X-Omni-SidYESOmiStor Security ID
AuthorizationYES驗證 SID 是否合法,產生過程需與帶入 SID 匹配
X-Omni-ActionYES欲執行的動作
X-Omni-ServiceYESService Name
X-Forwarded-ForLog Option提供 Logger 紀錄操作 IP,若是未帶入則使用 remote IP
X-Omni-CVLog Option提供 Logger 記錄 Client Version
X-Omni-OVLog Option提供 Logger 記錄 OS version
X-Omni-CTLog Option提供 Logger 記錄 Client Type
X-Omni-Req-EncodingOptionalgzip: 宣告 request payload 使用 gzip 壓縮
X-Omni-Resp-EncodingOptionalgzip: 要求 response payload 使用 gzip 壓縮
X-Omni-EncodingOptionalgzip: 指定 request 及 response payload 皆使用 gzip 壓縮
OriginOptionalCORS 呼叫時,傳入呼叫方 domain

API Response Header

名稱必要性說明
X-Omni-RequestIdYES該次 API 呼叫所對應之 UUID
X-Omni-StatusYES執行狀態
X-Omni-Status-MessageYES執行狀態說明
X-Omni-MessageOptional當有發生錯時會回傳錯誤說明
Content-EncodingOptionalgzip: response payload 使用 gzip 壓縮時傳回
X-Content-Type-OptionsOptionalnosniff: 當為 CORS 時傳回
Access-Control-Allow-CredentialsOptionalrue: 當 CORS 時傳回
Access-Control-Allow-MethodsOptionalOPTIONS, HEAD, GET, POST, PUT: 當 CORS 時傳回
Access-Control-Expose-HeadersOptionalStatus, X-Omni-RequestId, X-Omni-Status, X-Omni-Status-Message, X-Omni-Message, Content-Encoding: 當 CORS 時傳回
Access-Control-Allow-OriginOptional*: 當 CORS 時傳回

Query Operator

Query Operator 用於 keyconditions ,可定義每一個 condition 查詢條件。

運算條件說明值域型態
=等於,型態需與設定欄位相同單一值
BETWEEN範圍查詢,包含前後值,型態需與設定欄位相同LIST,size 為 2
<>不等於,同部分 SQL 版本支援之 !=單一值
>大於,型態需與設定欄位相同單一值
<小於,型態需與設定欄位相同單一值
>=不小於(大於或等於),型態需與設定欄位相同單一值
<=不大於(小於或等於),型態需與設定欄位相同單一值
LIKE查詢某種 pattern,需用 % 至於前或後或是同時單一值
IN查詢內容於列表內List (1至多個)
NOT IN查詢內容不在列表內List (1至多個)
範例
{
"schemaname": "schema_template",
"keyconditions" : [ [ "time", "BETWEEN", [ "2016-02-23 14:15:17", "2016-02-23 14:15:18" ] ], [ "name", "=", "tsdBtestAccount" ], [ "status", "IN", ["OPEN","INIT"], [ "alias", "<>", " "]  ] ]
}


PutEntries Action

  • PutEntries Action 是用以置放一筆至多筆資料(entries)。
  • 無論一筆資料或是多筆資料,TSDBase 處理時間之差異甚微,因此建議善加利用 batch 方式上傳資料。

Request
POST / HTTP/1.1
X-Omni-Sid: {SID}
X-Omni-Action: PutEntries
X-Omni-Service: {Service Name}
Authorization: {Authorization String}
					
{
"schemaname": "schema_template",
"entries": [{"number":"123","ulong":9223372036854775807,"deleted":true,"test":"2017-11-09 10:10:26","uinteger":2147483647,"double":-1.7976931348623157,"udouble":1.7976931348623157,"integer":-2147483648,"time":"2017-11-09 10:10:26","value":"abc123","long":-9223372036854775807}] 
 }
Response
HTTP/1.1 200 
X-Omni-RequestId:826c8c47b4765eb2b7abb8b553a5a13d 
X-Omni-Status:0
X-Omni-Status-Message:SUCCESS

{}

Query Action

  • 用來查詢 schema entries 資料,需透過 keyconditions 指定查詢條件(condition),condition 包含了 attribute name 與 query operator 與 query value,例如:[attrubute_name, query_operator,query_value]
    對於條件格式的進一步說明,請參考 Query Operator 單元。
  • 查詢時可利用 query_attributes 來過濾查詢得出的欄位,透過減量來降低資料傳輸時間。
  • 如資料筆數過多影響了查詢效率,可使用 limit 來限制資料筆數。
  • 基本查詢: 查詢 key 值,以 query operator = 指定要某一 attribute (通常為 deviceid, asusaccount 或是 userid),或以 query operator BETWEEN 指定查詢時間範圍。
  • [小提示] 若查詢結果之資料量過大而導致了 timeout,請延長客戶端 timeout 設定,TSDBase 不會因資料量過大而放棄回應。
  • [小叮嚀] 請勿使用 TSDBase API 設計 heartbeat Query 功能,如觸發系統防禦機制,將會導致 SID 被鎖定之後停權。

Request
POST / HTTP/1.1
X-Omni-Sid: {SID}
X-Omni-Action: Query
X-Omni-Service: {Service Name}
Authorization: {Authorization String}

{
  "schemaname": "test",
   "limit" : 100,
   "query_attributes" : ["deleted","time","integer","uinteger","long","ulong","double","udouble","number"],
   "keyconditions" : [["time","BETWEEN",["2016-10-01 00:00:00","2017-11-09 10:34:26"]]]
}
Response
HTTP/1.1 200 
X-Omni-RequestId: 961da734cef9dd53856b308c083e1a21 
X-Omni-Status: 0
X-Omni-Status-Message: SUCCESS

{
  "schemaname": "test",
  "entries": [{"number":"123","ulong":9223372036854775807,"deleted":true,"uinteger":2147483647,"double":-1.7976931348623157,"udouble":1.7976931348623157,"integer":-2147483648,",time":"2017-11-09 10:10:26","long":-9223372036854775807}]
}

API Utilities

Java 

Status Code

Status CodeDescription
0Success
2Authentication Fail
5Authorization Fail
6Encoding Not Support
201AUTH Input Data FAIL
280AUTH Unauthorized
281scope privilege violation on destination
282scope privilege violation on source
283client id not match original request
300Stream Exception
301Xml Stream Exception
302JSON Stream Exception
310Required Field Validator Exception
311Field Format Exception
312Empty Input Exception
313ServiceName Validation Exception
314SchemaName Validation Exception
315AttributeName Validation Exception
316AttributeType NOT SET Exception
317AttributeType Validation Exception
318SucKey Is Duplicatecess
319Attribute Is Duplicate
320SID Is Duplicate
350X Omni Action NOT SET
351X Omni Service NOT SET
352Schemaname NOT SET
353Schema Sids NOT SET
354SidControl SID NOT SET
355SidControl Role NOT SET
356SidControl SID NOT VALIDATE
357Schema Key Schema NOT SET
358Schema Key Schema Size NOT Allow
359Schema Key Schema Setting NOT Allow
360Schema Key Schema Range NOT Allow
361Schema Key Schema S NOT Allow
370Query Condition Format Exception
371Query Conditionin Is Duplicate
372Query Conditionin Is Not Setting In Schema
373Query Conditionin ASUSACCOUNT Is Duplicate
374Query Conditionin ASUSACCOUNT Operator Is Not Validate
375Query Conditionin Input Is Not Validate
376Query Conditionin Not Include Any Key
391Query Attributes Is not Validate
392Query Return Is not Validate
393Query NumberFormatException
394Query Funcs Is not Validate
395Query Funcs Format Exception
396Query Funcs Column Is not Validate
397Query Limit not Validate
404Schema Not Found
405SCHEMA ACTION NOT SUPPORT
410SERVICE NOT EXIST
411X Omni Action NOT SUPPORT
440Table Not Found
501SID NOT Authorize
502SID CHECK ACL FAIL
600SERVICE ISEXISTED
601SCHEMA ISEXISTED
700ADVANCEDQUERY NOTSUPPORT
701Advanced Query Not Support Change Schema
900System Error
901Need Retry Error
980System TimeOut
999A general error