公開
マニュアル一覧へ

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

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

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

テキストデータ送信
プロトコルHTTPTCPUDP
メソッドPOST（なし）（なし）
エンドポイントgw.iot.iij.jpgw.iot.iij.jpgw.iot.iij.jp
ポート番号801992119920
リクエストパス/v1（なし）（なし）
文字コードUTF-8UTF-8UTF-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} を記載しています。
デバイスモニタリング機能を利用せず、データハブ、データストレージ、クラウドアダプタ機能のみを利用する場合は、このフォーマットに従う必要はありません。（参考：デバイスモニタリング）

バイナリデータ送信
プロトコルHTTPTCPUDP
メソッドPOST（なし）（なし）
エンドポイントgw.iot.iij.jpgw.iot.iij.jpgw.iot.iij.jp
ポート番号801992319922
リクエストパス/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
 デバイス情報取得
取得フォーマット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 プロトコルで接続する方法を記載しています。クラウドアダプタ や 8. サービス活用リファレンス などのクラウドアダプタ関連ページもご参照ください。

接続方法

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