Object Storage Service:Set up upload callbacks for mobile apps

Background information

Set up direct data transfer for mobile applications 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. 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 an upload callback works.

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.

Purposes

• You can use an 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 the uploaded image.
  imageInfo.width	The width of the uploaded image.
  imageInfo.format	The format of the uploaded image. Examples: JPG and PNG.

• You can use an upload callback to specify custom 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 the app version, operating system version, GPS coordinates, and mobile phone model. In this case, you can specify the following custom 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 coordinates

  • 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 and sends callbackBody to the app server. This way, the app server receives the information about the app client.

Requirements on the app server for upload callbacks

• A service that receives POST requests is deployed. This service must have a public IP address. Example: http://example.com/callback.php.

• This service must correctly respond to OSS, and the response must be in the JSON format. You can specify a custom response. OSS returns the response from the app server to the Android or iOS app. For more information, see Callback.

Configure upload callback requests on the mobile app side

To trigger an 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: The URL of the app server to which the callback request is sent, such as http://example.com/callback.php. This URL must be accessible over the Internet.

• callbackBody: The preceding system variables OSS returns to the app server. You can specify one or more variables returned in callbackBody.

For example, you are an app developer, and the URL of the app server is http://example.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.

The following section describes two types of requests for an upload callback:

• Example of an upload callback request on an iOS app:

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

• Example of an upload callback request on an 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://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");
       }
  });

Sample upload callback request received by the app server

The upload callback requests received by the app server vary based on the preceding configurations of callbackUrl and callbackBody. 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 Callback.

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 performs RSA signature verification on the x-oss-pub-key-url and authorization response headers sent by OSS. Only callback requests that pass RSA signature verification are sent from OSS. The sample programs provided in this topic include the headers for RSA signature verification for your reference.

The app server processes the callback request

filename=test.txt&size=5&phone=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. In that case, OSS sends the HTTP 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. In that case, OSS returns the HTTP status code 200 and the response from the app server to the Android or iOS app.

Download sample programs

The sample programs only examine 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 URL: Click here.

  • To run the sample program, decompress the downloaded package and run java -jar oss-callback-server-demo.jar 9000. 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 an error occurs, modify the code based on the sample code. This package contains the code for a Maven project.

• PHP

  • Download URL: 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 URL: Click here.

  • To run the sample program, decompress the downloaded package and run python callback_app_server.py. This program functions as a simple HTTP server. To run this program, you may need to install the dependencies for RSA.

• Ruby

  • Download URL: Click here.

  • To run the sample program, run the ruby server.rb command.

FAQ

Can I change the callback URL and use another server to receive callbacks and check whether the upload succeeds?

You cannot change the callback URL because the parameters are signed and verified by the OSS server, and tampered content cannot pass the verification.