7.4.6. RESTful API
RESTful APIの使用を開始するにはトークンを生成する必要があります。
このトークンはGETまたはPOSTメソッドに含める必要があります。表7-7はRESTful APIの詳細です。
REST APIには以下の制限事項があります。
- HTTPリクエストのボディサイズは100KB以下
- HTTPリクエストのタイムアウトは10秒
表7-7 RESTful API
| REST API | HTTPメソッド | 説明 | ||
|---|---|---|---|---|
| /api/user/get/api_token | GET | RESTful APIトークンを取得します。 指定可能なパラメーター: p LoRaWAN®サーバーのパスワード 例: GET /api/user/get/api_token?p=xxxx
このAPIはREST APIのトークンを取得するために使用されます。 APIトークンを取得するには、HTTP GETメソッドのクエリパラメータとしてパスワード「p」を渡す必要があります。 | ||
| /api/user/generate/api_token | GET | RESTFul APIトークンを再生成します。 指定可能なパラメーター： p LoRaWAN®サーバーのパスワード 例: GET /api/user/get/api_token?p=xxxx このAPIはREST APIのトークンを再生成するために使用されます。 APIトークンを取得するにはHTTP PostメソッドのPOST BODY内にパスワード「p」が必要です。
| ||
| /api/device/uplink | GET | 指定した時間範囲でデバイスのアップリンクデータを取得します。 指定可能なパラメーター: start データレコードをスキップする番号。 length 返されるデータレコードの最大数。 deveui アップリンクデータを取得するデバイスを指定します。 ftime アップリンクデータレコードをフィルタリングする時間範囲の開始時間。 ttime アップリンクデータレコードをフィルタリングする時間範囲の終了時間。 | ||
| /api/device/downlink | POST | ダウンリンクデータを送信してデバイスを指定します。
Content-Type: aplication/x-www-form-urlencoded
指定可能なパラメーター: deveui ダウンリンクを送信するデバイスのDevice EUI。 port ダウンリンクを送信するデバイスのポート番号。 data 16進数のダウンリンクデータ。このフィールドはbase64を受け入れません。 txpower ダウンリンクの送信電力(txpower)。値の範囲は1〜20です。 | ||
/api/device/downlink/list | GET | 指定したデバイスのダウンリンクキューを取得します。
deveui ダウンリンクの一覧を取得するデバイスのDevice EUI。 index キュー内のダウンリンクを一つだけ指定する場合のインデックス。 | ||
/api/device/downlink/delete | POST | 指定したデバイスのダウンリンクキューを削除します。
Content-Type: aplication/x-www-form-urlencoded
deveui ダウンリンクを削除するデバイスのDevice EUI。 index キュー内のダウンリンクを一つだけ削除する場合のインデックス。 | ||
/api/device/downlink/alldelete | POST | 全デバイスのダウンリンクキューを削除します。 | ||
/api/device/list | GET | デバイスリストを取得します。
start スキップするデバイスの数。 length 取得するデバイスの最大数。 deveui 検索するデバイスの正規表現文字列。 | ||
| /api/device/create | POST | デバイスを作成します。 指定可能なパラメーター: deveui Device EUIの8バイトの16進数。 devaddr Device Addressの4バイトの16進数。 activate アクティベーション方法: abpまたはotaa。 lorawan_class LoRaWAN®クラス: AかC appeui Application EUIの8バイトの16進数。 appkey Application Keyの16バイトの秘密鍵。 appskey Application Session Keyの16バイトの秘密鍵。 nwkskey Network Session Keyの16バイトの秘密鍵。 devname オプションのフィールド。作成されたデバイスの名前。 appid オプションのフィールド。作成されたデバイスのアプリケーションタイプ。 lorawan、sensor、tracker、las_sensor、airq_sensor、smoke_sensor、watermeter、gba_sensor light_sensor、parking_sensor、ble_sensor、netvox_r311a、netvox_rb11eです。 rx_window オプションのフィールド。デバイスの有効なRXウィンドウです。 「rx1」「rx2」「both」のいずれかです。 値が「rx1」「x2」「both」と等しくない場合、「rx1」を指定したことになります。 rx2_freq オプションのフィールド。デバイスのMhz単位のRX2ウィンドウ周波数です。 rx_windowが「rx2」「both」に等しい場合のみ有効になります。 この値が割り当てられていない場合、システムは選択されたchannel_planに従って適切なrx2_freqを選択します。 rx2_dr オプションのフィールド。デバイスのRX2ウィンドウDataRate。 サポートされるデータレートには、「DR0」「DR1」「DR2」「DR3」「DR4」「DR5」が含まれます。 この値が割り当てられていない場合、システムは選択されたchannel_planに従って適切なrx2_drを選択します。 relax オプションのフィールド。 「true」はリラックスカウンターチェックを有効にし、「false」は無効にします。 値が「true」でも「false」でもない場合、「true」を選択したことになります。 relax_counter_length オプションのフィールド。 リラックスカウンターの長さ。 32または16で、relaxフィールドが有効（relax = true）になっている場合のみアクティブになります。 値が32または16に等しくない場合、自動的に32に調整されます。 channel_plan オプションのフィールド。 デバイスのチャネルプラン。 現在サポートされているチャネルプランは次のとおりです。 EU863-870 チャネルプランが上記のオプションと等しくない場合、「AS923」が選択されたことになります。 enable_adr オプションのフィールド。「true」はデバイスADRを有効にし、「false」は無効にします。 値が「true」でも「false」でもない場合、「true」が選択されたことになります。 cflist オプションのフィールド。デバイスのJoinAccepet CFList ID。 CFListはデバイスの作成後に作成できます。 | ||
/api/device/multicreate | POST | 同時に複数のデバイスを作成します。
Content-Type: application/json
/api/device/createと同じデバイスのJSON配列 例: [{"deveui": "000b78fffe01249b", "devaddr": "fe01249b", "activate": "otaa", "lorawan_class": "A", "appeui": "abf7158809cf4f3c", "appkey": "2b7e151628aed2a6abf7158809cf4f3c"}] | ||
| /api/device/delete | POST | デバイスを削除します。 deveui Device EUIの8バイトの16進数。 | ||
/api/device/multidelete | POST | 同時に複数のデバイスを削除します。 Conten-Type: application/json
deveuiのJSON配列。Device EUIは8バイトの16進数。 例: ["000b78fffe01249b"] | ||
/api/device/alldelte | POST | 同時に全デバイスを削除します。 | ||
| /api/cflist/list | GET | CFlistを取得します。 このAPIはCFList情報を取得するために使用されます。 LoRaWAN®サーバーからデバイスメタデータをプルバックするために、APIトークンをHTTP GETメソッドのクエリパラメーターとして渡す必要があります。 応答はJSONオブジェクトです。 TYPE、COUNT、LISTの3つの項目があり、TYPEは「cflist」である必要があります。 COUNTはCFList内のアイテムの数です。LISTはcflist内のアイテムのIDによる昇順です。 指定可能なパラメーター: start 応答の開始点。 length CFListの返される最大数。 | ||
| /api/cflist/create | POST | CFListを作成します。
Conten-Type: aplication/x-www-form-urlencoded 指定可能なパラメーター: id CFList ID name CFList Name freq1 Mhz単位のCFListの「Frequency 1」 freq2 Mhz単位のCFListの「Frequency 2」 freq3 Mhz単位のCFListの「Frequency 3」 freq4 Mhz単位のCFListの「Frequency 4」 freq5 Mhz単位のCFListの「Frequency 5」 | ||
| /api/cflist/delete | POST | CFListを削除します。
Conten-Type: aplication/x-www-form-urlencoded
指定可能なパラメーター: id CFList ID | ||
| /api/post/list | GET | HTTP POST URLリストを取得します。 | ||
| /api/post/update | POST | HTTP POST URLリストを更新します。
Conten-Type: aplication/x-www-form-urlencoded
posts POST URLを記述するJSONオブジェクトを含むJSON配列。 clearall すべてのPOST URLをクリアする場合は、clearallを1に設定します。 |
表7-8は各REST APIのcURL入力例です。
表7-8 REST APIリクエスト
REST API | cURL入力例 |
|---|---|
/api/user/get/api_token | curl http://192.168.0.111:8080/api/user/get/api_token --get \ |
/api/user/generate/api_token | curl http://192.168.0.111:8080/api/user/get/api_token \ |
/api/device/uplink | curl http://192.168.0.111:8080/api/device/uplink --get \ --data-urlencode "token=2102372cfe4f0eee93444bc1fae38d7a" \ --data-urlencode "deveui=000b78fffe050a7a" |
/api/device/downlink | curl http://192.168.0.111:8080/api/device/downlink \ --data-urlencode "token=2102372cfe4f0eee93444bc1fae38d7a" \ --data-urlencode "deveui=000b78fffe050a7a" \ --data-urlencode "port=15" \ --data-urlencode "data=6432" |
/api/device/downlink/delete | curl http://192.168.0.111:8080/api/device/downlink/delete \ --data-urlencode "token=2102372cfe4f0eee93444bc1fae38d7a" \ --data-urlencode "deveui=000b78fffe050a7a" |
/api/device/list | curl http://192.168.0.111:8080/api/device/list --get \ --data-urlencode "token=2102372cfe4f0eee93444bc1fae38d7a" |
/api/device/multicreate | curl http://192.168.0.111:8080/api/device/multicreate\ ?token=2102372cfe4f0eee93444bc1fae38d7a \ --header 'Content-Type:application/json' \ --data @- <<EOF [{ "deveui": "000b78fffe01249b", "devaddr": "fe01249b", "activate": "otaa", "lorawan_class": "A", "appeui": "abf7158809cf4f3c", "appkey": "2b7e151628aed2a6abf7158809cf4f3c" }] EOF |
/api/device/delete | curl http://192.168.0.111:8080/api/device/delete \ --data-urlencode "token=2102372cfe4f0eee93444bc1fae38d7a" \ --data-urlencode "deveui=000b78fffe050a7a" |
/api/device/multidelete | curl http://192.168.0.111:8080/api/device/multidelete\ --header 'Content-Type: application/json' \ --data '["000b78fffe01249b"]' |
/api/device/create | curl http://192.168.0.111:8080/api/device/create \ --data-urlencode "token=2102372cfe4f0eee93444bc1fae38d7a" \ --data-urlencode "deveui=000b78fffe050a7a" \ --data-urlencode "devaddr=fe050a7a" \ --data-urlencode "activate=abp" \ --data-urlencode "lorawan_class=A" \ --data-urlencode "appskey=2b7e151628aeda6abf7158809cf4f3c" \ --data-urlencode "nwskey=2b7e151628aeda6abf7158809cf4f3c" |
/api/device/alldelte | curl -X POST http://192.168.0.111:8080/api/device/alldelete\ |
/api/cflist/list | curl http://192.168.0.111:8080/api/cflist/list --get \ --data-urlencode "token=2102372cfe4f0eee93444bc1fae38d7a" |
/api/cflist/create | curl http://192.168.0.111:8080/api/cflist/create \ --data-urlencode "token=2102372cfe4f0eee93444bc1fae38d7a" \ --data-urlencode "id=TestCFList" \ --data-urlencode "name=Test CF List" \ --data-urlencode "freq1=920.1" \ --data-urlencode "freq2=920.5" \ --data-urlencode "freq3=920.7" \ --data-urlencode "freq4=920.9" \ --data-urlencode "freq5=921.1" |
/api/cflist/delete | curl http://192.168.0.111:8080/api/cflist/delete \ --data-urlencode "token=2102372cfe4f0eee93444bc1fae38d7a" \ --data-urlencode "id=TestCFList" |
/api/post/list | curl http://192.168.0.111:8080/api/post/list\ |
/api/post/update | curl http://192.168.0.111:8080/api/post/update --data @- <<EOF token=2102372cfe4f0eee93444bc1fae38d7a&posts=[{"url":"http://10.42.43.1:8080/test","id":"lorawan","authorization":"","customization":""}] EOF |
リスト7-2とリスト7-3は、RESTful APIをGo言語から使用する例です。それぞれアップリンクデータの取得とデバイスの作成を行います。
リスト7-2 アップリンクデータを取得するGoの例
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
resp,_ := http.Get("http://192.168.0.111:8080/api/device/uplink?token=c0b2843c2e744bdc2a19d1b8fc9b176b")
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}
リスト7-3 デバイスを作成するGoの例
package main
import (
"strings"
"fmt"
"net/http"
"io/ioutil"
)
func main() {
resp, _:= http.Post("http://192.168.0.111:8080/api/device/create","application/x-www-form-urlencoded",strings.NewReader("token=c0b2843c2e744bdc2a19d1b8fc9b176b&deveui=000b78fffeabcdee&devaddr=feabcdee&lorawan_class=A&activate=abp&appskey=2b7e151628aed2a6abf7158809cf4f3c&nwkskey=2b7e151628aed2a6
abf7158809cf4f3c"))
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}
REST APIのレスポンス
表7‑9 REST APIレスポンス
REST API | フォーマット | 説明 |
|---|---|---|
/api/user/get/api_token | Content-Type: application/json
{ "status": "OK" | "FAILED", "token": string, "expired_time": number } | statusは"OK"または"FAILED"のいずれかです。statusが"FAILED"の場合、追加メンバーreasonで"Password Error"、"No API Token, Please generate it first"、または"DB Error: ${error}"のいずれかが返ります。 tokenはREST APIにアクセスするためのトークンです。 expired_timeは1970/01/01 00:00:00からのミリ秒単位の有効期限です。 |
/api/user/generate/api_token | Content-Type: application/json
{ "status": "OK" | "FAILED", <"token": string>, <"expired_time": number> }
注: < >内はオプションメンバー | tokenとexpired_timeはstatusが"OK"の場合のみ返ります。
statusは"OK"または"FAILED"のいずれかです。statusが"FAILED"の場合、追加メンバーreasonで"Password Error" または"DB Error: ${error}"のいずれかが返ります。 tokenはREST APIにアクセスするためのトークンです。 expired_timeは1970/01/01 00:00:00からのミリ秒単位の有効期限です。 |
| /api/device/uplink | Content-Type: application/json [{表7-1}] | 各オブジェクトのメンバーは「表7-1」の「JSONフィールド（REST API）」に記載されたオブジェクトの配列です。 配列内のデータの順序は時間の降順です。最新のデータは配列の先頭にあります。 |
/api/device/downlink | Content-Type: text/plain
|
|
/api/device/downlink/list
| Content-Type: text/plain
Content-Type: application/json [{ "port": number, "data": string }] | リクエストでインデックスを指定した場合、レスポンスは空または一つのオブジェクトを含む配列を返します。 |
/api/device/downlink/delete | Content-Type: text/plain
|
|
/api/device/downlink/alldelete
| Content-Type: text/plain
|
|
/api/device/list | countはデバイスレコードの配列長。 recordsはオブジェクトの配列。各オブジェクトには表7-3の情報が含まれます。 | |
/api/device/multicreate | Content-Type: application/json
{ "error": null | "failed" | "no input", "total": number, "failed": [{ "deveui": string, "reason": "表7‑9: /api/device/create" }] } | null error: 成功。failedは空の配列になります。 failed error: エラー発生。failedは空でない配列、totalは0以外の数になります。 no input error: リクエストボディにJSON配列以外が指定されています。totalは0、failedは空の配列になります。 total: 生成または更新に成功したデバイスの数。 reason: 表7‑9の/api/device/createに記載された文字列（ただしOKとFAILED: DeviceEUI Registered!!は除く）。
|
/api/device/delete | Content-Type: application/json
| 2はリクエストにdeveuiが指定されなかった場合、またはデータベースでエラーが発生した場合に返ります。 |
/api/device/multidelete | Content-Type: application/json
{ "error": null | "failed" | "no input", "matched": number, "deleted": number, "failed": [string] }
| null error: 成功。failedは空の配列になります。 failed error: エラー発生。failedは空でない配列になります。 no input error: リクエストボディにJSON配列以外が指定されています。 matched: （予約値） deleted: 削除されたデバイスの数 failed: deveuiの配列 |
/api/device/alldelete | Content-Type: text/plain
| 2はデータベースでエラーが発生した場合に返ります。 |
/api/device/create | Content-Type: text/plain
| 2と22はデータベースでエラーが発生した場合に返ります。 |
/api/cflist/list
| Content-Type: application/json
{ "type": "cflist", "count": number, "list": [{表7-7: /api/cflist/create}] } | listは表7-7の/api/cflist/createに記載されたメンバーを持つオブジェクトの配列。 |
/api/cflist/create | Content-Type: application/json
{ "status": "OK" | "FAILED", <"reason">: | "FAILED:${error}" | "DB Error ${error}" | "CFList ID is not defined." | "CFList ID can not contain any space or number sign." | "CFList ID contains invalid symbols." | "CFList Name is not defined." | "CFList Name contains invalid symbols.." | "Channel Freq 1 is not an number." | "Channel Freq 2 is not an number." | "Channel Freq 3 is not an number." | "Channel Freq 4 is not an number." | "Channel Freq 5 is not an number." | "CFList had been registered" }
| statusがOKの場合、reasonは返りません。 ${error}にはデータベースで生成された文字列が入ります。 |
/api/cflist/delete | Content-Type: application/json
{ "status": "OK" | "FAILED", <"reason">: | "DB Err ${error}" | "Unknown CFList(s)." }
| statusがOKの場合、reasonは返りません。 |
/api/post/list | 表7-7の/api/cflist/listに記載されたメンバーを持つオブジェクトの配列。 | |
/api/post/update | Content-Type: text/plain
| 2はデータベースでエラーが発生した場合に返ります。 8はpostsがリクエスト中に表れなかった場合に返ります。 |