General Instructions
API is called in accordance with HTTP protocol, each region should use a different domain name, and the specific domain name is “drds.{region}.baidubce.com”. The data exchange format is JSON, and all request/response body contents are UTF-8 encoded.
Identity verification
The Identity Verification is required for users who use DRDS API. Users who fail to pass the Identity Verification can go to the "Identity Verification" under the security authentication in the Baidu AI Cloud Official Website Console for the authentication. Baidu Cloud provides two authentication methods: Personal Authentication and [Enterprise Authentication](UserGuide/Identity Verification/Personal Authentication.md). You can choose one for authentication according to the actual situation.
API authentication mechanism
Access Key and request signature mechanism are used for security authentication of all APIs. The Access Key consists of Access Key ID and Secret Access Key, both of which are strings. For each HTTP request, use the algorithm described below to generate an authentication string. 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 is bce-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 period of validity of the signature.
- SignedHeaders is a list of header fields involved in the signature algorithm. A semicolon (;) is used to separate header domain names, e.g., host;x-bce-date. The list is arranged in the lexicographical order. (This API signature uses the host and x-bce-date headers only)
- The signature is a hexadecimal representation of a 256-bit signature, and consists of 64 lowercase letters.
When Baidu AI Cloud receives the user's request, the system uses the same SK and the same authentication mechanism to generate the authentication string. Then, the system compares the authentication string with that contained in the user's request. If both authentication strings are the same, the system deems that the user has the specified operation privilege, so the system performs relevant operations. If both authentication strings are different, the system ignores this operation and return an error code.
For the detailed content of the authentication mechanism, see the Authentication Mechanism.
Communication protocol
The system supports HTTP and HTTPS calling methods. To improve the data security, we recommend to use the HTTPS calling method.
Description of the request structure
The data exchange format is JSON, and all request/response body contents are UTF-8 encoded.
The request parameters include the following 4 types:
Parameter Type | Description |
---|---|
URI | It is usually used to specify the operating entity, e.g.,: POST /v{version}/instance/{instanceId} |
Query parameters | Means the request parameter contained in the URL, which is usually used to indicate the action to be taken on the entity. |
HEADER | It is transferred through the HTTP header field, e.g.,: x-bce-date |
RequestBody | Means the request data body organized in the JSON format |
Description of the response structure
The response value has two forms:
Response content | Description |
---|---|
HTTP STATUS CODE | For example, 200, 400, 403, and 404 |
ResponseBody | Means the response data body organized in the JSON format |
API version number
Parameters | Type | Parameter Position | Description | Whether Required |
---|---|---|---|---|
version | String | URI parameter | It is the API version number, whose current value is v1. | Yes |
Idempotence
If the user encounters a request timeout or an internal server error when calling the interface used to create the resource, the user may try to resend the request. Thus, it may cause the creation of excessive resources. In this case, the user can use the clientToken parameter to avoid creating more resources than expected, that is to say, guarantee the idempotence of the request.
The idempotence is based on the clientToken. The clientToken is an ASCII string with a length of not exceeding 64 bits and is usually placed in a query string, e.g., https://drds.bj.baidubce.com/v1/instance?clientToken=be31b98c-5e41-4838-9830-9be700de5a20
.
If the user uses the same clientToken value to call the creation interface, the server returns the same request result. Therefore, after encountering an error and retrying to send the request, the user can provide the same clientToken value to ensure that only one resource. If the user provides a used clientToken value, but uses other different request parameters (including queryString and requestBody) or even a different url Path, the system returns the error code “IdempotentParameterMismatch”.
The period of validity of the clientToken is 24 hours and starts from the time when the server receives the clientToken the last time. That is to say, if the client sends the same clientToken constantly, the clientToken is valid for a long time.
Date and time specification
The date and time can be expressed in many ways. For unification, unless it is established by convention or has corresponding specifications, UTC time shall be adopted everywhere where date and time are required, ISO 8601 shall be followed, and the following restrictions shall be made:
- The date is represented in the format of
YYYY-MM-DD
, for example,2014-06-01
represents June 1, 2014. hh:mm:ss
mode must be adopted for time representation, and a capital letter Z is attached for representation of UTC time. For example,23:00:10Z
represents 23:00:10 UTC.- Where the date and time are indicated at the same time, add the letter T between the two parts, for example.
2014-06-01T23:00:10Z
represents that the UTC time is 23:0:10 on Sunday, June 1, 2014.
Service domain name
Region | Service endpoint | Protocol |
---|---|---|
Beijing | drds.bj.baidubce.com | HTTP and HTTPS |
Guangzhou | drds.gz.baidubce.com | HTTP and HTTPS |
Suzhou | drds.su.baidubce.com | HTTP and HTTPS |
Wuhan | Not supported temporarily. Coming soon | —— |
Singapore | Not supported temporarily. Coming soon | —— |
Common request header and common response header
Common request header
Header field | Description | Whether Required |
---|---|---|
Authorization | Includes the Access Key and request signature For detailed information, see Authentication. | Yes |
Content-Type | application/json; charset=utf-8 | Yes |
x-bce-date | Means the time of creating the request. The date is represented in the form of YYYY-MM-DD. For example, 2014-06-01 represents June 1, 2014. If the user uses the standard Date field, the header field can be left blank. When both exist, the x-bce-date prevails. | Yes |
Public response header
Header field | Description |
---|---|
Content-Type | application/json; charset=utf-8 |
x-bce-request-id | Means the requestId corresponding to the request |
Error code
Error code format
When an error in the user’s access to the API takes place, the system returns the corresponding error code and error message to the user, facilitating to locate the problem and conduct proper processing. When an error occurs in the request, the detailed error message gets returned via the Response Body in the format below:
Parameter Name | Type | Description |
---|---|---|
code | String | Indicates the specific error type. |
message | String | Detailed description on this error. |
requestId | String | Means the requestId causing the error |
Example:
{
"code":"IllegalRequestUrl",
"message":"The requested url belongs to domain which is not under acceleration",
"requestId":" 81d0b05f-5ad4-1f22-8068-d5c9de60a1d7"
}
Common error code
Error code | Error message | HTTP status code | Description |
---|---|---|---|
AccessDenied | Access denied. | 403 Forbidden | You’ve no permission to access corresponding resources. |
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 does not meet the semantics requirements. For example, a required item is missing, or the value type does not match. In consideration of its compatibility, all unrecognized items should be directly ignored and this error should not be returned. |
InternalError | We encountered an internal error Please try again. | 500Internal Server Error | Means all other undefined errors. It should not be used when there’re other types of errors (including general and service-customized errors) that correspond definitely. |
InvalidAccessKeyId | The Access Key ID you provided does not exist in our records. | 403 Forbidden | The Access Key ID does not exist. |
InvalidHTTPAuthHeader | The HTTP authorization header is invalid. Consult the service documentation for details. | 400 Bad Request | Means an error in the Authorization header field format. |
InvalidHTTPRequest | There was an error in the body of your HTTP request. | 400 Bad Request | Means an HTTP body format error. For example, it does not conform to the specified Encoding. |
InvalidURI | Could not parse the specified URI. | 400 Bad Request | The URI form is incorrect. For example, the keywords defined by some services do not match. For the ID mismatch problem, 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 URI version number is invalid. |
OptInRequired | A subscription for the service is required. | 403 Forbidden | No corresponding service has been opened. |
PreconditionFailed | The specified If-Match header doesn’t match the ETag header. | 412 Precondition Failed | For more information, please see Etag. |
RequestExpired | Request has expired. Timestamp date is XXX. | 400 Bad Request | Means the request timeout. XXX must be changed to an x-bce-date value. If there is only Date in the request, you need to change Date to date time. |
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 contained in the Authorization header field is inconsistent with the server verification. |
DRDS error code
Error Code | Error Message | HTTP Status Code | Description |
---|---|---|---|
InstanceNotExist | Instance not exist. | 403 | The specified DRDS instance does not exist. |
AccessDenied | Access denied. | 403 | The operation is prohibited. |
InvalidAction | Invalid Action. | 400 | Means an invalid operation. |
InternalFailure | We encountered an internal error Please try again. | 400 | Means an internal error |
ValidationError | Validation Error. | 400 | The verification gets failed. |
AlreadyMaxLimit | Already Max Limit. | 400 | Reach the maximum limit |
DbinstanceStateChange | Operation not allowed. | 404 | Means a DRDS instance status error. |
InternalServerError | Internal Server Error. | 503 | Means an internal server error |
Definition of specifications for encrypted transmission of the password
All interface parameters involving the password need to be encrypted. Transmitting the password in the form of plaintext is prohibited. All passwords are encrypted by the AES-128-ECB encryption algorithm, with the first 16 bits of the SK as the key. The PKCS5Padding algorithm is used for length completion. In addition, the binary byte stream generated after encryption is converted to the hexadecimal and transmitted to the server in the form of string.
For the encryption process, refer to the following codes. It is described by taking the Python as an example:
# -*- coding: utf-8 -*-
from Crypto.Cipher import AES
from binascii import b2a_hex, a2b_hex
"""
If the package does not exist after calling Cipher package, install the pycryptodome package.
"""
def encrypt(secretkey, password):
"""Encrypt adminpass by AES-128-ECB/PKCS5Padding, the key is secretkey."""
pendding = 16 - len(password) % 16
password += chr(pendding) * (pendding)
return b2a_hex(AES.new(secretkey[:16], AES.MODE_ECB).encrypt(password))
def decrypt(secretkey, password):
"""Decrypt adminpass by AES-128-ECB/PKCS5Padding, the key is secretkey."""
decrypted = AES.new(secretkey[:16], AES.MODE_ECB).decrypt(a2b_hex(password))
pendding = ord(decrypted[len(decrypted) - 1])
return decrypted[:-pendding]
Typesetting agreement
Typesetting format | Meaning |
---|---|
<> | Variable |
[] | Optional |
{} | Required |
\ | Mutex relationship |
Monospaced font Courier New | Screen output |