Real Name Authentication

Baidu AI Cloud provides two authentication methods: personal authentication and enterprise authentication. You can choose either of them.

Authentication Mechanism

Access Key and request signature are used for all API security certification. The Access Key consists of an Access Key ID and a Secret Access Key, both of which are strings. For each HTTP request, an authentication string is generated with the following algorithm. Submit an authentication string in the Authorization header field. The server verifies the correctness of the authentication string based on the generation algorithm. The format of the authentication string is bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}.

• The version is a positive integer.
• The timestamp is the UTC time when the signature is generated.
• The expirationPeriodInSeconds represents the expiration date of the signature.
• SignedHeaders is the list of header fields involved in the signature algorithm Use semicolons (;) to separate header domain names, e.g., host;x-bce-date. The list is in lexicographic order. (API signature only uses the headers of host and x-bce-date)
• 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 and compare it with the authentication string contained in the user's request. If the authentication strings are the same, the system considers that the user has the specified operation permission and operates accordingly. If the authentication strings are different, the system ignores the operation and returns the error code. For more information of the authentication mechanism, please see the Authentication Mechanism.

Communications Protocol

HTTP and HTTPS are both supported. HTTPS is recommended to improve data security.

Request Structure Specifications

The data exchange format is JSON, and all request/response body contents are encoded in UTF-8.

The request parameters include the following 4 types:

Parameter Type	Instruction
URI	Used to specify the operating entity, such as PUT /v1/cluster/{clusterUuid}
Query parameter	Request parameter carried in the URL
HEADER	Passed in via HTTP header field, e.g., x-bce-date
RequestBody	Request data body organized in JSON format

Response Structure Description

Response values are in two forms:

Response Contents	Instruction
HTTP STATUS CODE	Such as 200, 400, 403, 404, etc.
ResponseBody	Response data body organized in JSON format

Version Number

Parameters	Type	Parameter Position	Description	Required
version	String	URI parameter	API version number	Required

Idempotence

In case of a request timeout or an internal server error when calling the creation interface, the user may try to resend the request, and creating more resources than expected is avoided with the clientToken parameter to ensure the idempotence of the request.

The idempotence is based on clientToken, which is an ASCII string with a length of up to 64 bits and is usually placed in a query string, such as http://bcc.bj.baidubce.com/v1/instance?clientToken=be31b98c-5e41-4838-9830-9be700de5a20.

If a creation interface is called with the same clientToken value, the server will return the same request result. So, in case of an error, the creation interface is re-called with the same clientToken value, to ensure that only one resource is created. If a used clientToken is provided, but other request parameters (including queryString and requestBody) are different and even url Path is different, IdempotentParameterMismatch error code will be returned.

The clientToken is valid for 24 hours, from the last time when the server receives the clientToken. That is to say, the clientToken constantly sent by the client is valid for a long time.

Date and Time

Date and time are represented in many ways. For the purpose of consistency, unless a convention or specification exists, all the date and time fields specified in the HTTP standard must adopt GMT, and all other date and time fields must adopt UTC and comply with ISO 8601, with the following constraints:

• The date always adopts the form of YYYY-MM-DD, for example, 2014-06-01 represents June 1, 2014.
• The time always adopts the form of hh:mm:ss, and the capital Z is added at the end to indicate UTC time. For example, '23:00:10Z` indicates the UTC time of 23:0:10.
• For the combination of date and time, add the capital T between the two. For example, 2014-06-01T23:00:10Z indicates the UTC time of 23:0:10 on June 1, 2014.

Normalized String

Generally, a string contains any Unicode character. This flexibility brings a lot of confusion in programming. So, the concept of "normalized string" is introduced. A normalized string only contains percent-encoding characters and URI (Uniform Resource Identifier) unreserved characters. RFC 3986 specifies that unreserved characters include: letters (A-Z, and a-z), numbers (0-9), hyphen (-), dot (.), underline (_), and tilde (~). How to convert a string to a normalized string:

• Convert the string to the byte stream encoded in UTF-8.
• Leave all URI unreserved characters unchanged.
• Perform the percent-encoding as specified by RFC 3986 to the rest bytes, which means the % is followed by two hexadecimal letters representing the byte value. All letters are capitalized.

Example: Original string: this is an example for 测试, and corresponding normalized string: this%20is%20an%20example%20for%20%E6%B5%8B%E8%AF%95.

BMR Product Encoding Requirements

• The content is parsed. All request/response body contents are currently encoded in UTF-8, and more encoding types are supported at a later time.

• The request needs the following UrlEncode:

  • Objectname, in which Resource ignores "/" during the UrlEncode.
  • Querystring's Value.
  • x-bce-copy-source ("/" ignored).
  • Custom Meta: The Meta Value only supports the visible ASCII characters, and the UrlEncode is recommended if other characters are used.

Basic Concepts of BMR

Cluster: The computing cluster composed of instance groups.

Job: The jobs in the same cluster are executed in the submission order.

BOS: Baidu Object Storage.

Bucket: The file bucket in the object storage system.

BOS Key ("Key" for short): The unique identifier used by Baidu Object Storage to indicate the file resources at the user's Bucket level.

Access Key ID / Secret Access Key: BMR's API services adopt the mechanism of Access Key and request signature. The Access Key consists of an Access Key ID and a Secret Access Key, both of which are strings.