Return Data Specification

This documentation provides a comprehensive guide to ​​data response and callback mechanisms in object storage services​​, covering three core subsystems:

• ​​Client Response Control (ReturnBody)​​ - Customize client-side returns using dynamic variables ($(bucket), $(x:customVar)), supporting key-value pairs for standard uploads and JSON for multipart uploads
• ​​Server Callback Protocol (CallbackBody)​​ - Configure HMAC-SHA1 signed callbacks for asynchronous system integration
• ​​File Naming & Processing (SaveKey/PersistentOps)​​ - Generate storage paths with timestamp/UUID variables, and set up automated workflows like video transcoding

returnBody Return Mechanism

Scenario 1: Return a request URL specified by returnBody and returnUrl

For example:

    bucket:     image
    key:        205.jpg
    returnBody: bucket=$(bucket)&key=$(key)
    returnUrl:  http://www.abc.com

The content returned to the uploader is:

    http://www.abc.com?bucket=image&key=205.jpg&hash=610d0284a0923298247d3a269ee28908cdcc7476

Scenario 2: Specify returnBody, if not specified returnUrl, return returnBodythe specified content.

returnBodyIt is convenient to customize the information returned to the client. Currently, two parameter methods are supported: custom substitution variables and specified substitution variables . The two methods can be used in combination at will.

Note:

1. For normal uploading, the returnBody content returns the file hash value by default; for multipart uploading, the returnBody content returns the file hash value and key by default.
2. After setting, the returnBodyreturned content is encoded by URL-safe Base64 . For better illustration, the following example shows the decoded content.

custom substitution variable

• Format: $(x:variable)
• Example:

    ReturnBody: position=$(x:position)&message=$(x:message)
    Request Parameter: position=abc&message=Success

The content returned to the uploader by ordinary upload is:

    position=abc&message=Success&hash=610d0284a0923298247d3a269ee28908cdcc7476

The content returned to the uploader for multipart upload is:

    {
        "position":"abc",
        "message":"Success",
        "key":"filename",
        "hash":"610d0284a0923298247d3a269ee28908cdcc7476"
    }

Note: The custom variable must be in UTF-8 format and cannot contain &, otherwise it will be parsed as garbled characters.

special substitution variables

• Format: $(variable)
• Example:

    returnBody：url=$(url)&fsize=$(fsize)&bucket=$(bucket)
    url=http://abc.com/1.jpg
    fsize=1231341
    bucket=test

The content returned to the uploader by ordinary upload is:

    url=http://abc.com/1.jpg&fsize=1231341&bucket=test&hash=610d0284a0923298247d3a269ee28908cdcc7476

The content returned to the uploader for multipart upload is:

    {
        "url":"http://abc.com/1.jpg",
        "fsize":"1231341",
        "bucekt":"test",
        "key":"1.jpg",
        "hash":"610d0284a0923298247d3a269ee28908cdcc7476"
    }

Note: The specified parameter order is the order in which the results of these parameter values are returned.

• Variable Description:

Specified Variable	Description	Upload Interface
$(persistentID)	The process ID for upload preprocessing or triggering persistence processing.	Normal upload (limited use for multipart upload)
$(bucket)	Retrieve the name of the target bucket.	Normal upload/multipart upload
$(key)	Retrieve the resource name of the file stored in the bucket.	Normal upload/multipart upload
$(fname)	The original filename of the upload.	Normal upload/multipart upload
$(hash)	The resource’s Etag.	Normal upload/multipart upload
$(fsize)	Resource size in bytes.	Normal upload/multipart upload
$(url)	The actual path to access the resource.	Normal upload/multipart upload
$(ip)	The source IP address of the request.	Normal upload/multipart upload
$(imageInfo)	Basic information about the uploaded image.	Normal upload/multipart upload
$(exif)	Exif information about the uploaded image.	Normal upload/multipart upload
$(avinfo)	Video metadata in JSON format, URL-safe Base64 encoded.	Normal upload/multipart upload
$(mimeType)	Resource type, for example, image/jpg for JPG images.	Normal upload/multipart upload

callbackBody Callback Mechanism

callbackBodyIt is suitable for callbackUrlcustomizing the format of the information returned to the client when the user opens the settings, that is, calling back the server.

Note: The callback content is encoded by URLEncode, and the callback server can perform relevant decoding after receiving the callback content

callbackBody supports three parameter methods: constants, custom substitution variables, and specified substitution variables, which can be used in combination.

Callback data description

Constants

• Format: key1=value1&key2=value2
• Description: After the object storage platform obtains this constant parameter, it will directly call back the information without any processing callbackUrl.
• example:

username=john&age=21

custom substitution variable

• Format: $(x:variable)
• Example:

    callbackBody: position=$(x:position)&message=$(x:message)

If $(x:position)=abc, $(x:message)=Success, the content returned to the callback server is:

    position%3dabc%26message%3dSuccess%0a%0a

Note: The custom variable must be in UTF-8 format and cannot contain &, otherwise it will be parsed as garbled characters.

special substitution variables

• Format: $(variable)
• Example:

    callbackBody: url=$(url)&fsize=$(fsize)&bucket=$(bucket)
    url=http://abc.com/1.jpg
    fsize=1231341
    bucket=test

Then the content returned to the callback server (with a urlencode encoding) is:

    url%3daHR0cDovL2FiYy5jb20vMS5qcGc%3d%26fisize%3d1231341%26bucket%3dtest%0a

