Skip to main content

获取上传凭证​

简要描述​

  • 初始化表单直传任务，获取上传所需的临时 URL、字段和 Header。

请求方式​

  • post

请求 URL​

  • {API_ADDRESS}/object/initiate_form_data
header 名示例值选填类型说明
operationID1646445464564必填string用于全局链路追踪，建议使用时间戳，在每个请求中独立
tokeneyJhbxxxx3Xs必填string管理员 token

请求参数示例​

{
  "name": "avatar.png",
  "size": 204800,
  "contentType": "image/png",
  "group": "avatar",
  "millisecond": 600000
}
字段名选填类型说明
name必填string对象名称，通常为文件名
size必填int64文件大小（字节）
contentType必填string文件 MIME 类型，如 image/png
group选填string文件分组标识，用于在存储端区分业务目录
millisecond选填int64上传地址有效时长（毫秒），不填使用服务端默认值

成功返回示例​

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "id": "upload-task-id",
    "url": "https://storage.example.com/form-upload",
    "file": "file",
    "header": [
      {
        "key": "Content-Type",
        "value": "multipart/form-data"
      }
    ],
    "formData": {
      "policy": "BASE64_POLICY",
      "signature": "SIGN_VALUE",
      "key": "tmp/avatar.png"
    },
    "expires": 1715065020123,
    "successCodes": [
      200
    ]
  }
}

成功返回示例的参数说明​

参数名类型说明
errCodeint错误码，0 表示成功
errMsgstring错误简要信息，为空
errDlterrDlt错误详细信息，为空
dataobject通用数据对象，具体结构见下方
idstring上传任务 ID，稍后调用完成接口时使用
urlstring第三方存储直传地址
filestring文件内容对应的表单字段名
headerKeyValues 数组直传 HTTP Header 列表
formDatamap<string,string>需要在表单中追加的业务字段集合
expiresint64凭证过期时间戳（毫秒）
successCodesarray直传成功时可接受的 HTTP 状态码，如 200

上传说明​

  1. 构造 multipart/form-data 请求，目标地址为返回的 url。
  2. 将 header 中给出的键值添加到 HTTP Header。
  3. 在请求体中写入 formData 的所有键值对，键名和键值须保持原样。
  4. 将真实的文件内容放入 file 字段（字段名必须与返回值一致），例如 -F "file=@avatar.png"。
  5. 根据 successCodes 列表判断上传是否成功，收到成功响应后再调用确认接口。

示例命令：

curl -X POST "https://storage.example.com/form-upload" \
  -H "Content-Type: multipart/form-data" \
  -F "policy=BASE64_POLICY" \
  -F "signature=SIGN_VALUE" \
  -F "key=tmp/avatar.png" \
  -F "file=@avatar.png"