RESTful API¶

Device API¶

เป็น API ที่เกี่ยวข้องกับ Device โดย Domain name ของ API คือ https://api.nexpie.io มีรายละเอียดดังนี้

1. การ Publish ข้อความ ไปที่ Topic ต่างๆ สามารถใช้งานได้ 2 แบบ

• แบบที่ 1 เป็นการระบุ Topic ในรูปแบบ URL Path

EndPoint:

https://api.nexpie.io/device/message/{any}/{topic}

Method:

PUT

Request Header:

Authorization : Device ClientID:Token

Request Body:

Content-type : text/plain

ข้อความที่ต้องการ Publish ไปที่ Topic

Return:

Response Object

• status => รหัสตอบกลับ (HTTP Response Code)

• message => ข้อความตอบกลับ

ตัวอย่าง:

PUT /device/message/mythings/bedroom/light HTTP/1.1

Host: api.nexpie.io

Authorization: Device 777d5c96-4c83-4aa6-a273-5ee7c5f453b1:abcduKh8r2tP1zVc1W1nG8YWZeu21234

ON

• แบบที่ 2 เป็นการระบุ Topic ผ่าน Parameter (Query String)

EndPoint:

https://api.nexpie.io/device/message

Method:

PUT

Request Header:

Authorization : Device ClientID:Token

Parameter:

topic :string คือ Topic ที่ต้องการ Publish ข้อความไปหา ({any}/{topic})

Return:

Response Object

• status => รหัสตอบกลับ (HTTP Response Code)

• message => ข้อความตอบกลับ

ตัวอย่าง:

PUT /device/message?topic=mything/bedroom/light HTTP/1.1

Host: api.nexpie.io

Authorization: Device 777d5c96-4c83-4aa6-a273-5ee7c5f453b1:abcduKh8r2tP1zVc1W1nG8YWZeu21234

OFF

2. การ Publish ข้อความส่วนตัว (Private Message) ไปยัง Device แบบเจาะจง Device สามารถใช้งานได้ 2 แบบ

• แบบที่ 1 เป็นการระบุ Topic ในรูปแบบ URL Path

EndPoint:

https://api.nexpie.io/device/private/{any}/{topic}

Method:

PUT

Request Header:

Authorization : Device ClientID ของ Device ที่ต้องการส่งข้อความไปหา:Token ของ Device ที่ต้องการส่งข้อความไปหา

Request Body:

Content-type : text/plain

ข้อความส่วนตัวที่ต้องการ Publish ไปยัง Device ที่ต้องการ ภายใต้ Topic ที่ระบุ

Return:

Response Object

• status => รหัสตอบกลับ (HTTP Response Code)

• message => ข้อความตอบกลับ

ตัวอย่าง:

PUT /device/private/topic/for/me HTTP/1.1

Host: api.nexpie.io

Authorization: Device 777d5c96-4c83-4aa6-a273-5ee7c5f453b1:abcduKh8r2tP1zVc1W1nG8YWZeu21234

Hello Device

• แบบที่ 2 เป็นการระบุ Topic ผ่าน Parameter (Query String)

EndPoint:

https://api.nexpie.io/device/private

Method:

PUT

Request Header:

Authorization : Device ClientID ของ Device ที่ต้องการส่งข้อความไปหา:Token ของ Device ที่ต้องการส่งข้อความไปหา

Parameter:

topic :string คือ Topic ที่ต้องการ Publish ข้อความส่วนตัวหา ({any}/{topic})

Return:

Response Object

• status => รหัสตอบกลับ (HTTP Response Code)

• message => ข้อความตอบกลับ

ตัวอย่าง:

PUT /device/private?topic=topic/for/me HTTP/1.1

Host: api.nexpie.io

Authorization: Device 777d5c96-4c83-4aa6-a273-5ee7c5f453b1:abcduKh8r2tP1zVc1W1nG8YWZeu21234

Hello Device

3. การอ่านข้อมูล Shadow Data ของ Device (ต้องเป็น Device ที่อยู่ใน Group เดียวกัน)

EndPoint:

https://api.nexpie.io/device/shadow/data

Method:

GET

Request Header:

Authorization : Device ClientID:Token

Parameter:

