對象存儲OSS存儲的文件(Object)信息包含Key、Data和Object Meta。Object Meta是對文件的屬性描述,包括HTTP標準屬性(HTTP Header)和用戶自定義元數據(User Meta)兩種。您可以通過設置HTTP標準屬性來自定義HTTP請求的策略,例如文件(Object)緩存策略、強制下載策略等。您還可以通過設置用戶自定義元數據來標識Object的用途或屬性等。
注意事項
本文以華東1(杭州)外網Endpoint為例。如果您希望通過與OSS同地域的其他阿里云產品訪問OSS,請使用內網Endpoint。關于OSS支持的Region與Endpoint的對應關系,請參見OSS訪問域名、數據中心、開放端口。
本文以從環境變量讀取訪問憑證為例。如何配置訪問憑證,請參見Java配置訪問憑證。
本文以OSS域名新建OSSClient為例。如果您希望通過自定義域名、STS等方式新建OSSClient,請參見新建OSSClient。
要設置文件元數據,您必須具有
oss:PutObject
權限;要獲取文件元數據,您必須具有oss:GetObject
權限。具體操作,請參見為RAM用戶授權自定義的權限策略。
設置文件元數據
以下為設置HTTP標準屬性和自定義元數據的詳細示例。
設置HTTP標準屬性
以下代碼用于設置HTTP標準屬性。
import com.aliyun.oss.ClientException; import com.aliyun.oss.OSS; import com.aliyun.oss.common.auth.*; import com.aliyun.oss.OSSClientBuilder; import com.aliyun.oss.OSSException; import com.aliyun.oss.common.utils.BinaryUtil; import com.aliyun.oss.common.utils.DateUtil; import com.aliyun.oss.model.ObjectMetadata; import java.io.ByteArrayInputStream; public class Demo { public static void main(String[] args) throws Exception { // Endpoint以華東1(杭州)為例,其它Region請按實際情況填寫。 String endpoint = "https://oss-cn-hangzhou.aliyuncs.com"; // 從環境變量中獲取訪問憑證。運行本代碼示例之前,請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider(); // 填寫Bucket名稱,例如examplebucket。 String bucketName = "examplebucket"; // 填寫不包含Bucket名稱在內的Object完整路徑,例如testfolder/exampleobject.txt。 String objectName = "testfolder/exampleobject.txt"; String content = "Hello OSS"; // 填寫Bucket所在地域。以華東1(杭州)為例,Region填寫為cn-hangzhou。 String region = "cn-hangzhou"; // 創建OSSClient實例。 ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration(); clientBuilderConfiguration.setSignatureVersion(SignVersion.V4); OSS ossClient = OSSClientBuilder.create() .endpoint(endpoint) .credentialsProvider(credentialsProvider) .clientConfiguration(clientBuilderConfiguration) .region(region) .build(); try { // 創建上傳文件的元數據。 ObjectMetadata meta = new ObjectMetadata(); String md5 = BinaryUtil.toBase64String(BinaryUtil.calculateMd5(content.getBytes())); // 開啟文件內容MD5校驗。開啟后OSS會把您提供的MD5與文件的MD5比較,不一致則拋出異常。 meta.setContentMD5(md5); // 指定上傳的內容類型。內容類型決定瀏覽器將以什么形式、什么編碼讀取文件。如果沒有指定則根據文件的擴展名生成,如果沒有擴展名則為默認值application/octet-stream。 meta.setContentType("text/plain"); // 設置內容被下載時的名稱。 meta.setContentDisposition("attachment; filename=\"DownloadFilename\""); // 設置上傳文件的長度。如超過此長度,則上傳文件會被截斷,上傳的文件長度為設置的長度。如小于此長度,則為上傳文件的實際長度。 meta.setContentLength(content.length()); // 設置內容被下載時網頁的緩存行為。 meta.setCacheControl("Download Action"); // 設置緩存過期時間,格式是格林威治時間(GMT)。 meta.setExpirationTime(DateUtil.parseIso8601Date("2022-10-12T00:00:00.000Z")); // 設置內容被下載時的編碼格式。 meta.setContentEncoding("gzip"); // 設置Header。 meta.setHeader("yourHeader", "yourHeaderValue"); // 上傳文件。 ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(content.getBytes()), meta); } 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(); } } } }
關于HTTP Header的更多信息,請參見RFC2616。
設置自定義元數據
您可以自定義文件的元數據來對文件進行描述。
以下代碼用于設置文件的自定義元數據。
package com.aliyun.oss.demo; import com.aliyun.oss.ClientException; import com.aliyun.oss.OSS; import com.aliyun.oss.common.auth.*; import com.aliyun.oss.OSSClientBuilder; import com.aliyun.oss.OSSException; import com.aliyun.oss.model.ObjectMetadata; import java.io.ByteArrayInputStream; public class Demo { public static void main(String[] args) throws Exception { // Endpoint以華東1(杭州)為例,其它Region請按實際情況填寫。 String endpoint = "https://oss-cn-hangzhou.aliyuncs.com"; // 從環境變量中獲取訪問憑證。運行本代碼示例之前,請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider(); // 填寫Bucket名稱,例如examplebucket。 String bucketName = "examplebucket"; // 填寫不包含Bucket名稱在內的Object完整路徑,例如testfolder/exampleobject.txt。 String objectName = "testfolder/exampleobject.txt"; String content = "Hello OSS"; // 填寫Bucket所在地域。以華東1(杭州)為例,Region填寫為cn-hangzhou。 String region = "cn-hangzhou"; // 創建OSSClient實例。 ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration(); clientBuilderConfiguration.setSignatureVersion(SignVersion.V4); OSS ossClient = OSSClientBuilder.create() .endpoint(endpoint) .credentialsProvider(credentialsProvider) .clientConfiguration(clientBuilderConfiguration) .region(region) .build(); try { // 創建文件元數據。 ObjectMetadata meta = new ObjectMetadata(); // 設置自定義元數據property值為property-value。建議使用Base64編碼。 meta.addUserMetadata("property", "property-value"); // 上傳文件。 ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(content.getBytes()), meta); } 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(); } } } }
下載文件時,文件元數據也會同時下載。 一個文件可以有多個元數據,總大小不能超過8 KB。
修改文件元數據
以下代碼用于修改文件的元數據。
import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.common.utils.DateUtil;
import com.aliyun.oss.model.CopyObjectRequest;
import com.aliyun.oss.model.ObjectMetadata;
public class Demo {
public static void main(String[] args) throws Exception {
// Endpoint以華東1(杭州)為例,其它Region請按實際情況填寫。
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 從環境變量中獲取訪問憑證。運行本代碼示例之前,請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 填寫源Bucket名稱。
String sourceBucketName = "yourSourceBucketName";
// 填寫源Object的完整路徑。
String sourceObjectName = "yourSourceObjectName";
// 填寫與源Bucket處于同一地域的目標Bucket名稱。
String destinationBucketName = "yourDestinationBucketName";
// 填寫目標Object的完整路徑。
String destinationObjectName = "yourDestinationObjectName";
// 填寫Bucket所在地域。以華東1(杭州)為例,Region填寫為cn-hangzhou。
String region = "cn-hangzhou";
// 創建OSSClient實例。
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
try {
// 設置源文件與目標文件相同,調用ossClient.copyObject方法修改文件元數據。
CopyObjectRequest request = new CopyObjectRequest(sourceBucketName, sourceObjectName, destinationBucketName, destinationObjectName);
ObjectMetadata meta = new ObjectMetadata();
// 指定上傳的內容類型。內容類型決定瀏覽器將以什么形式、什么編碼讀取文件。如果沒有指定則根據文件的擴展名生成,如果沒有擴展名則為默認值application/octet-stream。
meta.setContentType("text/plain");
// 設置內容被下載時的名稱。
meta.setContentDisposition("Download File Name");
// 設置內容被下載時網頁的緩存行為。
meta.setCacheControl("Download Action");
// 設置緩存過期時間,格式是格林威治時間(GMT)。
meta.setExpirationTime(DateUtil.parseIso8601Date("2022-10-12T00:00:00.000Z"));
// 設置內容被下載時的編碼格式。
meta.setContentEncoding("gzip");
// 設置header。
meta.setHeader("<yourHeader>", "<yourHeaderValue>");
// 設置自定義元數據property值為property-value。
meta.addUserMetadata("property", "property-value");
request.setNewObjectMetadata(meta);
// 修改元數據。
ossClient.copyObject(request);
} 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();
}
}
}
}
獲取文件元數據
您可以通過以下兩種方法獲取文件元數據。
方法 | 描述 |
ossClient.getSimplifiedObjectMeta | 獲取文件的ETag、Size(文件大小)、 LastModified(最后修改時間)。該方法對應的接口為GetObjectMeta。 |
ossClient.getObjectMetadata | 獲取文件的全部元數據。該方法對應的接口為HeadObject。 |
以下代碼用于獲取文件元數據。
import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.ObjectMetadata;
import com.aliyun.oss.model.SimplifiedObjectMeta;
public class Demo {
public static void main(String[] args) throws Exception {
// Endpoint以華東1(杭州)為例,其它Region請按實際情況填寫。
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 從環境變量中獲取訪問憑證。運行本代碼示例之前,請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 填寫Bucket名稱,例如examplebucket。
String bucketName = "examplebucket";
// 填寫不包含Bucket名稱在內的Object完整路徑,例如testfolder/exampleobject.txt。
String objectName = "testfolder/exampleobject.txt";
// 填寫Bucket所在地域。以華東1(杭州)為例,Region填寫為cn-hangzhou。
String region = "cn-hangzhou";
// 創建OSSClient實例。
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
try {
// 依次填寫Bucket名稱以及Object的完整路徑。
// 獲取文件的部分元數據。
SimplifiedObjectMeta objectMeta = ossClient.getSimplifiedObjectMeta(bucketName, objectName);
System.out.println(objectMeta.getSize());
System.out.println(objectMeta.getETag());
System.out.println(objectMeta.getLastModified());
// 開啟訪問跟蹤功能后,用于獲取包含最后一次訪問時間(X-Oss-Last-Access-Time)在內的文件元數據。僅Java SDK 3.16.0及以上版本支持獲取X-Oss-Last-Access-Time。
System.out.println(objectMeta.getHeaders().get("x-oss-last-access-time"));
// 獲取文件的全部元數據。
ObjectMetadata metadata = ossClient.getObjectMetadata(bucketName, objectName);
System.out.println(metadata.getContentType());
System.out.println(metadata.getLastModified());
System.out.println(metadata.getExpirationTime());
} 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();
}
}
}
}
相關文檔
關于文件元數據的更多內容,請參見管理文件元數據。
關于設置和獲取文件元數據的完整示例代碼,請參見GitHub示例。
關于在簡單上傳過程中設置文件元數據的API接口說明,請參見PutObject。
關于獲取文件元數據的API接口說明,請參見GetObjectMeta和HeadObject。