OSS 文件上传接口客户端调用说明

1. 功能概述

/v2/oauth2/oss/getAccessKey 用于获取阿里云 OSS 临时上传凭证（STS）。客户端拿到凭证后，可直接向 OSS 上传文件，无需经过我方服务器中转，上传速度与稳定性更好。

2. 调用接口

请求地址：POST {开放平台地址}/v2/oauth2/oss/getAccessKey

请求体（JSON）：

字段	类型	必填	说明
`fileSuffix`	String	custom 模式必填	文件后缀名，字母/数字 1~8 位，可带或不带点，如 `pdf`、`.xlsx`

请求示例：

响应示例：

{
  "code": "2000",
  "success": true,
  "message": null,
  "data": {
    "accessKeyId": "STS.NYaGQdN***********33Pa4dvoyC",
    "accessKeySecret": "3gxctNQs9V***********YJ9FoNCwkQhbKmPiRmpSdd7",
    "securityToken": "CAISqAR1q6***********vQo4527qiKQEzD1zMFbbtImarSoTz2IHh...",
    "bucketName": "custom-file-upload",
    "endPoint": "oss-cn-beijing.aliyuncs.com",
    "region": "cn-beijing",
    "expiration": "2026-09-22T07:11:45Z",
    "objectKey": "custom/{appkey}/2bacdfdc3e344ebbbbd4ce88add8cb41.pdf"
  },
  "reqId": "0cca7ae7-56ed-4718-bd8a-505c8493ca96"
}

响应字段说明（data 内）：

字段	说明
`accessKeyId` / `accessKeySecret` / `securityToken`	STS 临时凭证三元组，用于构造 OSS 客户端
`bucketName` / `endPoint` / `region`	目标桶与地域信息
`expiration`	凭证过期时间（UTC），默认 3600 秒，请在过期前完成上传
`objectKey`	说明：本次唯一允许上传的对象 key；

3. 上传文件（Java 示例）

引入阿里云 OSS SDK：

<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.17.4</version>
</dependency>

上传（key 必须使用接口返回的 objectKey）：

大文件建议使用分片上传（凭证已包含分片上传权限）：

4. 错误码

code	含义	处理建议
`2000`	成功	—
`505072`	文件后缀名不合法	`fileSuffix` 仅允许字母/数字 1~8 位（如 `pdf`），勿含空格、`/`、`..` 等
`505073`	appKey 缺失	检查 access_token 是否正确
`505071`	系统未知异常	稍后重试，持续失败请联系我方并提供响应中的 `reqId`

上传阶段若返回 OSS AccessDenied，通常是：

上传的 key 与返回的 objectKey 不一致；

凭证已过期（对比 expiration），请重新获取。

5. 注意事项

一次凭证一个文件：每次调用接口生成一个新的 objectKey，一个凭证只能上传这一个文件；上传多个文件请多次调用接口获取。

凭证有效期：默认 3600 秒，以 expiration 为准；过期后请重新获取，不要缓存复用旧凭证。

objectKey 不可自定义：路径前缀 custom/{appKey}/ 由服务端按租户自动生成，客户端无法（也无需）指定存储目录。

安全性：STS 凭证为临时凭证且权限已最小化（仅单个对象），即使泄露影响面也被限制在单文件。请勿将凭证写入日志或前端代码长期保存。

文件大小：当前接口未强制限制单文件大小，请按业务合理控制；超大文件建议使用分片上传。

HTTP文件上传

OSS 文件上传接口客户端调用说明#

1. 功能概述#

2. 调用接口#

3. 上传文件（Java 示例）#