GB/T 31916.3-2018 English PDF (GBT31916.3-2018)

This Part of GB/T 31916 provides an architecture of distributed file storage; stipulates general requirements and application interface of distributed file storage. This Part is applicable to the design, development, testing and application of distributed file storage.

GB/T 31916.3-2018
NATIONAL STANDARD OF THE
PEOPLE’S REPUBLIC OF CHINA
ICS 35.100.05
L 79
Information Technology - Cloud Data Storage and
Management - Part 3: Distributed File Storage
Application Interface
ISSUED ON: JUNE 7, 2018
IMPLEMENTED ON: JANUARY 1, 2019
Issued by: State Administration for Market Regulation;
Standardization Administration of the People’s Republic of
China.
Table of Contents
Foreword ... 5
1 Scope ... 6
2 Compliance ... 6
3 Normative References ... 6
4 Terms, Definitions and Abbreviations ... 7
4.1 Terms and Definitions ... 7
4.2 Abbreviations ... 7
5 Interface Positioning and System Structure of Distributed File Storage ... 7 5.1 Interface Positioning of Distributed File Storage ... 7
5.2 System Structure of Distributed File Storage ... 8
6 General Requirements of Application Interface ... 9
6.1 Overview ... 9
6.2 Naming Rules ... 9
6.3 Supplementary Error Message ... 10
6.4 Public Request Header ... 10
6.5 Public Response Header ... 10
7 Requirements of File Interface ... 10
7.1 Overview ... 10
7.2 Create File ... 11
7.3 Delete File ... 14
7.4 Upload File ... 16
7.5 Download File ... 19
7.6 Append File ... 22
7.7 Copy File ... 24
7.8 Rename File ... 27
7.9 View File Status ... 29
7.10 Modify File Attribute ... 32
7.11 File Search ... 35
7.12 File Read ... 37
7.13 File Write ... 40
8 Requirements of Folder Interface ... 42
8.1 Overview ... 42
8.2 Create Folder ... 42
8.3 Delete Folder ... 45
8.4 Upload Folder ... 47
8.5 Download Folder ... 50
8.6 Copy Folder ... 52
8.7 Rename Folder ... 55
8.8 View Folder Status ... 57
8.9 Modify Folder Attribute ... 59
8.10 Folder Search ... 62
8.11 List Folder Content ... 64
9 Requirements of Recycle Bin Interface ... 66
9.1 Overview ... 66
9.2 Recover Files in Recycle Bin ... 67
9.3 Query Files in Recycle Bin ... 69
9.4 Final Delete Files in Recycle Bin ... 71
9.5 Clear Trash ... 73
9.6 Recover All ... 75
10 Requirements of Extended Attribute Interface ... 77
10.1 Overview ... 77
10.2 Set Extended Attribute ... 77
10.3 Delete Extended Attribute ... 80
10.4 Read Extended Attribute ... 82
10.5 List Extended Attribute ... 85
11 Requirements of Snapshot Interface ... 87
11.1 Overview ... 87
11.2 Create Snapshot ... 87
11.3 Delete Snapshot ... 89
11.4 List Snapshot ... 91
11.5 Rename Snapshot ... 94
12 Requirements of Access Control List Interface ... 96
12.1 Overview ... 96
12.2 Add ACL Rule ... 97
12.3 Read ACL ... 99
12.4 Modify ACL Rule ... 102
12.5 Delete ACL ... 105
12.6 Delete ACL Rule ... 106
12.7 Delete Default ACL Rule ... 108
Appendix A (normative) Distributed File Storage Management Interface ... 111 Appendix B (normative) Supplementary Error Message ... 130
Information Technology - Cloud Data Storage and
Management - Part 3: Distributed File Storage
Application Interface
1 Scope
This Part of GB/T 31916 provides an architecture of distributed file storage; stipulates general requirements and application interface of distributed file storage. This Part is applicable to the design, development, testing and application of distributed file storage.
2 Compliance
The interface defined in this Part can be divided into required and optional. Specifically speaking, file interface, folder interface and recycle bin interface are required, while others are optional. Parameters commanded by each interface might contain required parameters and optional parameters. Compliance contains the following
circumstances:
a) A system implements all the interfaces (including required interfaces and optional interfaces), which may be claimed as complete compliance with this Part.
b) A system implements all the required interfaces, which may be claimed as compliance with this Part.
c) A system does not implement all the required interfaces, which may be claimed as non-compliance with this Part.
3 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 31916.1-2015 Information Technology - Cloud Data Storage and Management - Figure 2 -- General Architecture of Distributed File Storage
Metadata server: provide directory information of the whole file system and manage various storage servers; serve as the core of the whole file system. Metadata server maintains a table, which records all the file names and corresponding relations with the file storage address in the file system. Metadata server also has the function of managing the various storage servers. There may be one or multiple metadata servers. Data storage server: used to store actual file data. All the distributed file storage needs at least one storage server. After inquiring the actual storage address of a certain file, the client-side would directly communicate with the storage server, so as to acquire the file.
Monitoring server: provide management functions like service monitoring and log recording of the whole distributed file storage. It can provide management support to the whole service operation. In certain distributed file storage, the function of monitoring server is integrated into metadata server.
Client-side: host that adopts distributed file storage for storage and access is called the client-side of distributed file storage. After successfully connecting with the file system, it can implement operation of the file system through application interface. 6 General Requirements of Application Interface
6.1 Overview
General requirements of distributed file storage application interface include 8 items of content, namely, interface protocol, identity security management, naming rules, 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 parts in GB/T 31916.1-2015.
6.2 Naming Rules
Naming rules of all the files, folds and paths are as follows:
---Name may adopt letters, numbers, underlines (_), short horizontal lines (-) and Chinese characters.
---Name shall start with letters, numbers or Chinese characters.
---The maximum length of name may allow 256 characters.
Please refer to RFC 7159 for the part that needs naming in all the responses. number be larger than or equals to the system’s
lowest file replication number. Default
value is system’s lowest file replication
number.
Retention time
in recycle bin String
Positive integer + unit; an example of
format: 12 min. Unit includes (s), (min),
(h), (d) and (M). The maximum value is 24
months. Default value is 1 day.
Optional
7.2.6 Request message body
Null.
7.2.7 Response status code
Please refer to Table 4 for response status code and its description.
Table 4 -- Response Status Code
Status
Code Description
200 OK; creation is successful
400 InvalidFileName; file name does not comply with naming rules
400 InvalidFilePermission; file permission parameter is incorrect
400 InvalidFileSize; the size of file creation requested by user is larger than the maximum file size set up by the system 400
InvalidReplicationNumber; the modification of file replication number requested by user is not a positive integer between 0 ~ 512, or is smaller than the system’s lowest file replication number
400 InvalidTrashTime; file retention time does not comply with the format, or exceeds 24 months 401 Unauthorized; user does not input authentication information, or authentication information is incorrect 403 Forbidden; user does not have the permission to create file
404 NoSuchFolder; file path requested by user does not exist
409 FileAlreadyExists; file name created by user is the same as an existing file; file name overwrite is marked as “false” 501 Not Implemented; server does not support this functional interface
7.2.8 Definition of response
Please refer to Table 8 for request message parameters.
Table 8 -- Request Message Parameters
Parameter Name Type Description Selection Status
File name overwrite Int
“0” signifies overwrite is allowed; “1”
signifies overwrite is not allowed; “2”
signifies automatic re-naming into
FileName-1, FileName-2……and so on.
Default value is 1.
Optional
File permission String
“r” signifies readable; “w” signifies
writable; “x” signifies executable. Default
value is rwx.
Optional
Replication
number Short
Positive integer between 0 ~ 512. It shall
be larger than or equals to the system’s
lowest file replication number. Default
value is system’s lowest file replication
number.
Optional
Retention time
in recycle bin String
Positive integer + unit; an example of
format: 12 min. Unit includes (s), (min),
(h), (d) and (M). The maximum value is 6
months. Default value is 1 day.
Optional
7.4.6 Request message body
Please refer to Table 9 for a description of various parameters in request message body.
Table 9 -- Request Message Body
Parameter Name Type Description Selection Status
Location of
local file String
File name shall comply with the file
naming rules described in 6.2 Required
7.4.7 Response status code
Please refer to Table 10 for a description of response status code and its description. Table 10 -- Response Status Code
Status
Code Description
200 OK; upload is successful
400 InvalidFileName; file name does not comply with naming rules
400 InvalidPermission; file permission parameter is incorrect
400 InvalidFileSize; the size of uploaded file requested by user is larger than the In which, [Account] signifies account ID. [Path] signifies the location of file that is about to be downloaded.
7.5.4 Request message header
Range header is optional, in which, [start] signifies the starting byte of transmitted file. [end] signifies the ending byte of transmitted file. Both of them shall be expressed in integer. The remaining shall be defined in accordance with public request header. 7.5.5 Request message parameter
Null.
7.5.6 Request message body
Please refer to Table 12 for a description of various parameters in request message body.
Table 12 -- Request Message Body
Parameter Name Type Description Selection Status
Location of file after
downloading to the
local
String Its name shall comply with the file naming rules described in 6.2 Required Aliasname of file
after downloading String
File name shall comply with the file
naming rules described in 6.2 Optional
7.5.7 Response status code
Please refer to Table 13 for response status code and its description.
Table 13 -- Response Status Code
Status
Code Description
200 OK; downloading is successful
206 Partial Content; downloading of partial file content is successful
400 InvalidFileName; file name does not comply with naming rules
400 InvalidFolderName; user-appointed download path does not comply with naming rules 400 InvalidRange; user-appointed transmission range is beyond the range of file size 401 Unauthorized; user does not input authentication information, or authentication information is incorrect 403 Forbidden; user does not have the permission to read file
404 NoSuchFile; file path requested by user does not exist
404 NoSuchFolder; user’s local path does not exist
Define it in accordance with public request header.
7.8.5 Request message parameters
Please refer to Table 21 for request message parameters.
Table 21 -- Request Message Parameters
Parameter Name Type Description Selection Status
File name overwrite Int
“0” signifies overwrite is allowed; “1”
signifies overwrite is not allowed; “2”
signifies automatic re-naming into
FileName-1, FileName-2……and so on.
Default value is 1.
Optional
7.8.6 Request message body
Please refer to Table 22 for a description of various parameters in request message body.
Table 22 -- Request Message Body
Parameter Name Type Description Selection Status
New name of file String
File name shall comply with the file naming
rules described in 6.2 Required
7.8.7 Response Status Code
Please refer to Table 23 for response status code and its description.
Table 23 -- Response Status Code
Status
Code Description
200 OK; rename is successful
400 InvalidFileName; file name does not comply with naming rules
401 Unauthorized; user does not input authentication information, or authentication information is incorrect 403 Forbidden; user does not have the permission to alter file
404 NoSuchFile; file path requested by user does not exist
409 FileAlreadyExists; new file name is the same as an existing file, and file name overwrite is marked as “1” 501 Not Implemented; server does not support this functional interface
7.8.8 Definition of response
7.10.3 Request URL
In which, [Account] signifies account ID. [Path] signifies the path of file to be modified. 7.10.4 Request message header
Define it in accordance with public request header.
7.10.5 Request message parameters
Null.
7.10.6 Request message body
Please refer to Table 26 for a description of various parameters in request message body.
Table 26 -- Request Message Body
Parameter Name Type Description Selection Status
File permission String
“r” signifies readable; “w” signifies
writable; “x” signifies executable. Default
value is rwx.
Optional
File replication number Int
Positive integer between 0 ~ 512. It shall
be larger than or equals to the system’s
lowest file replication number. Default
value is replication number of original file.
Optional
Retention time
in recycle bin String
Positive integer + unit; an example of
format: 12 min. Unit includes (s), (min),
(h), (d) and (M). The maximum value is 24
months. Default value is the original
trashtime of the file.
Optional
7.10.7 Response status code
Please refer to Table 27 for response status code and its description.
Table 27 -- Response Status Code
Status
Code Description
200 OK; modify attribute is successful
400 InvalidFileName; file name does not comply with naming rules
400 InvalidPermission; file permission parameter is incorrect
400 InvalidReplicationNumber; the modification of file replication number requested by user is not a positive integer between 0 ~ 512, or is smaller than the system’s lowest In which, [Account] signifies account ID. [Path] signifies file path.
7.12.4 Request message header
Define it in accordance with public request header.
7.12.5 Request message parameters
Please refer to Table 32 for request message parameters.
Table 32 -- Request Message Parameters
Parameter Name Type Description Selection Status
Starting
location Long
Non-negative integer, expressed in Byte. It
signifies the starting location of file read. It shall
be less than or equals to file length. Default
value is 0.
Optional
Read
length Long
Non-negative integer, expressed in Byte. It
signifies the length of file read. Default value is
file length.
Optional
7.12.6 Request message body
Null.
7.12.7 Response status code
Please refer to Table 33 for response status code and its description.
Table 33 -- Response Status Code
Status
Code Description
200 OK; read is successful
400 InvalidFileName; appointed file does not comply with naming rules
400 InvalidOffset; starting location is invalid
400 InvalidLength; read length is invalid
401 Unauthorized; user does not input authentication information, or authentication information is incorrect 403 Forbidden; user does not have the permission to read the file
404 NoSuchFile; file requested by user does not exist
501 Not Implemented; server does not support this functional interface
7.12.8 Definition of response
Parameter Name Type Description Selection Status
Write content String Write content Required
7.13.7 Response status code
Please refer to Table 37 for response status code and its description.
Table 37 -- Response Status Code
Status
Code Description
200 OK; write is successful
400 InvalidFileName; appointed file does not comply with naming rules
400 InvalidOffset; starting location is invalid
400 InvalidLength; write length is invalid
401 Unauthorized; user does not input authentication information, or authentication information is incorrect 403 Forbidden; user does not have the permission to write the file
404 NoSuchFile; file requested by user does not exist
501 Not Implemented; server does not support this functional interface
7.13.8 Definition of response
7.13.9 Response message header
Define it in accordance with public response header.
7.13.10 Response message body
Null.
7.13.11 Examples of request and response message
Examples of request message and response message are as follows.
Examples:
Request message:
8.2.4 Request message header
Define it in accordance with public request header.
8.2.5 Request message parameters
Please refer to Table 38 for request message parameters.
Table 38 -- Request Message Parameters
Parameter Name Type Description Selection Status
Folder name String Folder name shall comply with the file naming rules described in 6.2 Required Folder name overwrite Boolean
“true” signifies overwrite is allowed; “false”
signifies overwrite is not allowed. Default
value is false.
Optional
Folder permission String
“r” signifies readable; “w” signifies
writable; “x” signifies executable. Default
value is rwx.
Optional
8.2.6 Request message body
Null.
8.2.7 Response status code
Please refer to Table 39 for response status code and its description.
Table 39 -- Response Status Code
Status
Code Description
200 OK; creation is successful
400 InvalidFolderName; folder name does not comply with naming rules
400 InvalidPermission; folder permission parameter is incorrect
401 Unauthorized; user does not input authentication information, or authentication information is incorrect 403 Forbidden; user does not have the permission to create folder
404 NoSuchFolder; folder path requested by user does not exist
409 FolderAlreadyExists; folder name created by user is the same as an existing folder; folder name overwrite is marked as “false” 501 Not Implemented; server does not support this functional interf...