Online Debugging

On-line debugging address

Request Structure

Brief Introduction for Request Structure

1. API service domain name

The API service domain name of the Data Transmission Service (DTS) API includes:

2. Communication protocol

An HTTP protocol that API call follows.

3. Request parameters

For each request of the Baidu AI Cloud API, you need to specify two types of parameters: A common request parameter and an interface request parameter. The common request parameter is a request parameter for each interface, which is held by each interface. See the description of the “request parameter” of each interface.

The request parameters include the following four types:

4. API version number

5. Character codes

With the character codes, the system can parse the content. All request/response body contents are UTF-8-encoded. The system will support more encoding types subsequently.

Common Header

Common Request Header

The standard header fields of the HTTP protocol are not listed here. The common header field appears in each Data Transmission Service (DTS) API, which is required, in which the x-bce-content-sha256 header fields only appear in POST and PUT requests. You can put POST, PUT, DELETE, and other request data in the request body.

Common Response Header

Instruction for Special Request Parameters of Interfaces

The interface request parameters are related to the specific interfaces. The interface request parameters supported by different interfaces are also different.

Taking a Query Task List as an example, the supported interface request parameters are as follows:

The instruction of each field is as below:

Final Request Form

The final request consists of the following sections:

1. Request domain name: dts.baidubce.com。
2. Request path: The request paths of interfaces are different. See interface details.
3. Request mode: A request mode supporting a RESTful style. This interface documentation refers to four modes: POST, GET, PUT, and DELETE.
4. Request header: Public request header, including authentication information. For details, see Common Header.
5. Final request parameter string Includes an interface path parameter (one behind the question mark in the request path) and an interface request parameter.
6. Request body: A json structural body that consists of a RequestBody parameter structure as specified by the interface.

Signature Authentication

Data Transmission Service (DTS) API may authenticate the identity of each access request to guarantee the user identity security. The security authentication adopts Access Key and signature request mechanism. The Access Key consists of Access Key ID and Access Key Secret, which are strings issued by Baidu AI Cloud to you. Access Key ID is used to identify your identity, Access Key Secret is a key used to encrypt the signed string and verify the signed string at the server, which must keep secret strictly.

For each HTTP request, the user needs to generate a signature string according to the method mentioned below and put the authentication string into the Authorization header field requested by HTTP.

Signature String Format

bce-auth-v{version}/{accessKeyId}/{timestamp}/{expireTime}/{signedHeaders}/{signature}

Signature Application Steps

For the acquisition of AK/SK, see Acquire AK/SK

Signature Generation Algorithm

For the introductions to the signature generating algorithm, see Authentication Mechanism.

Other Instructions

Definition of Password Encryption and Transmission Specification

All interface parameters involving the passwords should be encrypted, and any plaintext transmission should be 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 supplementation. Besides, the binary byte stream generated after the encryption is converted into a hexadecimal byte and transmitted to the server in the form of a string.

For the encryption process, refer to the following codes. It is described by taking the Python for example:

# -*- coding: utf-8 -*-

from Crypto.Cipher import AES
from binascii import b2a_hex, a2b_hex
"""
If the system prompts that the packet does not exist after importing the packet Cipher, you need to install the pycryptodome packet.
"""

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]

Idempotence

If you experience request timeout or internal error of server when calling a Create Interface, you may attempt to resend a request. In this case, the user does not create more resources than expected via the clientToken parameter, i.e., ensuring the idempotence of the request.

Idempotence is based on clientToken, which is an ASCII string not exceeding 64 bits in length. It is located in a query string, such as http://dts.baidubce.com/v1/task?clientToken=be31b98c-5e41-4838-9830-9be700de5a20.

If you call the Create Interface with the same clientToken value, the server returns the same request result. Therefore, whenever you need to retry after you encounter an error, you can ensure only one resource is created by providing the same clientToken value; and if you provide clientToken that is used, other request parameters (including queryString and requestBody) are different, and even the url Path is different, an error codeIdempotentParameterMismatch is returned.

The clientToken has a period of validity of 24 hours, starting from the time when the server receives such clientToken last time. That is to say if the client sends the same clientToken constantly, such clientToken may be effective permanently.

Date and Time Specification

Date and time can be represented in several ways. For the sake of unity, unless otherwise sanctioned by usage or specified, UTC is adopted wherever date and time indications are required, which follows ISO 8601, and subject to the following restraints:

1. The date is represented in the form of YYYY-MM-DD, e.g., 2014-06-01 represents June 1, 2014.
2. The time is represented in the form of hh: mm: ss, and suffixed with an upper case Z at the end to represent the UTC. For example, 23:00:10Z indicates that the UTC is 23:00:10.
3. For the representation involving the date and time merge, an upper case T is inserted between the date and time, e.g., 2014-06-01T23:00:10Z represents the UTC, 23:00:10, June 1, 2014.

Typesetting convention