跳到主要内容

获取对象上传信息

POST 
/v1/storages/get-objects-upload-info

批量获取上传对象所需信息。

此接口受到云存储桶权限配置和身份认证鉴权的控制，请确认请求所属身份有对应资源的操作权限。

关于云存储权限配置，请参考文档：云存储基础权限 和 云存储安全规则。

💡 提示：如云存储操作被基础权限或安全规则所拦截，可能会遇到的错误码： STORAGE_EXCEED_AUTHORITY

💡 提示：如云存储操作被身份鉴权机制所拦截，可能会遇到的错误码： ACTION_FORBIDDEN

获取上传信息后，在客户端使用响应信息完成文件直传存储桶。示例步骤如下：

第一步：通过 HTTP API 获取上传信息

curl -L 'https://{envId}.api.tcloudbasegateway.com/v1/storages/get-objects-upload-info' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '[
    {
      "objectId": "filename.jpg"
    }
  ]'

返回信息结构：接口返回一个数组，成功项中包含上传所需字段，失败项包含 code/message 便于排查。

[
  {
    "objectId": "dirname/filename.jpg",
    "uploadUrl": "https://url/filename.jpg",
    "authorization": "q-sign-algorithm=sha1&q-ak=...",
    "token": "xxx",
    "cloudObjectMeta": "xxx",
    "downloadUrl": "https://url/filename.jpg?sign=xxx&t=yyy",
    "downloadUrlEncoded": "https://url/filename.jpg?sign=xxx&t=yyy",
    "cloudObjectId": "cloud://your-envId.bucket/filename.jpg"
  },
  {
    "code": "COS_ACTION_FAILED",
    "message": "Execute COS action failed."
  }
]

第二步：从返回结果中提取上传文件所需字段，完成文件上传

例如，使用 jq 等工具提取数组中第一个成功项的字段：

response=$(curl ...)
upload_url=$(echo "$response" | jq -r '.[0].uploadUrl')
auth=$(echo "$response" | jq -r '.[0].authorization')
token=$(echo "$response" | jq -r '.[0].token')
meta=$(echo "$response" | jq -r '.[0].cloudObjectMeta')

接着利用上述字段，使用 PUT 方法在对应 URL 上传文件：

curl -X PUT "$upload_url" \
  -H "Authorization: $auth" \
  -H "X-Cos-Security-Token: $token" \
  -H "X-Cos-Meta-Fileid: $meta" \
  --data-binary @filename.jpg

Request​

Body

arrayrequired

上传对象请求参数，数组格式

  • Array [
    • objectId 对象 ID，例如文件名称 (string)required
    signedHeader object
    property name* string[]
  • Array [

    • string

  • ]
  • ]

Responses​

调用成功时返回

Response Headers
  • X-Request-Id string

    请求ID

Schema
  • Array [
    • oneOf
    uploadUrl uri
    downloadUrl uri
    downloadUrlEncoded uri
    token 上传时所需要的 token，填充 X-Cos-Security-Token 请求头 (string)
    authorization 上传时所需要的 authorization 认证信息，填充 Authorization 请求头 (string)
    cloudObjectMeta 上传时所需要的 metadata 信息，填充 X-Cos-Meta-Fileid 请求头 (string)
    cloudObjectId 对象上传后的云端对象 ID (string)
    objectId 本次请求的对象 ID (string)
  • ]
Loading...