Token｜MQTT 連線設定

API Domain

https://ioe-api.nextdrive.io/device-management

MQTT Configuration

① Operate device command for setting MQTT config

Summary

① Operate device command for setting MQTT config

Path

POST /v1/devices/<dsn>/commands

Description

Through this API, you can set the MQTT connection parameters for a specific Gateway.

Permission

  • Business::Admin, and Business::Operator (if the device is under the same business)

  • Business::Dealer (if the device attached the dealer tag)

  • EndUser (if you are the device owner)

Request Header

Authorization

<accessToken>

Request Params

Example Value
JSON
dsn: "NDTEST1234567"

Schema
JSON
dsn: string(NextDrive defined DSN)

Request Body

Content Type

application/json

Example Value
JSON
{
  "invokeType": "async",
  "identifier": "externalMqttService",
  "params": {
    "command": "setMqttConfig",
    "host": "mqtt.example.com",
    "port": 8883,
    "keepAlive": 60,
    "protocolVersion": "3.1.1",
    "username": "username",
    "password": "password",
    "tls": true,
    "tlsVersion": "tlsv1.2",
    "caCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
    "clientCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
    "clientKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
    "verifyPeer": true,
    "qos": 1,
    "cleanSession": true,
    "connectTimeout": 10
  }
}

Schema
JSON
{
  "invokeType": "async"                          | required,
  "identifier": "externalMqttService"            | required,
  "params": json object,
    {
      "command": "setMqttConfig"                 | required,
      "host": string                             | required,
      "port": integer                            | required,
      "keepAlive": integer(unit: second)         | optional(default: 60),
      "protocolVersion": string(<"3.1.1"|"5.0">) | required,
      "username": string                         | required,
      "password": string                         | required,
      "tls": boolean                             | optional(default: false),
      "tlsVersion": string(<"tlsv1.2"|"tlsv1.3">)| optional(default: "tlsv1.2"),
      "caCert": string                           | optional(default: null),
      "clientCert": string                       | optional(default: null),
      "clientKey": string                        | optional(default: null),
      "verifyPeer": boolean                      | optional(default: false),
      "qos": integer(0~2)                        | optional(default: 1),
      "cleanSession": boolean                    | optional(default: true),
      "connectTimeout": integer(unit: second)    | optional(default: 10)
    }
}

Note

MQTT settings may not take effect immediately, so async is used to design related APIs.


200

Response

Status Code

200

Description

Successful request

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "successful request",
  "data": {
    "sessionId": "7b2e0ca2-60d0-4a92-9cc0-0befe917d4c9",
    "requestTime": 1671494400000
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    "sessionId": string,
    "requestTime": timestamp
  }
}
400

Response

Status Code

400

Description

Invalid parameter

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40001,
  "message": "Invalid parameter: XXXXXX"
}

Schema

Invalid Parameter Error
403

Response

Status Code

403

Description

Forbidden

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40300,
  "message": "Forbidden: XXXXXX"
}

Schema

  1. No permission to operate on the device.

  2. The device does not support the specified command.

  3. params do not match the value range of the specified command

  4. The device is offline.
404

Response

Status Code

404

Description

Not found

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40400,
  "message": "Not found: dsn doesn't exist"
}

Schema

The device is not found.
500

Response

Status Code

500

Description

System error

Content Type

application/json

Example Value

 
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 50000,
  "message": "Something went wrong"
}

Schema

Internal server error such as database error, redis error, …etc.
② Get the details of setting MQTT config

Summary

② Get the details of setting MQTT config

Path

GET /v1/devices/<dsn>/commands/sessions/<sessionId>

Description

Through this API, you can check the execution status of the MQTT connection parameters setting of a specific Gateway.

Permission

  • Business::Admin, and Business::Operator (if the device is under the same business)

  • Business::Dealer (if the device attached the dealer tag)

  • EndUser (if you are the device owner)

Request Header

Authorization

<accessToken>

Request Params

Example Value
JSON
sessionId: "abbb3398-7157-4609-9ddc-629d7704d292"

Schema
JSON
sessionId: string(UUID format)

Note

Records are retained for only 3 months.


200

Response

Status Code

200

Description

Successful request

Content Type

application/json

