Conditional downloads let you attach conditions to a download request so that OSS transfers the object only when the conditions are met—reducing unnecessary network traffic and speeding up your app's cache-validation logic. If the conditions are not met, OSS skips the transfer and returns an error instead.
Prerequisites
Before you begin, ensure that you have:
An
OSSClientinstance initialized using a custom domain name or Security Token Service (STS). For details, see Initialization.The
ossGetObjectpermission. For details, see Grant custom access policies to a RAM user.
The bucket region is determined by the endpoint you specify during initialization.
Conditions
OSS supports four conditional request headers. Set one or more headers on OSSGetObjectRequest to control when the object is transferred:
If-Modified-Since: The object is downloaded only when its last modified time is after the specified time.If-Unmodified-Since: The object is downloaded only when its last modified time is at or before the specified time.If-None-Match: The object is downloaded only if its ETag does not match the specified ETag.If-Match: The object is downloaded only if its ETag matches the specified ETag.
Download an object with conditions
The following example downloads exampledir/exampleobject.txt from examplebucket using all four conditional headers.
OSSGetObjectRequest *get = [OSSGetObjectRequest new];
// Bucket name
get.bucketName = @"examplebucket";
// Full path of the object. Do not include the bucket name.
get.objectKey = @"exampledir/exampleobject.txt";
NSMutableDictionary *headerFields = [NSMutableDictionary dictionary];
// Download only if the object was modified after this time.
[headerFields setValue:@"Fri, 13 Oct 2021 14:47:53 GMT" forKey:@"If-Modified-Since"];
// Download only if the object was not modified after the current time.
[headerFields setValue:[[NSDate new] oss_asStringValue] forKey:@"If-Unmodified-Since"];
// Download only if the object's ETag does not match this value.
[headerFields setValue:@"5B3C1A2E0563E1B002CC607C****" forKey:@"If-None-Match"];
// Download only if the object's ETag matches this value.
[headerFields setValue:@"fba9dede5f27731c9771645a3986****" forKey:@"If-Match"];
get.headerFields = headerFields;
[[[client getObject:get] continueWithBlock:^id _Nullable(OSSTask * _Nonnull task) {
if (!task.error) {
NSLog(@"get object success!");
} else {
NSLog(@"get object error: %@", task.error);
}
return nil;
}] waitUntilFinished];What's next
For the underlying API operation, see GetObject.
For
OSSClientinitialization options, see Initialization.