tencent cloud

Cloud Object Storage

DocumentaçãoCloud Object StorageAPI DocumentationObject APIsBasic OperationsReturnBody

ReturnBody

PDF
Modo Foco
Tamanho da Fonte
Última atualização: 2025-11-28 17:42:56
Users can obtain information about the object in the response by including the ReturnBody parameter in upload requests (PUT Object, POST Object, CompleteMultipartUpload).

System Variable

The supported system variables for the upload callback ReturnBody are listed in the following table:
Note:
Obtaining exif, videoinfo, and imageinfo information depends on the capabilities of the CI (Cloud Infinite, CI) service. Obtaining these three types of variables will incur corresponding fees from the CI service; for details, refer to the CI Billing Overview.
Variable Name
Variable Description
Whether Sub-Variables Are Included
Required or Not
bucket
The target bucket for object upload.
No
No
object
The object name used for uploading the object to the bucket.
No
No
size
Object size, in bytes.
No
No
region
The region of the bucket for object upload.
No
No
mimeType
Object metadata Content-Type.
No
No
exif
If the uploaded object is an image type, it supports viewing the image's exif information, and the variable format is ${exif.sub-variable}.
Note:
To avoid ReturnBody carrying too much content and affecting interface performance, it is not recommended to directly fill in ${exif}; it is advised to specify the specific sub-variables.
Yes
No
videoInfo
If the uploaded object is an audio or video type, it supports viewing the metadata of the audio and video resources. The variable format is ${videoInfo.sub-variable}.
Note:
To avoid ReturnBody carrying too much content and affecting interface performance, it is not recommended to directly fill in ${videoInfo}; it is advised to specify the specific sub-information items.
Yes
No
imageInfo
If the uploaded object is an image type, it supports viewing the basic information of the image. The variable format is ${imageInfo.sub-variable}.
Note:
To avoid ReturnBody carrying excessive content and affecting interface performance, it is not recommended to directly fill in ${imageInfo}; it is advised to specify the specific sub-variables.
Yes
No
When using the exif, imageInfo, videoInfo variables, note the following points:
These three types of variables are only supported in domestic public cloud regions.
Obtaining these three types of variables depends on the capabilities of the CI (Cloud Infinite, CI) service. Users need to activate the CI service and ensure that the COS service role has the permission to invoke the CI service. Obtaining these three types of variables will incur corresponding fees from the CI service. For details, refer to CI billing overview.
Sub-variables are supported, such as ${variableName.sub-variable} and ${variableName.second-level-sub-variable}. To avoid ReturnBody carrying excessive content and affecting interface performance, it is not recommended to directly fill in ${imageInfo}; it is advised to specify the specific sub-variables.
For the specific sub-variables supported by variables, refer to the product documentation of CI and MPS services.
Note:
The exif and imageInfo variables only support image files, while videoInfo only supports audio and video files. A format mismatch will cause the callback to fail (Error Code 203).
exif: Obtain image EXIF
imageInfo: Obtain basic image information
videoInfo: Obtain media information

Procedure

Step One: Construct the ReturnBody Parameter

1. Express the desired object information in json format. In the sample below, bucket, key, myfilesize, and height are user-defined parameter names. Variable names are wrapped in ${}, and the values corresponding to these variable names represent the callback information to be obtained. For supported variable names in ReturnBody, refer to System Variables above. Sample:
# Example of Obtaining Image Information
{
    "bucket": "${bucket}",
    "key": "${object}",
    "myfilesize": "${size}",
    "height": "${imageInfo.height}"
}

# Sample for Obtaining Video Information Refer to the response content when magicvar = 1 in Obtain media information
{
    "bucket":"${bucket}",
    "key":"${object}",
    "myfilesize":"${size}",
    "video_duration":"${videoInfo.format.duration}",
    "video_bitrate":"${videoInfo.format.bit_rate}"
}

2. Convert the above json format to a string and Base64-encode it.
# Example of Obtaining Image Information
eyJidWNrZXQiOiAiJHtidWNrZXR9IiwgImtleSI6ICIke29iamVjdH0iLCAibXlmaWxlc2l6ZSI6ICIke3NpemV9IiwgImhlaWdodCI6ICIke2ltYWdlSW5mby5oZWlnaHR9In0=

