全部產品
Search

搜尋本產品

    Object Storage Service：標量檢索（Java SDK V1）

    文件中心

    Object Storage Service：標量檢索（Java SDK V1）

    更新時間：Nov 26, 2025

    標量檢索是OSS提供的基於Object中繼資料的索引功能，允許您自訂條件，從Bucket儲存的海量Object中快速尋找與指定的Object名稱、ETag、儲存類型、大小、最後修改時間等條件匹配的Object。

    注意事項

    • 僅Java SDK 3.16.0及以上版本支援使用標量索引功能。

    • 華東1（杭州）、華東2（上海）、華北1（青島）、華北2（北京）、華北3（張家口）、華南1（深圳）、華南3（廣州）、西南1（成都）、中國香港、新加坡、印尼（雅加達）、德國（法蘭克福）、美國（維吉尼亞）、美國（矽谷）、英國（倫敦）地區的Bucket支援使用標量檢索功能。更多資訊，請參見資料索引。

    • 本文以華東1（杭州）外網Endpoint為例。如果您希望通過與OSS同地區的其他阿里雲產品訪問OSS，請使用內網Endpoint。關於OSS支援的Region與Endpoint的對應關係，請參見地區和Endpoint。

    • 本文以從環境變數讀取存取憑證為例。如何配置訪問憑證，請參見Java配置訪問憑證。

    • 本文以OSS網域名稱建立OSSClient為例。如果您希望通過自訂網域名、STS等方式建立OSSClient，請參見常見情境配置樣本。

    • 阿里雲帳號預設擁有資料索引的相關許可權。如果您希望通過RAM使用者或者STS的方式執行資料索引相關操作，例如：

      • 開啟中繼資料管理功能，您必須擁有oss:OpenMetaQuery許可權。

      • 擷取中繼資料索引庫資訊，您必須擁有oss:GetMetaQueryStatus許可權。

      • 查詢滿足指定條件的Object，您必須擁有oss:DoMetaQuery許可權。

      • 關閉中繼資料管理功能，您必須擁有oss:CloseMetaQuery許可權。

    開啟標量檢索功能

    以下代碼用於為Bucket開啟標量檢索功能。開啟後，OSS會為Bucket建立中繼資料索引庫並為Bucket中的所有Object建立中繼資料索引。中繼資料索引庫建立完成後，OSS會繼續對Bucket中新增檔案進行准即時的增量追蹤掃描並為增量檔案建立中繼資料索引。

    import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.MetaQueryMode;

public class OpenMetaQuery {
    public static void main(String[] args) throws com.aliyuncs.exceptions.ClientException {
        // Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 填寫Bucket名稱，例如examplebucket。
        String bucketName = "examplebucket";
        // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為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 {
            // 開啟標量檢索功能。
            ossClient.openMetaQuery(bucketName);
        } catch (OSSException oe) {
            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("Error Message: " + ce.getMessage());
        } finally {
            // 關閉OSSClient。
            if(ossClient != null){
                ossClient.shutdown();
            }
        }
    }
}

    擷取中繼資料索引庫資訊

    以下擷取指定Bucket的中繼資料索引庫資訊。

    import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.GetMetaQueryStatusResult;

public class GetMetaQueryStatus {
    public static void main(String[] args) throws com.aliyuncs.exceptions.ClientException {
        // Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 填寫Bucket名稱，例如examplebucket。
        String bucketName = "examplebucket";
        // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為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 {
            // 擷取指定儲存空間（Bucket）的中繼資料索引庫資訊。
            GetMetaQueryStatusResult getResult = ossClient.getMetaQueryStatus(bucketName);
            // 擷取當前掃描類型。
            System.out.println(getResult.getPhase());
            // 擷取中繼資料索引庫的狀態。
            System.out.println(getResult.getState());
            // 擷取中繼資料索引庫的建立時間。
            System.out.println(getResult.getCreateTime());
            // 擷取中繼資料索引庫的更新時間。
            System.out.println(getResult.getUpdateTime());
        } catch (OSSException oe) {
            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("Error Message: " + ce.getMessage());
        } finally {
            // 關閉OSSClient。
            if(ossClient != null){
                ossClient.shutdown();
            }
        }
    }
}

    查詢滿足指定條件的Object

    以下代碼用於查詢滿足指定條件Object，並按照指定欄位和排序方式列出Object資訊。

    import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.*;
import java.util.ArrayList;
import java.util.List;

