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​

Body

arrayrequired

Upload object request parameters, array format

  • Array [
    • objectId Object ID, e.g., file name (string)required
    signedHeader object
    property name* string[]
  • Array [

    • string

  • ]
  • ]

Responses​

Returned when the call is successful

Response Headers
  • X-Request-Id string

    Request ID

Schema
  • Array [
    • oneOf
    uploadUrl uri
    downloadUrl uri
    downloadUrlEncoded uri
    token Token required for upload, fill in the X-Cos-Security-Token header (string)
    authorization Authorization information required for upload, fill in the Authorization header (string)
    cloudObjectMeta Metadata information required for upload, fill in the X-Cos-Meta-Fileid header (string)
    cloudObjectId Cloud object ID after object upload (string)
    objectId Object ID for this request (string)
  • ]
Loading...