全部产品

HTTPClient

更新时间:2020-08-06 15:47:26

介绍

HttpClient Widget 提供了调用PDS API基本方法。支持自动刷新 token,支持上传文件等。基于此Widget,接入PDS可以更加简单。

接入例子

1. 调用PDS API例子

(1) 引入js

  1. <script src="https://g.alicdn.com/pds/pds-widgets/${version}/index.min.js"></script>

(2) 创建 client

  1. var domain_id = 'hz001'
  2. var client = new PDSWidgets.HttpClient({
  3. endpoint: `http://${domain_id}.api.alicloudpds.com`,
  4. path_type: 'OSSPath',
  5. token_info: {
  6. access_token: ''
  7. }
  8. })

(3) 调用接口

  1. var result = await client.request('/drive/list', {})
  2. var result = await client.request('/file/list', {...})
  3. ...

API的URI和参数请看API接口文档

(4) 事件监听

TokenExpired 错误和自动刷新token

  1. client.on('error', async function (err, opt) {
  2. if(err.code='TokenExpired'){
  3. //需要更新token了
  4. //请调接口获取token_info, 再setToken
  5. var tokenInfo = await client.refreshToken({
  6. client_id: '',
  7. refresh_token: ''
  8. ...
  9. })
  10. client.setToken(tokenInfo)
  11. //也可以将token_info 存到localStorage供刷新页面后重新载入
  12. //localStorage.setItem('my-token-xxx', JSON.stringify(tokenInfo))
  13. }
  14. else{
  15. //其他错误处理
  16. console.log(err.toJSONString(), err.code, opt)
  17. }
  18. })

(5) 上传文件

  1. <input type="file" id="f" />
  1. document.querySelector('#f').onchange = async function(e){
  2. if(e.target.files.length==0) return;
  3. var file = e.target.files[0]
  4. var targetInfo = {
  5. drive_id: '1',
  6. parent_key_path: '/'
  7. }
  8. //上传文件
  9. await client.uploadFile(file, targetInfo, {
  10. onProgress(cp){
  11. console.log(cp.progress) //0-100
  12. }
  13. });
  14. console.log('Done')
  15. }

接口详解

1. HttpClient 构造函数

  1. new HttpClient(opt)

opt[] 参数说明:

字段 必须 描述
token_info 必须包含 access_token 字段,一般为调用PDS获取token返回的JSON格式。
domain_id domain_id 和 endpoint 必选一个
endpoint domain_id 和 endpoint 必选一个, 如: https://hz01.api.alicloudpds.com
path_type Domain的Path类型,可选范围:[OSSPath, PDSPath], 默认: “OSSPath”
version API版本,默认: “v2” 。 目前只支持”v2”。

2. request(url, data={}, options={}, retries=1)

所有API的url和data参数,都可以在API接口文档中找到。

参数说明:

字段 必须 描述
url 请求路径
data 请求参数
options 请求配置
retries 重试次数,默认: 1,表示重试1次。设置为0,则不重试。

(1) url

相对路径,格式举例:

  • /drive/list
  • /share/list
  • /file/list

注意: 不管是PDSPath,还是OSSPath, 文件相关的url 格式都是 /file/* 。即OSSPath的获取文件列表url是 /file/list 而不是 /osspath/file/list

(2) data[]

举例:OSSPath 获取文件列表

  1. var result = await client.request('/file/list', {
  2. share_id: 'xxxx',
  3. parent_file_path: '/test/',
  4. //marker: '',
  5. //limit: 100
  6. })
  7. //result.items
  8. //result.next_marker

(3) options[]

request底层使用了axios库发送请求。

options参数详情请看: axios 支持参数

3. refreshToken(opt)

opt[]参数:

字段 必须 描述
refresh_token tokenInfo 中 refresh_token 。refresh_token 失效时间是7天,access_token 失效时间是2小时。 refresh_token 在调用过此接口后失效(会生成新的refresh_token)。 refresh_token 只要没有失效,就可以用来调用这个接口。
client_id App的ID。
client_secret 如果是web server类型的app,client_secret是必须的。web前端页面不推荐直接使用web server APP。
endpoint auth服务的endpoint。格式为:https://${domain_id}.auth.alicloudpds.com

用法:

  1. var tokenInfo = await client.refreshToken({...})

4. setToken(tokenInfo)

在刷新token拿到tokenInfo之后,可以通过此接口更新 client 中的 token_info。

tokenInfo字段:

字段 必须 描述
access_token access_token
expire_time access_token的有效期时间,格式为ISOString, 如: 2020-03-03T00:00:00.290Z
refresh_token refresh_token

5. uploadFile(file, targetInfo, options={})

(1) 依赖js

使用此方法上传文件结束时需要校验文件完整性, 必须引入这个 js 才能使用:

  1. <script src="https://dev.g.alicdn.com/pds/pds-widgets/0.1.2/crc-lib.min.js"></script>
  • 引入的js版本要保持一致, 最新版本请看: 版本说明

(2) 参数说明

file 是HTML5的 file对象。

targetInfo[] 字段说明:

字段 必须 描述
drive_id drive_id和share_id必选一个。
share_id drive_id和share_id必选一个。
parent_file_id (PDSPath)目录的ID。 parent_file_id和parent_file_path必选一个
parent_file_path (OSSPath)目录的路径。 parent_file_id和parent_file_path必选一个
new_name 新的名字。默认为 HTML5的 file.name

options[]字段说明:

字段 必须 描述
onReady 创建了上传任务之后的回调方法。onReady(task)。 task可以start(), stop()等。
onProgress 进度变化callback方法。onProgress(checkpoint)。checkpoint.progress 即为上传的进度, 取值从0-100.
max_chunk_size 分块大小。默认: 5*1024*1024 (5MB)
init_chunk_con 初始分块并发数。默认: 3
chunk_con_auto 根据网速自动调节分块并发数。默认:true
verbose 打印详细日志。默认:true
use_https 是否使用https上传到OSS。默认:false。 如果为true更安全但是会影响上传速度,使用时需要权衡。