全部产品
Search

搜索本产品

    Object Storage Service：Kelola metadata objek (Java SDK V1)

    文档中心

    Object Storage Service：Kelola metadata objek (Java SDK V1)

    更新时间：Nov 27, 2025

    Objek yang disimpan di Object Storage Service (OSS) terdiri dari kunci, data, dan metadata objek. Metadata objek menggambarkan atribut suatu objek dan mencakup header HTTP standar serta metadata pengguna. Anda dapat mengatur header HTTP standar untuk membuat kebijakan permintaan HTTP kustom, seperti kebijakan cache objek dan unduhan paksa. Selain itu, Anda juga dapat menetapkan metadata pengguna pada suatu objek untuk mengidentifikasi tujuan atau atributnya.

    Catatan penggunaan

    • Topik ini menggunakan titik akhir publik wilayah China (Hangzhou). 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 lebih lanjut 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.

    • Untuk mengatur metadata objek, Anda harus memiliki izin oss:PutObject. Untuk mengambil metadata objek, Anda harus memiliki izin oss:GetObject. Untuk informasi lebih lanjut, lihat Menyambungkan kebijakan kustom ke RAM user.

    Atur metadata objek

    Contoh berikut menunjukkan cara mengatur header HTTP standar dan metadata kustom.

    • Atur header HTTP standar

      Kode berikut menunjukkan cara mengatur header HTTP standar.

      import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
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 {
        // Titik akhir wilayah China (Hangzhou) digunakan sebagai contoh. Tentukan titik akhir aktual Anda.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Tentukan nama bucket. Misalnya, examplebucket.
        String bucketName = "examplebucket";
        // Tentukan path lengkap objek. Jangan sertakan nama bucket dalam path lengkap. Misalnya, testfolder/exampleobject.txt.
        String objectName = "testfolder/exampleobject.txt";
        String content = "Hello OSS";
        // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur wilayah menjadi cn-hangzhou.
        String region = "cn-hangzhou";

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

        try {
            // Buat metadata untuk objek yang akan diunggah.
            ObjectMetadata meta = new ObjectMetadata();

            String md5 = BinaryUtil.toBase64String(BinaryUtil.calculateMd5(content.getBytes()));
            // Aktifkan validasi MD5 untuk konten objek. Setelah fitur ini diaktifkan, OSS membandingkan hash MD5 objek yang diunggah dengan hash MD5 yang Anda berikan. Jika kedua nilai hash berbeda, pengecualian akan dilemparkan.
            meta.setContentMD5(md5);
            // Tentukan tipe konten objek yang akan diunggah. Tipe konten menentukan cara browser membaca objek. Jika parameter ini tidak ditentukan, tipe konten akan dihasilkan berdasarkan ekstensi file objek. Jika objek tidak memiliki ekstensi file, nilai default application/octet-stream digunakan.
            meta.setContentType("text/plain; charset=utf-8");
            // Atur header. Misalnya, atur kelas penyimpanan untuk objek yang diunggah.
            meta.setHeader("x-oss-storage-class", StorageClass.Standard);
            
            // Hapus komentar pada baris berikut sesuai kebutuhan.
            
            // Atur nama objek saat diunduh.
            // meta.setContentDisposition("attachment; filename=\"DownloadFilename\"");
            // Atur panjang objek yang akan diunggah. Jika objek lebih panjang dari nilai ini, maka akan dipotong. Jika objek lebih pendek, panjang aktualnya yang digunakan.
            // meta.setContentLength(content.length());
            // Atur perilaku caching halaman web saat objek diunduh.
            // meta.setCacheControl("Download Action");
            // Atur waktu kedaluwarsa cache. Waktu harus dalam format GMT.
            // meta.setExpirationTime(DateUtil.parseIso8601Date("2022-10-12T00:00:00.000Z"));
            // Atur format encoding objek saat diunduh.
            // meta.setContentEncoding("gzip");

            // Unggah objek.
            ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(content.getBytes()), meta);
        } catch (OSSException oe) {
            System.out.println("Terjadi OSSException, yang berarti permintaan Anda berhasil mencapai OSS, "
                    + "tetapi ditolak dengan tanggapan error karena suatu alasan.");
            System.out.println("Pesan Error:" + oe.getErrorMessage());
            System.out.println("Kode Error:" + oe.getErrorCode());
            System.out.println("ID Permintaan:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Terjadi ClientException, yang berarti klien mengalami "
                    + "masalah internal serius saat mencoba berkomunikasi dengan OSS, "
                    + "seperti tidak dapat mengakses jaringan.");
            System.out.println("Pesan Error:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

      Untuk informasi lebih lanjut tentang header HTTP, lihat RFC 2616.

    • Atur metadata kustom

      Anda dapat mengatur metadata kustom untuk mendeskripsikan suatu objek.

      Kode berikut menunjukkan cara mengatur metadata kustom untuk suatu objek.

      import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.ObjectMetadata;
import java.io.ByteArrayInputStream;

public class Demo {
    public static void main(String[] args) throws Exception {
        // Titik akhir wilayah China (Hangzhou) digunakan sebagai contoh. Tentukan titik akhir aktual Anda.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Tentukan nama bucket. Misalnya, examplebucket.
        String bucketName = "examplebucket";
        // Tentukan path lengkap objek. Jangan sertakan nama bucket dalam path lengkap. Misalnya, testfolder/exampleobject.txt.
        String objectName = "testfolder/exampleobject.txt";
        String content = "Hello OSS";
        // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur wilayah menjadi cn-hangzhou.
        String region = "cn-hangzhou";

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

        try {
            // Buat metadata objek.
            ObjectMetadata meta = new ObjectMetadata();
            // Atur metadata kustom. Kami merekomendasikan agar Anda menggunakan encoding Base64.
            meta.addUserMetadata("key1", "value1");
            meta.addUserMetadata("key2", "value2");

            // Unggah objek.
            ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(content.getBytes()), meta);            
        } catch (OSSException oe) {
            System.out.println("Terjadi OSSException, yang berarti permintaan Anda berhasil mencapai OSS, "
                    + "tetapi ditolak dengan tanggapan error karena suatu alasan.");
            System.out.println("Pesan Error:" + oe.getErrorMessage());
            System.out.println("Kode Error:" + oe.getErrorCode());
            System.out.println("ID Permintaan:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Terjadi ClientException, yang berarti klien mengalami "
                    + "masalah internal serius saat mencoba berkomunikasi dengan OSS, "
                    + "seperti tidak dapat mengakses jaringan.");
            System.out.println("Pesan Error:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

      Metadata suatu objek diunduh bersama objek tersebut. Suatu objek dapat memiliki beberapa entri metadata, dengan ukuran total tidak melebihi 8 KB.

    Ubah metadata objek

    Kode berikut menunjukkan cara mengubah metadata suatu objek.

    import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
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 {
        // Titik akhir wilayah China (Hangzhou) digunakan sebagai contoh. Tentukan titik akhir aktual Anda.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Tentukan nama bucket sumber.
        String sourceBucketName = "yourSourceBucketName";
        // Tentukan path lengkap objek sumber.
        String sourceObjectName = "yourSourceObjectName";
        // Tentukan nama bucket tujuan. Bucket tujuan harus berada di wilayah yang sama dengan bucket sumber.
        String destinationBucketName = "yourDestinationBucketName";
        // Tentukan path lengkap objek tujuan.
        String destinationObjectName = "yourDestinationObjectName";
        // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur wilayah menjadi cn-hangzhou.
        String region = "cn-hangzhou";

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

        try {
            // Atur objek sumber sama dengan objek tujuan. Panggil metode ossClient.copyObject untuk mengubah metadata objek.
            CopyObjectRequest request = new CopyObjectRequest(sourceBucketName, sourceObjectName, destinationBucketName, destinationObjectName);

            ObjectMetadata meta = new ObjectMetadata();
            // Tentukan tipe konten objek yang akan diunggah. Tipe konten menentukan cara browser membaca objek. Jika parameter ini tidak ditentukan, tipe konten akan dihasilkan berdasarkan ekstensi file objek. Jika objek tidak memiliki ekstensi file, nilai default application/octet-stream digunakan.
            meta.setContentType("text/plain; charset=utf-8");
            // Atur header. Misalnya, atur kelas penyimpanan untuk objek yang diunggah.
            meta.setHeader("x-oss-storage-class", StorageClass.Standard);
            
            // Hapus komentar pada baris berikut sesuai kebutuhan.
            
            // Atur nama objek saat diunduh.
            // meta.setContentDisposition("attachment; filename=\"DownloadFilename\"");
            // Atur panjang objek yang akan diunggah. Jika objek lebih panjang dari nilai ini, maka akan dipotong. Jika objek lebih pendek, panjang aktualnya yang digunakan.
            // meta.setContentLength(content.length());
            // Atur perilaku caching halaman web saat objek diunduh.
            // meta.setCacheControl("Download Action");
            // Atur waktu kedaluwarsa cache. Waktu harus dalam format GMT.
            // meta.setExpirationTime(DateUtil.parseIso8601Date("2022-10-12T00:00:00.000Z"));
            // Atur format encoding objek saat diunduh.
            // meta.setContentEncoding("gzip");            
           
            // Atur metadata kustom.
            meta.addUserMetadata("key1", "value1");
            meta.addUserMetadata("key2", "value2");
            
            request.setNewObjectMetadata(meta);

            // Ubah metadata.
            ossClient.copyObject(request);
        } catch (OSSException oe) {
            System.out.println("Terjadi OSSException, yang berarti permintaan Anda berhasil mencapai OSS, "
                    + "tetapi ditolak dengan tanggapan error karena suatu alasan.");
            System.out.println("Pesan Error:" + oe.getErrorMessage());
            System.out.println("Kode Error:" + oe.getErrorCode());
            System.out.println("ID Permintaan:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Terjadi ClientException, yang berarti klien mengalami "
                    + "masalah internal serius saat mencoba berkomunikasi dengan OSS, "
                    + "seperti tidak dapat mengakses jaringan.");
            System.out.println("Pesan Error:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

    Ambil metadata objek

    Anda dapat menggunakan dua metode berikut untuk mengambil metadata objek.

    Metode

    Deskripsi

    ossClient.getSimplifiedObjectMeta

    Mendapatkan ETag, Ukuran, dan waktu LastModified objek. Metode ini sesuai dengan operasi API GetObjectMeta.

    ossClient.getObjectMetadata

    Mendapatkan seluruh metadata objek. Metode ini sesuai dengan operasi API HeadObject.

    Kode berikut menunjukkan cara mengambil metadata objek.

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

public class Demo {
    public static void main(String[] args) throws Exception {
        // Titik akhir wilayah China (Hangzhou) digunakan sebagai contoh. Tentukan titik akhir aktual Anda.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Tentukan nama bucket. Misalnya, examplebucket.
        String bucketName = "examplebucket";
        // Tentukan path lengkap objek. Jangan sertakan nama bucket dalam path lengkap. Misalnya, testfolder/exampleobject.txt.
        String objectName = "testfolder/exampleobject.txt";
        // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur wilayah menjadi cn-hangzhou.
        String region = "cn-hangzhou";

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

        try {
            // Tentukan nama bucket dan path lengkap objek.
            // Ambil metadata sebagian objek.
            SimplifiedObjectMeta objectMeta = ossClient.getSimplifiedObjectMeta(bucketName, objectName);
            System.out.println("Ambil metadata sebagian objek");
            System.out.println(objectMeta.getSize());
            System.out.println(objectMeta.getETag());
            System.out.println(objectMeta.getLastModified());
            // Setelah Anda mengaktifkan pelacakan akses, Anda dapat memperoleh metadata objek yang mencakup waktu akses terakhir (X-Oss-Last-Access-Time). Anda hanya dapat memperoleh X-Oss-Last-Access-Time jika menggunakan Java SDK versi 3.16.0 atau lebih baru.
            System.out.println(objectMeta.getHeaders().get("x-oss-last-access-time"));

            // Ambil seluruh metadata objek.
            ObjectMetadata metadata = ossClient.getObjectMetadata(bucketName, objectName);
            System.out.println("Ambil seluruh metadata objek");
            System.out.println(metadata.getContentType());
            System.out.println(metadata.getLastModified());
            System.out.println(metadata.getExpirationTime());
            System.out.println(metadata.getETag());
            System.out.println(metadata.getContentMD5());
            System.out.println(metadata.getContentLength());
            System.out.println(metadata.getObjectType());
            System.out.println(metadata.getUserMetadata());
        } catch (OSSException oe) {
            System.out.println("Terjadi OSSException, yang berarti permintaan Anda berhasil mencapai OSS, "
                    + "tetapi ditolak dengan tanggapan error karena suatu alasan.");
            System.out.println("Pesan Error:" + oe.getErrorMessage());
            System.out.println("Kode Error:" + oe.getErrorCode());
            System.out.println("ID Permintaan:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Terjadi ClientException, yang berarti klien mengalami "
                    + "masalah internal serius saat mencoba berkomunikasi dengan OSS, "
                    + "seperti tidak dapat mengakses jaringan.");
            System.out.println("Pesan Error:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

    Referensi

    • Untuk informasi lebih lanjut tentang metadata objek, lihat Kelola metadata objek.

    • Untuk kode contoh lengkap yang digunakan untuk mengatur dan mengambil metadata objek, lihat contoh GitHub.

    • Untuk informasi lebih lanjut tentang operasi API yang dapat Anda panggil untuk mengatur metadata objek selama unggahan sederhana, lihat PutObject.

    • Untuk informasi lebih lanjut tentang operasi API yang dapat Anda panggil untuk mengambil metadata objek, lihat GetObjectMeta dan HeadObject.