alias :string คือ ชื่อ Device (Device Alias) ของ Shadow ที่ต้องการอ่าน (ถ้าเป็นอ่าน Shadow ของตัวเองไม่ต้องส่ง Parameter นี้ไป)

Return:

Response Object

• status => รหัสตอบกลับ (HTTP Response Code)

• data => Shadow Data ของ Device (JSON)

ตัวอย่าง:

GET /device/shadow/data?alias=sensor HTTP/1.1

Host: api.nexpie.io

Authorization: Device 777d5c96-4c83-4aa6-a273-5ee7c5f453b1:abcduKh8r2tP1zVc1W1nG8YWZeu21234

4. การเขียนข้อมูลลง Shadow Data แบบเขียนผสาน (Merge)

EndPoint:

https://api.nexpie.io/device/shadow/data

Method:

PUT

Request Header:

Authorization : Device ClientID:Token

Parameter:

alias :string คือ ชื่อ Device (Device Alias) ของ Shadow ที่ต้องการเขียน (ถ้าเป็นเขียน Shadow ของตัวเองไม่ต้องส่ง Parameter นี้ไป)

Request Body:

ข้อมูลที่ต้องการเขียนลง Shadow Data อยู่ในรูปแบบ JSON ดังนี้ {data: {field name 1: value1, field name 2: value2, ..., field name n: value n}}

Return:

Response Object

• status => รหัสตอบกลับ (HTTP Response Code)

• data => ข้อมูลการอัพเดท Device Shadow Data (JSON)

ตัวอย่าง:

PUT /device/shadow/data?alias=test HTTP/1.1

Host: api.nexpie.io

Authorization: Device 777d5c96-4c83-4aa6-a273-5ee7c5f453b1:abcduKh8r2tP1zVc1W1nG8YWZeu21234

{data:{temperature:33.7, config: {item1: a, item2: b}, note: test case}}

5. การเขียนข้อมูลลง Shadow Data แบบเขียนทับ (Overwrite)

EndPoint:

https://api.nexpie.io/device/shadow/data

Method:

POST

Request Header:

Authorization : Device ClientID:Token

Parameter:

alias :string คือ ชื่อ Device (Device Alias) ของ Shadow ที่ต้องการเขียน (ถ้าเป็นเขียน Shadow ของตัวเองไม่ต้องส่ง Parameter นี้ไป)

Request Body:

ข้อมูลที่ต้องการเขียนลง Shadow Data อยู่ในรูปแบบ JSON ดังนี้ {data: {field name 1: value1, field name 2: value2, ..., field name n: value n}}

Return:

Response Object

• status => รหัสตอบกลับ (HTTP Response Code)

• data => ข้อมูลการอัพเดท Device Shadow Data (JSON)

ตัวอย่าง:

POST /device/shadow/data?alias=test HTTP/1.1

Host: api.nexpie.io

Authorization: Device 777d5c96-4c83-4aa6-a273-5ee7c5f453b1:abcduKh8r2tP1zVc1W1nG8YWZeu21234

{data:{temperature:33.7, config: {item1: a, item2: b}, note: test case}}

Shadow Batch Update¶

จะใช้ในกรณีที่ IoT Device ไม่สามารถส่งข้อมูลขึ้น Cloud Platform ได้ตามเวลาที่กำหนด เช่น อาจจะเกิดจากปัญหาการเชื่อมต่ออินเตอร์เน็ต เป็นต้น ทำให้ IoT Device จำเป็นต้องเก็บข้อมูลไว้ที่หน่วยความจำของ Device เองก่อน เช่น เก็บลง SD Card เป็นต้น และเมื่อสามารถเชื่อมต่อ Cloud Platform ได้ จึงทำการส่งข้อมูลที่เก็บไว้ทั้งหมดขึ้น Cloud Platform อีกที โดยสามารถส่งค่าขึ้น Platform ครั้งละหลาย ๆ จุดพร้อมกันได้

การเขียน Shadow แบบ Batch ทำได้ 3 ช่องทาง ได้แก่

1. REST API คือ การเขียนข้อมูลเป็น Batch โดยดำเนินการผ่าน REST API ซึ่งสามารถเขียนได้ทั้งแบบผสาน (Merge) หรือเขียนทับ (Overwrite) มีรายละเอียดดังนี้

EndPoint:

https://api.nexpie.io/device/shadow/batch

Method:

PUT (กรณี Merge) หรือ POST (กรณี Overwrite)

