API接收地址

https://tsdb.qiniu.com

API返回内容

响应报文

• 如果请求成功,返回HTTP状态码200:

HTTP/1.1 200 OK

• 如果请求失败,返回包含如下内容的JSON字符串（已格式化,便于阅读）:

{
    "error":   "<errMsg    string>"
}

• 如果请求包含数据获取,则返回相应数据的JSON字符串；

创建数据仓库

请求语法

POST /v4/repos/<RepoName>
Content-Type: application/json
Authorization: Pandora <auth>
{
    "region": <Region>,
    "metadata":{
        "key1":"value1",
        ...
    }
}

请求内容

示例

curl -X POST https://tsdb.qiniu.com/v4/repos/test_repo \
-H 'Content-Type: application/json' \
-H 'Authorization: Pandora 2J1e7iG13J66GA8vWBzZdF-UR_d1MF-kacOdUUS4:NTi3wH_WlGxYOnXsvgUrO4XMD6Y=' \
-d '{
    "region": "nb", 
    "metadata":{
        "info":"this repo is be for the use of test"
    }
}'

创建序列

请求语法

POST /v4/repos/<RepoName>/series/<SeriesName>
Content-Type: application/json
Authorization: Pandora <auth>
{
    "retention": <Retention>,
    "metadata": {
        "key": "value",
         ...
    }
}

请求内容

示例

curl -X POST https://tsdb.qiniu.com/v4/repos/test_repo/series/test_series \
-H 'Content-Type: application/json' \
-H 'Authorization: Pandora 2J1e7iG13J66GA8vWBzZdF-UR_d1MF-kacOdUUS4:NTi3wH_WlGxYOnXsvgUrO4XMD6Y=' \
{
    "retention": "1d",
    "metadata": {
        "author": "Lynk Lee"
    }
}

数据查询

请求语法

GET /v4/repos/<RepoName>/query?q=<Sql>[&timezone=<TimeZone>]
Authorization: Pandora <auth>

or

POST /v4/repos/<RepoName>/query[?timezone=<TimeZone>]
Content-Type: application/json
Authorization: Pandora <auth>
{
    "sql" : <Sql>
}

or

POST /v4/repos/<RepoName>/query[?timezone=<TimeZone>]
Content-Type: text/plain
Authorization: Pandora <auth>
<Sql>

请求内容

• 查询默认时区为+00或者-00,即utc

• 存储在tsdb中的数据的时间戳都是UTC时间,timezone参数用于指定查询者所在的时区相对UTC时间的偏移量

• TimeZone取值范围为[-12, +14],表示与utc时区的偏移量,如东八区(中国)应写成+08,会将查询范围整体加上8小时,西五区应该写成-05,查询范围的时间则被减去5小时。

举例说明:

1466510400000000000是UTC时间2016-06-21 12:00:00,和东八区时间2016-06-21 20:00:00的unixnano表示

select value from cpu where time > '2016-06-21T12:00:00Z'

当以上查询语句的timezone参数为+08的时候,该sql语句能够检索的数据的时间范围为

(2016-06-21 04:00:00 UTC,当前时间)

当以上查询语句的timezone参数为+00的时候,该sql语句能够检索的数据的时间范围为

('2016-06-21 12:00:00 UTC', 当前时间]

当写入的数据点的时间戳为1466510400000000000的时候,如果想要查到该点,可以

select value from cpu where time = '2016-06-21T12:00:00Z' //timezone=0

或者

select value from cpu where time = '2016-06-21T20:00:00Z' //timezone=8

响应报文

200OK
type QueryRet struct {
    Results []Result     `json:"results,omitempty"`
}
type Result struct {
    Series []Serie      `json:"series,omitempty"`
}
type Serie struct {
    Name    string            `json:"name,omitempty"`
    Tags    map[string]string `json:"tags,omitempty"`
    Columns []string          `json:"columns,omitempty"`
    Values  [][]interface{}   `json:"values,omitempty"`
}

以上是tsdb返回的结果序列化之前的结构体

