Noun Interpretation

Before using TSDB API, users need to understand the core Concept of TSDB.

Calling Methods

Overview

TSDB API is designed in a Restful style, and each API function (also called a resource) is uniquely determined using a URI (Universal Resource Identifier). The request method for resources is to send standard HTTP requests, such as GET, PUT, POST, etc., to the URI corresponding to the resources. At the same time, the request needs to abide by the signature algorithm and contain agreed request parameters.

General Conventions

• Use UTF-8 for all codes
• The date format is yyyy-MM-dd, for example,2015-08-10
• Adopt the time format UTC format: yyyy-MM-ddTHH: mm: ssZ, such as 2015-08-20T01: 24:32Z

• Treat application/JSON as the content-type ; charset=UTF-8

  • Enclose key of type object in double quotation marks (")
  • Represent key of type object with lowerCamelCase

Public Request Header

Public Response Header

Response States Code

The returned response status code follows 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 actions must be taken in order to complete the request.
• 4xx: Client Error - The request contains the wrong syntax or cannot be fulfilled.
• 5xx: Server Error - The server failed to fulfill a valid request.

HTTP Request Body

TSDB service requires that details of one request shall be described with the help of JSON structure.

example

The following is a standard request message body format when writing to data point:

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

HTTP Response

TSDB service uses the JSON-formatted message body as the return format of HTTP response.

example

The following is a standard request response to get the metric list:

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

General Error Return Format

When an error occurs on the calling interface, the generic error format is returned. Http's return states code is 4xx or 5xx, and the returned message body will include unique global requests, error codes, and error messages. The caller can locate the problem according to the error code and error information. When you cannot determine the cause of the error, you can send a ticket to contact the technicians of Baidu and provide a request id to solve the problem quickly.

Definition of message body

Return examples

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

Signature Authentication

TSDB API authenticates every access request to ensure user security. Access Key and request signature are used for security certification. The Access Key consists of an Access Key ID and a Secret Access Key, both of which are strings and granted to Baidu AI Cloud users. Access Key ID is used to indicate the user. Access Key Secret is the key used to encrypt the signature string and to verify the signature string at the server end, so it must be strictly kept confidential.

In response to every HTTP request, the user needs to generate a signature string according to the method mentioned below and put the authentication string into the Authorization header field requested by HTTP.

Signature String Format

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

Wherein:

• The version number is a positive integer and currently has a value of 1.
• Timestamp is the time when the signature is generated. The time format conforms to the General Appointment. ExpireTime represents the signature's expiration date, in seconds, calculated from the time specified by timestamp.
• SignedHeaders is the list of header fields involved in the signature algorithm The header domain names are separated by semicolons （;）, such as host; X-bce-date. The list is in lexicographic order. When signedHeaders is empty, the default value is taken.
• The signature is a hexadecimal representation of a 256-bit signature and consists of 64 lowercase letters. The generation method is given by the following Signature generation algorithm.

Signature Generation Algorithm

See Authorization Mechanism for a specific introduction of signature generation algorithm.

Multi-Region Selection

Region represents an independent region and is an important concept in Baidu AI CLOUD. Please refer to the Region selection instructions. Except for a few services in Baidu AI CLOUD, such as account services, which are globally valid, the vast majority of services are isolated between regions. The independent deployment of services in each region does not affect each other. Sharing data between services needs to be done through explicit copying. Referencing a region in the API must use its ID. TSDB currently supports http and https calls.

Service Domain Name

Data API service domain name, in which {database-name} is the name of the database.

Management API service domain name is

Access data APIs via IP

Through the above service domain name, you can know that the data APIs distinguish the time series databases from each via the domain name's prefix. Taking the data point write as an example, the head information is as follows:

    POST /v1/datapoint HTTP/1.1
    HOST: {database-name}.tsdb.iot.gz.baidubce.com
    Authorization: {authorization}
    Content-Type: application/json; charset=utf-8
    x-bce-date: 2016-06-08T16:49:51Z
    

During access to the time series database service using the IP, the API uses the url parameter to differentiate the time series databases from each other. The format is database={database-name}. Similarly, taking the data point write as an example, the head information is as follows:

    POST /v1/datapoint?database={database-name} HTTP/1.1
    HOST: {ip}
    Authorization: {authorization}
    Content-Type: application/json; charset=utf-8
    x-bce-date: 2016-06-08T16:49:51Z