バケットからオブジェクトをダウンロードする際に、オブジェクトの最終更新日時または ETag に基づいて条件を指定できます。ETag はオブジェクトのコンテンツの識別子です。指定された条件が満たされた場合にのみ、オブジェクトはダウンロードされます。条件が満たされない場合は、エラーが返され、ダウンロードはトリガーされません。条件付きダウンロードにより、ネットワークトラフィックとリソース消費が削減され、ダウンロード効率が向上します。
条件
OSS は、次の条件をサポートしています。
`If-Modified-Since` と `If-Unmodified-Since` は併用できます。`If-Match` と `If-None-Match` も併用できます。
ETag を取得するには、`ossClient.getObjectMeta` メソッドを使用します。
パラメーター | 説明 |
If-Modified-Since | 指定した時刻が実際の変更時刻より前の場合、ファイルは転送されます。それ以外の場合は、`304 Not Modified` エラーが返されます。 |
If-Unmodified-Since | 指定した時刻が実際の変更時刻と同じか、それより後の場合、ファイルは転送されます。それ以外の場合は、`412 Precondition Failed` エラーが返されます。 |
If-Match | 指定した ETag が OSS オブジェクトの ETag と一致する場合、ファイルは転送されます。それ以外の場合は、`412 Precondition Failed` エラーが返されます。 |
If-None-Match | 指定した ETag が OSS オブジェクトの ETag と一致しない場合、ファイルは転送されます。それ以外の場合は、`304 Not Modified` エラーが返されます。 |
注意事項
このトピックでは、中国 (杭州) リージョンのパブリックエンドポイントを使用します。同じリージョン内の他の Alibaba Cloud サービスから OSS にアクセスするには、内部エンドポイントを使用します。サポートされているリージョンとエンドポイントの詳細については、「リージョンとエンドポイント」をご参照ください。
このトピックでは、アクセス認証情報は環境変数から取得されます。アクセス認証情報の設定方法の詳細については、「アクセス認証情報の設定」をご参照ください。
このトピックでは、OSS エンドポイントを使用して OSSClient インスタンスを作成します。カスタムドメイン名または Security Token Service (STS) を使用して OSSClient インスタンスを作成する場合は、「一般的なシナリオの設定例」をご参照ください。
条件付きダウンロードを実行するには、
oss:GetObject権限が必要です。詳細については、「RAM ユーザーへのカスタム権限の付与」をご参照ください。
サンプルコード
次のサンプルコードは、`ossClient.getObject` メソッドを使用して条件付きダウンロードを実行する方法を示しています。`ossClient.downloadFile` メソッドも条件付きダウンロードをサポートしており、同様の方法で使用されます。
import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.GetObjectRequest;
import java.io.File;
import java.util.Date;
public class Demo {
public static void main(String[] args) throws Exception {
// 中国 (杭州) リージョンのエンドポイントを例として使用します。実際のエンドポイントを指定してください。
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// アクセス認証情報を環境変数から取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// バケット名を指定します。例: examplebucket
String bucketName = "examplebucket";
// オブジェクトの完全なパスを指定します。バケット名は含めないでください。例: testfolder/exampleobject.txt
String objectName = "testfolder/exampleobject.txt";
String pathName = "D:\\localpath\\examplefile.txt";
// バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを cn-hangzhou に設定します。
String region = "cn-hangzhou";
// OSSClient インスタンスを作成します。
// OSSClient インスタンスが不要になったら、shutdown メソッドを呼び出してリソースを解放します。
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
try {
GetObjectRequest request = new GetObjectRequest(bucketName, objectName);
// オブジェクトが 2023 年 9 月 26 日 13:27:04 に最終更新されたと仮定します。Tue Sep 25 13:27:04 CST 2023 のように、それより前の時刻を指定すると、If-Modified-Since 条件が満たされ、ダウンロードがトリガーされます。
request.setModifiedSinceConstraint(new Date("Tue Sep 25 13:27:04 CST 2023"));
// OSS オブジェクトをローカルファイルにダウンロードします。
ossClient.getObject(request, new File(pathName));
} catch (OSSException oe) {
System.out.println("Caught an OSSException, which means your request made it to OSS, "
+ "but was rejected with an error response for some reason.");
System.out.println("Error Message:" + oe.getErrorMessage());
System.out.println("Error Code:" + oe.getErrorCode());
System.out.println("Request ID:" + oe.getRequestId());
System.out.println("Host ID:" + oe.getHostId());
} catch (ClientException ce) {
System.out.println("Caught an ClientException, which means the client encountered "
+ "a serious internal problem while trying to communicate with OSS, "
+ "such as not being able to access the network.");
System.out.println("Error Message:" + ce.getMessage());
} finally {
if (ossClient != null) {
ossClient.shutdown();
}
}
}
}
関連ドキュメント
条件付きダウンロードの API 操作の詳細については、「GetObject」をご参照ください。