Token｜資料存取

API Domain

https://ioeapi.nextdrive.io

Data Point Access

①　Device Data Acquire (request)

Summary

① Device Data Acquire (request)

Path

POST /data-point/v1/commands/get-scopes/dsns/<dsn>

Description

Through this API, you can acquire devices data through the gateway.
Due to asynchronous communication, you can get data by event subscription.

After config, IoE platform pushes data to your endpoint when data is submitted by a gateway to.
For details, please refer to "WS format｜Required Data " and "ED format｜Required Data".

If you request to acquire device data by this API, a sessionId will be sent to identify the data.

Request Body

Content Type

application/json

Example Value

Body:

JSON
{
  "scopes": [
    {
      "name": "operationStatus"
    }
  ]
}

Schema
JSON
{
  "scopes": [
    {
      "name": string | required
    }
  ]
}

Note

This API only works when the gateway and the device are both online.
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"
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    "sessionId": string
  }
}
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

Note

  • Invalid parameter
② Device Data Acquire (get result)

Summary

② Device Data Acquire (get result)

Path

GET /data-point/v1/commands/results/sessions/<sessionId>

Description

Through this API, you can acquire devices data through the "sessionId" returned in "Device Data Acquire (request)".

Request Params

Content Type

application/json

Example Value

Path parameter:

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

Schema
JSON
sessionId: string
200

Response

Status Code

200

Description

Successful request

Content Type

application/json

Example Value

Different responses will be returned based on the command execution status.
Please refer to the following for details:

ack with results
JSON
{
  "code": 20000,
  "message": "Successful Request",
  "data": {
    "type": "read", // or "write"

    // Device info
    "dsn": "TPS5YE0000001",
    "model": "StgBattery",
    
    // Scope command request
    "sessionId": "abbb3398-7157-4609-9ddc-629d7704d292",
    "requestTime": 1671494400000,
    
    // Scope command ack
    "ackTime": 1671494400000,      // or null
    "ack": "success",              // or null
    
    // Scope command result
    "responseTime": 1671494400000, // or null
    "response": [                  // or empty []
      {
        "name": "chargeableElectricity",
        "result": "success",       // or "failure"
        "value": "280.576"         // use it when value exists
      },
      {
        "name": "temperatureSetting",
        "result": "success",       // or "failure"
        "value": "25"              // use it when value exists
      }
    ]
  }
}
ack without results
JSON
{
  "code": 20000,
  "message": "Successful Request",
  "data": {
    "type": "read",

    // Device info
    "dsn": "TPS5YE0000001",
    "model": "StgBattery",
    
    // Scope command request
    "sessionId": "abbb3398-7157-4609-9ddc-629d7704d292",
    "requestTime": 1671494400000,
    
    // Scope command ack
    "ackTime": 1671494400000,
    "ack": "success",
    
    // Scope command result
    "responseTime": null,
    "response": []
  }
}
failed ack (without results)
JSON
{
  "code": 20000,
  "message": "Successful Request",
  "data": {
    "type": "read", // or "write"

    // Device info
    "dsn": "TPS5YE0000001",
    "model": "StgBattery",
    
    // Scope command request
    "sessionId": "abbb3398-7157-4609-9ddc-629d7704d292",
    "requestTime": 1671494400000,
    
    // Scope command ack
    "ackTime": 1671494400000,      // or null
    "ack": "failure",              // or null
    "ackError": "Something wrong", // optional field, use it when failure
    
    // Scope command result
    "responseTime": null
    "response": []
  }
}
no ack and no results
JSON
{
  "code": 20000,
  "message": "Successful Request",
  "data": {
    "type": "read",

    // Device info
    "dsn": "TPS5YE0000001",
    "model": "StgBattery",
    
    // Scope command request
    "sessionId": "abbb3398-7157-4609-9ddc-629d7704d292",
    "requestTime": 1671494400000,
    
    // Scope command ack
    "ackTime": null,
    "ack": null,

    // Scope command result
    "responseTime": null,
    "response": []
  }
}

Schema
JSON
{
  "code": integer,
  "message": string,
  "data": {
    "type": string,
    "dsn": string,
    "model": string,
    "sessionId": string,
    "requestTime": integer,
    "ackTime": integer,
    "ack": string,
    "responseTime": integer,
    "response": [
      {
        "name": string,
        "result": string,
        "value": number  
      }
    ]
  }
}

Note

  1. The fields under data are all set as mandatory. The key must be there, but the value may be null.

  2. If the result field in response is null, it means the gateway did not receive it. If the result field in response is failure, it means the gateway received it but an error occurred

  3. The sessionId will expire after 3 months and the result cannot be found.
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 Parameter Error

Note

sessionId is not in UUID format
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"
}

Schema

Invalid Parameter Error

Note

sessionId does not exist