All Products
Search
Document Center

Object Storage Service:Conditional download

Last Updated:Mar 04, 2024

You can specify one or more conditions when you download an object. If the specified conditions are met, the object is downloaded. Otherwise, the object is not downloaded and an error is returned.

Usage notes

  • Before you run the sample code in this topic, you must create an OSSClient instance by using methods such as using a custom domain name or Security Token Service (STS). For more information, see Initialization.

Download conditions

The following table describes the available object download conditions.

Note
  • Both If-Modified-Since and If-Unmodified-Since can exist at the same time as object download conditions. Both If-Match and If-None-Match can exist at the same time as object download conditions.

  • You can obtain the ETag by using ossClient.getObjectMeta.

Parameter

Description

If-Modified-Since

If the specified time is earlier than the time when an object is modified, the object can be downloaded. Otherwise, 304 Not Modified is returned.

If-Unmodified-Since

If the specified time is later than or equal to the time when an object is modified, the object can be downloaded. Otherwise, 412 Precondition Failed is returned.

If-Match

If the specified ETag matches that of an object, the object can be downloaded. Otherwise, 412 Precondition Failed is returned.

If-None-Match

If the specified ETag does not match that of an object, the object can be downloaded. Otherwise, 304 Not Modified is returned.

Examples

The following sample code provides an example on how to perform conditional download:

// Specify the name of the bucket and the full path of the object. In this example, the name of the bucket is examplebucket and the full path of the object is exampledir/exampleobject.txt. 
// Do not include the bucket name in the full path of the object. 
String bucketName = "examplebucket";
String objectKey = "exampledir/exampleobject.txt";
// Construct a request to download the object. 
Map<String, String> headers = new HashMap<>();
// If the specified time is earlier than the time when the object was last modified, the object can be downloaded. Otherwise, 304 Not modified is returned. 
headers.put(OSSHeaders.GET_OBJECT_IF_MODIFIED_SINCE, "Fri, 13 Nov 2015 14:47:53 GMT");
// If the specified time is later than or equal to the time when the object was last modified, the object can be downloaded. Otherwise, 412 Precondition failed is returned.
// headers.put(OSSHeaders.GET_OBJECT_IF_UNMODIFIED_SINCE, "Fri, 13 Nov 2015 14:47:53 GMT");
// If the specified ETag matches that of the object, the object can be downloaded. Otherwise, 412 Precondition failed is returned.
// headers.put(OSSHeaders.GET_OBJECT_IF_MATCH, "5B3C1A2E0563E1B002CC607C*****");
// If the specified ETag does not match that of the object, the object can be downloaded. Otherwise, 304 Not modified is returned.
// headers.put(OSSHeaders.GET_OBJECT_IF_NONE_MATCH, "5B3C1A2E0563E1B002CC607C*****");
GetObjectRequest get = new GetObjectRequest(bucketName, objectKey);
get.setRequestHeaders(headers);

OSSAsyncTask task = oss.asyncGetObject(get, new OSSCompletedCallback<GetObjectRequest, GetObjectResult>() {
    @Override
    public void onSuccess(GetObjectRequest request, GetObjectResult result) {
        // The request is successful. 
        InputStream inputStream = result.getObjectContent();
        byte[] buffer = new byte[2048];
        int len;
        try {
            while ((len = inputStream.read(buffer)) != -1) {
                // Process the downloaded data. 
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    @Override
    public void onFailure(GetObjectRequest request, ClientException clientExcepion, ServiceException serviceException) {
        // Handle request exceptions. 
        if (clientExcepion != null) {
            // Handle client exceptions, such as network exceptions. 
            clientExcepion.printStackTrace();
        }
        if (serviceException != null) {
            // Handle service exceptions. 
            Log.e("ErrorCode", serviceException.getErrorCode());
            Log.e("RequestId", serviceException.getRequestId());
            Log.e("HostId", serviceException.getHostId());
            Log.e("RawMessage", serviceException.getRawMessage());
        }
    }
});

References

  • For the complete sample code that is used to perform conditional download, visit GitHub.

  • For more information about the API operation that you can call to perform conditional download, see GetObject.

  • For more information about how to initialize an OSSClient instance, see Initialization.