Skip to main content

Get object upload information

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

Batch obtain information required to upload objects.

This API is subject to cloud storage bucket permission configuration and identity authentication and authorization. Ensure the requesting identity has the necessary permissions for the corresponding resources.

For cloud storage permission configuration, see Cloud Storage Basic Permissions and Cloud Storage Security Rules.

💡 Tip: If cloud storage operations are blocked by basic permissions or security rules, you may encounter the error code: STORAGE_EXCEED_AUTHORITY

💡 Tip: If cloud storage operations are blocked by the identity authentication mechanism, you may encounter the error code: ACTION_FORBIDDEN

After obtaining the upload information, use the response data on the client side to complete the direct upload to the storage bucket. Example steps are as follows:

Step 1: Obtain upload information via 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"
    }
  ]'

Response Structure: The interface returns an array. Successful items contain the fields required for upload, while failed items contain code/message for troubleshooting.

[
  {
    "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."
  }
]

Step 2: Extract the required fields from the response and complete the file upload

For example, use tools like jq to extract fields from the first successful item in the array:

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')

Then use the above fields to upload the file with a PUT request to the corresponding 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​

Responses​

Returned when the call is successful

Response Headers
    X-Request-Id

    Request ID