IIJ IoTサービス オンラインマニュアル

Gateway API

デバイスからGateway APIへセンサーデータを送信することで、IoTサービスが提供するプラットフォーム機能（デバイスモニタリング、データハブ、データストレージ、クラウドアダプタ）を利用することができます。


Gateway APIは、HTTP、FTP、TCP、UDP、MQTT プロトコルに対応しています。
ゲートウェイデバイスとIoTサービスプラットフォーム間の通信は、インターネットに出ない閉域網での接続となるため、通信の暗号化を行うことなく安全にデータを送ることが出来ます。
データハブ、クラウドアダプタによるデータ転送、データストレージからのデータ取得時にHTTPS/MQTTS通信を用いることで暗号化処理をIoTサービスプラットフォーム、クラウドにオフロードし、モバイル通信量・バッテリ消費の削減につなげることが出来ます。
また、Gateway API経由で、SIMの電話番号、IMSI、デバイスID、ラベル機能で設定したラベル情報といったデバイス情報の取得や、ラベル情報の更新・削除も可能です。

送信時の仕様は、以下の項目を参照して下さい。
※Gateway APIのエンドポイントはホスト名(gw.iot.iij.jp)の指定が必須となります。


HTTP/TCP/UDP

テキストデータ送信
プロトコルHTTPTCPUDP
メソッドPOST（なし）（なし）
エンドポイントgw.iot.iij.jpgw.iot.iij.jpgw.iot.iij.jp
ポート番号801992119920
リクエストパス/v1（なし）（なし）
文字コードUTF-8UTF-8UTF-8
リクエストボディ文字列文字列文字列
1リクエストあたりの最大データサイズ

256KB
（AWS IoTのメッセージ最大サイズは128KBになります。クラウドアダプタをご利用の際はご注意ください）

※制限を超えるデータを送信すると「HTTP/1.1 413 Request Entity Too Large」レスポンスを返します

1KB

※制限を超えるデータを送信すると「Request Data Too Large」文字列を返します

1KB

※制限を超えるデータを送信してもレスポンスは返しません

送信コマンド例 ※ (Linux)
curl -X POST http://gw.iot.iij.jp/v1 \
  -d '{"name":"test_data","value":100.0}'

ファイルを指定して送信する場合

curl -X POST -d @data.txt http://gw.iot.iij.jp/v1
echo -n '{"name":"test_data","value":100.0}' |
  nc gw.iot.iij.jp 19921

ファイルを指定して送信する場合

cat data.txt | nc gw.iot.iij.jp 19921
echo -n '{"name":"test_data","value":100.0}' |
  nc -u -w 1 gw.iot.iij.jp 19920

ファイルを指定して送信する場合

cat data.txt | nc -u -w 1 gw.iot.iij.jp 19920
レスポンス送信が成功した場合、HTTP/1.1 200 OKを返します

送信が成功した場合、受信したバイト数を返します。

例）received bytes=32

レスポンスは返しません

※送信コマンド例のデータは、デバイスモニタリング機能を利用する場合の例 {"name": "test_data", "value": 100.0} を記載しています。デバイスモニタリング機能を利用せず、データハブ、データストレージ、クラウドアダプタ機能のみを利用する場合は、必ずしもこのフォーマットに従う必要はありません。（参考：デバイスモニタリング）


バイナリデータ送信
プロトコルHTTPTCPUDP
メソッドPOST（なし）（なし）
エンドポイントgw.iot.iij.jpgw.iot.iij.jpgw.iot.iij.jp
ポート番号801992319922
リクエストパス/v1/binary（なし）（なし）
リクエストボディバイナリデータバイナリデータバイナリデータ
1リクエストあたりの最大データサイズ

256KB
（AWS IoTのメッセージ最大サイズは128KBになります。クラウドアダプタをご利用の際はご注意ください）

※制限を超えるデータを送信すると「HTTP/1.1 413 Request Entity Too Large」レスポンスを返します

1KB

※制限を超えるデータを送信すると「Request Data Too Large」文字列を返します

1KB

※制限を超えるデータを送信してもレスポンスは返しません

送信コマンド例 (Linux)
echo -en "\xde\xad\xbe\xef" |
  curl -H "Content-Type: application/octet-stream" \
  --data-binary @- gw.iot.iij.jp/v1/binary

ファイルを指定して送信する場合

curl -H "Content-Type: application/octet-stream" \
  --data-binary @data.bin gw.iot.iij.jp/v1/binary
echo -en "\xde\xad\xbe\xef" |
  nc gw.iot.iij.jp 19923

ファイルを指定して送信する場合

nc gw.iot.iij.jp 19923 < data.bin
echo -en "\xde\xad\xbe\xef" |
  nc -u -w 1 gw.iot.iij.jp 19922

ファイルを指定して送信する場合

nc -u -w 1 gw.iot.iij.jp 19922 < data.bin
レスポンス送信が成功した場合、HTTP/1.1 200 OKを返します

送信が成功した場合、受信したバイト数を返します。

例） received bytes=32

レスポンスは返しません


ファイルデータ送信
プロトコルHTTP
メソッドPOST
エンドポイントgw.iot.iij.jp
ポート番号80
リクエストパス/v1/upload
リクエストボディHTTPマルチパート
1リクエストあたりの最大データサイズ100MB
送信コマンド例 (Linux)

例1)

