openTSDB详解之api/uid/tsmeta【待完善】
api/uid/tsmeta
这个端点可以让你查询，编辑或者删除时间序列元数据信息，这个元数据信息是和具体的时间序列的metric，tag name，tag value相关联的。一些字段被TSD设置，但是一些却是可以有用户设置的。【译者注：这些特性和uidmeta很相像】。当使用POST方法时，仅仅请求中的字段将会被存储。存在的字段不会被包含在内，将会被单独留下。使用PUT方法将会覆写用户所有的可变字段，使用给定值，或者默认值，如果一个给出的字段没有被提供。
请注意：删除一个meta data 项不会删除时间序列的数据点。这个操作既不会移除UID 分配，同时也不会移除相关UID meta对象。
1. Verbs
- GET 查看一或多个
TS meta data - POST 仅仅更新提供的字段
- PUT 覆写所有用户可配置的meta data字段
- DELETE 删除TS meta data
2. GET Requests
一个GET请求能够查找TS meta对象，为一个或者多个时间序列，如果它们存在与存储系统中。两种类型的查询是被支持的：
- tsuid 单个十六进制的TSUID可能被应用，并且一个meta data 对象将会被返回。结果将会包涵单个对象。
- metric 与数据点查询相似，你能应用一个metric并且已到多个tag pair。任何TS meta data匹配于查询的都将被返回。结果将会是一或多个对象的数组。仅仅metric 查询被应用于一次调用，并且通配符或者分组符是不被支持的。
2.1 Example TSUI GET Request
http://localhost:4242/api/uid/tsmeta?tsuid=00002A000001000001
2.2 Example Metric GET Request
http://localhost:4242/api/uid/tsmeta?m=sys.cpu.nice&dc=lga
3. POST/PUT Requests
默认情况下，你能仅仅写数据到一个TS meta 对象，如果该对象已经存在的话。TS meta data被创建通过meta sync CLI命令或者实时的当数据点被写入的时候。如果你尝试写数据到tsmeta endpoint，为一个不存在的TSUID时，一个错误将会被返回，并且不会存储任何的数据。
一个请求中可以包含的字段有：
3.1 Note
自定义的字段不能通过查询字符串传递。你必须使用POST或者PUT方法
3.2 warning
如果你使用PUT方式请求，你没有应用的任何字段将会被覆写成他们本来的默认值。例如：description字段将会被设置成一个空字符串，同时custom字段将会被重置成null。
在opentSDB 2.1中，你可能应用一个metric 样式的查询，如果UID存在，对于给定的metric以及tags，一个新的TS meta对象将会被存储。数据可能被应用通过POST针对上述字段，作为一个正常的请求，然后tsuid字段必须是留空。另外，两个查询字符串必须被应用：
- m - 与GET请求或者数据点查询相同，
m代表A metric 以及tags - create - 一个值为true的标签
例如：
http://localhost:4242/api/uid/tsmeta?display_name=Testing&m=sys.cpu.nice{host=web01,dc=lga}&create=true&method_override=post 如果一个TS meta对象已经存在，对于给出的metric和tags，字段将会被更新或者覆写。
4.1 Example POST or PUT Request
查询字符串
Json 内容
{
"tsuid":"00002A000001000001",
"displayName":"System CPU Time for Webserver 01",
"custom": {
"owner": "Jane Doe",
"department": "Operations",
"assetTag": "12345"
}
}4.2 Example DELETE Request
查询字符串
http://localhost:4242/api/uid/tsmeta?tsuid=00002A000001000001&method_override=delete
{
"tsuid":"00002A000001000001"
}5. Response
一个成功的GET,POST,PUT请求的响应将会返回完整的TS meta 数据对象带有任何给定的变化。成功的DELETE调用将会返回一个204 状态码，并且没有任何内容。当修改数据时，如果任何的状态是存在的。例如：调用没有提供任何存储的数据，响应将会是304，不带有任何的内容。如果请求的TSUID不存在与系统中，一个404将会被返回，同时伴有一个错误消息。如果无效的数据被应用，一个错误将会被返回。
除了其他字段之外，所有请求字段都将显示在响应中：
5.1 Example Response
{
"tsuid": "00002A000001000001",
"metric": {
"uid": "00002A",
"type": "METRIC",
"name": "sys.cpu.0",
"description": "System CPU Time",
"notes": "",
"created": 1350425579,
"custom": null,
"displayName": ""
},
"tags": [
{
"uid": "000001",
"type": "TAGK",
"name": "host",
"description": "Server Hostname",
"notes": "",
"created": 1350425579,
"custom": null,
"displayName": "Hostname"
},
{
"uid": "000001",
"type": "TAGV",
"name": "",
"description": "Website hosting server",
"notes": "",
"created": 1350425579,
"custom": null,
"displayName": "Web Server 01"
}
],
"description": "Measures CPU activity",
"notes": "",
"created": 1350425579,
"units": "",
"retention": 0,
"max": "NaN",
"min": "NaN",
"custom": {
"owner": "Jane Doe",
"department": "Operations",
"assetTag": "12345"
},
"displayName": "",
"dataType": "absolute",
"lastReceived": 1350425590,
"totalDatapoints", 12532
}6.实战案例
笔者在自己的openTSDB测试集群测试http://192.168.211.4:4399/api/uid/tsmeta?m=test_meta地址，得到数据如下：
[
{
"tsuid": "000005000003000005",
"metric": {
"uid": "000005",
"type": "METRIC",
"name": "test_meta",
"description": "",
"notes": "",
"created": 0,
"custom": null,
"displayName": ""
},
"tags": [
{
"uid": "000003",
"type": "TAGK",
"name": "accessNumber",
"description": "",
"notes": "",
"created": 0,
"custom": null,
"displayName": ""
},
{
"uid": "000005",
"type": "TAGV",
"name": "cs",
"description": "",
"notes": "",
"created": 0,
"custom": null,
"displayName": ""
}
],
"description": "",
"notes": "",
"created": 1541500656,
"units": "",
"retention": 0,
"max": "NaN",
"min": "NaN",
"displayName": "",
"dataType": "",
"lastReceived": 1541502954,
"totalDatapoints": 224
},
{
"tsuid": "000005000003000008",
"metric": {
"uid": "000005",
"type": "METRIC",
"name": "test_meta",
"description": "",
"notes": "",
"created": 0,
"custom": null,
"displayName": ""
},
"tags": [
{
"uid": "000003",
"type": "TAGK",
"name": "accessNumber",
"description": "",
"notes": "",
"created": 0,
"custom": null,
"displayName": ""
},
{
"uid": "000008",
"type": "TAGV",
"name": "firminal",
"description": "",
"notes": "",
"created": 0,
"custom": null,
"displayName": ""
}
],
"description": "",
"notes": "",
"created": 1541500656,
"units": "",
"retention": 0,
"max": "NaN",
"min": "NaN",
"displayName": "",
"dataType": "",
"lastReceived": 1541502955,
"totalDatapoints": 224
}
]
