业务级 API 文档

生成访问令牌

最近更新时间:2022-03-21 12:23:03

功能描述

用于生成调用智能媒资托管服务的访问令牌(Access Token)。调用该接口需要用到媒体库密钥,所以必须在后端调用该接口以保证密钥安全。

  • 该接口用于获取后续调用媒体托管其他接口的访问令牌(Access Token),调用该接口需要用到媒体库密钥,所以必须在后端调用该接口以保证密钥安全。
  • 请求参数中的 UserId 为可选的业务自身的用户身份识别,媒体托管后端不理解该参数的具体含义,仅用于区分访问令牌所属的用户及记录相关操作的操作者,建议开发者将用于前端用户操作媒体托管的访问令牌,指定 UserId 为业务自身用于识别用户的标识,如小程序 openid 或业务自身的用户 ID 等,将用于后端服务直接操作媒体托管的访问令牌,指定 UserId 为空。
  • 请求参数中的 ClientId 为可选的业务自身的客户端识别,用于同个用户多端登录时识别不同的端,可用于用户主动清除其他客户端的有效访问令牌,例如当用户分别使用多台手机客户端、手机微信小程序及 PC 微信小程序登录时,业务后台可以记录用户所登录的客户端数量,并允许用户主动清除指定客户端的登录状态,此时可调用相关接口一并清除指定客户端上的访问令牌。
  • 当申请管理员权限的访问令牌且 UserId 为空时,在后续使用访问令牌发起请求时可同时携带 UserId 用做临时身份,此时该请求的访问者将视为该指定用户身份。
  • 同一用户身份可申请的访问令牌数量不限制,满足多端同时登录的需求。
  • 当使用访问令牌调用接口时,该访问令牌将自动续期,续期后的有效期为 Period 参数所指定的时长。
  • 业务后端在收到前端的获取请求令牌请求时,应当首先验证前端的用户身份,随后根据业务中该用户的权限来指定获取请求令牌请求中的 Grant 参数。

请求

请求示例

GET /api/v1/token?library_id=`{LibraryId}`&library_secret=`{LibrarySecret}`&space_id=`{SpaceId}`&user_id=`{UserId}`&client_id=`{ClientId}`&session_id=`{SessionId}`&local_sync_id=`{LocalSyncId}`period=`{Period}`&grant=`{Grant}`&allow_space_tag=`{AllowSpaceTag}`


POST /api/v1/token?library_id=`{LibraryId}`&library_secret=`{LibrarySecret}`&space_id=`{SpaceId}`&user_id=`{UserId}`&client_id=`{ClientId}`&local_sync_id=`{LocalSyncId}`&period=`{Period}`&grant=`{Grant}`&allow_space_tag=`{AllowSpaceTag}`

说明:

花括号内为发起请求时的可变参数,实际使用时不包含花括号,例如:/api/v1/token?library_id=smhxxx&library_secret=1234abcd&space_id=spacexxx&user_id=ABCD1234&grant=upload_file,create_directory,下同。

请求参数

请求参数 描述 是否必选
LibraryId 媒体库 ID,在媒体托管控制台创建媒体库后获取,请参阅 创建媒体库
LibrarySecret 媒体库密钥,在媒体托管控制台创建媒体库后获取,请参阅 创建媒体库
SpaceId 空间 ID,可同时指定多个空间 ID,使用英文逗号(,)分隔。 如果媒体库为单租户模式,则无需指定该参数。
如果媒体库为多租户模式,当需要操作租户空间时,无需指定该参数。当进行其他操作时,若授予管理员权限则该参数为可选,否则必须指定该参数
UserId 用户身份识别,由业务后台自行控制
ClientId 客户端识别,由业务后台自行控制
SessionId SessionId,由业务后台自行控制
LocalSyncId 同步盘 syncId,由业务后台自行控制
Period 令牌有效时长及每次使用令牌后自动续期的有效时长,可选参数,单位为秒,有效值为正整数,传入其他值将使用默认值 86400(24小时),传入小于 1200 的值将自动使用最小值 1200(20分钟)
AllowSpaceTag 空间标记,表示能够访问的空间
Grant 授予的权限,如为空则只拥有读取权限,可指定此参数在只读基础上同时附加下述多个权限,并使用英文逗号(,)分隔

以下是父节点 Grant 的参数内容:

请求参数 父节点 描述 是否必选
acl Grant 使用基于目录和文件的细粒度权限控制
admin Grant 管理员权限,拥有所有权限
create_space Grant 拥有创建租户空间权限
delete_space Grant 拥有删除租户空间权限
space_admin Grant 租户空间管理员权限,拥有除租户空间操作以外的所有权限
create_directory Grant 拥有创建目录或相簿权限
delete_directory Grant 拥有删除目录或相簿权限(未开启回收站)/将目录或相簿移入回收站权限(开启回收站)
delete_directory_permanent Grant 开启回收站时,拥有永久删除目录或相簿权限
move_directory Grant 拥有重命名或移动目录或相簿权限
copy_directory Grant 拥有重复制目录或相簿权限
upload_file Grant 拥有上传文件权限,但不允许覆盖已有文件
upload_file_force Grant 拥有上传文件权限,且允许覆盖已有文件
begin_upload Grant 拥有开始上传文件权限,但不允许覆盖已有文件
begin_upload_force Grant 拥有开始上传文件权限,且允许覆盖已有文件
confirm_upload Grant 拥有完成上传文件权限;将开始上传与完成上传权限分离,主要用于业务前后端权限的分离,使完成上传必须经过业务后端;如果同时需要开始上传和完成上传权限,可简单指定 upload_file 或 upload_file_force
create_symlink Grant 拥有创建符号链接权限,但不允许覆盖已有文件或符号链接
create_symlink_force Grant 拥有创建符号链接权限,且允许覆盖已有文件或符号链接
delete_file Grant 拥有删除文件权限(未开启回收站)/将文件移入回收站权限(开启回收站)
delete_file_permanent Grant 开启回收站时,拥有永久删除文件权限
move_file Grant 拥有重命名或移动文件权限,但不允许覆盖已有文件
move_file_force Grant 拥有重命名或移动文件权限,且允许覆盖已有文件
copy_file Grant 拥有复制文件权限,但不允许覆盖已有文件
copy_file_force Grant 拥有复制文件权限,且允许覆盖已有文件
delete_recycled Grant 拥有删除回收站项目权限
restore_recycled Grant 拥有恢复回收站项目权限

请求体

可指定访问令牌扩展属性(仅限使用 POST 方法)。

{
    "shareDirectoryIdList":[1,2,3],
    "shareAuthority":{"canDownload":false},
    "shareDirectoryHistoryIdList":[1,2,3],
    "attachInfo": "operatorPhoneNumber:18628769878"
}

请求体字段说明:

节点名称(关键字) 描述 是否必选
attachInfo 触发信息,用于记录日志
shareDirectoryIdList 分享 ID 集合
shareDirectoryHistoryIdList 分享历史版本 ID 集合
shareAuthority 分享权限对象

响应

响应码

删除成功,返回 HTTP 204 No Content。

响应体

{ "accessToken": "xxx", "expiresIn": 86400 }

响应体字段说明:

节点名称(关键字) 描述
accessToken 字符串,访问令牌的具体值
expiredIn 整数,访问令牌的有效时长,单位为秒
目录