curl -H "Content-Type: multipart/form-data" \
  -F "data=@image.jpg" gw.iot.iij.jp/v1/upload

例2)

curl -X POST -T image.jpg \
  -H 'Content-Disposition: attachment; filename="image.jpg"' \
  http://gw.iot.iij.jp/v1/upload
プロトコルFTP
送信モード

passive/active モード

エンドポイントgw.iot.iij.jp
ユーザー名任意の文字列
パスワード任意の文字列
最大データサイズ100MB
送信コマンド例 (Linux)

passiveモード例）

ftp -n << EOF
 open gw.iot.iij.jp
 user anonymous anything
 binary
 put image.jpg
 bye
 EOF

activeモード例）

ftp -n << EOF
 open gw.iot.iij.jp
 user anonymous anything
 binary
 pass
 put image.jpg
 bye
 EOF



 デバイス情報取得
取得フォーマットCSVTSVJSON
プロトコルHTTP
メソッドGET
リクエストパス/v1/dvc-state/csv/v1/dvc-state/tsv/v1/dvc-state/json
リクエストボディ / パラメータなし
送信コマンド例 (Linux)
curl http://gw.iot.iij.jp/v1/dvc-state/csv
curl http://gw.iot.iij.jp/v1/dvc-state/tsv
curl http://gw.iot.iij.jp/v1/dvc-state/json
受信レスポンス例 ※
id,dvc-99999999
ipAddress,10.10.10.1
name,コンテナAデバイス
データ送信状態,ON
送信間隔,10sec
設置場所,松江
id	dvc-99999999
ipAddress	10.10.10.1
name	コンテナAデバイス
データ送信状態	ON
送信間隔	10sec
設置場所	松江
{
  "id": "dvc-99999999",
  "ipAddress": "10.10.10.1",
  "name": "コンテナAデバイス",
  "labelContents": {
    "データ送信状態": "ON",
    "送信間隔": "10sec",
    "設置場所": "松江"
  }
}

※ デバイス名に「コンテナAデバイス」、ラベルに「データ送信状態：ON」「送信間隔：10sec」「設置場所：松江」を設定した場合のレスポンス例となります
※ 利用方法として、ラベル機能を用いたデバイスステート(状態)管理も参照ください。


 ラベル取得・更新・削除
操作取得全更新部分更新・追加・削除
プロトコルHTTP
メソッドGETPUTPATCH
リクエストパス/v1/dvc-state/json/label-contents/v1/dvc-state/json/label-contents/v1/dvc-state/json/label-contents
リクエストボディ / パラメータなし新たに設定するラベル情報をリクエストボディに JSON フォーマットで指定します。
指定されたラベル情報で全て上書きされるため、以前に設定されていたラベルは削除されます。		更新するラベル情報をリクエストボディに JSON フォーマットで指定します。
既に設定されているラベルが指定された場合は、ラベルが更新されます。
設定されていないラベルの場合は、ラベルが追加されます。
ラベルの値に null を指定された場合は、ラベルが削除されます。
リクエストボディに指定されなかったラベルは保持されます。
送信コマンド例 (Linux)
curl http://gw.iot.iij.jp/v1/dvc-state/json/label-contents
curl -X PUT \
  -H "Content-type: application/json; charset=utf-8" \
  -d '{
    "データ送信状態": "ON",
    "送信間隔": "5sec",
    "設置日": "2021/1/1"
  }' \
  http://gw.iot.iij.jp/v1/dvc-state/json/label-contents
curl -X PATCH \
  -H "Content-type: application/json; charset=utf-8" \
  -d '{
    "送信間隔": "5sec",
    "設置日": "2021/1/1",
    "設置場所": null
  }' \
  http://gw.iot.iij.jp/v1/dvc-state/json/label-contents
受信レスポンス例 ※
{
  "データ送信状態": "ON",
  "送信間隔": "10sec",
  "設置場所": "松江"
}



{
  "データ送信状態": "ON",
  "送信間隔": "5sec",
  "設置日": "2021/1/1"
}
{
  "データ送信状態": "ON",
  "送信間隔": "5sec",
  "設置日": "2021/1/1" 
}

※ デバイス名に「コンテナAデバイス」、ラベルに「データ送信状態：ON」「送信間隔：10sec」「設置場所：松江」がコマンド実行前に設定されていた場合のレスポンス例となります


MQTT

クラウドアダプタを用いてMQTTプロトコルで接続する方法を記載しています。クラウドアダプタや7. サービス活用リファレンスのクラウドアダプタ関連のページも参照ください。

接続方法

AWS
プロトコルMQTT
エンドポイントgw.iot.iij.jp
ポート番号1883
接続コマンド例
# publish
 mosquitto_pub -d -h gw.iot.iij.jp -t "topic/test" -m "Test Message"
 
# subscribe
 mosquitto_sub -d -h gw.iot.iij.jp -t "topic/test"


データ種別とサービス機能の対応


データ種別

備考

テキストデータバイナリデータファイルデータ
デバイスモニタリング ○ × × テキストデータはデバイスモニタリングに記載のJSONフォーマットのみ対応
データストレージ ○ ○ ○ バイナリデータは全てBase64エンコードされて保存される
データハブ ○ ○ ×
クラウドアダプタHTTP転送 ○ ○ × AWS IoTの場合JSONのみ対応
クラウドアダプタMQTT接続 ○ ○ ×