Upload file ke bucket dengan versioning diaktifkan menggunakan OSS Java SDK - Object Storage Service

Topik ini menjelaskan cara mengunggah file (objek) ke bucket yang diaktifkan fitur versioning.

Catatan

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.
Untuk mengunggah file, Anda harus memiliki izin oss:PutObject. Untuk informasi selengkapnya, lihat Berikan kebijakan akses kustom kepada Pengguna RAM.

Unggah simple

Pada bucket dengan versioning diaktifkan, OSS secara otomatis menghasilkan ID versi unik untuk setiap objek baru. ID tersebut dikembalikan dalam bidang x-oss-version-id pada header respons. Pada bucket dengan versioning ditangguhkan, ID versi objek baru adalah "null". Jika Anda mengunggah objek dengan nama yang sama, objek baru akan menimpa objek sebelumnya. OSS memastikan hanya satu versi objek yang memiliki ID versi "null".

Kode berikut menunjukkan cara melakukan unggah simple:

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

public class Demo {
    public static void main(String[] args) throws Exception {
        // Titik akhir wilayah China (Hangzhou) digunakan sebagai contoh. Gantilah dengan Titik akhir yang sebenarnya.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Tentukan nama bucket. Contoh: examplebucket.
        String bucketName = "examplebucket";
        // Tentukan path lengkap objek. Path lengkap tidak boleh mengandung nama bucket.
        String objectName = "exampledir/object";
        // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur Region menjadi cn-hangzhou.
        String region = "cn-hangzhou";

        // Buat instans OSSClient.
        // Saat instans OSSClient tidak lagi digunakan, 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 {
            // Contoh berikut menunjukkan cara mengunggah string.
            String content = "Hello OSS";
            PutObjectResult result = ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(content.getBytes()));
            // Lihat ID versi objek yang diunggah.
            System.out.println("result.versionid: " + result.getVersionId());
        } catch (OSSException oe) {
            System.out.println("Terjadi OSSException, yang berarti permintaan Anda sampai ke OSS, "
                    + "tetapi ditolak dengan tanggapan kesalahan karena suatu alasan.");
            System.out.println("Pesan Kesalahan:" + oe.getErrorMessage());
            System.out.println("Kode Kesalahan:" + 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 Kesalahan:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Unggah append

Pada bucket yang diaktifkan versioning, Anda hanya dapat menambahkan data ke versi terkini dari objek yang dapat ditambahkan dengan memanggil operasi AppendObject. Anda tidak dapat menambahkan data ke versi sebelumnya dari objek yang dapat ditambahkan.

Catatan

Saat Anda memanggil operasi AppendObject pada versi terkini objek yang dapat ditambahkan, OSS tidak membuat versi sebelumnya untuk objek tersebut.
Saat Anda memanggil operasi PutObject atau DeleteObject pada versi terkini objek yang dapat ditambahkan, OSS menyimpan objek tersebut sebagai versi sebelumnya. Anda tidak dapat lagi menambahkan data ke objek ini.
Anda tidak dapat memanggil operasi AppendObject pada versi terkini objek yang tidak dapat ditambahkan, seperti objek biasa atau penanda hapus.

Kode berikut menunjukkan cara melakukan unggah append:

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

public class Demo {
    public static void main(String[] args) throws Exception {
        // Titik akhir wilayah China (Hangzhou) digunakan sebagai contoh. Gantilah dengan Titik akhir yang sebenarnya.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Tentukan nama bucket. Contoh: examplebucket.
        String bucketName = "examplebucket";
        // Tentukan path lengkap objek. Path lengkap tidak boleh mengandung nama bucket.
        String objectName = "exampledir/object";
        String content1 = "Hello OSS A \n";
        String content2 = "Hello OSS B \n";
        String content3 = "Hello OSS C \n";
        // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur Region menjadi cn-hangzhou.
        String region = "cn-hangzhou";

        // Buat instans OSSClient.
        // Saat instans OSSClient tidak lagi digunakan, 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 {
            ObjectMetadata meta = new ObjectMetadata();
            // Tentukan tipe konten dari konten yang diunggah.
            meta.setContentType("text/plain");

            // Atur beberapa parameter menggunakan AppendObjectRequest.
            AppendObjectRequest appendObjectRequest = new AppendObjectRequest(bucketName, objectName, new ByteArrayInputStream(content1.getBytes()),meta);

            // Atur satu parameter menggunakan AppendObjectRequest.
            // Atur nama bucket.
            //appendObjectRequest.setBucketName("<yourBucketName>");
            // Atur nama file.
            //appendObjectRequest.setKey("<yourObjectName>");
            // Atur konten yang akan ditambahkan. Anda dapat menggunakan InputStream atau File. Contoh ini menggunakan InputStream.
            //appendObjectRequest.setInputStream(new ByteArrayInputStream(content1.getBytes()));
            // Atur konten yang akan ditambahkan. Anda dapat menggunakan InputStream atau File. Contoh ini menggunakan File.
            //appendObjectRequest.setFile(new File("<yourLocalFile>"));
            // Tentukan metadata file. Ini hanya berlaku untuk operasi append pertama.
            //appendObjectRequest.setMetadata(meta);

            // Operasi append pertama.
            // Atur posisi untuk mulai menambahkan data.
            appendObjectRequest.setPosition(0L);
            AppendObjectResult appendObjectResult = ossClient.appendObject(appendObjectRequest);
            // Nilai CRC 64-bit dari file.
            System.out.println(appendObjectResult.getObjectCRC());

            // Operasi append kedua.
            // nextPosition menentukan posisi untuk operasi append berikutnya, yaitu panjang file saat ini.
            appendObjectRequest.setPosition(appendObjectResult.getNextPosition());
            appendObjectRequest.setInputStream(new ByteArrayInputStream(content2.getBytes()));
            appendObjectResult = ossClient.appendObject(appendObjectRequest);

            // Operasi append ketiga.
            appendObjectRequest.setPosition(appendObjectResult.getNextPosition());
            appendObjectRequest.setInputStream(new ByteArrayInputStream(content3.getBytes()));
            appendObjectResult = ossClient.appendObject(appendObjectRequest);
        } catch (OSSException oe) {
            System.out.println("Terjadi OSSException, yang berarti permintaan Anda sampai ke OSS, "
                    + "tetapi ditolak dengan tanggapan kesalahan karena suatu alasan.");
            System.out.println("Pesan Kesalahan:" + oe.getErrorMessage());
            System.out.println("Kode Kesalahan:" + 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 Kesalahan:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Unggah multi-bagian

Pada bucket yang diaktifkan versioning, Anda dapat memanggil operasi CompleteMultipartUpload untuk menyelesaikan unggah multi-bagian. OSS menghasilkan ID versi unik untuk seluruh file. ID tersebut dikembalikan dalam bidang x-oss-version-id pada header respons.

Kode berikut menunjukkan cara melakukan unggah multi-bagian:

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

public class Demo {
    public static void main(String[] args) throws Exception {
        // Titik akhir wilayah China (Hangzhou) digunakan sebagai contoh. Gantilah dengan Titik akhir yang sebenarnya.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Tentukan nama bucket. Contoh: examplebucket.
        String bucketName = "examplebucket";
        // Tentukan path lengkap objek. Path lengkap tidak boleh mengandung nama bucket.
        String objectName = "exampledir/object";
        String localFile = "D://example.txt";
        // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur Region menjadi cn-hangzhou.
        String region = "cn-hangzhou";

        // Buat instans OSSClient.
        // Saat instans OSSClient tidak lagi digunakan, 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 {
            /* Langkah 1: Inisialisasi event unggah multi-bagian.
             */
            InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(bucketName, objectName);
            InitiateMultipartUploadResult upresult = ossClient.initiateMultipartUpload(request);
            // ID unggah dikembalikan. Ini adalah pengenal unik untuk event unggah multi-bagian. Anda dapat menggunakan ID unggah ini untuk melakukan operasi seperti membatalkan atau mengkueri unggah multi-bagian.
            String uploadId = upresult.getUploadId();

            /* Langkah 2: Unggah bagian-bagian.
             */
            // partETags adalah kumpulan objek PartETag. PartETag terdiri dari ETag dan nomor bagian suatu bagian.
            List<PartETag> partETags =  new ArrayList<PartETag>();
            // Hitung jumlah bagian.
            final long partSize = 1 * 1024 * 1024L;   // 1 MB
            final File sampleFile = new File(localFile);
            long fileLength = sampleFile.length();
            int partCount = (int) (fileLength / partSize);
            if (fileLength % partSize != 0) {
                partCount++;
            }
            // Iterasi melalui bagian-bagian dan unggah.
            for (int i = 0; i < partCount; i++) {
                long startPos = i * partSize;
                long curPartSize = (i + 1 == partCount) ? (fileLength - startPos) : partSize;
                InputStream instream = new FileInputStream(sampleFile);
                // Lewati bagian yang sudah diunggah.
                instream.skip(startPos);
                UploadPartRequest uploadPartRequest = new UploadPartRequest();
                uploadPartRequest.setBucketName(bucketName);
                uploadPartRequest.setKey(objectName);
                uploadPartRequest.setUploadId(uploadId);
                uploadPartRequest.setInputStream(instream);
                // Atur ukuran bagian. Kecuali bagian terakhir, ukuran minimum setiap bagian adalah 100 KB.
                uploadPartRequest.setPartSize(curPartSize);
                // Atur nomor bagian. Setiap bagian yang diunggah memiliki nomor bagian yang berkisar antara 1 hingga 10.000. Jika nomor bagian berada di luar rentang ini, OSS mengembalikan kode kesalahan InvalidArgument.
                uploadPartRequest.setPartNumber( i + 1);
                // Bagian-bagian tidak perlu diunggah secara berurutan. Bahkan dapat diunggah dari klien yang berbeda. OSS menggabungkan bagian-bagian tersebut menjadi file lengkap berdasarkan nomor bagiannya.
                UploadPartResult uploadPartResult = ossClient.uploadPart(uploadPartRequest);
                // Setelah setiap bagian diunggah, respons dari OSS berisi PartETag. PartETag disimpan ke partETags.
                partETags.add(uploadPartResult.getPartETag());
            }

            /* Langkah 3: Selesaikan unggah multi-bagian.
             */
            // Saat melakukan operasi ini, Anda harus menyediakan semua partETags yang valid. Setelah OSS menerima partETags yang dikirimkan, OSS memverifikasi validitas setiap bagian. Setelah semua bagian diverifikasi, OSS menggabungkannya menjadi file lengkap.
            CompleteMultipartUploadRequest completeMultipartUploadRequest =
                    new CompleteMultipartUploadRequest(bucketName, objectName, uploadId, partETags);

            CompleteMultipartUploadResult completeMultipartUploadResult = ossClient.completeMultipartUpload(completeMultipartUploadRequest);
            // Lihat ID versi file yang diunggah.
            System.out.println("restore object versionid: " + completeMultipartUploadResult.getVersionId());

        } catch (OSSException oe) {
            System.out.println("Terjadi OSSException, yang berarti permintaan Anda sampai ke OSS, "
                    + "tetapi ditolak dengan tanggapan kesalahan karena suatu alasan.");
            System.out.println("Pesan Kesalahan:" + oe.getErrorMessage());
            System.out.println("Kode Kesalahan:" + 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 Kesalahan:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Referensi

Untuk informasi selengkapnya tentang unggah simple, lihat PutObject.
Untuk informasi selengkapnya tentang unggah append, lihat AppendObject.
Untuk informasi selengkapnya tentang unggah multi-bagian, lihat CompleteMultipartUpload.