调用说明
所有文档

          数据传输服务 DTS

          调用说明

          在线调试

          在线调试地址

          请求结构

          请求结构简介

          1. API 服务域名

          数据传输服务 DTS API 的服务域名包括:

          Region EndPoint Protocol
          全局 dts.baidubce.com HTTP and HTTPS

          2. 通信协议

          API 调用遵循 HTTP 协议。

          3. 请求参数

          百度智能云 API 的每个请求都需要指定两类参数:即公共请求参数以及接口请求参数。其中公共请求参数是每个接口都要用到的请求参数,而接口请求参数是各个接口所特有的,具体见各个接口的“请求参数”描述。

          请求参数包括如下4种:

          参数类型 参数说明
          URI 通常用于指明操作实体,如:POST /v{version}/task/{dtsId}
          Query参数 URL中携带的请求参数
          HEADER 通过HTTP头域传入,如:x-bce-date
          RequestBody 通过JSON格式组织的请求数据体

          4. API 版本号

          参数 类型 参数位置 描述 是否必须
          version string URL参数 API 版本号,当前API 版本为 v1

          5. 字符编码

          可解析内容,所有 request/response body 内容目前均使用 UTF-8 编码,后续会支持更多 encoding 类型。

          公共头

          公共请求头

          参数名称 描述
          Authorization 包含Access Key与请求签名。
          Content-Type application/json; charset=utf-8。
          x-bce-date 表示日期的字符串,符合 API 规范。
          Host 表示请求 API 的域名。
          x-bce-content-sha256 表示内容部分的SHA256签名的十六进制字符串。 这里内容指HTTP Request Payload Body。 即 Content 部分在被 HTTP encode之前的原始数据。

          HTTP协议的标准头域不再这里列出。公共头域将在每个数据传输服务 DTS API 中出现,是必需的头域,其中x-bce-content-sha256头域只出现在POST和PUT请求中。POST、PUT、DELETE等请求数据放在request body中。

          公共响应头

          参数名称 描述
          Content-Type application/json; charset=utf-8。
          x-bce-request-id 数据传输服务 DTS 后端生成,并自动设置到响应头域中。

          接口特殊请求参数说明

          接口请求参数与具体的接口有关,不同的接口支持的接口请求参数也不一样。

          查询任务列表为例,支持的接口请求参数如下:

          参数名称 类型 是否必须 参数位置 描述
          version string URL参数 API 版本号
          marker string Query参数 批量获取列表的查询的起始位置,是一个由系统生成的字符串
          maxKeys string Query参数 每页包含的最大数量,最大数量通常不超过100,缺省值为10

          其中各字段说明如下:

          字段 说明
          参数名称 该接口支持的请求参数名,用户可以在使用此接口时将其作为接口请求参数。
          类型 此接口参数的数据类型。
          是否必须 标志此参数是否是必须的,若为“是”;,则表明调用该接口必须传入此参数;若为“否”,表示可以不传入。
          参数位置 此接口参数的所属位置。
          描述 简要描述了此接口请求参数的内容。

          最终请求形式

          最终的请求由以下几部分组成:

          1. 请求域名: dts.baidubce.com。
          2. 请求路径: 各个接口请求路径不同,详见具体接口详情。
          3. 请求方式: 支持RESTful风格的请求方式,本接口文档中涉及POST,GET,PUT,DELETE四种方式。
          4. 请求头: 包括鉴权信息在内的各个公共请求头。详细参考公共头
          5. 最终请求参数串: 包括接口路径参数(请求路径中问号后面的部分)和接口请求参数。
          6. 请求body体:根据接口规定的RequestBody参数结构组成的json结构体。

          签名认证

          数据传输服务 DTS API 会对每个访问的请求进行身份认证,以保障用户的安全。安全认证采用 Access Key 与请求签名机制。Access Key 由 Access Key ID 和 Secret Access Key 组成,均为字符串,由百度智能云官方颁发给用户。其中 Access Key ID 用于标识用户身份,Access Key Secret 是用于加密签名字符串和服务器端验证签名字符串的密钥,必须严格保密。

          对于每个HTTP请求,用户需要使用下文所描述的方式生成一个签名字符串,并将认证字符串放在HTTP请求的Authorization头域里。

          签名字符串格式

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

          签名申请步骤

          关于AK/SK的获取,请参看获取AK/SK

          签名生成算法

          有关签名生成算法的具体介绍,请参看鉴权认证机制

          其他说明

          密码加密传输规范定义

          所有涉及密码的接口参数都需要加密,禁止明文传输。密码一律采用AES-128-ECB加密算法进行加密,用SK的前16位作为密钥,用PKCS5Padding算法进行长度补全。此外,加密后生成的二进制字节流需要转成十六进制,并以字符串的形式传到服务端。

          加密过程可参考以下代码,以Python为例,进行说明:

          # -*- coding: utf-8 -*-
          
          from Crypto.Cipher import AES
          from binascii import b2a_hex, a2b_hex
          """
          若引入包Cipher后提示不存在该包,则安装pycryptodome包
          """
          
          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]

          幂等性

          当调用创建接口时如果遇到了请求超时或服务器内部错误,用户可能会尝试重发请求,这时用户通过 clientToken 参数避免创建出比预期要多的资源,即保证请求的幂等性。

          幂等性基于 clientToken,clientToken 是一个长度不超过 64 位的 ASCII 字符串,通常放在 query string 里,如http://dts.baidubce.com/v1/task?clientToken=be31b98c-5e41-4838-9830-9be700de5a20

          如果用户使用同一个 clientToken 值调用创建接口,则服务端会返回相同的请求结果。因此用户在遇到错误进行重试的时候,可以通过提供相同的 clientToken 值,来确保只创建一个资源;如果用户提供了一个已经使用过的 clientToken,但其他请求参数(包括 queryString 和 requestBody)不同甚至 url Path 不同,则会返回 IdempotentParameterMismatch 的错误代码。

          clientToken 的有效期为 24 小时,以服务端最后一次收到该 clientToken 为准。也就是说,如果客户端不断发送同一个 clientToken,那么该 clientToken 将长期有效。

          日期与时间规范

          日期与时间的表示有多种方式。为统一起见,除非是约定俗成或者有相应规范的,凡需要日期时间表示的地方一律采用UTC时间,遵循ISO 8601,并做以下约束:

          1. 表示日期一律采用YYYY-MM-DD方式,例如2014-06-01表示2014年6月1日
          2. 表示时间一律采用hh:mm:ss方式,并在最后加一个大写字母Z表示UTC时间。例如23:00:10Z表示UTC时间23点0分10秒。
          3. 凡涉及日期和时间合并表示时,在两者中间加大写字母T,例如2014-06-01T23:00:10Z表示UTC时间2014年6月1日23点0分10秒。

          排版约定

          排版格式 含义
          < > 变量
          [ ] 可选项
          { } 必选项
          | 互斥关系
          等宽字体 Courier New 屏幕输出
          上一篇
          API概览
          下一篇
          数据传输任务