GB/T 31916.5-2015Information technology—Cloud data storage and management—Part 5: Key-Value based cloud data management application interface (English PDF)

3.1 Terms and Definitions

What is defined in GB/T 31916, and the following terms and definitions are applicable to this document.

3.1.1 Key-Value Based Cloud Data Management

Key-Value based cloud data management refers to a data management mode, which organizes data through Key-Value data model and externally provides operation of various data objects in Key-Value data model through the mode of service.

5.1 Overview

General requirements of Key-Value based cloud data management application interface include 8 items of content: interface protocol, identity security management, data consistency requirement, description of status code message, supplementary error message, public request header, public response header and description of error message. Specifically speaking, 4 items of requirements (interface protocol, identity security management, description of status code message and description of error message) can be found in corresponding sections in GB/T 31916.1.

5.2 Requirement of Data Consistency

In order to guarantee data’s BASE characteristic, cloud data management shall satisfy the requirement of final data consistency. Key-Value based cloud data management should satisfy the requirement of strong data consistency. When availability and fault tolerance are playing a dominant role, it may be degraded into the requirement of final data consistency.

NOTE: data management system has two consistency requirements, namely, strong consistency and final consistency. In order to guarantee data’s ACID characteristic, relational database management system shall satisfy the requirement of strong data consistency. Strong consistency means after data updating is completed, any subsequent access will return updated value. Final consistency: storage system […]

6.2 List Out all the Tables under the Account

6.2.1 Functional description

List out the name of all the tables under the given account.

The result data set is constituted of the name of multiple tables. The result data set shall be in XML format (see GB/T 18793-2002); return to the client-side through response message body.

6.2.2 Definition of request

Definition of request shall be expressed in:

6.2.3 Request URL

Request URL shall be expressed in:

In which, [Account] expresses account ID.

6.2.4 Request message header

Define it in accordance with public request header.

6.2.5 Request message body

6.4.2 Definition of request

Definition of request shall be expressed in:

6.4.3 Request URL

In which, [Account] expresses account ID; [Table] expresses table name.

6.4.4 Request message header

Define it in accordance with the definition of public request header.

6.4.5 Request message body

Null.

6.4.6 Response status code

Status code includes: 204, 400, 401, 404, 405, 408, 500, 501 and 503.

6.4.7 Response message header

Define it in accordance with public response header.

6.4.8 Response message body

When 204 is returned, there is no message body.

When 400 is returned, error name included in the message body is one of the following:

When 401 is returned, error name included in the message body is one of the following:

When 404 is returned, error name included in the message body is:

When 405 is returned, error name included in the message body is:

When 408 is returned, error name included in the message body is:

When 500 is returned, error name included in the message body is:

When 501 is returned, error name included in the message body is:

6.5.9 Examples

Please refer to Example 1 for request message.

Example 1:

6.6.4 Request message header

User needs to appoint Content-type.

6.6.5 Request message body

User-defined.

6.6.6 Response status code

Status code includes 201, 204, 400, 401, 404, 405, 408, 409, 413, 415, 500, 501 and

503.

If the creation of metadata is successful, response status code shall be 201. If the update of metadata is successful, response status code is 204.

6.6.7 Response message header

Define it in accordance with public response header.

6.6.8 Response message body

When 201 is returned, there is no message body.

When 204 is returned, there is no message body.

When 400 is returned, error name included in the message body is one of the following:

When 401 is returned, error name included in the message body is one of the following:

When 404 is returned, error name included in the message body is:

When 405 is returned, error name included in the message body is:

6.7.2 Definition of request

Definition of request shall be expressed in:

6.7.3 Request URL

Request URL shall be expressed in:

In which, [Account] expresses account ID; [Table] expresses table name.

6.7.4 Request message header

Define it in accordance with the definition of public request header.

6.7.5 Request message body

Information that request message body shall include is shown in Table 5.

Table 5 -- Information of Request Message Body

Name Type Description

Selection

Status

Label

Include all the rows of insert/update data;

Parent tag: Null.

Required

Label

Include the row key of all the rows of insert/update data;

Parent tag:

Required

Character

String

Appoint to create or update column in a certain row. If row key already exists, then, update data. If row key does not exist, then, insert a new row;

Parent tag:

Required […]

6.8 Delete Data

6.8.1 Functional description

Delete one or multiple columns from a certain row or multiple rows.

The input data set provided by user is constituted of multiple rows. Each row includes row key, column name and time stamp (optional). Data set shall be in XML format, which shall be transmitted to the server-side along with the request message body.

In terms of a certain row of delete data, when row key is merely included: if the row key exists in the target data table, then, delete all the columns in that row; if this row does not exist, then, this operation fails.

In terms of a certain row of delete data, when row key and several column names are included and row key exists in the target data table: if a certain column exists, then, delete this column; if a certain column does not exist, then, this operation fails.

If time stamp is set up under a certain column name of a certain row of delete data, then, delete all the column value versions that are earlier than the appointed time stamp. If time stamp is not set up, then, delete all the data versions.

6.8.2 Definition of request

Definition of request shall be expressed in:

6.8.3 Request URL

Request URL shall be expressed in:

In which, [Account] expresses account ID; [Table] expresses table name.

6.8.4 Request message header

Define it in accordance with public request header.

6.8.5 Request message body

Information that request message body shall include is shown in Table 6.

6.9.2 Definition of request

Definition of request shall be expressed in:

6.9.3 Request URL

Request URL shall be expressed in:

In which, [Account] expresses account ID; [Table] expresses table name.

6.9.4 Request message header

Define it in accordance with public request header.

6.9.5 Request message body

Information that request message body shall include is shown in Table 7.

Table 7 -- Information of Request Message Body

Name Type Description

Selection

Status

Label

Include all the rows to be acquired;

Parent tag: Null.

Required

Label

Include the row key of all the rows to be acquired;

Parent tag:

Required […]

6.10 Data Query through Conditional Expression

6.10.1 Functional description

Adopt a set of conditional expressions to inquire a certain database table; return rows that satisfy the condition. Multiple conditional expressions shall be connected through operator “AND” or “OR”. An example of conditional expression is demonstrated below.

Example:

In query conditions, if the appointed column does not exist, then, conditional expression returns null.

In query conditions, if the time stamp of column is appointed, then, column value involved in the logic operation is the latest version before the time stamp. If this version does not exist, then, it is equivalent to the nonexistence of the column. If the time stamp of column is not appointed, then, column value involved in the logic operation is the latest version.

The result data set is constituted of multiple rows. Each row includes row key and value of specific column. In terms of each row, by default, row key returns the result, while by default, column does not return the result (unless it is explicitly appointed that this column needs return). The result data set shall be in XML format, which shall be returned to the server-side along with the response message body.

In the appointed return column, if this column does not exist in a certain row, then, this row shall not include this column.

In the definition of return column, if the time stamp of column is appointed, then, the returned column value shall be the latest version before that time stamp; if this version does not exist, then, it is equivalent to the nonexistence of the column. If the time stamp of column is not appointed, then, the returned column value shall be the latest version.

Query request can appoint the size and offset of the result set, namely, the row count in the last returned result, so as to implement page-by-page query. This function may also be implemented by restricting the data volume that the client-side may have access to at a time, and simultaneously, adding an identifier of unfinished data to the response message. This Part does not stipulate relevant implementation details.

When the size of the result set is not appointed, and the query result exceeds the maximum result set size previously set up by the cloud storage system, then, return the maximum row count of result set; and the response status code shall be 206.

Otherwise, return the appointed row count of result set; and the response status code […]