openTSDB详解之/api/uid/uidmeta-CFANZ编程社区

openTSDB详解之`/api/uid/uidmeta`

本文译自 http://opentsdb.net/docs/build/html/api_http/uid/uidmeta.html

1. /api/uid/uidmeta

这个端点允许编辑或者删除uid meta data信息，这是与metrics,tag names, 以及 tag values相联系的meta data。一些字段可以通过TSD去设置，其它的可以能够被用户设置。当使用post方法时，只存储与请求一起提供的字段。 未包含的现有字段会单独保留。使用 put 方法将会使用给出的值覆写所有用户可变的字段或者当一个字段值没有提供时使用默认值。

Note

删除一个meta data条目不会删除 UID 分配，同时也不会删除任何数据点，或者是时间序列的信息。删除操作仅仅删除指定的meta data对象，而不是真实值。如果你查询相同的uid，你将看到带有空字段的默认meta data。

1.1 Verbs

GET ：仅仅查询字符串
POST : 仅仅更新提供的字段
PUT : 覆写所有用户配置的元数据字段
DELETE : 删除UID meta data

1.2 Requests

可以随请求的字段包括:

Name	Data Type	Required	Description	Default	QS	RW	Example
uid	String	Required	A hexadecimal representation of the UID		uid	RO	00002A
type	String	Required	The type of UID, must be metric, tagk or tagv		type	RO	metric
description	String	Optional	A brief description of what the UID represents		description	RW	System processor time
displayName	String	Optional	A short name that can be displayed in GUIs instead of the default name		display_name	RW	System CPU Time
notes	String	Optional	Detailed notes about what the UID represents		notes	RW	Details
custom	Map	Optional	A key/value map to store custom fields and values	null	RW	See Below

1.2.1 note

自定义的字段不能通过查询字符串传递。你必须使用POST或者PUT动作。

1.2.2 warning

如果你使用put方法请求，请求中不提供的任何字段都将被其默认值覆盖。例如，description字段将会被设置成空字符串，同时 custom字段将会被重置为空。

1.3 Example GET Request

http://localhost:4242/api/uid/uidmeta?uid=00002A&type=metric

1.4 Example POST or PUT Request

Query String
http://localhost:4242/api/uid/uidmeta?uid=00002A&type=metric&method=post&display_name=System%20CPU%20Time
JSON Content

{
    "uid":"00002A",
    "type":"metric",
    "displayName":"System CPU Time",
    "custom": {
        "owner": "Jane Doe",
        "department": "Operations",
        "assetTag": "12345"
    }
}

1.5 Example DELETE Request

Query String
http://localhost:4242/api/uid/uidmeta?uid=00002A&type=metric&method=delete
JSON Content

{
    "uid":"00002A",
    "type":"metric"
}

1.6 Response

GET,POST,PUT 方法的一个成功的响应将会返回所有的UID meta data对象带有给定更改。成功的DELETE调用将会返回一个204状态码并且没有任何内容。当修改数据时，如果发生任何改变，例如：调用没有提供任何存储数据，响应将会是304，且不带有任何内容。如果请求UID不存在于系统中，一个404将会被返回，且不带有任何错误消息。如果无效的数据被提供，那么将会返回一个错误。

除了其它的一些字段，所有的请求字段都将会在响应中显示。

openTSDB详解之/api/uid/uidmeta_jar

1.7 Example Response

{
    "uid": "00002A",
    "type": "TAGV",
    "name": "web01.mysite.com",
    "description": "Website hosting server",
    "notes": "This server needs a new boot disk",
    "created": 1350425579,
    "custom": {
        "owner": "Jane Doe",
        "department": "Operations",
        "assetTag": "12345"
    },
    "displayName": "Webserver 01"
}

2. 实战案例

这里笔者结合我自己的opentsdb系统。实战操练一下这个http api。

uri1: http://192.168.211.4:4399/api/uid/uidmeta?uid=000001&type=tagk但是有读者可能有疑问，你怎么知道这个tagk的uid为000001？有两种方法可以推导出这个uid=000001是存在的。
访问hbase的底层表tsdb-uid表，从中可以看到这个值是否存在
因为opentsdb的每个uid（包括metric，tag k ，tag v的uid）都是从1开始增长的，所以这里的uid=000001是肯定存在的。【这里的uid位数我是通过document推导出来的，至于为什么是六位数，我暂不清楚，会跟字节数有关系么？】如果将这个uid=000001替换成0x000001，则会抛出错误

java.lang.RuntimeException: java.lang.IllegalArgumentException: contains illegal character for hexBinary: 0x000001
  at net.opentsdb.tsd.UniqueIdRpc.handleUIDMeta(UniqueIdRpc.java:177) ~[tsdb-2.3.0.jar:]
  at net.opentsdb.tsd.UniqueIdRpc.execute(UniqueIdRpc.java:61) ~[tsdb-2.3.0.jar:]
  at net.opentsdb.tsd.RpcHandler.handleHttpQuery(RpcHandler.java:283) [tsdb-2.3.0.jar:]
  at net.opentsdb.tsd.RpcHandler.messageReceived(RpcHandler.java:134) [tsdb-2.3.0.jar:]
  at org.jboss.netty.channel.SimpleChannelUpstreamHandler.handleUpstream(SimpleChannelUpstreamHandler.java:70) [netty-3.9.4.Final.jar:na]
  ····