7.4.6. RESTful API

RESTful APIの使用を開始するにはトークンを生成する必要があります。 

このトークンはGETまたはPOSTメソッドに含める必要があります。表7-7はRESTful APIの詳細です。

REST APIには以下の制限事項があります。

  • HTTPリクエストのボディサイズは100KB以下
  • HTTPリクエストのタイムアウトは10秒


表7-7 RESTful API
REST APIHTTPメソッド説明
/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_tokenGET

RESTFul APIトークンを再生成します。


指定可能なパラメーター:

p

LoRaWAN®サーバーのパスワード

例:

GET /api/user/get/api_token?p=xxxx


このAPIはREST APIのトークンを再生成するために使用されます。

APIトークンを取得するにはHTTP PostメソッドのPOST BODY内にパスワード「p」が必要です。

このAPIは古いトークンを消去して新しいトークンを再生成します。

/api/device/uplinkGET

指定した時間範囲でデバイスのアップリンクデータを取得します。


指定可能なパラメーター:

start

データレコードをスキップする番号。

length

返されるデータレコードの最大数。

deveui

アップリンクデータを取得するデバイスを指定します。

ftime

アップリンクデータレコードをフィルタリングする時間範囲の開始時間。

ttime

アップリンクデータレコードをフィルタリングする時間範囲の終了時間。

/api/device/downlinkPOST

ダウンリンクデータを送信してデバイスを指定します。

 

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/createPOST

デバイスを作成します。


指定可能なパラメーター:

deveui

Device EUIの8バイトの16進数。

devaddr

Device Addressの4バイトの16進数。

activate

アクティベーション方法: abpまたはotaa

lorawan_class

LoRaWAN®クラス: AC

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
US902-928
CN779-787
EU433
AU915-928
AS923
KR920-923
IND865-867
RU864-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/deletePOST

デバイスを削除します。

 
指定可能なパラメーター:

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/listGET

CFlistを取得します。

このAPIはCFList情報を取得するために使用されます。

LoRaWAN®サーバーからデバイスメタデータをプルバックするために、APIトークンをHTTP GETメソッドのクエリパラメーターとして渡す必要があります。

応答はJSONオブジェクトです。

TYPE、COUNT、LISTの3つの項目があり、TYPEは「cflist」である必要があります。

COUNTはCFList内のアイテムの数です。LISTはcflist内のアイテムのIDによる昇順です。


指定可能なパラメーター:

start

応答の開始点。

length

CFListの返される最大数。

/api/cflist/createPOST

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/deletePOST

CFListを削除します。

 

Conten-Type: aplication/x-www-form-urlencoded

 

指定可能なパラメーター:

id

CFList ID

/api/post/listGETHTTP POST URLリストを取得します。
/api/post/updatePOST

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 \
  --data-urlencode "p=admin"

/api/user/generate/api_token

curl http://192.168.0.111:8080/api/user/get/api_token \
   --data-urlencode "p=admin"

/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\
  ?token=2102372cfe4f0eee93444bc1fae38d7a \

    --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\
?token=2102372cfe4f0eee93444bc1fae38d7a

/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\
?token=2102372cfe4f0eee93444bc1fae38d7a

/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言語で記述された2つの例を示しています。

 

リスト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>

}

 

注: < >内はオプションメンバー

tokenexpired_timestatusが"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

  1. OK
  2. No DevEUI
  3. DBErr ${error}
  4. Device deveui:${deveui} is not existed.
  5. FAILED: No DeviceEUI.
  6. FAILED: Downlink ID contains invalid symbols.
  7. FAILED: No Downlink Port.
  8. FAILED: Downlink Port contains invalid symbols.
  9. FAILED: No Downlink Data.
  10. FAILED: Downlink Data contains invalid symbols.
  11. FAILED: LoRaWAN Server Socket Error
  12. FAILED: LoRaWAN Server Socket Timeout

 

/api/device/downlink/list

 

Content-Type: text/plain

  1. FAILED: No DeviceEUI.
  2. FAILED: Invalid Index
  3. Device deveui:${deveui} is not existed.
  4. FAILED: LoRaWAN Server Socket Error
  5. FAILED: LoRaWAN Server Socket Timeout

 

Content-Type: application/json

[{

    "port": number,

    "data": string

}]

リクエストでインデックスを指定した場合、レスポンスは空または一つのオブジェクトを含む配列を返します。

/api/device/downlink/delete

Content-Type: text/plain

  1. OK
  2. FAILED: No DeviceEUI.
  3. FAILED: Invalid Index
  4. Device deveui:${deveui} is not existed.
  5. FAILED: LoRaWAN Server Socket Error
  6. FAILED: LoRaWAN Server Socket Timeout

 

/api/device/downlink/alldelete

 

Content-Type: text/plain

  1. OK
  2. FAILED: LoRaWAN Server Socket Error
  3. FAILED: LoRaWAN Server Socket Timeout

 

/api/device/list

Content-Type: application/json

 

{

    "count": number,

    "records": [{表7-3}]

}

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

 

  1. OK
  2. FAILED
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

 

  1. OK
  2. FAILED
  3. When an error occurs in the database
2はデータベースでエラーが発生した場合に返ります。

/api/device/create

Content-Type: text/plain

 

  1. OK
  2. FAILED
  3. FAILED: System Device Full, Limit: ${number}
  4. FAILED:DevEUI is null.
  5. FAILED:DevAddr is null.
  6. FAILED:DevAddr contains invalid symbols.
  7. FAILED:DevEUI contains invalid symbols.
  8. FAILED:DevEUI is not in HEX format.
  9. FAILED:DevAddr is not in HEX format.
  10. FAILED:Application Session Key is not in HEX format.
  11. FAILED:Network Session Key is not in HEX format.
  12. FAILED:Application EUI is not in HEX format.
  13. FAILED:Application Key is not in HEX format.
  14. FAILED:Unknown Activate Method ${activate}
  15. FAILED: Device Name contains illegal symbols
  16. FAILED: Device AppID Error
  17. FAILED: Device Channel Plan Error
  18. FAILED: Device CFList Error
  19. FAILED:RX2 Frequency is Not An Number.
  20. FAILED:RX2 DataRate is not supported.
  21. FAILED: DeviceEUI Registered!!
  22. FAILED: ${error}

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

Content-Type: application/json

 

[{表7-7: /api/post/list}]

表7-7/api/cflist/listに記載されたメンバーを持つオブジェクトの配列。

/api/post/update

Content-Type: text/plain

 

  1. OK
  2. FAILED:${error}
  3. FAILED:Invalidate Input URL ${url}
  4. FAILED:Invalidate Input Authorization ${authorization}
  5. FAILED:Invalidate Input Authorization ${customization}
  6. FAILED: Too Many Post Targets.
  7. FAILED: Post List is empty.
  8. FAILED: Targets is Undefined.

2はデータベースでエラーが発生した場合に返ります。

8はpostsがリクエスト中に表れなかった場合に返ります。