# Example of Obtaining Video Information
ewogICAgImJ1Y2tldCI6ICIke2J1Y2tldH0iLAogICAgImtleSI6ICIke29iamVjdH0iLAogICAgIm15ZmlsZXNpemUiOiAiJHtzaXplfSIsCiAgICAidmlkZW9fZHVyYXRpb24iOiAiJHt2aWRlb0luZm8uZm9ybWF0LmR1cmF0aW9ufSIsCiAgICAidmlkZW9fYml0cmF0ZSI6ICIke3ZpZGVvSW5mby5mb3JtYXQuYml0X3JhdGV9Igp9

Step 2: Include the ReturnBody Parameter in the Upload Object Request

1. In the PUT Object request, pass the Base64-encoded result via the request header x-cos-return-body. The request example is as follows:
PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-Type: Content Type
Content-Length: Content Length
Content-MD5: MD5
x-cos-return-body: eyJidWNrZXQiOiAiJHtidWNrZXR9IiwgImtleSI6ICIke29iamVjdH0iLCAibXlmaWxlc2l6ZSI6ICIke3NpemV9IiwgImhlaWdodCI6ICIke2ltYWdlSW5mby5oZWlnaHR9In0=
Authorization: Auth String

[Object Content]
2. In the POST Object request, pass the Base64-encoded result via the form field x-cos-return-body.
POST / HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 29 Aug 2019 07:39:34 GMT
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Length: 1119
Connection: close

------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="q-sign-algorithm"

sha1
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="q-ak"

AKIDLdDGwRp0KIuI9sZDeJG3xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="q-key-time"

1759216346;1759217246
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="q-signature"

71f6d4a559axxxxxxxxxxxxxxxxxxxxxxxxx
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="policy"

eyJleHBpcmF0aW9uIjoiMjAyNS0wOS0zMFQwNzoyNzoyNi4wMDBaIiwiY29uZGl0aW9ucyI6W3sicS1zaWduLWFsZ29yaXRobSI6InNoYTEifSx7InEtYWsiOiJBS0lETGRER3dScDBLSXVJOXNaRGVKRzN4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHgifSx7InEtc2lnbi10aW1lIjoiMTc1OTIxNjM0NjsxNzU5MjE3MjQ2In0seyJidWNrZXQiOiJleGFtcGxlYnVja2V0LTEyNTAwMDAwMDAifSx7ImtleSI6ImV4YW1wbGVvYmplY3QifV19
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="x-cos-security-token"

ZflOqzkNb2266djz4xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="key"

exampleobject
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="x-cos-return-body"

ewogICAgImJ1Y2tldCI6ICIke2J1Y2tldH0iLAogICAgImtleSI6ICIke29iamVjdH0iLAogICAgIm15ZmlsZXNpemUiOiAiJHtzaXplfSIsCiAgICAidmlkZW9fZHVyYXRpb24iOiAiJHt2aWRlb0luZm8uZm9ybWF0LmR1cmF0aW9ufSIsCiAgICAidmlkZW9fYml0cmF0ZSI6ICIke3ZpZGVvSW5mby5mb3JtYXQuYml0X3JhdGV9Igp9
------WebKitFormBoundaryZBPbaoYE2gqeB21N
Content-Disposition: form-data; name="file"; filename="example.mp4"
Content-Type: video/mp4

[Object Content]
------WebKitFormBoundaryZBPbaoYE2gqeB21N--
3. In the Complete Multipart Upload request, pass the Base64-encoded result via the request header x-cos-return-body.
POST /exampleobject?uploadId=UploadId HTTP/1.1
Host: exmaplebucket-1250000000.cos.region.myqcloud.com
x-cos-return-body: ewogICAgImJ1Y2tldCI6ICIke2J1Y2tldH0iLAogICAgImtleSI6ICIke29iamVjdH0iLAogICAgIm15ZmlsZXNpemUiOiAiJHtzaXplfSIsCiAgICAidmlkZW9fZHVyYXRpb24iOiAiJHt2aWRlb0luZm8uZm9ybWF0LmR1cmF0aW9ufSIsCiAgICAidmlkZW9fYml0cmF0ZSI6ICIke3ZpZGVvSW5mby5mb3JtYXQuYml0X3JhdGV9Igp9
Date: GMT Date
Content-Type: application/xml
Content-Length: Content Length
Content-MD5: MD5
Authorization: Auth String

