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 | gw.iot.iij.jp | gw.iot.iij.jp | |||||||||
ポート番号 | 80 | 19921 | 19920 | |||||||||
リクエストパス | /v1 | (なし) | (なし) | |||||||||
文字コード | UTF-8 | UTF-8 | UTF-8 | |||||||||
リクエストボディ | 文字列 | 文字列 | 文字列 | |||||||||
1リクエストあたりの最大データサイズ | 256 KB ※ AWS IoT のメッセージ最大サイズは 128 KB になります。クラウドアダプタをご利用の際はご注意ください。 ※ 制限を超えるデータを送信すると「HTTP/1.1 413 Request Entity Too Large」レスポンスを返します。 |
1 KB ※ 制限を超えるデータを送信すると「Request Data Too Large」文字列を返します。 |
1 KB ※ 制限を超えるデータを送信してもレスポンスは返しません。 |
|||||||||
送信コマンド例 ※(Linux) |
ファイルを指定して送信する場合
|
ファイルを指定して送信する場合
|
ファイルを指定して送信する場合
|
|||||||||
レスポンス | 送信が成功した場合、HTTP/1.1 200 OK を返します。 | 送信が成功した場合、受信したバイト数を返します。 例)received bytes=32 |
レスポンスは返しません。 |
※ 送信コマンド例のデータは、デバイスモニタリング機能を利用する場合の例 {"name": "test_data", "value": 100.0} を記載しています。
デバイスモニタリング機能を利用せず、データハブ、データストレージ、クラウドアダプタ機能のみを利用する場合は、このフォーマットに従う必要はありません。(参考:デバイスモニタリング)
バイナリデータ送信
プロトコル | HTTP | TCP | UDP | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
メソッド | POST | (なし) | (なし) | |||||||||||
エンドポイント | gw.iot.iij.jp | gw.iot.iij.jp | 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) |
ファイルを指定して送信する場合
|
ファイルを指定して送信する場合
|
ファイルを指定して送信する場合
|
|||||||||||
レスポンス | 送信が成功した場合、HTTP/1.1 200 OKを返します。 | 送信が成功した場合、受信したバイト数を返します。 例) received bytes=32 |
レスポンスは返しません。 |
ファイルデータ送信
プロトコル | HTTP | |||||
---|---|---|---|---|---|---|
メソッド | POST | |||||
エンドポイント | gw.iot.iij.jp | |||||
ポート番号 | 80 | |||||
リクエストパス | /v1/upload | |||||
リクエストボディ | HTTP マルチパート | |||||
1リクエストあたりの最大データサイズ | 100 MB | |||||
送信コマンド例(Linux) |
例1)
例2)
|
プロトコル | FTP | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
送信モード | passive/active モード |
|||||||||||||||
エンドポイント | gw.iot.iij.jp | |||||||||||||||
ユーザー名 | 任意の文字列 | |||||||||||||||
パスワード | 任意の文字列 | |||||||||||||||
最大データサイズ | 100 MB | |||||||||||||||
送信コマンド例(Linux) |
passive モード 例)
active モード 例)
|
デバイス情報取得
取得フォーマット | CSV | TSV | JSON | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
プロトコル | HTTP | ||||||||||||||||||||||||
メソッド | GET | ||||||||||||||||||||||||
リクエストパス | /v1/dvc-state/csv | /v1/dvc-state/tsv | /v1/dvc-state/json | ||||||||||||||||||||||
リクエストボディ / パラメータ | なし | ||||||||||||||||||||||||
送信コマンド例(Linux) |
|
|
|
||||||||||||||||||||||
受信レスポンス例 ※ |
|
|
|
※ デバイス名に「コンテナAデバイス」、ラベルに「データ送信状態:ON」「送信間隔:10sec」「設置場所:松江」を設定した場合のレスポンス例です。
利用方法として、ラベル機能を用いたデバイスステート(状態)管理 もご参照ください。
ラベル取得・更新・削除
操作 | 取得 | 全更新 | 部分更新・追加・削除 | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
プロトコル | HTTP | |||||||||||||||||||
メソッド | GET | PUT | PATCH | |||||||||||||||||
リクエストパス | /v1/dvc-state/json/label-contents | /v1/dvc-state/json/label-contents | /v1/dvc-state/json/label-contents | |||||||||||||||||
リクエストボディ / パラメータ | なし | 新たに設定するラベル情報をリクエストボディに JSON フォーマットで指定します。 指定されたラベル情報で全て上書きされるため、以前に設定されていたラベルは削除されます。 |
更新するラベル情報をリクエストボディに JSON フォーマットで指定します。 既に設定されているラベルが指定された場合は、ラベルが更新されます。 設定されていないラベルの場合は、ラベルが追加されます。 ラベルの値に null を指定された場合は、ラベルが削除されます。 リクエストボディに指定されなかったラベルは保持されます。 |
|||||||||||||||||
送信コマンド例 (Linux) |
|
|
|
|||||||||||||||||
受信レスポンス例 ※ |
|
|
|
※ デバイス名に「コンテナAデバイス」、ラベルに「データ送信状態:ON」「送信間隔:10sec」「設置場所:松江」がコマンド実行前に設定されていた場合のレスポンス例です。
MQTT
クラウドアダプタを用いて MQTT プロトコルで接続する方法を記載しています。クラウドアダプタ や 8. サービス活用リファレンス などのクラウドアダプタ関連ページもご参照ください。
接続方法
AWS | ||||||
---|---|---|---|---|---|---|
プロトコル | MQTT | |||||
エンドポイント | gw.iot.iij.jp | |||||
ポート番号 | 1883 | |||||
接続コマンド例 |
|
データ種別とサービス機能の対応
データ種別 | 備考 |
|||
---|---|---|---|---|
テキストデータ | バイナリデータ | ファイルデータ | ||
デバイスモニタリング | ○ | × | × | テキストデータは デバイスモニタリング に記載の JSON フォーマットのみ対応しています |
データストレージ | ○ | ○ | ○ | バイナリデータは Base64 エンコードされます |
データハブ | ○ | ○ | × | |
クラウドアダプタHTTP転送 | ○ | ○ | × | AWS IoT の場合は JSON のみ対応しています |
クラウドアダプタMQTT接続 | ○ | ○ | × |