API calls follow the HTTP protocol. Each region uses a different domain name. The specific domain name is cfs{region}.baidubce.com。 The data exchange format is JSON, and all request/response body contents are encoded in UTF-8.The fsId used in the URL parameter is the unique resource ID of the file system
be careful:1. Before using the API interface, please enter the "Real Name Authentication" page for "Enterprise Authentication" or "Personal Authentication" according to the user's actual situation. For detailed operation steps, seeReal name authentication。2. For region information, seeService Domain Name。
API authentication mechanism
Access Key and request signature mechanisms are used for security authentication of all APIs.The Access Key consists of the Access Key ID and the Secret Access Key, both of which are strings.For each HTTP request, generate an authentication string using the algorithm described below.The submitted authentication string is placed in the Authorization header field.The server verifies the correctness of the authentication string according to the generation algorithm.The format of the authentication string isbce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}。
Version is a positive integer.
Timestamp is the UTC time when the signature is generated.
ExpirationPeriodInSeconds indicates the validity period of the signature.
SignedHeaders is the list of header fields involved in the signature algorithm.The header names are separated by semicolons (;), such as host;x-bce-date。The list is arranged lexicographically.(This API signature only uses host and x-bce-date headers)
Signature is the hexadecimal representation of 256 bit signatures, which consists of 64 lowercase letters.
When Baidu Smart Cloud receives the user's request, the system will use the same SK and the same authentication mechanism to generate the authentication string, and compare it with the authentication string contained in the user's request.If the authentication string is the same, the system thinks that the user has the specified operation authority and executes the related operations;If the authentication string is different, the system will ignore the operation and return an error code.
If a request timeout or internal server error is encountered when calling some interfaces, the user may try to resend the request. At this time, the user can avoid creating more resources than expected through the clientToken parameter, that is, ensure the idempotence of the request.
Idempotency is based on clientToken, which is an ASCII string with a length of no more than 64 bits, usually placed in a query string, such ashttp://bcc.bj.baidubce.com/v1/instance?clientToken=be31b98c-5e41-4838-9830-9be700de5a20。
If the user calls the creation interface with the same clientToken value, the server will return the same request result.Therefore, when a user encounters an error and retries, he can ensure that only one resource is created by providing the same clientToken value;If the user provides a used clientToken, but other request parameters (including queryString and requestBody) are different or even the url path is different, the error code of IdempotentParameterMismatch will be returned.
The validity period of the clientToken is 24 hours, subject to the last time the server receives the clientToken.That is, if the client continuously sends the same clientToken, the clientToken will be valid for a long time.
Date and time specification
There are many ways to express date and time.For the sake of uniformity, UTC time shall be used wherever date and time expression is required, unless it is established by convention or has corresponding specificationsISO 8601, and make the following constraints:
The date is always represented by YYYY-MM-DD, for example, 2014-06-01 means June 1, 2014.
The time is expressed in hh: mm: ss mode, and a capital letter Z is added at the end to indicate UTC time.For example, 23:00:10Z means 23:00:10 UTC time.
Where the date and time are combined, add a capital letter T between them. For example, 2014-06-01T23:00:10Z means 23:0:10 UTC time on June 1, 2014.
Request Parameters
The request parameters include the following 4 types:
Parameter type
explain
URI
Usually used to indicate the operation entity, such as PUT/v1/cfs/{fsId}
Query String
Request parameters carried in URL
Header
Incoming through the HTTP header domain, such as x-bce-date
Request Body
Request data body organized by JSON format
Return Value Description
The return value is divided into two forms:
Return content
explain
HTTP Status Code
For example, 200400403404
Response Body
Response data body organized in JSON format
Public request header
The following table lists the common header fields carried by all CFS APIs.The standard header fields of the HTTP protocol are not listed here
HEADER
Must
explain
Authorization
yes
Signature string. For the method of generating signature string, please refer to the authentication mechanism
Content-Type
yes
application/json; charset=utf-8
x-bce-date
Optional
Signature Date
Public response header
The following table lists the common response header fields of all CFS APIs.The standard response header fields of the HTTP protocol are not listed here
HEADER
explain
Content-Type
application/json; charset=utf-8
x-bce-request-id
The requestId of this request
Error code
When an error occurs in the request, the response body returns the detailed error information in the following format:
Parameter name
type
explain
code
String
Error code
message
String
Error description
requestId
String
The requestId of this request
Example:
{"requestId" : "ae2225f7-1c2e-427a-a1ad-5413b762957d","code" : "NoSuchKey","message" : "The resource you requested does not exist"}
BCE public error code
The following table lists the common error codes for all APIs.Each service should customize the error code on this basis.
Code
Message
HTTP Status Code
explain
AccessDenied
Access denied.
403 Forbidden
No permission to access the corresponding resource.
InappropriateJSON
The JSON you provided was well-formed and valid, but not appropriate for this operation.
400 Bad Request
The JSON format in the request is correct, but the semantics do not meet the requirements.For example, a required item is missing or the value type does not match.For compatibility reasons, all unrecognized items should be ignored directly and this error should not be returned.
InternalError
We encountered an internal error. Please try again.
500Internal Server Error
All other undefined errors.It should not be used when there are other types of errors (including general and service customized) that have clear corresponding.
InvalidAccessKeyId
The Access Key ID you provided does not exist in our records.
403 Forbidden
Access Key ID does not exist.
InvalidHTTPAuthHeader
The HTTP authorization header is invalid. Consult the service documentation for details.
400 Bad Request
The format of the Authorization header field is incorrect.
InvalidHTTPRequest
There was an error in the body of your HTTP request.
400 Bad Request
The HTTP body format is incorrect, for example, it does not conform to the specified Encoding.
InvalidURI
Could not parse the specified URI.
400 Bad Request
The URI format is incorrect.For example, the keywords of some service definitions do not match.For problems such as ID mismatch, more specific error codes should be defined, such as NoSuchKey.
MalformedJSON
The JSON you provided was not well-formed.
400 Bad Request
The JSON format is illegal.
InvalidVersion
The API version specified was invalid.
404 Not Found
The version number of the URI is illegal.
OptInRequired
A subscription for the service is required.
403 Forbidden
The corresponding service is not activated.
PreconditionFailed
The specified If-Match header doesn't match the ETag header.
412 Precondition Failed
See ETag for details.
RequestExpired
Request has expired. Timestamp date is XXX.
400 Bad Request
The request timed out.XXX should be changed to the value of x-bce-date.If there is only Date in the request, you need to convert Date to datetime.
IdempotentParameterMismatch
The request uses the same client token as a previous, but non-identical request.
403 Forbidden
The API parameters corresponding to clientToken are different.
SignatureDoesNotMatch
The request signature we calculated does not match the signature you provided. Check your Secret Access Key and signing method. Consult the service documentation for details.
400 Bad Request
The signature attached in the Authorization header field is inconsistent with the server verification.
CFS service error code
Error code
Error description
HTTP status code
semantics
InstanceNotFound
The specified CFS instance does not exist.
404 Not Found
The specified CFS instance does not exist
InvalidFSType
The FS TYPE is invalid.
400 Bad Request
Wrong type of file system
InvalidFSName
The FS NAME is invalid.
400 Bad Request
The file system name does not meet the requirements
InvalidFSProtocol
The FS PROTOCOL is invalid.
400 Bad Request
The file system does not support this protocol
AvailabilityZoneNotFound
The specified availability zone does not exist.
400 Bad Request
The zone set by the user does not exist
InvalidVpcId
The vpc id is invalid.
400 Bad Request
Vpc id error
CreateOrderFail
We encountered an internal error. Please try again.
500 Internal Server Error
Failed to create the order. Please try again later
DuplicateRequest
The request is duplicate.
400 Bad Request
Duplicate request to create file system instance
FsNumQuotaExceeded
The number of CFS exceeded current quota.
413 Request Entity Too Large
CFS quantity exceeds user quota limit
DropCreatingFS
The fs is in creating, can not drop.
400 Bad Request
Cannot delete the file system instance being created
DropMountedFS
The fs has mount target , please drop before clear mount target.
400 Bad Request
File system instances with mount points cannot be deleted
FSNotInService
The fs is not in service, not allow this operation.
400 Bad Request
File system service is unavailable
InvalidSubnetId
The subnet id is invalid.
400 Bad Request
The subnet ID provided by the user is unavailable
InvalidVpcOrSubnet
Invalid VPC ID or Subnet ID.
400 Bad Request
When creating a mount point, the vpc id or subnet id provided is incorrect
AlreadyMounted
The fs already has mount target in the same subnet.
400 Bad Request
The file system has been mounted to the target subnet
DropCreatingMount
The mount target is in creating, can not drop.
400 Bad Request
Cannot delete the mount point being created
MountTargetNotFound
The request mount target id is not found.
404 Not Found
No target mount point found
MissingParameter
A required parameter 'parameterName' is not supplied.
400 Bad Request
The request is missing the required parameter 'parameterName'
InvalidParameter
The parameter 'parameterName' is invalid.
400 Bad Request
The parameter 'parameterName' is illegal
ResourceNotExists
The resource does not exist.
404 Not Found
The requested host is not configured in the region corresponding to the gateway
EOFException
Unexpected EOF read on the socket.
400 Bad Request
The inputstream exception in the read request is usually eof
RequestTimeTooSkewed
The difference between the request time and the server's time is too large.
403 Forbidden
Invalid timestamp in Authorization
ServiceError
the dependency service is unavailable, host is {host}
424 Failed Dependency
Service is fused
UnsupportedProtocol
The protocol '{http}' is not supported.
403 Forbidden
Protocol verification does not support http or https requests
QualifyNotPass
The User has not pass qualify.
403 Forbidden
Fail to pass real name authentication
RateLimit
There are too many connections. The host is {host}
421 Misdirected Request
Request speed limit
IllegalRequestUri
The request URI contains some forbidden characters.
400 Bad Request
URL validation failed
RequestUriForbidden
The request URI is forbidden or not included.
400 Bad Request
The requested uri is not in the service allowed uri
RequestEntityTooLargeException
Request entity is too large, should not exceed 50M.
413 Request Entity Too Large
For multipart/type requests, the file size is greater than 50M
RequestEntityEmptyException
Request entity is empty.
400 Bad Request
Request of multipart/type, the file byte stream is 0
ParseBodyException
Parsing request body exception
500 Internal Server Error
If there is a mapping file, an exception occurs when mapping the body
ServiceUnavailable
Service or dependent service is unavailable.
503 Service Unavailable
Network errors such as abnormal or timeout connection with backend request
InvalidClientToken
The client token is invalid, client token must be a ascii string of no longer than 64 bits.
400 Bad Request
Wrong clientToken value of idempotent request
MultiRequestConflict
The request is refused because of a previous is in progress.
409 Conflict
When an idempotent request is being processed, another request is received