This topic describes how to set up an Object Storage Service (OSS)-based direct data transfer service for mobile apps and configure upload callback.

Background information

Set up direct data transfer for mobile apps describes how to set up an OSS-based direct data transfer service for a mobile app. After the OSS-based direct transfer service is set up for an Android or iOS app, a Security Token Service (STS) token is issued to an app user when the app user sends an upload request. However, the app user can use the STS token to upload data to OSS multiple times until the token becomes invalid. As a result, the app server cannot identify the data uploaded by the app user, which complicates data management for the app developers. To address this issue, OSS provides the upload callback feature.

Procedure

The following figure shows how upload callback works.Callback

After OSS receives an upload request sent from an Android or iOS app (Step 5), OSS triggers an upload callback task (Step 6) to send a callback request to the app server. Then, the app server returns a response to OSS, and OSS sends the upload result to the Android or iOS app based on the response (Step 7). For more information, see Callback in OSS API Reference.

Purposes

  • You can use upload callback to send the basic information about the uploaded object to the app server.

    The following table describes the variables that can be included in the returned basic information. The format of the returned content is specified when the object is uploaded by using the Android or iOS app.

    System variable Description
    bucket The bucket to which the object is uploaded by using the mobile app.
    object The name of the object after the object is uploaded to OSS by using the mobile app.
    etag The ETag of the uploaded object, which is the ETag field included in the upload result returned to the mobile app user.
    size The size of the uploaded object.
    mimeType The type of the uploaded data.
    imageInfo.height The height of an uploaded image.
    imageInfo.width The width of an uploaded image.
    imageInfo.format The format of an uploaded image. Examples: JPG and PNG.
  • You can use upload callback to customize callback parameters for the app server to obtain information about the app client.

    For example, you are an app developer and you want to obtain information about device information, such as the app version, operating system version, the GPS location, and mobile phone model. In this case, you can customize the following parameters for the app when objects are uploaded by using the Android or iOS app:

    • x:version: the app version
    • x:system: the operating system version
    • x: gps: the GPS location
    • x: phone: the mobile phone model

    After you configure the preceding parameters, these parameters are carried when the Android or iOS app client uploads an object to OSS. Then, OSS includes these parameters in callbackBody sent to the app server. This way, the app server receives the information about the app client.

Requirements on the app server for upload callback

  • A service that can receive POST requests is deployed. This service must have a public IP address such as www.abc.com/callback.php or 11.22.33.44/callback.php.
  • This service must correctly respond to OSS, and the response must be in the JSON format. You can customize the content in the response. OSS returns the response from the app server to the Android or iOS app. For more information, see Callback in OSS API Reference.

Configure upload callback requests on the mobile app side

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

  • callbackUrl: specifies the URL of the app server to which the callback request is sent, such as http://abc.com/callback.php. This URL must be accessible over the Internet.
  • callbackBody: specifies the preceding system variables OSS returns to the app server. You can specify one or more variables returned in the callbackBody.

Assume that you are an app developer, and the URL of the app server is http://abc.com/callback.php. You want to obtain the object name and size and specify x: phone as the mobile phone model and x:system as the operating system version.

Sample requests for upload callback:

  • Sample request for upload callback on the iOS app:
    OSSPutObjectRequest * request = [OSSPutObjectRequest new];
    request.bucketName = @"<bucketName>";
    request.objectKey = @"<objectKey>";
    request.uploadingFileURL = [NSURL fileURLWithPath:@<filepath>"];
    // Set callback parameters.
    request.callbackParam = @{
                              @"callbackUrl": @"http://abc.com/callback.php",
                              @"callbackBody": @"filename=${object}&size=${size}&photo=${x:photo}&system=${x:system}"
                              };
    // Customize variables.
    request.callbackVar = @{
                            @"x:phone": @"iphone6s",
                            @"x:system": @"ios9.1"
                            };
  • Sample request for upload callback on the Android app:
    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://abc.com/callback.php");
            put("callbackBody", "filename=${object}&size=${size}&photo=${x:photo}&system=${x:system}");
        }
    });
    put.setCallbackVars(new HashMap<String, String>() {
         {
             put("x:phone", "IPOHE6S");
             put("x:system", "YunOS5.0");
         }
    });

Sample upload callback request received by the app server

The upload callback requests received by the app server differ in URLs and callbackBody content based on the preceding configurations of callbackUrl and callbackBody. Example:

POST /index.html HTTP/1.0
Host: 121.43.113.8
Connection: close
Content-Length: 81
Content-Type: application/x-www-form-urlencoded
User-Agent: ehttp-client/0.0.1
authorization: kKQeGTRccDKyHB3H9vF+xYMSrmhMZjzzl2/kdD1ktNVgbWE****G0G2SU/RaHBovRCE8OkQDjC3uG33esH2txA==
x-oss-pub-key-url: aHR0cDovL2dvc3NwdWJsaWMuYWxpY2RuLmNv****YWxsYmFja19wdWJfa2V5X3YxLnBlbQ==
filename=test.txt&size=5&photo=iphone6s&system=ios9.1

For more information, see Callback in OSS API Reference.

The app server determines whether the upload callback request is sent from OSS

If your app server is attacked and receives invalid requests, the app server needs to determine whether the callback request is sent from OSS.

To determine whether the callback request is sent from OSS, the app server uses the x-oss-pub-key-url and authorization parameters in the header sent by OSS for RSA signature verification. Only callback requests that pass RSA signature verification are considered as from OSS. The sample programs provided in this topic include the parameters for RSA signature verification for your reference.

The app server processes the callback request

After the app server determines that the callback request is sent from OSS, the format of the request to the app server is specified. Example:
filename=test.txt&size=5&photo=iphone6s&system=ios9.1

The app server can parse the content sent by OSS to obtain the desired data. After the data is obtained, the app server can store the data for subsequent management.

OSS processes the response from the app server

One of the following scenarios may occur:

  • OSS sends the callback request to the app server. The app server fails to receive the request or is inaccessible. OSS sends the status code 203 to the Android or iOS app. However, data has been stored in OSS.
  • The app server receives the callback request from OSS and responds to OSS properly. OSS returns the status code 200 and the response from the app server to the Android or iOS app.

Download sample programs

The sample programs only check the signature received by the app server. You must manually add the code that is executed to parse the format of the callback request received by the app server.

  • Java
    • Download link: Click here.
    • To run the sample program, decompress the downloaded package and run the java -jar oss-callback-server-demo.jar 9000 command. 9000 is the default port. You can change the port number.
      Note The JAR package example runs on OSS SDK for Java 1.7. If errors occur, modify the code based on the code sample. This package contains the code for a Maven project.
  • PHP
    • Download link: Click here.
    • To run the sample program, decompress the downloaded package to an Apache environment. This specific environment is required to obtain some headers due to PHP-specific features. Modify the sample code based on the actual environment.
  • Python
    • Download link: Click here.
    • To run the sample program, decompress the downloaded package and run the python callback_app_server.py command. This program functions as a simple HTTP server. To run this program, you may need to install the dependency for RSA.
  • Ruby
    • Download link: Click here.
    • To run the sample program, run the ruby aliyun_oss_callback_server.rb command.