You can obtain the following information about an attribute definition: attribute ID, attribute type, attribute name, and attribute unit of measure. If the requested attribute does not exist, then an error message is received in the response message.
Request line
Post baseURL/dbapi.do?action=retrieveAttributeDef&dataset=<Datasetname>
The request body for HTTP-POST must be in JSON format.
To get the dynamic attribute definitions, use HTTP-POST and specify the attribute definition ID in the request body.
Request body
{
"attrIds":[
"",
"",
""
]
}
Request example using GET
GET /dbapi.do?action=retrieveAttributeDef&dataset=defaultDs&attrIds=numCPU,cpuUsage,memory HTTP /1.1 Authorization:Basic ZnJlZDpmcmVk
Request example using POST
POST /dbapi.do?action=retrieveAttributeDef&dataset=defaultDs HTTP /1.1 Authorization:Basic ZnJlZDpmcmVk
{
"attrIds":[
"numCPU",
"cpuUsage",
"memory"
]
}
Request parameters
| Parameter | Type | Description |
|---|---|---|
| action | String | retrieveAttributeDef
Specify the API function to be invoked. |
| dataset | String | Dataset name. From 2 to 32 alphanumeric, underscore (_), and hyphen (-) characters are allowed. |
| attrIds | String[ ] |
(Optional) Attribute IDs are involved in request URL for GET method and in request body for POST method. From 2 to 32 alphanumeric, underscore (_), and hyphen (-) characters are allowed. GET: One or more comma-separated attribute IDs. Example: A,B,C POST: JSON format Example: { “attrIds”:[“A”,”B”,”C”] } |
Response body
{
"retrieved":[
{
"id":"",
"name":"",
"unit":"",
"type":"",
"bandFactor":
"dynamic":
}
],
"failed":[
{
"code":"",
"id":"",
"error":""
}
]
}
Response example
{
"retrieved":[
{
"id":"cpuUsage",
"name":"cpuUsage",
"unit":"null",
"type":"timeseries",
"bandFactor":1.000000
"dynamic":false
}
],
"failed":[
{
"code":"42050005",
"id":"numCPU",
"error":"Attribute definition with {id}:[numCPU] does not exist"
},
{
"code":"42050005",
"id":"memory",
"error":"Attribute definition with {id}:[memory] does not exist"
}
]
}
Response parameters
|
Parameter |
Type |
Description |
|---|---|---|
| retrieved | Object[ ] | Retrieved attribute definition. |
| retrieved:id | String | Attribute definition ID. |
| retrieved:name | String | Attribute definition name |
| retrieved:unit | String |
Attribute definition unit. It is blank if unit is not specified at the time of creation. |
| retrieved:type | String |
Attribute definition type. It is either scalar or time series. |
| retrieved:bandFactor | Float |
Attribute definition band factor. Precision of time series data point is controlled by band factor value. |
| retrieved:dynamic | Boolean |
Specifies weather attribute definition is dynamic or not. If attribute is not dynamic, this information is not displayed. |
| failed | Object[ ] | List of failed entities. |
| failed:code | String | Eight-digit hexadecimal error code. |
| failed:id | String | Failed attribute ID. |
| failed:error | String | Error message. |
Status codes
|
Status code |
Message |
Description |
|---|---|---|
| 200 | OK | Request was successful, and the response body contains the requested log details. |
| 206 | PARTIAL CONTENT | Request is in progress, and the incremental content is available in the response body. |
| 277 | PARTIAL OK | Request completed successfully with some failures. Check the response body for details. |
| 400 | BAD REQUEST | Request URL or request body validation failed. Check the response body for details. |
| 401 | UNAUTHORIZED | Supplied authentication token is invalid or does not have the appropriate credentials to access the resource. |
| 404 | NOT FOUND | API server could not find a resource matching the request. |
| 405 | METHOD NOT ALLOWED | Request HTTP method is not allowed for the operation. |
| 500 | SERVER ERROR | API operation request failed. Check the response body for details. |
Response codes
The following table lists the common API response codes that might be generated through the standard API. If an error response is not listed, examine the HTTP status codes to determine the best method for addressing the issue.
| Response code | Message | Condition |
|---|---|---|
| 42050005 | Attribute definition with {id}:[cpuUsage] does not exist. | Minimum of one attribute definition is obtained and getting one or more attribute definitions failed. Specified attribute definition does not exist. |
| 4202000F | Invalid value specified for parameter {id}. {id} contains invalid characters. The valid characters are characters are alphanumeric, - , and _. | Minimum of one attribute definition is obtained and getting one or more attribute definitions failed. The static part of the attribute definition ID contains invalid characters. |
| 4 202000F | Invalid value specified for parameter {id}. {id} length must be between 2 to 32 characters. | Minimum of one attribute definition is obtained and getting one or more attribute definitions failed. The length of the static part of the attribute ID exceeds the allowed length. |
| 42020007 | No regular expression is specified. | Minimum of one attribute definition is obtained and getting one or more attribute definitions failed. The regular expression is not specified in the dynamic attribute ID. |
| 42010002 | Invalid JSON Request. | Specified JSON input is invalid. |
| 420000E9 | License is not valid. | License is not uploaded, or the uploaded license is invalid or expired. |
| 420000E9 | Authorization needed. | Request is sent with an invalid authentication token. |
| 420000E4 | Dataset with {name}:[ds1] does not exist. | Request is sent for a dataset that does not exist. |
| 420000E0 | HTTP method [PUT] is not supported for action [retrieveAttributeDef]. | Request is sent with any HTTP method other than GET or POST. |
| 420100E2 | Application encountered an internal error. | API server encountered an unknown error. |