public class DoMetaQuery {
    public static void main(String[] args) throws Exception {
        // Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 填寫Bucket名稱，例如examplebucket。
        String bucketName = "examplebucket";
        // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為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 {
            // 查詢滿足指定條件的檔案（Object），並按照指定欄位和排序方式列舉檔案資訊。
            int maxResults = 20;
            // 指定查詢小於1048576位元組的檔案，且最多返回20個結果，返回結果按升序排列。
            String query = "{\"Field\": \"Size\",\"Value\": \"1048576\",\"Operation\": \"lt\"}";
            String sort = "Size";
            DoMetaQueryRequest doMetaQueryRequest = new DoMetaQueryRequest(bucketName, maxResults, query, sort);
            Aggregation aggregationRequest = new Aggregation();
            Aggregations aggregations = new Aggregations();
            List<Aggregation> aggregationList = new ArrayList<Aggregation>();
            // 指定彙總操作的欄位名稱。
            aggregationRequest.setField("Size");
            // 指定彙總操作的操作符，max表示最大值。
            aggregationRequest.setOperation("max");
            aggregationList.add(aggregationRequest);
            aggregations.setAggregation(aggregationList);

            // 設定彙總操作。
            doMetaQueryRequest.setAggregations(aggregations);
            doMetaQueryRequest.setOrder(SortOrder.ASC);
            DoMetaQueryResult doMetaQueryResult = ossClient.doMetaQuery(doMetaQueryRequest);
            if(doMetaQueryResult.getFiles() != null){
                for(ObjectFile file : doMetaQueryResult.getFiles().getFile()){
                    System.out.println("Filename: " + file.getFilename());
                    // 擷取標識Object的內容。
                    System.out.println("ETag: " + file.getETag());
                    // 擷取Object的存取權限
                    System.out.println("ObjectACL: " + file.getObjectACL());
                    // 擷取Object的類型。
                    System.out.println("OssObjectType: " + file.getOssObjectType());
                    // 擷取Object的儲存類型。
                    System.out.println("OssStorageClass: " + file.getOssStorageClass());
                    // 擷取Object的標籤個數。
                    System.out.println("TaggingCount: " + file.getOssTaggingCount());
                    if(file.getOssTagging() != null){
                        for(Tagging tag : file.getOssTagging().getTagging()){
                            System.out.println("Key: " + tag.getKey());
                            System.out.println("Value: " + tag.getValue());
                        }
                    }
                    if(file.getOssUserMeta() != null){
                        for(UserMeta meta : file.getOssUserMeta().getUserMeta()){
                            System.out.println("Key: " + meta.getKey());
                            System.out.println("Value: " + meta.getValue());
                        }
                    }
                }
            } else if(doMetaQueryResult.getAggregations() != null){
                for(Aggregation aggre : doMetaQueryResult.getAggregations().getAggregation()){
                    // 擷取彙總欄位名稱。
                    System.out.println("Field: " + aggre.getField());
                    // 擷取彙總欄位的操作符。
                    System.out.println("Operation: " + aggre.getOperation());
                    // 擷取彙總操作的結果值。
                    System.out.println("Value: " + aggre.getValue());
                    if(aggre.getGroups() != null && aggre.getGroups().getGroup().size() > 0){
                        // 擷取分組彙總的值。
                        System.out.println("Groups value: " + aggre.getGroups().getGroup().get(0).getValue());
                        // 擷取分組彙總的總個數。
                        System.out.println("Groups count: " + aggre.getGroups().getGroup().get(0).getCount());
                    }
                }
            } else {
                System.out.println("NextToken: " + doMetaQueryResult.getNextToken());
            }
        } catch (OSSException oe) {
            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("Error Message: " + ce.getMessage());
        } finally {
            // 關閉OSSClient。
            ossClient.shutdown();
        }
    }
}

    關閉標量檢索功能

    以下代碼用於關閉標量檢索功能。

    import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;

public class CloseMetaQuery {
    public static void main(String[] args) throws Exception {
        // Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 填寫Bucket名稱，例如examplebucket。
        String bucketName = "examplebucket";
        // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為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 {
            // 關閉儲存空間（Bucket）的標量檢索功能。
            ossClient.closeMetaQuery(bucketName);
        } catch (OSSException oe) {
            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("Error Message: " + ce.getMessage());
        } finally {
            // 關閉OSSClient。
            if(ossClient != null){
                ossClient.shutdown();
            }
        }
    }
}

    相關文檔

    • 關於開啟中繼資料管理功能的API介面說明，請參見OpenMetaQuery。

    • 關於擷取中繼資料索引庫資訊的API介面說明，請參見GetMetaQueryStatus。

    • 關於查詢滿足指定條件的Object，並按照指定欄位和排序方式列出Object資訊的API介面說明，請參見DoMetaQuery。

    • 關於關閉中繼資料管理功能的API介面說明，請參見CloseMetaQuery。