DocsICP FilingConsole
Documentation
Home Page Object Storage Service User Guide Object Direct client upload Upload data to OSS from apps Set up upload callbacks for mobile apps

Set up upload callbacks for mobile apps

Updated at:
Copy as MD
Product
My Favorites

This topic describes how to set up a direct data transfer service for mobile apps using Object Storage Service (OSS) and how to configure upload callbacks.

Background information

Set up direct data transfer for mobile applications describes how to set up a direct data transfer service for mobile apps using OSS. However, this solution has a drawback. For Android and iOS mobile apps, you can request a Security Token Service (STS) token once and use it to upload data to OSS multiple times. As a result, the application server cannot determine which data the user has uploaded, which makes it difficult for the application developer to manage the data. To address this issue, OSS provides the upload callback feature.

Procedure

The development flow for an upload callback is as follows:

image

After OSS receives data from an Android or iOS app (Step 5 in the figure) and before it returns the upload result to the user (Step 7), OSS triggers an upload callback task (Step 6). During the callback, OSS sends a request to your application server, waits for a response, and then forwards this response to the Android or iOS app. For more information, see Callback.

Purpose of upload callbacks

  • Upload callbacks inform the application server about the basic information of an uploaded file.

    This information can include one or more of the variables in the following table. The format of the returned content is specified by the Android or iOS app during the upload.

    System variable

    Description

    bucket

    The bucket to which the mobile app uploads the file.

    object

    The name of the file after it is uploaded to OSS by the mobile app.

    etag

    The ETag of the uploaded file. This is the etag field returned to the user.

    size

    The size of the uploaded file.

    mimeType

    The resource type.

    imageInfo.height

    The image height.

    imageInfo.width

    The image width.

    imageInfo.format

    The image format, such as JPG or PNG.

  • Upload callbacks can be used to set custom parameters to pass information.

    As a developer, you may want to know the user's app version, operating system version, GPS information, and phone model. You can specify the following custom parameters when an Android or iOS device uploads a file:

    • x:version: Specifies the app version.

    • x:system: Specifies the operating system version.

    • x:gps: Specifies the GPS information.

    • x:phone: Specifies the phone model.

    The Android or iOS app includes these parameters when it uploads a file to OSS. OSS then adds these parameters to the CallbackBody and sends it to the application server. This process allows the application server to receive the information.

Requirements for the application server

  • Deploy a service that can receive POST requests. This service must have a public network address, such as http://example.com/callback.php.

  • The service must return a valid response to OSS. The response must be in JSON format and can contain custom content. OSS forwards this response from the application server to the Android or iOS app. For more information, see Callback.

Set up an upload callback on the mobile app

To trigger an upload callback when OSS receives an upload request, include the following content when you construct the upload request in the mobile app:

  • The callback URL (`callbackUrl`). This is the URL of the server to which the callback request is sent, such as http://example.com/callback.php. This address must be accessible from the Internet.

  • The body of the callback request (`callbackBody`) that is sent to the application server. The body can include one or more of the system variables that OSS provides.

Suppose that your application server's upload callback URL is http://example.com/callback.php. You want to obtain the name and size of the uploaded file, and you have defined the x:phone variable for the phone model and the x:system variable for the operating system version.

The following are two examples of upload callbacks:

  • Example for specifying an upload callback on iOS: 

    OSSPutObjectRequest * request = [OSSPutObjectRequest new];
request.bucketName = @"<bucketName>";
request.objectKey = @"<objectKey>";
request.uploadingFileURL = [NSURL fileURLWithPath:@"<filepath>"];
// Set callback parameters.
request.callbackParam = @{
                          @"callbackUrl": @"http://example.com/callback.php",
                          @"callbackBody": @"filename=${object}&size=${size}&phone=${x:phone}&system=${x:system}"
                          };
// Set custom variables.
request.callbackVar = @{
                        @"x:phone": @"iphone6s",
                        @"x:system": @"ios9.1"
                        };

  • Example for specifying an upload callback on Android: 

    PutObjectRequest put = new PutObjectRequest(testBucket, testObject, uploadFilePath);
ObjectMetadata metadata = new ObjectMetadata();
metadata.setContentType("application/octet-stream");
put.setMetadata(metadata);
put.setCallbackParam(new HashMap<String, String>() {
    {
        put("callbackUrl", "http://example.com/callback.php");
        put("callbackBody", "filename=${object}&size=${size}&phone=${x:phone}&system=${x:system}");
    }
});
put.setCallbackVars(new HashMap<String, String>() {
     {
         put("x:phone", "iPhone 6s");
         put("x:system", "YunOS5.0");
     }
});

Callback request received by the application server

The callback request that the application server receives varies depending on the configured callback URL and body. The following code provides an example:

POST /index.html HTTP/1.0
Host: 203.0.113.0
Connection: close
Content-Length: 81
Content-Type: application/x-www-form-urlencoded
User-Agent: ehttp-client/0.0.1
authorization: kKQe**************/kdD1ktNVgbWE**************
x-oss-pub-key-url: aHR0**************
filename=test.txt&size=5&phone=iphone6s&system=ios9.1

For more information, see the Callback API reference.

Verify that the callback request is from OSS

If your callback server is targeted by a malicious attack, such as receiving forged callback requests that disrupt normal operations, you must verify that each callback request is from OSS.

To do this, perform RSA validation on the x-oss-pub-key-url and authorization parameters in the header that OSS sends to the application server. A request is from OSS only if it passes the RSA validation. The sample programs in this topic provide an example of this implementation for your reference.

Process the callback request

The application server verifies that the request is from OSS and specifies the content format for the callback, such as 

filename=test.txt&size=5&phone=iphone6s&system=ios9.1

The application server can parse the content that OSS returns to obtain the required data. After obtaining the data, the application server can store it for future management.

How OSS processes the application server response

Two scenarios can occur:

  • OSS sends the callback request to the application server, but the server fails to receive it or is inaccessible. In this case, OSS returns status code 203 to the Android or iOS app. The data is already stored in OSS.

  • The application server receives the callback request from OSS and returns a valid response. In this case, OSS returns status code 200 to the Android or iOS app and forwards the application server's response to the app.

Download sample programs

The sample programs demonstrate only how to verify the signature that the application server receives. You must add your own code to parse the content of the callback body.

  • Java

    • Download URL.

    • How to run: After you decompress the package, run java -jar oss-callback-server-demo.jar 9000. In this example, 9000 is the port number, which you can change.

      Note

      This JAR example was tested on Java 1.7. If you encounter any issues, you may need to modify the code. This is a Maven project.

  • PHP

    • Download URL.

    • How to run: Deploy the decompressed package in an Apache environment. Because of the nature of PHP, the method for retrieving some headers depends on the environment. You may need to refer to the example and modify it for your specific environment.

  • Python

    • Download URL.

    • How to run: After you decompress the package, run python callback_app_server.py. The program implements a simple HTTP server. You may need to install the RSA dependency to run this program.

  • Ruby Version

FAQ

Can I change the callback URL to have another server receive the callback and confirm the upload status?

No, you cannot. The parameters are signed and verified by the OSS server-side. Any tampered content will fail the validation.

Previous：Set up a direct upload service for mobile applicationsNext：Upload data to OSS from mini programs