功能描述
用于生成调用智能媒资托管服务的访问令牌(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}`&period=`{Period}`&grant=`{Grant}`
说明:
花括号内为发起请求时的可变参数,实际使用时不包含花括号,例如:
/api/v1/token?library_id=smhxxx&library_secret=1234abcd&space_id=spacexxx&user_id=ABCD1234&grant=upload_file,create_directory
,下同。请求参数
请求参数 | 描述 | 是否必选 |
LibraryId | 是 | |
LibrarySecret | 是 | |
SpaceId | 空间 ID,可同时指定多个空间 ID,使用英文逗号(,)分隔 | 如果媒体库为单租户模式,则无需指定该参数 如果媒体库为多租户模式,当需要操作租户空间时,无需指定该参数。当进行其他操作时,若授予管理员权限则该参数为可选,否则必须指定该参数 |
UserId | 用户身份识别,由业务后台自行控制 | 否 |
ClientId | 客户端识别,由业务后台自行控制 | 否 |
SessionId | SessionId,由业务后台自行控制 | 否 |
Period | 令牌有效时长及每次使用令牌后自动续期的有效时长,可选参数,单位为秒,有效值为正整数,传入其他值将使用默认值 86400(24小时),传入小于 300 的值将自动使用最小值 300(5 分钟),传入大于 315360000 的值将自动使用最大值 315360000(10 年) | 否 |
Grant | 授予的权限,如为空则只授予读取权限,可指定此参数在只读基础上同时附加下述多个权限项,并使用英文逗号(,)分隔,例如: create_directory,upload_file | 否 |
以下是 Grant 参数支持的权限项:
权限项 | 描述 |
admin | 管理员权限,授予所有权限 |
create_space | 授予创建租户空间权限 |
delete_space | 授予删除租户空间权限 |
space_admin | 租户空间管理员权限,授予除租户空间操作以外的所有权限 |
create_directory | 授予创建目录或相簿权限 |
delete_directory | 授予删除目录或相簿权限(未开启回收站)/将目录或相簿移入回收站权限(开启回收站) |
delete_directory_permanent | 开启回收站时,授予永久删除目录或相簿权限 |
move_directory | 授予重命名或移动目录或相簿权限 |
copy_directory | 授予重复制目录或相簿权限 |
upload_file | 授予上传文件权限,但不允许覆盖已有文件 |
upload_file_force | 授予上传文件权限,且允许覆盖已有文件 |
begin_upload | 授予开始上传文件权限,但不允许覆盖已有文件 |
begin_upload_force | 授予开始上传文件权限,且允许覆盖已有文件 |
confirm_upload | 授予完成上传文件权限;将开始上传与完成上传权限分离,主要用于业务前后端权限的分离,使完成上传必须经过业务后端;如果同时需要开始上传和完成上传权限,可简单指定 upload_file 或 upload_file_force |
create_symlink | 授予创建符号链接权限,但不允许覆盖已有文件或符号链接 |
create_symlink_force | 授予创建符号链接权限,且允许覆盖已有文件或符号链接 |
delete_file | 授予删除文件权限(未开启回收站)/将文件移入回收站权限(开启回收站) |
delete_file_permanent | 开启回收站时,授予永久删除文件权限 |
move_file | 授予重命名或移动文件权限,但不允许覆盖已有文件 |
move_file_force | 授予重命名或移动文件权限,且允许覆盖已有文件 |
copy_file | 授予复制文件权限,但不允许覆盖已有文件 |
copy_file_force | 授予复制文件权限,且允许覆盖已有文件 |
delete_recycled | 授予删除回收站项目权限 |
restore_recycled | 授予恢复回收站项目权限 |
响应
响应码
生成成功,返回 HTTP 204 No Content。
响应体
{ "accessToken": "xxx", "expiresIn": 86400 }
响应体字段说明:
节点名称(关键字) | 描述 |
accessToken | 字符串,访问令牌的具体值 |
expiredIn | 整数,访问令牌的有效时长,单位为秒 |