全部产品
Search

搜索本产品

    Object Storage Service：Scalar retrieval (Java SDK V1)

    文档中心

    Object Storage Service：Scalar retrieval (Java SDK V1)

    更新时间：Nov 27, 2025

    Scalar retrieval adalah fitur Object Storage Service (OSS) yang mengindeks metadata objek, memungkinkan Anda menentukan kondisi kustom untuk menemukan objek dalam bucket yang sesuai dengan kriteria tertentu, seperti nama objek, ETag, kelas penyimpanan, ukuran, dan waktu modifikasi terakhir.

    Catatan

    • Hanya Java SDK versi 3.16.0 dan yang lebih baru yang mendukung fitur scalar retrieval.

    • Bucket di wilayah China (Hangzhou), China (Shanghai), China (Qingdao), China (Beijing), China (Zhangjiakou), China (Shenzhen), China (Guangzhou), China (Chengdu), China (Hong Kong), Singapura, Indonesia (Jakarta), Jerman (Frankfurt), AS (Virginia), AS (Silicon Valley), dan Inggris (London) mendukung fitur scalar retrieval. Untuk informasi selengkapnya, lihat Pengindeksan data.

    • Pada topik ini, titik akhir publik wilayah China (Hangzhou) digunakan. Untuk mengakses OSS dari layanan Alibaba Cloud lainnya dalam wilayah yang sama, gunakan titik akhir internal. Untuk detail wilayah dan titik akhir yang didukung, lihat Wilayah dan titik akhir.

    • Pada topik ini, kredensial akses diperoleh dari variabel lingkungan. Untuk informasi selengkapnya tentang cara mengonfigurasi kredensial akses, lihat Konfigurasi kredensial akses.

    • Pada topik ini, instans OSSClient dibuat menggunakan titik akhir OSS. Jika Anda ingin membuat instans OSSClient menggunakan nama domain kustom atau Security Token Service (STS), lihat Contoh konfigurasi untuk skenario umum.

    • Secara default, akun Alibaba Cloud memiliki izin untuk melakukan operasi pengindeksan data. Jika Anda ingin menggunakan pengguna Resource Access Management (RAM) atau STS untuk melakukan operasi pengindeksan data, Anda harus memiliki izin yang diperlukan. Contohnya:

      • Untuk mengaktifkan fitur manajemen metadata, Anda harus memiliki izin oss:OpenMetaQuery.

      • Untuk mengambil informasi tentang pustaka indeks metadata, Anda harus memiliki izin oss:GetMetaQueryStatus.

      • Untuk mengkueri objek yang memenuhi kondisi tertentu, Anda harus memiliki izin oss:DoMetaQuery.

      • Untuk menonaktifkan fitur manajemen metadata, Anda harus memiliki izin oss:CloseMetaQuery.

    Aktifkan fitur scalar retrieval

    Kode berikut mengaktifkan fitur scalar retrieval untuk sebuah bucket. Setelah diaktifkan, OSS akan membuat pustaka indeks metadata untuk bucket tersebut dan membangun indeks metadata untuk semua objek di dalamnya. Setelah pustaka indeks metadata dibuat, OSS akan terus melakukan pemindaian inkremental hampir real-time terhadap file baru di bucket dan membangun indeks metadata untuk file tersebut.

    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 {
        // Titik akhir China (Hangzhou) digunakan sebagai contoh. Tentukan titik akhir aktual untuk wilayah Anda.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Tentukan nama bucket. Contoh: examplebucket.
        String bucketName = "examplebucket";
        // Peroleh kredensial akses dari variabel lingkungan. Sebelum menjalankan kode ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), setel Region ke cn-hangzhou.
        String region = "cn-hangzhou";

        // Buat instans OSSClient.
        // Saat instans OSSClient tidak lagi diperlukan, panggil metode shutdown untuk melepas sumber daya.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // Aktifkan fitur scalar retrieval.
            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 {
            // Matikan instans OSSClient.
            if(ossClient != null){
                ossClient.shutdown();
            }
        }
    }
}

    Dapatkan informasi tentang pustaka indeks metadata

    Kode berikut mengambil informasi tentang pustaka indeks metadata dari bucket tertentu.

    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 {
        // Titik akhir China (Hangzhou) digunakan sebagai contoh. Tentukan titik akhir aktual untuk wilayah Anda.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Tentukan nama bucket. Contoh: examplebucket.
        String bucketName = "examplebucket";
        // Peroleh kredensial akses dari variabel lingkungan. Sebelum menjalankan kode ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), setel Region ke cn-hangzhou.
        String region = "cn-hangzhou";

        // Buat instans OSSClient.
        // Saat instans OSSClient tidak lagi diperlukan, panggil metode shutdown untuk melepas sumber daya.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // Dapatkan informasi tentang pustaka indeks metadata dari bucket yang ditentukan.
            GetMetaQueryStatusResult getResult = ossClient.getMetaQueryStatus(bucketName);
            // Dapatkan jenis pemindaian saat ini.
            System.out.println(getResult.getPhase());
            // Dapatkan status pustaka indeks metadata.
            System.out.println(getResult.getState());
            // Dapatkan waktu pembuatan pustaka indeks metadata.
            System.out.println(getResult.getCreateTime());
            // Dapatkan waktu pembaruan pustaka indeks metadata.
            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 {
            // Matikan instans OSSClient.
            if(ossClient != null){
                ossClient.shutdown();
            }
        }
    }
}

    Kueri objek yang memenuhi kondisi tertentu

    Kode berikut mengkueri objek yang memenuhi kondisi tertentu dan mencantumkan informasi objek berdasarkan bidang dan urutan pengurutan yang ditentukan.

    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 {
        // Titik akhir China (Hangzhou) digunakan sebagai contoh. Tentukan titik akhir aktual untuk wilayah Anda.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Tentukan nama bucket. Contoh: examplebucket.
        String bucketName = "examplebucket";
        // Peroleh kredensial akses dari variabel lingkungan. Sebelum menjalankan kode ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), setel Region ke cn-hangzhou.
        String region = "cn-hangzhou";

        // Buat instans OSSClient.
        // Saat instans OSSClient tidak lagi diperlukan, panggil metode shutdown untuk melepas sumber daya.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // Kueri file (objek) yang memenuhi kondisi tertentu, dan cantumkan informasi file berdasarkan bidang dan urutan pengurutan yang ditentukan.
            int maxResults = 20;
            // Kueri file yang ukurannya kurang dari 1.048.576 byte, kembalikan maksimal 20 hasil, dan urutkan hasil secara ascending.
            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>();
            // Tentukan nama bidang untuk operasi agregasi.
            aggregationRequest.setField("Size");
            // Tentukan operator untuk operasi agregasi. Misalnya, max menunjukkan nilai maksimum.
            aggregationRequest.setOperation("max");
            aggregationList.add(aggregationRequest);
            aggregations.setAggregation(aggregationList);

            // Tetapkan operasi agregasi.
            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());
                    // Dapatkan ETag yang mengidentifikasi konten objek.
                    System.out.println("ETag: " + file.getETag());
                    // Dapatkan izin akses objek.
                    System.out.println("ObjectACL: " + file.getObjectACL());
                    // Dapatkan tipe objek.
                    System.out.println("OssObjectType: " + file.getOssObjectType());
                    // Dapatkan kelas penyimpanan objek.
                    System.out.println("OssStorageClass: " + file.getOssStorageClass());
                    // Dapatkan jumlah tag untuk objek.
                    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()){
                    // Dapatkan nama bidang agregasi.
                    System.out.println("Field: " + aggre.getField());
                    // Dapatkan operator bidang agregasi.
                    System.out.println("Operation: " + aggre.getOperation());
                    // Dapatkan nilai hasil operasi agregasi.
                    System.out.println("Value: " + aggre.getValue());
                    if(aggre.getGroups() != null && aggre.getGroups().getGroup().size() > 0){
                        // Dapatkan nilai pengelompokan dan agregasi.
                        System.out.println("Groups value: " + aggre.getGroups().getGroup().get(0).getValue());
                        // Dapatkan jumlah total pengelompokan dan agregasi.
                        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 {
            // Matikan instans OSSClient.
            ossClient.shutdown();
        }
    }
}

    Nonaktifkan fitur scalar retrieval

    Kode berikut menonaktifkan fitur scalar retrieval.

    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 {
        // Titik akhir China (Hangzhou) digunakan sebagai contoh. Tentukan titik akhir aktual untuk wilayah Anda.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Tentukan nama bucket. Contoh: examplebucket.
        String bucketName = "examplebucket";
        // Peroleh kredensial akses dari variabel lingkungan. Sebelum menjalankan kode ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), setel Region ke cn-hangzhou.
        String region = "cn-hangzhou";

        // Buat instans OSSClient.
        // Saat instans OSSClient tidak lagi diperlukan, panggil metode shutdown untuk melepas sumber daya.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // Nonaktifkan fitur scalar retrieval untuk 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 {
            // Matikan instans OSSClient.
            if(ossClient != null){
                ossClient.shutdown();
            }
        }
    }
}

    Referensi

    • Untuk informasi selengkapnya tentang operasi API untuk mengaktifkan fitur manajemen metadata, lihat OpenMetaQuery.

    • Untuk informasi selengkapnya tentang operasi API untuk mengambil informasi tentang pustaka indeks metadata, lihat GetMetaQueryStatus.

    • Untuk informasi selengkapnya tentang operasi API untuk mengkueri objek yang memenuhi kondisi tertentu dan mencantumkan informasi objek berdasarkan bidang dan urutan pengurutan yang ditentukan, lihat DoMetaQuery.

    • Untuk informasi selengkapnya tentang operasi API untuk menonaktifkan fitur manajemen metadata, lihat CloseMetaQuery.