Gateway API

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

Gateway API は、HTTP、FTP、TCP、UDP、MQTT プロトコルに対応しています。
ゲートウェイデバイスと IoTサービスプラットフォーム間の通信は、インターネットに出ない閉域網での接続なので、通信の暗号化を行うことなく安全にデータが送れ、デバイスの省電力などに貢献します。
また、Gateway API 経由で SIM の電話番号、IMSI、デバイス ID、ラベル機能で設定したラベル情報といったデバイス情報の取得や、ラベル情報の更新・削除も行えます。

送信時の仕様は、以下をご参照ください。
※ Gateway API のエンドポイントはホスト名（gw.iot.iij.jp）の指定が必須です。

HTTP/TCP/UDP

テキストデータ送信

プロトコル

HTTP

TCP

UDP

メソッド

POST

（なし）

エンドポイント

gw.iot.iij.jp

ポート番号

80

19921

19920

リクエストパス

/v1

（なし）

文字コード

UTF-8

リクエストボディ

文字列

１リクエストあたりの最大データサイズ

256 KB

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

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

1 KB

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

1 KB

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

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

バイナリデータ送信

プロトコル

HTTP

TCP

UDP

メソッド

POST

（なし）

エンドポイント

gw.iot.iij.jp

ポート番号

80

19923

19922

リクエストパス

/v1/binary

（なし）

リクエストボディ

バイナリデータ

1リクエストあたりの最大データサイズ

256 KB

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

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

1 KB

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

1 KB

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

送信コマンド例 (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リクエストあたりの最大データサイズ

100 MB

送信コマンド例（Linux）

例１）

curl -H "Content-Type: multipart/form-data" \

  -F "data=@image.jpg" gw.iot.iij.jp/v1/upload

例２）

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

ユーザー名

任意の文字列

パスワード

任意の文字列

最大データサイズ

100 MB

送信コマンド例（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

デバイス情報取得

取得フォーマット

CSV

TSV

JSON

プロトコル

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

メソッド

GET

PUT

PATCH

リクエストパス

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

接続方法

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接続	○	○	×

公開
マニュアル一覧へ

ご契約者向け
マニュアル一覧へ

Gateway API

HTTP/TCP/UDP

テキストデータ送信

バイナリデータ送信

ファイルデータ送信

デバイス情報取得

ラベル取得・更新・削除

MQTT

接続方法

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