• 每个QueryRet对应的是一个请求返回的结果
• QueryRet中每个Result对应一条sql的查询结果
• Result中的每个Series对应一个tagSet的结果,即Result每有一个不同的tags组合,就会有一个Serie的结果添加到Result.Seires这个slice中

一个简单的查询,如SELECT value FROM cpu_load_short WHERE region='us-west'结果类似如下json字符串:

{
    "results": [
        {
            "series": [
                {
                    "name": "cpu_load_short",
                    "columns": [
                        "time",
                        "value"
                    ],
                    "values": [
                        [
                            "2015-01-29T21:55:43.702900257Z",
                            0.55
                        ],
                        [
                            "2015-01-29T21:55:43.702900257Z",
                            23422
                        ],
                        [
                            "2015-06-11T20:46:02Z",
                            0.64
                        ]
                    ]
                }
            ]
        }
    ]
}

根据名称查询数据仓库信息

请求语法

GET /v4/repos/<RepoName>
Authorization: Pandora <auth>

响应报文

200 OK
Content-Type: application/json
{
    "name": <RepoName>,
    "region": <Region>,
    "metadata": <Metadata>,
    "createTime": <CreateTime>,
    "deleting": <"true"|"false">
}

• 如果请求成功,且没有数据,则返回一个空列表:

200 OK
Content-Type: application/json
[ ]

响应内容

查询所有数据仓库信息

请求语法

GET /v4/repos
Authorization: Pandora <auth>

响应报文

200 OK
Content-Type: application/json
[
    {
        "name": <RepoName>,
        "region": <Region>,
        "metadata": <Metadata>,
        "createTime": <CreateTime>,
        "deleting": <"true"|"false">
    },
    ...
]

• 如果请求成功,且没有数据,则返回一个空列表:

200 OK
Content-Type: application/json
[ ]

查询某个数据仓库下所有序列信息

请求语法

GET /v4/repos/<RepoName>/series[?showMeta=<true|false>]
Authorization: Pandora <auth>

请求内容

响应报文

200 OK
Content-Type: application/json
[
    {
        "name": <SeriesName>,
        "retention": <Retention>,
        "metadata": <Metadata>, 
        "createTime": <CreateTime>,
        "type":<Type>,
        "deleting": <"true"|"false">
    },
    ...
]

• 如果请求成功,且没有数据,则返回一个空列表:

200 OK
Content-Type: application/json
[ ]

响应内容

更新数据仓库的meta data

请求语法

POST /v4/repos/<RepoName>/meta
Content-Type: application/json
Authorization: Pandora <auth>
{
    "metadata": {
        "key1":"value1",
        ...
    }
}

请求内容

示例

curl -X POST https://tsdb.qiniu.com/v4/repos/test_repo/meta \
-H 'Content-Type: application/json \
-H 'Authorization: Pandora 2J1e7iG13J66GA8vWBzZdF-UR_d1MF-kacOdUUS4:NTi3wH_WlGxYOnXsvgUrO4XMD6Y=' \
-d '{
    "metadata": {
        "author":"Lynk Lee"
    }
}'

删除数据仓库的meta data

请求语法

DELETE /v4/repos/<RepoName>/meta
Authorization: Pandora <auth>

删除数据仓库

请求语法

DELETE /v4/repos/<RepoName>
Authorization: Pandora <auth>

更新序列的meta data

请求语法

POST /v4/repos/<RepoName>/series/<SeriesName>/meta
Content-Type: application/json
Authorization: Pandora <auth>
{
    "metadata": <Metadata>
}

请求内容

删除序列的meta data

请求语法

DELETE /v4/repos/<RepoName>/series/<SeriesName>/meta
Authorization: Pandora <auth>

删除序列

请求语法

DELETE /v4/repos/<RepoName>/series/<SeriesName>
Authorization: Pandora <auth>

错误代码及相关说明

创建、管理相关接口报错

仓库(Repo)层错误

序列(Series)层错误

查询语句相关