介绍
所有文档

          时序时空数据库 TSDB

          介绍

          名词解释

          在使用TSDB API前,用户需了解TSDB相关的核心概念

          调用方式

          概述

          TSDB API的设计采用了Restful风格,每个API功能(也可以称之为资源)都使用URI(Universal Resource Identifier)来唯一确定。对资源的请求方式是通过向资源对应的URI发送标准的 HTTP 请求,比如 GET、PUT、POST等,同时,请求需要遵守签名算法,并包含约定的请求参数。

          通用约定

          • 所有编码都采用UTF-8
          • 日期格式采用yyyy-MM-dd方式,如2015-08-10
          • 时间格式采用UTC格式:yyyy-MM-ddTHH:mm:ssZ, 如2015-08-20T01:24:32Z
          • Content-type为application/json; charset=UTF-8

            • object类型的key必须使用双引号(")括起来
            • object类型的key必须使用lowerCamelCase表示

          公共请求头

          头域(Header) 是否必须 说明
          Authorization 必须 包含Access Key与请求签名
          Host 必须 包含API的域名
          x-bce-date 必须 表示时间的字符串,符合时间格式要求
          Content-Type 可选 application/json; charset=utf-8

          公共响应头

          头域(Header) 说明
          Content-Type 只支持JSON格式,application/json; charset=utf-8
          x-bce-request-id TSDB后端生成,并自动设置到响应头域中

          响应状态码

          返回的响应状态码遵循RFC 2616 section 6.1.1

          • 1xx: Informational - Request received, continuing process.
          • 2xx: Success - The action was successfully received, understood, and accepted.
          • 3xx: Redirection - Further action must be taken in order to complete the request.
          • 4xx: Client Error - The request contains bad syntax or cannot be fulfilled.
          • 5xx: Server Error - The server failed to fulfill an apparently valid request.

          请求消息体格式(HTTP Request Body)

          TSDB服务要求使用JSON格式的结构体来描述一个请求的具体内容。

          示例

          以下是一个标准的写入data point时的请求消息体格式:

          {
              "datapoints": [{
                  "metric": "cpu_idle",
                  "tags": {
                      "host": "server1",
                      "rack": "rack1"
                  },
                  "timestamp": 1465376157007,
                  "value": 51
              }]
          }

          请求返回格式(HTTP Response)

          TSDB服务均采用JSON格式的消息体作为响应返回的格式。

          示例

          以下是一个标准的获取metric列表的请求返回:

          {
              "metrics": [
                  "cpu_idle",
                  "mem_used"
              ]
          }

          通用错误返回格式

          当调用接口出错时,将返回通用的错误格式。Http的返回状态码为4xx或5xx,返回的消息体将包括全局唯一的请求、错误代码以及错误信息。调用方可根据错误码以及错误信息定位问题,当无法定位到错误原因时,可以发工单联系百度技术人员,并提供requestid以便于快速地帮助您解决问题。

          消息体定义

          参数名 类型 说明
          requestId String 请求的唯一标识
          code String 错误类型代码
          message String 错误的信息说明

          错误返回示例

          {
              "requestId": "47e0ef1a-9bf2-11e1-9279-0100e8cf109a",
              "code":"NoSuchKey",
              "message":"The resource you requested does not exist"   
          } 

          签名认证

          TSDB API会对每个访问的请求进行身份认证,以保障用户的安全。安全认证采用Access Key与请求签名机制。Access Key由Access Key ID和Secret Access Key组成,均为字符串,由百度智能云官方颁发给用户。其中Access Key ID用于标识用户身份,Access Key Secret 是用于加密签名字符串和服务器端验证签名字符串的密钥,必须严格保密。

          对于每个HTTP请求,用户需要使用下文所描述的方式生成一个签名字符串,并将认证字符串放在HTTP请求的Authorization头域里。

          签名字符串格式

          bce-auth-v{version}/{accessKeyId}/{timestamp}/{expireTime}/{signedHeaders}/{signature}

          其中:

          • version是正整数,目前取值为1。
          • timestamp是生成签名时的时间。时间格式符合通用约定
          • expireTime表示签名有效期限,单位为秒,从timestamp所指定的时间开始计算。
          • signedHeaders是签名算法中涉及到的头域列表。头域名字之间用分号(;)分隔,如host;x-bce-date。列表按照字典序排列。当signedHeaders为空时表示取默认值。
          • signature是256位签名的十六进制表示,由64个小写字母组成,生成方式由如下签名生成算法给出。

          签名生成算法

          有关签名生成算法的具体介绍,请参看鉴权认证机制

          多区域选择

          Region代表着一个独立的地域,是百度智能云中的重要概念,请参考区域选择说明。百度智能云中的服务除了极少数如账号服务全局有效之外,绝大部分服务都是区域间隔离的。每个区域的服务独立部署互不影响。服务间共享数据需要通过显式拷贝完成。在API中引用区域必须使用其ID。目前TSDB支持http和https调用。

          服务域名

          数据API接口服务域名,其中{database-name}为数据库名称。

          区域 ID 域名 协议
          华北-北京 bj {database-name}.tsdb.iot.bj.baidubce.com http和https
          华南-广州 gz {database-name}.tsdb.iot.gz.baidubce.com http和https

          管理API接口服务域名为

          区域 ID 域名 协议
          华北-北京 bj tsdb.bj.baidubce.com http和https
          华南-广州 gz tsdb.gz.baidubce.com http和https
          上一篇
          Python-SDK
          下一篇
          数据API接口说明