全部產品
Search

搜尋本產品

    Object Storage Service：Java管理檔案中繼資料

    文件中心

    Object Storage Service：Java管理檔案中繼資料

    更新時間：Oct 25, 2024

    Object Storage Service儲存的檔案（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。