Example Value
No Ack, no result
JSON
{
  "code": 20000,
  "message": "Successful Request",
  "data": {
    // Command info
    "sessionId": "abbb3398-7157-4609-9ddc-629d7704d292",
    "invokeType": "async",
    "identifier": "externalMqttService",

    // Device info
    "dsn": "NDTEST1234567",
    "model": "Atto",
    
    // Command operation request
    "requestTime": 1671494400000,
    "request": {
      "command": "setMqttConfig",
      "host": "mqtt.example.com",
      "port": 8883,
      "keepAlive": 60,
      "protocolVersion": "3.1.1",
      "username": "username",
      "password": "password",
      "tls": true,
      "tlsVersion": "tlsv1.2",
      "caCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
      "clientCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
      "clientKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
      "verifyPeer": true,
      "qos": 1,
      "cleanSession": true,
      "connectTimeout": 10
    },
    
    // Command operation ack
    "ackTime": null,
    "ack": null,
    "ackError": null,
    
    // Command operation result
    "responseTime": null,
    "response": null
  }
}
Ack received, no result
JSON
{
  "code": 20000,
  "message": "Successful Request",
  "data": {
    // Command info
    "sessionId": "abbb3398-7157-4609-9ddc-629d7704d292",
    "invokeType": "async",
    "identifier": "externalMqttService",

    // Device info
    "dsn": "NDTEST1234567",
    "model": "Atto",
    
    // Command operation request
    "requestTime": 1671494400000,
    "request": {
      "command": "setMqttConfig",
      "host": "mqtt.example.com",
      "port": 8883,
      "keepAlive": 60,
      "protocolVersion": "3.1.1",
      "username": "username",
      "password": "password",
      "tls": true,
      "tlsVersion": "tlsv1.2",
      "caCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
      "clientCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
      "clientKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
      "verifyPeer": true,
      "qos": 1,
      "cleanSession": true,
      "connectTimeout": 10
    },
    
    // Command operation ack
    "ackTime": 1671494400000,
    "ack": null,
    "ackError": null,  // optional field, use it when failure
    
    // Command operation result
    "responseTime": null,
    "response": null
  }
}
Ack received, result received
JSON
{
  "code": 20000,
  "message": "Successful Request",
  "data": {
    // Command info
    "sessionId": "abbb3398-7157-4609-9ddc-629d7704d292",
    "invokeType": "async",
    "identifier": "externalMqttService",

    // Device info
    "dsn": "NDTEST1234567",
    "model": "Atto",
    
    // Command operation request
    "requestTime": 1671494400000,
    "request": {
      "command": "setMqttConfig",
      "host": "mqtt.example.com",
      "port": 8883,
      "keepAlive": 60,
      "protocolVersion": "3.1.1",
      "username": "username",
      "password": "password",
      "tls": true,
      "tlsVersion": "tlsv1.2",
      "caCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
      "clientCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
      "clientKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
      "verifyPeer": true,
      "qos": 1,
      "cleanSession": true,
      "connectTimeout": 10
    },
    
    // Command operation ack
    "ackTime": 1671494400000,
    "ack": null,
    "ackError": null,  // optional field, use it when failure
    
    // Command operation result
    "responseTime": 1671494400000,
    "response": {
      "result": "success"
    }
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    // Command info
    "sessionId": string(UUID format),
    "invokeType": string(<"async"|"sync">),
    "identifier": string(refer to Thing Protocol),

    // Device info
    "dsn": string(NextDrive defined DSN),
    "model": string(NextDrive defined model),
    
    // Command operation request
    "requestTime": timestamp,
    "request": json object | nullable,
    
    // Command operation ack
    "ackTime": timestamp | nullable,
    "ack": json object | nullable,
    "ackError": string | nullable,
    
    // Command operation result
    "responseTime": timestamp | nullable,
    "response": json object | nullable
  }
}

Note

Success.

操作成功，無錯誤

Out of memory.

記憶體不足，無法完成操作

A protocol error occurred.

協議錯誤，可能是使用了不支援的 MQTT 版本

Invalid input parameters.

傳入的參數無效，請檢查函式呼叫的參數

Client not connected.

客戶端尚未與 broker 建立連線

Connection refused.

broker 拒絕連線，可能是認證失敗或設定錯誤

Message not found (internal use only).

查無指定訊息，通常為內部用途

The connection was lost.

與 broker 的連線中斷，可能是網路問題或 broker 關閉

A TLS error occurred.

TLS/SSL 錯誤，可能是憑證問題或加密協議不匹配

Payload too large.

訊息內容太大，超過 broker 或客戶端的限制

This feature is not supported.

嘗試使用不被支援的功能

Authentication failed.

認證失敗，可能是使用者名稱或密碼錯誤

Access denied by ACL.

存取被拒，可能是存取控制列表（ACL）設定限制

Unknown error.

發生不明錯誤，無法確定原因

Unknown error. Check errno.

發生系統層級錯誤，需查看 errno 取得詳細資訊

Lookup error.

主機名稱查詢（DNS）失敗，無法解析主機名稱

