TOS Java SDK 支持设置下载对象的限定条件。您可以在下载对象时，设置下载对象的限制条件（如对象 ETag 或对象修改时间），当对象信息满足设置的限定条件时服务端才会返回对象数据，否则会返回相应错误。本文介绍如何通过限定条件下载对象。
tos:GetObject 权限，具体操作，请参见权限配置指南。tos:GetObjectVersion 权限，具体操作，请参见权限配置指南。TOS 支持的限定条件如下。
参数 | 描述 |
|---|---|
If-Modified-Since | 如果指定的时间早于对象最后修改时间，则正常下载，否则返回 304 错误（Not modified） |
If-Unmodified-Since | 如果指定的时间等于或者晚于对象最后修改时间，则正常下载，否则返回 412 错误（Precondition failed） |
If-Match | 如果指定的 ETag 和待下载对象的 ETag 匹配，则正常下载，否则返回 412 错误（ Precondition failed） |
If-None-Match | 如果指定的 ETag 和待下载对象的 ETag 不匹配，则正常下载，否则返回 304 错误（Not modified） |
以下代码展示如何设置限定条件，满足条件时下载目标桶 bucket-example 中的 example_dir 目录下的 example_object.txt 文件到本地。
import com.volcengine.tos.TOSV2; import com.volcengine.tos.TOSV2ClientBuilder; import com.volcengine.tos.TosClientException; import com.volcengine.tos.TosServerException; import com.volcengine.tos.model.object.*; import java.io.File; import java.io.FileOutputStream; import java.io.IOException; import java.text.DateFormat; import java.text.ParseException; import java.text.SimpleDateFormat; import java.util.Date; import java.util.Map; public class GetObjectWithIfConditionExample { public static void main(String[] args) { String endpoint = "your endpoint"; String region = "your region"; String accessKey = System.getenv("TOS_ACCESS_KEY"); String secretKey = System.getenv("TOS_SECRET_KEY"); String bucketName = "bucket-example"; // 对象名 String objectKey = "example_dir/example_object.txt"; // 对象数据保存的本地文件路径，需保证不存在，否则会覆盖原有文件 String filePath = "example_dir/example_file.txt"; TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey); // 以下代码展示几种限定条件的使用方式，您可以选择其中一种，也可以选择多种进行组合。 ObjectMetaRequestOptions options = new ObjectMetaRequestOptions(); // 条件1：如果指定的时间早于对象最后修改时间，则将其下载到本地文件 try{ DateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"); Date date = dateFormat.parse("2022-09-13 14:36:01"); options.setIfModifiedSince(date); } catch (ParseException e) { System.out.println("date parse failed"); e.printStackTrace(); } // 条件2：如果指定的时间不早于对象最后修改时间，则将其下载到本地文件 try{ DateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"); Date date = dateFormat.parse("2222-12-31 14:36:01"); options.setIfUnmodifiedSince(date); } catch (ParseException e) { System.out.println("date parse failed"); e.printStackTrace(); } // 条件3：如果指定的 Etag 与对象的 Etag 匹配，则将其下载到本地文件 // 对象的 Etag 可以通过 headObject 接口获取 HeadObjectV2Input head = new HeadObjectV2Input().setBucket(bucketName).setKey(objectKey); HeadObjectV2Output headOutput = tos.headObject(head); String etag = headOutput.getEtag(); // 设置条件 options.setIfMatch(etag); // 条件4：如果指定的 Etag 与对象的 Etag 不匹配，则将其下载到本地文件 // 此处设置一个错误的 etag，与对象 Etag 不匹配，仅作为示例 String wrongEtag = "XXXYYYZZZ"; options.setIfNoneMatch(wrongEtag); GetObjectV2Input input = new GetObjectV2Input().setBucket(bucketName).setKey(objectKey).setOptions(options); File file = new File(filePath); if (file.getParentFile() != null && !file.getParentFile().exists()) { // 此处判断文件路径的父文件夹是否存在，不存在则创建父文件夹 // 如果父文件夹不存在且不创建，直接写入会报 FileNotFoundException file.getParentFile().mkdirs(); } try(FileOutputStream fos = new FileOutputStream(file); GetObjectV2Output output = tos.getObject(input)) { if (output.getContent() != null) { byte[] buffer = new byte[4096]; int length; while ((length = output.getContent().read(buffer)) != -1) { fos.write(buffer, 0, length); } } fos.flush(); System.out.println("getObject succeed."); System.out.println("object's etag is " + output.getEtag()); System.out.println("object's lastModified is " + output.getLastModified()); System.out.println("object's crc64 value is " + output.getHashCrc64ecma()); System.out.println("object's storageClass is " + output.getStorageClass()); System.out.println("object's cacheControl is " + output.getCacheControl()); System.out.println("object's contentDisposition is " + output.getContentDisposition()); System.out.println("object's contentEncoding is " + output.getContentEncoding()); System.out.println("object's contentLanguage is " + output.getContentLanguage()); System.out.println("object's contentType is " + output.getContentType()); if (output.getCustomMetadata() != null) { System.out.println("object has custom meta data."); for (Map.Entry<String, String> entry : output.getCustomMetadata().entrySet()) { System.out.println("custom meta key: " + entry.getKey() + ", value: " + entry.getValue()); } } } catch (IOException e) { System.out.println("write data to file failed"); e.printStackTrace(); } catch (TosClientException e) { // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送 System.out.println("getObject failed"); System.out.println("Message: " + e.getMessage()); if (e.getCause() != null) { e.getCause().printStackTrace(); } } catch (TosServerException e) { // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息 // 使用限定条件下载，如果服务端返回 304/412 状态码，SDK 将抛出 TosServerException，您需要自行处理。 System.out.println("getObject failed"); System.out.println("StatusCode: " + e.getStatusCode()); System.out.println("Code: " + e.getCode()); System.out.println("Message: " + e.getMessage()); System.out.println("RequestID: " + e.getRequestID()); } catch (Throwable t) { // 作为兜底捕获其他异常，一般不会执行到这里 System.out.println("getObject failed"); System.out.println("unexpected exception, message: " + t.getMessage()); } } }
关于下载对象的 API 文档，请参见 GetObject。