This topic describes how to obtain signature information from the server in various programming languages based on POST policies, configure upload callbacks, and then use form upload to upload data to Object Storage Service (OSS).

Background information

When users upload objects to OSS, the information about the upload and names of the objects must be sent to the application server. When users upload images, information about the sizes of the images must be sent to the application server. To meet this requirement, OSS provides the upload callback feature.

Process

The following figure shows how upload callback works.Flowchart

If a user wants the application server to receive an upload callback request when the user uploads an object to OSS, configure a callback function to ensure that OSS sends the upload callback request to the application server. After the user uploads the object, the application server returns a response for the upload callback request to OSS. Then, OSS forwards the response to the user. This response is the upload result.

Examples

To obtain signature information from the server, configure upload callbacks, and then use form upload to upload data to OSS by using one of the following programming languages:

Process analysis

The following process describes the core code that is used and the messages that can be returned.

  1. A user sends a request to the application server to obtain the upload policy and callback configurations.
    In the upload.js file of the client source code, the value of the serverUrl variable can be used to configure the URL of the application server. After you configure the URL of the application server, the client sends a GET request to serverUrl to obtain the required information.
    // serverUrl specifies the URL of the application server that returns information about the signature and upload policies. Replace the sample IP address and port number with actual values in your business scenario. 
    serverUrl = 'http://88.88.88.88:8888'
  2. The application server returns the upload policy and the code that is used to configure upload callbacks to the user.
    The application server processes the GET request that is sent from the client for direct data transfer based on the services that are used to obtain information about the signature of the server. You can modify the corresponding code to ensure that the application server returns the correct message to the client. The configuration documents for different programming languages provide clear instructions for your reference.

    The following example describes a message body that is returned to a client. The message body is used as an important parameter to upload an object from the client.

    {
    "accessid":"LTAI5tAzivUnv4ZF1azP****",
    "host":"http://post-test.oss-cn-hangzhou.aliyuncs.com",
    "policy":"eyJleHBpcmF0aW9uIjoiMjAxNS0xMS0wNVQyMDoyMzoyM1oiLCJjxb25kaXRpb25zIjpbWyJjcb250ZW50LWxlbmd0aC1yYW5nZSIsMCwxMDQ4NTc2MDAwXSxbInN0YXJ0cy13aXRoIiwiJGtleSIsInVzZXItZGlyXC8i****",
    "signature":"I2u57FWjTKqX/AE6doIdyff1****",
    "expire":1446727949,
    "callback":"eyJjYWxsYmFja1VybCI6Imh0dHA6Ly9vc3MtZGVtby5hbGl5dW5jcy5jb206MjM0NTAiLAoiY2FsbGJhY2tCb2R5IjoiZmlsZW5hbWU9JHtvYmplY3R9JnNpemU9JHtzaXplfSZtaW1lVHlwZT0ke21pbWVUeXBlfSZoZWlnaHQ9JHtpbWFnZUluZm8uaGVpZ2h0fSZ3aWR0aD0ke2ltYWdlSW5mby53aWR0aH0iLAoiY2FsbGJhY2tCb2R5VHlwZSI6ImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCJ9",
    "dir":"user-dirs/"
    }

    The content that is returned for a callback in the preceding example is encoded in Base64. The following code shows the content decoded in Base64:

    {"callbackUrl":"http://oss-demo.aliyuncs.com:23450",
    "callbackBody":"filename=${object}&size=${size}&mimeType=${mimeType}&height=${imageInfo.height}&width=${imageInfo.width}",
    "callbackBodyType":"application/x-www-form-urlencoded"}
    Note The callback method that is used in the preceding example is provided only for reference. You can configure a callback method by modifying the server code.
    Parameter Description
    callbackUrl The URL of the application server to which OSS sends the request.
    callbackHost The Host header that is included in the request that is sent by OSS to the application server.
    callbackBody The content that OSS sends to the application server. The content can be an object or an image. You can send information about the name, size, or type of an object. You can send information about the height and width of an image.
    callbackBodyType The content type of the request.
  3. The user sends an object upload request to OSS.
    In the upload.js file of the client source code, the value of callbackbody is included in the callback body that is returned by the application server to the client in Step 2.
    new_multipart_params = {
         'key' : key + '${filename}',
         'policy': policyBase64,
         'OSSAccessKeyId': accessid,
         // Set the status code that is returned by the server to 200. If you do not configure this parameter, the 204 status code is returned. 
         'success_action_status' : '200', 
         'callback':  callbackbody,
         'signature': signature,
     };
  4. OSS sends a callback request to the application server based on callback configurations.
    After you upload the object to OSS, OSS analyzes the upload callback configurations of the client and sends the POST callback request to the application server. The following sample code shows the content of the request message:
    Hypertext Transfer Protocol
        POST / HTTP/1.1\r\n
        Host: 47.97.168.53\r\n
        Connection: close\r\n
        Content-Length: 76\r\n
        Authorization: fsNxFF0w******MNAoFb//a8x6v2lI1******h3nFUDALgku9bhC+cWQsnxuCo******tBUmnDI6k1PofggA4g==\r\n
        Content-MD5: eiEMyp7lbL8KStPBzMdr9w==\r\n
        Content-Type: application/x-www-form-urlencoded\r\n
        Date: Sat, 15 Sep 2018 10:24:12 GMT\r\n
        User-Agent: aliyun-oss-callback\r\n
        x-oss-additional-headers: \r\n
        x-oss-bucket: signedcallback\r\n
        x-oss-owner: 137918634953****\r\n
        x-oss-pub-key-url: aHR0cDovL2dvc3NwdWJsaWMuYWxpY2RuLmNvbS9jYWxsYmFja19wdWJfa2V5X3YxLnaH****\r\n
        x-oss-request-id: 534B371674E88A4D8906****\r\n
        x-oss-requester: 137918634953****\r\n
        x-oss-signature-version: 1.0\r\n
        x-oss-tag: CALLBACK\r\n
        eagleeye-rpcid: 0.1\r\n
        \r\n
        [Full request URI: http://47.xx.xx.53/]
        [HTTP request 1/1]
        [Response in frame: 39]
        File Data: 76 bytes
    HTML Form URL Encoded: application/x-www-form-urlencoded
        Form item: "filename" = ".snappython.png"
        Form item: "size" = "6014"
        Form item: "mimeType" = "image/png"
        Form item: "height" = "221"
  5. The application server returns a response to OSS.
    The application server verifies the access credentials based on the authorization method that is included in the message that is sent by OSS. If the verification is successful, the application server returns the following message to OSS in the JSON format :
    {
    "String value": "ok",
    "Key": "Status"
    }
  6. OSS forwards the response from the application server to the user.

Analysis of client source code

To download the client source code, click aliyun-oss-appserver-js-master.zip.
Note Plupload is used for the JavaScript code of the client. Plupload is a simple, easy-to-use, and powerful tool that provides advanced features to allow you to upload files. The tool supports multiple upload methods, including uploads by using HTML, Flash, Silverlight, and HTML4. Plupload detects the current environment and selects the most suitable upload method. The tool assigns the highest priority to HTML5 for uploads. For more information about Plupload, visit Plupload.com.

The following sample code describes common features:

  • Specify random names for the objects that you upload

    If you want to specify random object names without changing the name extension, you can use the following code to modify the function:

    function check_object_radio() {
        g_object_name_type = 'random_name';
    }
  • Retain the original object names

    If you want to retain the original object names, you can use the following code to modify the function:

    function check_object_radio() {
        g_object_name_type = 'local_name';
    }
  • Configure the directory to which you want to upload the object
    The directory to which the object is uploaded is determined by the server. You can upload objects only to a specified directory. This helps ensures data isolation. The following code shows how to set the path of the directory to abc/ by using PHP. The path of the directory must end with a forward slash (/).
    $dir ='abc/';
  • Configure upload conditions

    You can use Plupload filters to configure upload conditions, such as uploading only images, configuring limits for the size of objects that you can upload, and preventing repeated uploads of an object.

    var uploader = new plupload.Uploader({
        …
        filters: {
            mime_types : [ 
            // Specify that only images and ZIP objects can be uploaded. 
            { title : "Image files", extensions : "jpg,gif,png,bmp" },
            { title : "Zip files", extensions : "zip" }
            ], 
            // Specify that only objects that are smaller than 400 KB in size can be uploaded. 
            max_file_size : '400kb', 
            // Specify that the repeat upload of an object is denied. 
            prevent_duplicates : true 
        },
    • mime_types: specifies the extensions of the objects that you want to upload.
    • max_file_size: specifies the maximum size of the objects that you want to upload.
    • prevent_duplicates: specifies that an object cannot be repeatedly uploaded.
  • Obtain the names of uploaded objects

    You can obtain the names of the objects that are uploaded by using Plupload to call the FileUploaded event.

    FileUploaded: function(up, file, info) {
                if (info.status == 200)
                {
                    document.getElementById(file.id).getElementsByTagName('b')[0].innerHTML = 'upload to oss success, object name:' + get_uploaded_object_name(file.name);
                }
                else
                {
                    document.getElementById(file.id).getElementsByTagName('b')[0].innerHTML = info.response;
                }
        }

    You can use the get_uploaded_object_name(file.name) function to obtain the names of the objects that are uploaded to OSS. The file.name parameter specifies the names of the objects before the objects are uploaded.

  • Upload the signature

    You can use the following sample core code to obtain the policyBase64, accessid, and signature variables from the server by using JavaScript.

    function get_signature()
    {
        // Determine whether the value of the expire parameter exceeds the local time. If the value exceeds the local time, you must request a new signature. The signature is returned after three seconds. 
        now = timestamp = Date.parse(new Date()) / 1000; 
        if (expire < now + 3)
        {
            body = send_request()
            var obj = eval ("(" + body + ")");
            host = obj['host']
            policyBase64 = obj['policy']
            accessid = obj['accessid']
            signature = obj['signature']
            expire = parseInt(obj['expire'])
            callbackbody = obj['callback'] 
            key = obj['dir']
            return true;
        }
        return false;
    };

    The following code provides an analysis of the message that can be returned by the server.

    Note The message is not in a specific format. The accessid, policy, and signature fields are included in the message content.
    {"accessid":"LTAI5tAzivUnv4ZF1azP****",
    "host":"http://post-test.oss-cn-hangzhou.aliyuncs.com",
    "policy":"eyJleHBpcmF0aW9uIjoiMjAxNS0xMS0wNVQyMDoyMzoyM1oiLCJjxb25kaXRpb25zIjpbWyJjcb250ZW50LWxlbmd0aC1yYW5nZSIsMCwxMDQ4NTc2MDAwXSxbInN0YXJ0cy13aXRoIiwiJGtleSIsInVzZXItZGlyXC8i****",
    "signature":"I2u57FWjTKqX/AE6doIdyff1****",
    "expire":1446726203,"dir":"user-dir/"}
    • accessid: specifies the AccessKey ID for which the user sent the request.
    • host: specifies the domain name to which the user wants to send the upload request.
    • policy: specifies the form upload policy that is encoded as a string in Base64. For more information, see Appendix: Policy.
    • signature: specifies the signature string that is generated based on the Policy.
    • expire: specifies the point in time when the upload policy expires. The value of this parameter is specified in the server configurations. Before the expiration time, users can repeatedly use the policy to upload objects. Users do not need to obtain signatures from the server for each upload.
    Note To reduce the server load, you can obtain the signature each time you initialize an OSSClient instance to upload an object. If you use the OSSClient instance to upload another object, compare the local time with the expiration time of the signature to check whether the signature is expired. If the signature is expired, you can send a request to obtain a new signature. If the signature does not expire, you can use the existing signature.

    Policy analysis:

    {"expiration":"2015-11-05T20:23:23Z",
    "conditions":[["content-length-range",0,1048576000],
    ["starts-with","$key","user-dir/"]]

    In the preceding example, the starts-with field that is added to the policy specifies that the object name must start with user-dir. You can configure this field. The starts-with field is added to the policy because each application corresponds to a bucket in most scenarios. To prevent data from being overwritten, you can specify a prefix for the name of each object that you upload to OSS. After the user obtains the policy, the user can upload multiple objects, change the prefix of an object, and upload the object to the directory that is accessed by another user when the policy is valid. To resolve this issue, the prefix is specified by the application server. This way, even if the user obtains the policy, the user cannot upload the object to the directory that is accessed by another user. This helps ensure data security.

  • Configure the URL of the application server

    In the upload.js file of the client source code, the value of the serverUrl variable can be used to configure the URL of the application server. After you configure the URL of the application server, the client sends a GET request to serverUrl to obtain the required information.

    // serverUrl specifies the URL of the application server that returns information about the signature and upload policies. Replace the sample IP address and port number with actual values in your business scenario. 
    serverUrl = 'http://88.88.88.88:8888'

FAQ

How do I upload multiple objects to OSS at a time?

The service does not support API operations for uploading multiple objects to OSS at a time. If you want to upload multiple objects to OSS at a time, you can repeatedly perform the steps for uploading a single object.