• Variable Description:

Specified variable	Description	Upload interface
$(persistentID)	The process ID of upload preprocessing or trigger persistence processing.	Normal upload (limited use of multipart upload)
$(bucket)	Get the upload target space name.	Normal upload/multipart upload
$(key)	Get the resource name of the file saved in the space.	Normal upload/multipart upload
$(fname)	Uploaded original filename	Normal upload. /part upload
$(hash)	Etag of the resource	Normal upload. /part upload
$(fsize)	Resource size, in bytes.	Normal upload/multipart upload
$(mimeType)	Resource type, for example, the resource type of a JPG image is image/jpg.	Normal upload/multipart upload
$(url)	The actual path to access the resource, URL-safe Base64 encoded .	Normal upload/multipart upload
$(ip)	The source IP of this request.	Normal upload/multipart upload
$ (costTime)	The time from when the server accepts the request to when it starts to call back the server, in milliseconds.	Normal upload/multipart upload
$(avinfo)	Video metadata, in JSON format, encoded in URL-safe Base64 .	Normal upload/multipart upload
$(imageInfo)	The basic information of the uploaded image is encoded in URL-safe Base64 .	Normal upload/multipart upload
$(exif)	The exif information of the uploaded image is encoded in URL-safe Base64 .	Normal upload/multipart upload
$(mimeType)	Resource type, for example, the resource type of a JPG image is image/jpg.	Normal upload/multipart upload

Callback response description

After getting the response code and response content of the callback server (must be in JSON format), the object storage platform will return a response to the client according to the response code and response content of the callback server.

\1. When the response of the callback server is 200 and the returned content is a json string, the response code from Object Storage to the client is 200, and the response content is:

    {
      "hash": "<hash string>",
      "response": "<response string>"
    }

\2. When the callback server responds abnormally, the response code from Object Storage to the client is 579, and the response content is:

    {
      "hash": "<hash string>",
      "error": {
        "callbackUrl": "<callbackUrl string>",
        "callback_bodyType": "<callback_bodyType string>",
        "callback_body": "<callback_body string>",
        "token": "<token string>",
        "err_code": "<err_code string>",
        "error": "<unexpected response>"
      }
    }

Callback Safety Mechanism

CDNetwork Object Storage will add Authorizationfields to the request header of the callback.

Format:

    <Accesskey>:<Urlsafe_Base64_Encode(hmac_sha1(callBackUrlWithQuery+"\n"+urlsafe_base64_encode(callbackBody),SecretKey))>

example:

    d0e56f9f4a75267eba123348f839fbedcd9464c6:OTQzNzU5YWVjOTZlNTRlMWIwYmQzZTA2ZDhjMTFhOWEyNGM1ZjIzZg==

callback retry mechanism

When the upload callback fails, the default is to retry 3 times in a row, and then retries every 1 minute (5 retries), for a total of 8 retries.

1. If the callback succeeds after retrying, the normal callback response will be returned with a status code of 200.
2. If there is still no normal response from the callback server after retrying, an abnormal callback response will be returned with a status code of 579.

saveKey Custom Naming

saveKeyUsed for resource name customization, only works when the user upload scope does not specify a key. This field only supports single-file normal upload.
saveKey supports three parameter methods: constants, custom substitution variables, and specified substitution variables, which can be used in combination.

Resource name description

constant

• Format: value
• Description: After specifying constant parameters, Object Storage does not do any processing, and the information is directly reserved for naming.
• example:

    saveKey: constant

folder

Format: dirname/key

• Description: Object storage does not have the concept of multi-level file directories, but virtualized path files can be implemented using file names.
• example:

    saveKey: dir/key

custom substitution variable

Format: $(x:variable)
Example:

    saveKey: $(x:position)

If $(x:position)= test, the file will be named test after uploading to object storage

Note: The custom variable must be in UTF-8 format and cannot contain &, otherwise it will be parsed as garbled characters.

special substitution variables

• Format: $(variable)
• Example:

    saveKey: $(year)/$(month)/$(hash)

If the current time is April 2016, the file is uploaded to object storage and saved as the specific HASH value of 2016/04/file.

• Variable Description:

Specified variable	Description
$(fname)	Uploaded original filename
$(hash)	Etag of the resource
$(mimeType)	Resource type, for example, the resource type of a JPG image is image/jpg.
$(suffix)	The suffix name of the resource, obtained from the suffix of the original file. If the original file has no suffix, the default is unknown
$(fprefix)	The original filename of the resource (without the suffix part)
$(uuid)	random number
$(year)	Year of upload. Such as: 2015
$(month)	Month of upload. eg: 01
$(day)	Date of upload. eg: 01
$(hour)	Hour when uploading. eg: 01
$ (min)	Minutes when uploading. eg: 01
$(sec)	seconds when uploading. eg: 01

Transcoding Instruction description

For commands such as video transcoding and screenshots, refer to the Ops parameter format .
example:

Video transcoding:

    persistentOps=avthumb/mp4/vb/64k|saveas/YnVja2V0OmZpbGVrZXk=;avthumb/flv/vb/64k|saveas/YnVja2V0OmZpbGVrZXk=

Video screenshot:

    persistentOps=vframe/jpg/offset/10|saveas/YnVja2V0OmZpbGVrZXk=;vframe/jpg/offset/15|saveas/YnVja2V0OmZpbGVrZXk=

Note: Commands can be combined, and multiple commands ;can be spliced together.