[Request Body]

Step 3: Obtain the ReturnBody Information in the Response

1. The return of PUT Object will return object information in the response body in json format. The response example is as follows:
HTTP/1.1 200 OK
x-cos-request-id: NWU5MDNkZjVfYzVjNzJhMDlfMjVhNzNfMWMy****

{
 "bucket": "examplebucket-1250000000000",
 "height": "887",
 "key": "test.jpeg",
 "myfilesize": "214513"
}
2. The return of POST Object will return object information in the response body in json format. The response example is as follows:
HTTP/1.1 201 OK
x-cos-request-id: NWU5MDNkZjVfYzVjNzJhMDlfMjVhNzNfMWMy****

{
 "bucket": "examplebucket-1250000000000",
 "key": "test.mp4",
 "myfilesize": "214513",
 "video_duration": 1000,
 "video_bitrate": 1000
}
3. The Complete Multipart Upload request itself returns an XML request body, which contains important information about the multipart upload. Therefore, the ReturnBody-related information (object information, whether the ReturnBody calculation is successful, etc.) will be placed in the XML field ReturnBodyResult and returned to the user.
The ReturnBodyResult node is described below:
Node Name (Keyword)
Parent Node
Description
Type
ReturnBodyResult
CompleteMultipartUploadResult
ReturnBody's result information.
Container
Status
CompleteMultipartUploadResult.ReturnBodyResult
Whether the ReturnBody is obtained successfully. Supported enum values: 200, 203.
200 indicates a successful upload and successful obtainment of ReturnBody;
203 indicates a successful upload but failure to obtain ReturnBody.
Integer
Error
CompleteMultipartUploadResult.ReturnBodyResult
When the Status is 203, it indicates that the ReturnBody failed to be obtained. An Error is returned, providing the callback failure information.
Container
Code
CompleteMultipartUploadResult.ReturnBodyResult
The error code for callback failure information, such as GetReturnBodyFailed.
String
Message
CompleteMultipartUploadResult.ReturnBodyResult
The error message for a failed obtainment of ReturnBody.
String
ReturnBody
CompleteMultipartUploadResult.ReturnBodyResult
When the Status is 200, it indicates a successful upload and callback. The ReturnBody is returned, which is a Base64-encoded string of the ReturnBody json.
String
Response example:
HTTP/1.1 200 OK
Content-Type: application/xml

<CompleteMultipartUploadResult>
    <Location>http://examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Location>
    <Bucket>examplebucket-1250000000</Bucket>
    <Key>exampleobject</Key>
    <ETag>"aa259a62513358f69e98e******"</ETag>
    <ReturnBodyResult>
        <Status>200|203</Status>
        <!--When the Status is 203, it indicates that ReturnBody failed, and an Error is returned-->
        <Error>
            <Code>GetReturnBodyFailed</Code>
            <Message>Invalid return body params.</Message>
        </Error>
        <!--When the Status is 200, it indicates a successful upload and successful computation of ReturnBody. The Base64-encoded result of the json string is returned.-->
        <ReturnBody>
            eyJhIjogImIifQ==
        </ReturnBody>
    </ReturnBodyResult>
</CompleteMultipartUploadResult>

Return code

After the ReturnBody parameter is used in an upload request, the return codes mainly fall into the following cases:
A successful upload request and successful obtainment of ReturnBody, and 200 is returned.
Upload request succeeded, but failed to obtain ReturnBody:
Failure reason
Return code
ErrorCode
Message
The ReturnBody parameter is invalid.
203
GetReturnBodyFailed
Invalid return body params.
Calling the CI service results in a failure to obtain parameters due to reasons such as lack of access permissions or unactivated services.
203
GetReturnBodyFailed
Error status from ci: ${code}, should return 200 OK.
Here, ${code} is the error code returned by the data service, such as 400, 403, etc.
Upload failed. ReturnBody computation will not be triggered, and the returned error codes and messages follow the rules of regular upload requests.

Best Practices

Anterior: POST ObjectPróximo: HEAD Object

Ajuda e Suporte

Esta página foi útil?

comentários