Management API Introduction
Last Updated：2021-02-24
Create Database
| Method | API | Instruction |
|---|---|---|
| POST | /v1/database?clientToken={clientToken} | Create a database |
Request Parameters
| Parameter name | Parameter type | Required | Instruction |
|---|---|---|---|
| clientToken | String | Required | Used to guarantee the idempotence of the interface |
| databaseName | String | Required | Database name |
| description | String | Optional | Database description |
| ingestDataPointsMonthly | Int | Required | Write-in quota, unit: millions of points/month |
| queryUnitsMonthly | Int | Optional | Query quota, unit: ten thousands of points/month |
| storeBytesQuota | Int | Optional | Storage space capacity quota, unit: byte |
| purchaseLength | Int | Required | Purchase duration, unit: month |
| couponName | String | Optional | Coupon Number |
Payment instructions: CouponName is not empty and has a valid voucher number, then voucher payment will be preferred. If the voucher amount is insufficient, the voucher + account balance will be used for payment. If the voucher amount is invalid, the account balance will be used for payment. When the user purchases for 10, 11 or 12 months, due to preferential policies, it actually takes only fees of 10 months for a 12-month service.
Return Parameters
| Parameter name | Parameter type | Instruction |
|---|---|---|
| databaseId | String | Database ID |
| charge | BigDecimal | Consumption Amount, Unit: Yuan |
| expiredTime | Date | Expire date |
| orderId | String | Order ID |
Request Example
POST /v1/database?clientToken=ed35ec43-0f2a-4648-8828-de9b28caceda HTTP/1.1
Host: tsdb.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-06T11:52:41Z
{
"databaseName": "test",
"description": "test",
"ingestDataPointsMonthly": 1
"purchaseLength": 1
}Return Example
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 28597c34-096d-489c-908f-38844c92032e
{
"databaseId": "tsdb-5atue8m3sxsv",
"charge": 29.9,
"expiredTime": "2016-07-06T11:52:41Z",
"orderId": "d04da3c16bd042af9e916a75bb1fa19g"
}Delete Database
| Method | API | Instruction |
|---|---|---|
| DELETE | /v1/database/{databaseId} | Delete a database |
Request Parameters
| Parameter name | Parameter type | Required | Instruction |
|---|---|---|---|
| databaseId | String | Required | Database ID |
Request Example
DELETE /v1/database/tsdb-5atue8m3sxsv HTTP/1.1
Host: tsdb.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-06T11:52:41ZReturn Example
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 28597c34-096d-489c-908f-38844c92032eGet Database Information
| Method | API | Instruction |
|---|---|---|
| GET | /v1/database/{databaseId} | Get database information of database with ID {databaseId} |
Request Parameters
| Parameter name | Parameter type | Required | Instruction |
|---|---|---|---|
| databaseId | String | Required | Database ID |
Return Parameters
Return a Database object.
Database Objects
| Parameter name | Parameter type | Instruction |
|---|---|---|
| databaseId | String | Database ID |
| databaseName | String | Database name |
| description | String | Database description |
| endpoint | String | Domain name of database |
| quota.ingestDataPointsMonthly | Int | Write-in quota, unit: millions of points/month |
| quota.queryUnitsMonthly | Int | Query quota, unit: ten thousands of points/month |
| quota.storeBytesQuota | Int | Storage space capacity quota unit: GB |
| status | String | Database status, see Database status table |
| autoExport | Boolean | Do you want to enable automatic export |
| createTime | Date | Creation time of database |
| expiredTime | Date | Expire date |
Request Example
GET /v1/database/tsdb-5atue8m3sxsv HTTP/1.1
Host: tsdb.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-06T11:52:41ZReturn Example
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 28597c34-096d-489c-908f-38844c92032e
{
"databaseId": "tsdb-5atue8m3sxsv",
"databaseName": "test",
"description": "test",
"endpoint": "test.tsdb.iot.gz.baidubce.com",
"quota": {
"ingestDataPointsMonthly": 1，
"queryUnitsMonthly": 10,
"storeBytesQuota": 1
},
"status": "Active",
"autoExport": true,
"createTime": "2016-06-06T14:21:01Z",
"expiredTime": "2016-07-06T14:21:01Z"
}Get Database Lists
| Method | API | Instruction |
|---|---|---|
| GET | /v1/database | Get database lists |
Return Parameters
| Parameter name | Parameter type | Instruction |
|---|---|---|
| databases | List<Database> | Database list, an array of database object |
Request Example
GET /v1/database HTTP/1.1
Host: tsdb.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-06T11:52:41ZReturn Example
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 28597c34-096d-489c-908f-38844c92032e
{
"databases": [{
"databaseId": "tsdb-5atue8m3sxsv",
"databaseName": "test",
"description": "test",
"endpoint": "test.tsdb.iot.gz.baidubce.com",
"quota": {
"ingestDataPointsMonthly": 1
},
"status": "Active",
"autoExport": true,
"createTime": "2016-06-06T14:21:01Z",
"expiredTime": "2016-07-06T14:21:01Z"
}]
}Create a Delete Task
| Method | API | Instruction |
|---|---|---|
| PUT | /v1/database/{databaseId}?delete | create a delete task |
Request Parameters
| Parameter name | Parameter type | Required | Instruction |
|---|---|---|---|
| databaseId | String | Required | databaseId of data to delete |
| metrics | List<String> | Optional | The metric list corresponding to the data point to be deleted. "Metricfields list" and "metrics" must have and can only have one existence |
| metricFieldsList | List<MetricFields> | Optional | The field list corresponding to the data point to be deleted. "Metricfields list" and "metrics" must have and can only have one existence |
| start | Long | Optional | The start time corresponding to the data point to delete is Long.Min by default |
| end | Long | Optional | The end time corresponding to the data point to delete is Long.Max by default |
| tags | Object | Optional | For tags filtered by the data point to delete, each key of Object corresponds to a metric, and each value of Object is of type List < TagFilter >, which indicates the conditions that the Tag of the data point to delete needs to meet. Metric that appears in tags must be in metrics or metricFieldsList |
MetricFields objects
| Parameter name | Parameter type | Required | Instruction |
|---|---|---|---|
| metric | String | Required | Corresponding metric of data point to delete |
| fields | List<String> | Optional | Corresponding field list of data point to delete |
Return Parameters
| Parameter name | Parameter type | Instruction |
|---|---|---|
| taskId | String | Task ID |
Request Example
PUT /v1/database/tsdb-5atue8m3sxsv?delete HTTP/1.1
Host: tsdb.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-06T11:52:41Z
{
"metrics": [
"cpu_idle",
"server"
],
"tags": {
"cpu_idel": [{
"tagKey": "rack",
"in": ["rack1", "rack2"]
}],
"server":[{
"tagKey": "host",
"in": ["0.0.0.0"]
}]
},
"start": 13897024887,
"end": 13897029887
}Return Example
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 28597c34-096d-489c-908f-38844c92032e
{
"taskId": "123456"
}Create Export Task
| Method | API | Instruction |
|---|---|---|
| PUT | /v1/database/{databaseId}?export | create an export task |
Request Parameters
| Parameter name | Parameter type | Required | Instruction |
|---|---|---|---|
| databaseId | String | Required | Database ID |
| metrics | List<String> | Optional | Support list metrics export. If it is not set or empty, all metrics in database will be exported |
| format | String | Required | Format of exported file, currently only "CSV" is supported. |
| start | Long | Optional | The start time stamp of exported data will be Long.Min_Value by default if not set |
| end | Long | Optional | The end time stamp of exported data will be Long.Max_Value by default if not set |
| tags | Object | Optional | For tags filtered by the data points to export, the key of Object is metric, and the value is a list of TagFilters |
| bosUrl | String | Required | Export to the directory address of bos |
| singleFile | Boolean | Required | Export as a single file? The default setting is false if not set |
| Parameter name | Parameter type | Required | Instruction |
|---|---|---|---|
| tagKey | String | Required | Key of the tag of the metric to filter |
| in | List<String> | Optional | Value list of tags that can be included and can not coexist with notIn and like |
| notIn | List<String> | Optional | Value list of tags to filter which can not coexist with in and like |
| like | String | Optional | Rules to match, "%" matches any number of characters, "_" matches a single character, and escape character is " \ ". They cannot coexist with in and notIn |
Return Parameters
| Parameter name | Parameter type | Instruction |
|---|---|---|
| taskId | String | Task ID |
Request Example
Put /v1/database/{databaseId}?export HTTP/1.1
Host: tsdb.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-06T11:52:41Z
{
"bosUrl": "bos://bucket1",
"metrics": [
"cpu",
"memory"
],
"tags": {
"device": ["device1", device2"]
}
"singleFile": true
}Return Example
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 28597c34-096d-489c-908f-38844c92032e
{
"taskId": "i4jzt228238nxueyq932"
}Get Task Information
| Method | API | Instruction |
|---|---|---|
| GET | /v1/database/{databaseId}/task/{taskId} | Get the ID of database with ID {databaseId} as the {taskId} task information |
Request Parameters
| Parameter name | Parameter type | Required | Instruction |
|---|---|---|---|
| databaseId | String | Required | Database ID |
| taskId | String | Required | Task ID |
Return Parameters
Return a Task object, as described in the Task object below.
Task Objects
| Parameter name | Parameter type | Instruction |
|---|---|---|
| taskId | String | Task ID |
| type | String | Task type, Export or Delete |
| params | String | Task parameters vary according to different types, the contents are json strings |
| status | String | Task status, Pending/Running/Completed/Failed/Canceled |
| error.code | String | Task failure code, which is available when the task status is Failed |
| error.message | String | Task failure information, which is available when the task status is Failed |
| results | String | Task results vary according to different types, the contents are json strings. The Export task package contains exportedDataPointsCount, exportedLinesCount, exportedTime, bucketName, and objectNames. The Delete task package contains deletedDataPointsCount and failures |
| createTime | Date | Task creation time |
| completionTime | Date | Completion time of task, this field only exists when the status is Completed/Failed |
Request Example
GET /v1/database/tsdb-5atue8m3sxsv/task/123457 HTTP/1.1
Host: tsdb.gz.baidubce.com
Authorization: {authorization}
Content-Type: application/json; charset=utf-8
x-bce-date: 2016-06-06T11:52:41ZReturn Example
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-bce-request-id: 28597c34-096d-489c-908f-38844c92032e
{
"taskId":"idwby9gvtk0eg8a4x3hn",
"type":"Export",
"params":{
"bosUrl":"bos://bucket1/",
"metrics":[
],
"tags":{}
"start":0,
"end":9223372036854775807,
"singleFile":false
},
"status":"Completed",
"error":{
"code":"",
"message":""
},
"results":{
"exportedDataPointsCount":27375,
"exportedLinesCount":27375,
"objectNames":["file1","file2"]
},
"createTime":"2018-11-05T06:29:52Z",
"completionTime":"2018-11-05T06:30:10Z"
}