PDF GB/T 31916.5-2015 English
Search result: GB/T 31916.5-2015
| Standard ID | Contents [version] | USD | STEP2 | [PDF] delivered in | Name of Chinese Standard | Status |
| GB/T 31916.5-2015 | English | 230 |
Add to Cart
|
0-9 seconds. Auto-delivery.
|
Information Technology - Cloud Data Storage and Management - Part 5: Key-Value Based Cloud Data Management Application Interface
| Valid |
PDF Preview: GB/T 31916.5-2015
GB/T 31916.5-2015: PDF in English (GBT 31916.5-2015) GB/T 31916.5-2015
NATIONAL STANDARD OF THE
PEOPLE’S REPUBLIC OF CHINA
ICS 35.100.05
L 79
Information Technology - Cloud Data Storage and
Management - Part 5: Key-Value Based Cloud Data
Management Application Interface
ISSUED ON: SEPTEMBER 11, 2015
IMPLEMENTED ON: MAY 1, 2016
Issued by: General Administration of Quality Supervision, Inspection and
Quarantine.
Standardization Administration of the People’s Republic of
China.
Table of Contents
Foreword ... 3
1 Scope ... 4
2 Normative References ... 4
3 Terms, Definitions and Abbreviations ... 4
3.1 Terms and Definitions ... 4
3.2 Abbreviations ... 5
4 Key-Value Data Model ... 5
5 General Requirements of Key-Value Based Cloud Data Management
Application Interface ... 6
5.1 Overview ... 6
5.2 Requirement of Data Consistency ... 6
5.3 Supplementary Error Message ... 7
5.4 Public Request Header ... 7
5.5 Public Response Header ... 7
6 Definition of Key-Value Based Cloud Data Management Application Interface
... 7
6.1 Overview ... 7
6.2 List Out all the Tables under the Account ... 8
6.3 Create Table ... 10
6.4 Delete Table ... 11
6.5 Acquire Metadata ... 13
6.6 Add/update Metadata ... 16
6.7 Insert/update Data ... 18
6.8 Delete Data ... 22
6.9 Acquire Data ... 24
6.10 Data Query through Conditional Expression ... 29
Appendix A (normative) Supplementary Error Message ... 35
Information Technology - Cloud Data Storage and
Management - Part 5: Key-Value Based Cloud Data
Management Application Interface
1 Scope
This Part of GB/T 31916 provides Key-Value data model; stipulates general
requirements and definition of Key-Value based cloud data management application
interface.
This Part is applicable to the design, development and application of Key-Value based
cloud data management system.
2 Normative References
The following documents are indispensable to the application of this document. In
terms of references with a specified date, only versions with a specified date are
applicable to this document. In terms of references without a specified date, the latest
version (including all the modifications) is applicable to this document.
GB/T 7408-2005 Data Elements and Interchange Formats - Information Interchange -
Representation of Dates and Times;
GB/T 18793-2002 Information Technology - Extensible Markup Language (XML) 1.0;
GB/T 31916.1 Information Technology - Cloud Data Storage and Management - Part
1: General;
RFC 2616 Hypertext Transfer Protocol HTTP/1.1
3 Terms, Definitions and Abbreviations
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.
Figure 1 -- Key-Value Data Model
Key-Value data model is used to describe entity and its attribute.
NOTE 1: entity is any distinguishable and recognizable objective substance and abstract
incident in the real world, and the relations among the substances.
NOTE 2: attribute is a characteristic of entity. An entity may be described through several
attributes. Attribute includes attribute name and attribute value.
The constituent elements of Key-Value data model include table, row, column and time
stamp. Table is a data set constituted of rows. Each row describes an entity. Different
rows are uniquely identified through different row keys (R). Data in the rows is
constituted of a triad (K, V, T). Specifically speaking, “K” represents column name; “V”
represents column value; “T” represents time stamp. Column name describes entity’s
attribute name; column value describes entity’s attribute value. Time stamp is used to
identify column value’s version information. Through a triad (R, K, T), entity’s attribute
value can be uniquely identified.
5 General Requirements of Key-Value Based Cloud
Data Management Application Interface
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
a) List out all the tables under the account;
b) Create table;
c) Delete table;
d) Acquire metadata;
e) Add/update metadata.
Row-level operation includes:
a) Insert/update data;
b) Delete data;
c) Acquire data;
d) Data query through conditional expression.
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
Delete a table. Rows and columns included in the table will simultaneously be deleted.
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:
Parent tag:
Integral
System metadata: total size (kb) of all data in table;
Parent tag: Optional
Integral
System metadata: size (kb) of all row keys in table;
Parent tag: Optional
Integral
System metadata: size (kb) of all column names in
table;
Parent tag:
Optional
Integral
System metadata: size (kb) of all column values in
table;
Parent tag:
Optional
Time
System metadata: size (kb) of all time stamps in
table;
Parent tag:
Time format shall take GB/T 7408-2005 as a
reference.
Optional
When 400 is returned, error name included in the message body is:
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 406 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:
When 503 is returned, error name included in the message body is:
6.5.9 Examples
Please refer to Example 1 for request message.
Example 1:
In which,
[Account] expresses account ID;
[Table] expresses table name;
[Type] is user-defined request message body type, for example, text/plain, text/xml or
application/json;
[User-defined Metadata in request body] expresses user-defined metadata submitted
by user.
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:
server-side along with the request message body.
In terms of a certain row of insert/update data, if row key does not exist in the target
data table, then, insert this new row into the target data table.
In terms of a certain row of insert/update data, when row key exists in the target data
table: if the appointed column does not exist, then, add a new column to this row and
automatically allocate time stamp; if the appointed column exists, then, update this
column and automatically allocate time stamp.
Data management system needs to restrict the maximum row count in each table, the
maximum column count in each row, or the maximum data volume in each table in the
database. If the insert/update operation exceeds the restriction of data management
system, then, this operation fails.
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
Please refer to Example 2 for response message.
Example 2:
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.
transmitted to the server-side along with the request message body.
In terms of a certain row of request message body, when row key is merely included:
if the row key exists in the target data table, then, return all the columns in that row; if
this row does not exist, then, this operation fails. In terms of a certain row or request
message body, when row key and several column names are included, and the row
key exists in the target data table: if a certain column exists, then, return this column;
if a certain column does not exist, then, this operation fails.
In terms of a certain column name of a certain row of request message body, if time
stamp is not set up, then, return the column value of the latest version; if time stamp is
set up, then, return the column value of the (unique) latest version that is earlier than
the appointed time stamp; if the version does not exist, it is equivalent to the
nonexistence of the column, then, this operation fails.
The result data set is constituted of multiple rows. Each row includes row key, column
name and column value. The result data set shall be in XML format, which shall be
returned to the server-side along with the response message body.
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
......
Source: Above contents are excerpted from the PDF -- translated/reviewed by: www.chinesestandard.net / Wayne Zheng et al.
|