Request Header:

Authorization : Device ClientID:Token

Request Body:

ชุดข้อมูลที่ต้องการเขียนลง Shadow อยู่ในรูปแบบ JSON ดังนี้

{"batch" : [{"data":{ Shadow Data 1 }, "ts": time 1}, {"data":{ Shadow Data 2 }, "ts": time 2}, ..., {"data":{ Shadow Data n }, "ts": time n}], "merged": true or false}

Return:

Response Object

• deviceid => ClientID ของ Device ที่ถูกเขียน Shadow

• response => สรุปข้อมูลการอัพเดท Shadow (JSON)

ตัวอย่าง:

POST /device/shadow/batch HTTP/1.1

Host: api.nexpie.io

Authorization: Device 777d5c96-4c83-4aa6-a273-5ee7c5f453b1:abcduKh8r2tP1zVc1W1nG8YWZeu21234

{ "batch" : [ {"data":{"temp":25.9, "humid":9.6}, "ts":-90000}, {"data":{"temp":25.3, "humid":9.8}, "ts":-60000}, {"data":{"temp":24.5, "humid":9.1}, "ts":-30000}, {"data":{"temp":26.8, "humid":8.2}, "ts":0 }}

2. MQTT คือ การเขียนข้อมูลเป็น Batch จะใช้ Topic และ Payload ดูรายละเอียดได้ที่ Shadow Batch Update

3. CoAP API คือ การเขียนข้อมูลเป็น Batch โดยดำเนินการผ่าน CoAP Protocol ซึ่งสามารถเขียนได้ทั้งแบบผสาน (Merge) หรือเขียนทับ (Overwrite) เช่นกัน ดูรายละเอียดได้ที่ Shadow Batch Update

Data Store API¶

เป็น API ที่เกี่ยวข้องกับการดึงข้อมูลที่เก็บอยู่ใน Timeseries Data โดย Domain name ของ API คือ https://ds.nexpie.io/feed ฐานข้อมูลที่ใช้เก็บ คือ ซึ่งใช้ KairosDB ลักษณะการ Query ข้อมูล Parameter ต่างๆ ที่ส่งไปจะเป็นรูปแบบเดียวกับ KairosDB มีรายละเอียดดังนี้

EndPoint:

https://ds.nexpie.io/feed/api/v1/datapoints/query

Method:

POST

Request Header:

Authorization : Device ClientID:Token

Content-Type : application/json

Request Body:

เงื่อนไขที่ใช้ในการ Query อยู่ในรูปแบบ JSON สามารถแยกได้เป็น 2 ประเภท คือ

1. Query Properties ประกอบด้วย

• start_absolute => เวลาเริ่มที่มีหน่วยเป็นมิลลิวินาที(milliseconds)

• start_relative => เวลาเริ่มที่สัมพันธ์กับเวลาปัจจุบัน โดยนำเวลาปัจจุบันลบด้วยเวลาที่ระบุ ซึ่งระบุเป็นจำนวนและหน่วยของเวลา หน่วยที่เป็นไปได้มี ดังนี้ milliseconds, seconds, minutes, hours, days, weeks, months และ years ตัวอย่างเช่น หากเวลาเริ่มต้นคือ 5 นาที จุดข้อมูลที่ถูกส่งกลับมาจะอยู่ในช่วง 5 นาทีที่ผ่านมา

• end_absolute => เวลาสิ้นสุดที่มีหน่วยเป็นมิลลิวินาที(milliseconds) และต้องเป็นเวลาที่มีค่ามากกว่า start_absolute

• end_relative => ระบุเวลาสิ้นสุดที่สัมพันธ์กับเวลาปัจจุบัน โดยนำเวลาปัจจุบันลบด้วยเวลาที่ระบุ ซึ่งระบุเป็นจำนวนและหน่วยของเวลา หน่วยที่เป็นไปได้มี ดังนี้ milliseconds, seconds, minutes, hours, days, weeks, months และ years ตัวอย่างเช่น หากเวลาเริ่มต้นคือ 30 นาทีและเวลาสิ้นสุดคือ 10 นาที จุดข้อมูลที่ถูกส่งกลับมาจะอยู่ระหว่าง 30 นาทีล่าสุดจนถึง 10 นาทีสุดท้าย หากไม่ได้ระบุเวลาสิ้นสุดจะถือว่าเป็นวันที่และเวลาปัจจุบัน

• time_zone => เขตเวลาสำหรับช่วงเวลาของการ Query ข้อมูล หากไม่ได้ระบุจะใช้ UTC (สำหรับ time_zone ที่ NEXPIE Platform กำหนดให้จะเป็น GMT)

** หมายเหตุ ** : start_absolute และ start_relative จำเป็นต้องระบุค่า แต่เลือกใช้เพียงค่าใดค่าหนึ่งเท่านั้น ส่วน end_absolute และ end_relative จะระบุหรือไม่ก็ได้ ถ้าระบุก็เลือกใช้เพียงค่าใดค่าหนึ่งเช่นเดียวกัน

2. Metric Properties ประกอบด้วย

• name => ชื่อของ Metric ที่ต้องการ Query ข้อมูล ให้ระบุเป็น DeviceId (Client ID ของ Device) จาก NEXPIE Platform (ต้องระบุ)

• aggregators => Array ของการตั้งค่าการรวมหรือประมวลผลข้อมูลในรูปแบบต่างๆ ก่อนส่งจุดข้อมูลกลับมา ซึ่ง Parameters ที่เกี่ยวข้องมีดังนี้

  • name => ประเภทรูปแบบการประมวลผลข้อมูล ได้แก่ "avg" (Average), "dev" (Standard Deviation), "count", "first", "gaps", "histogram", "last", "least_squares", "max", "min", "percentile", "sum", "diff" (Difference), "div" (Divide), "rate", "sampler", "scale", "trim", "save_as", "filter", "js_function" (JS Aggregator), "js_filter" (JS Aggregator), "js_range" (JS Aggregator) ดูรายละเอียดเพิ่มเติมจาก kairosdb

• tags => สำหรับกรองข้อมูลที่ต้องการตาม Tag ใน NEXPIE Platform ระบุ Data Field ที่ต้องการ รูปแบบ คือ tags : { attr: [ field_1, field_2, ..., field_n ] }

• group_by => จัดกลุ่มจุดข้อมูลที่ Query โดยสามารถจัดตาม Tag, ช่วงเวลา, ค่าจุดข้อมูล หรือตามถังข้อมูล ใน NEXPIE Platform ใช้ Tag ในการจัดกลุ่มข้อมูล (แยกตาม Data Field)

• exclude_tags => จะให้แสดง Tag ในข้อมูลที่ส่งกลับมาด้วยหรือไม่ (true คือ แสดง Tag เป็นค่า Default, false คือ ไม่แสดง Tag)

• limit => เป็นการจำกัดจำนวนจุดข้อมูลที่จะ Query โดยจะเป็นการจำกัดจำนวนจุดข้อมูลจริงก่อนจะทำ aggregators

• order => การเรียงลำดับจุดข้อมูล (asc คือ เรียงจากน้อยไปมาก, desc คือ เรียงจากมากไปน้อย) โดยจะเรียงลำดับจุดข้อมูลจริงก่อนจะทำ aggregators

Return:

Response Object

ดึงข้อมูลสำเร็จ (status : 200)

ข้อมูลที่ Query ได้อยู่ในรูปแบบ JSON

ดึงข้อมูลล้มเหลว (status : 400 หรือ 500)

• 400 Bad Request => คำขอไม่ถูกต้อง เช่น ส่ง Parameter ไม่ครบหรือไม่ถูกต้อง

• 500 Internal Server Error => หากเกิดข้อผิดพลาดในการเรียกข้อมูลทางฝั่ง Server

ตัวอย่าง:

POST /api/v1/datapoints/query HTTP/1.1

Host: ds.nexpie.io/feed

Authorization: Device d560fbd3-aaaa-1234-9b90-1a3d94df4f81:PPWFpBR5vMMWrmAUc1x5tGSppbHsMCUv

Content-Type: application/json

{ "start_relative": { "value":1, "unit":"days" }, "metrics":[{ "name":"d560fbd3-aaaa-1234-9b90-1a3d94df4f81", "tags":{"attr":["temp", "humit"]}, "limit":50, "group_by":[{ "name":"tag", "tags":["attr"] }], "aggregators":[{ "name":"avg", "sampling":{ "value":"1", "unit":"minutes" } }] }] }