Proxy error.

透過代理伺服器時發生錯誤

Plugin deferred.

外掛程式延遲處理，可能是等待其他操作完成

Malformed UTF-8 string.

字串格式錯誤，非有效的 UTF-8 編碼

Keepalive error.

保持連線錯誤，可能是未收到預期的 PING 回應

Lookup error.

主機名稱查詢失敗，與 MOSQ_ERR_EAI 類似

Connection refused

連線被拒

Connection timed out

連線逾時

Network is unreachable

網路不可達

No route to host

找不到通往主機的路由

Address already in use

嘗試使用的本地位址已被佔用
400

Response

Status Code

400

Description

Invalid parameter

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40000,
  "message": "Invalid parameter: XXXXXX"
}

Schema

Invalid sessionId format
403

Response

Status Code

403

Description

Forbidden

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40300,
  "message": "Forbidden: XXXXXX"
}

Schema

No permission to operate on the device.
404

Response

Status Code

404

Description

Not found

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40400,
  "message": "Not found: sessionId doesn't exist"
}

Schema

  1. The device is not found.

  2. The sessionId is not found.
500

Response

Status Code

500

Description

System error

Content Type

application/json

Example Value

 
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 50000,
  "message": "Something went wrong"
}

Schema

Internal server error such as database error, redis error, …etc.
③ Operate device command for getting MQTT config

Summary

③ Operate device command for getting MQTT config

Path

POST /v1/devices/<dsn>/commands

Description

Through this API, you can get the MQTT connection parameters of a specific GW.

Permission

  • Business::Admin, and Business::Operator (if the device is under the same business)

  • Business::Dealer (if the device attached the dealer tag)

  • EndUser (if you are the device owner)

Request Header

Authorization

<accessToken>

Request Params

Example Value
JSON
dsn: "NDTEST1234567"

Schema
JSON
dsn: string(NextDrive defined DSN)

Request Body

Content Type

application/json

Example Value
JSON
{
  "invokeType": "sync",
  "identifier": "externalMqttService",
  "params": {
    "command": "getMqttConfig"
  }
}

Schema
JSON
{
  "invokeType": "sync"                | required,
  "identifier": "externalMqttService" | required,
  "params": {
    "command": "getMqttConfig"        | required
  }
}

Note

After the MQTT settings are completed, they can be obtained immediately. The relevant APIs are designed in a Sync way.


200

Response

Status Code

200

Description

Successful request

Content Type

application/json

Example Value
JSON
{
  "code": 20000,
  "message": "Successful Request",
  "data": {
    "sessionId": "abbb3398-7157-4609-9ddc-629d7704d292",
    "requestTime": 1671494400000,
    "responseTime": 1671494400000,
    "response": {
      "host": "mqtt.example.com",
      "port": 8883,
      "keepAlive": 60,
      "protocolVersion": "3.1.1",
      "username": "username",
      "password": "password",
      "tls": true,
      "tlsVersion": "tlsv1.2",
      "caCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
      "clientCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
      "clientKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
      "verifyPeer": true,
      "qos": 1,
      "cleanSession": true,
      "connectTimeout": 10
    }
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    "sessionId": string(UUID format),
    "requestTime": timestamp,
    "responseTime": timestamp,
    "response": json object
    {
      "host": string,
      "port": integer,
      "keepAlive": integer(unit: second),
      "protocolVersion": string(<"3.1.1"|"5.0">),
      "username": string,
      "password": string,
      "tls": boolean,
      "tlsVersion": string,
      "caCert": string,
      "clientCert": string,
      "clientKey": string,
      "verifyPeer": boolean,
      "qos": integer(0~2),
      "cleanSession": boolean,
      "connectTimeout": integer(unit: second)
    }
  }
}
400

Response

Status Code

400

Description

Invalid parameter

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40001,
  "message": "Invalid parameter: XXXXXX"
}

Schema

Invalid Parameter Error
403

Response

Status Code

403

Description

Forbidden

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40300,
  "message": "Forbidden: XXXXXX"
}

Schema

  1. No permission to operate on the device.

  2. The device does not support the specified command.

  3. params do not match the value range of the specified command.

  4. The device is offline.
404

Response

Status Code

404

Description

Not found

Content Type

application/json

Example Value
JSON
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 40400,
  "message": "Not found: dsn doesn't exist"
}

Schema

The device is not found.
500

Response

Status Code

500

Description

System error

Content Type

application/json

Example Value

 
{
  "requestId": "e867850b-0c81-43f4-ad58-459a54c65ec5",
  "code": 50000,
  "message": "Something went wrong"
}

Schema

Internal server error such as database error, redis error, …etc.