Object Storage Service：Menyalin objek menggunakan OSS SDK untuk Java

Catatan penggunaan

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

• Dalam topik ini, kredensial akses diperoleh dari variabel lingkungan. Untuk informasi lebih lanjut tentang cara mengonfigurasi kredensial akses, lihat Konfigurasi Kredensial Akses.

• Dalam topik ini, instance OSSClient dibuat dengan menggunakan titik akhir OSS. Jika Anda ingin membuat instance OSSClient dengan menggunakan nama domain kustom atau Layanan Token Keamanan (STS), lihat Contoh Konfigurasi untuk Skenario Umum.

• Untuk menyalin objek, Anda harus memiliki izin baca pada objek sumber dan izin baca serta tulis pada bucket tujuan.

• Pastikan tidak ada kebijakan retensi yang dikonfigurasi untuk bucket sumber dan bucket tujuan. Jika tidak, pesan kesalahan Objek yang Anda tentukan tidak dapat diubah. akan dikembalikan.

• Bucket sumber dan tujuan harus berada di wilayah yang sama. Sebagai contoh, objek tidak dapat disalin dari bucket yang terletak di Wilayah China (Hangzhou) ke bucket lain yang terletak di Wilayah China (Qingdao).

Menyalin objek kecil

Anda dapat menggunakan metode ossClient.copyObject untuk menyalin objek yang ukurannya lebih kecil dari 1 GB. Tabel berikut menjelaskan metode konfigurasi untuk ossClient.copyObject.

Tabel berikut menjelaskan parameter yang dapat Anda konfigurasikan untuk CopyObjectRequest.

Tabel berikut menjelaskan parameter yang dapat Anda konfigurasikan untuk CopyObjectResult.

Anda dapat menggunakan salah satu metode berikut untuk menyalin objek kecil:

• Salinan Sederhana

  Kode berikut memberikan contoh cara menggunakan salinan sederhana untuk menyalin objek bernama srcexampleobject.txt dari bucket srcexamplebucket ke objek bernama desexampleobject.txt di bucket desexamplebucket:

  import com.aliyun.oss.*;
  import com.aliyun.oss.common.auth.*;
  import com.aliyun.oss.common.comm.SignVersion;
  import com.aliyun.oss.model.*;
  
  public class Demo {
      public static void main(String[] args) throws Exception {
          // Dalam contoh ini, titik akhir wilayah China (Hangzhou) digunakan. Tentukan titik akhir aktual Anda.
          String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
          // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode sampel, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi.
          EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
          // Tentukan nama bucket sumber.
          String sourceBucketName = "srcexamplebucket";
          // Tentukan jalur lengkap objek sumber. Jangan sertakan nama bucket dalam jalur lengkap.
          String sourceKey = "srcexampleobject.txt";
          // Tentukan nama bucket tujuan. Bucket tujuan harus berada di wilayah yang sama dengan bucket sumber.
          String destinationBucketName = "desexamplebucket";
          // Tentukan jalur lengkap objek tujuan. Jangan sertakan nama bucket dalam jalur lengkap.
          String destinationKey = "desexampleobject.txt";
          // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur wilayah ke cn-hangzhou.
          String region = "cn-hangzhou";
  
          // Buat instance OSSClient.
          // Panggil metode shutdown untuk melepaskan sumber daya ketika OSSClient tidak lagi digunakan.
          ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
          clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
          OSS ossClient = OSSClientBuilder.create()
          .endpoint(endpoint)
          .credentialsProvider(credentialsProvider)
          .clientConfiguration(clientBuilderConfiguration)
          .region(region)               
          .build();
  
          try {
              // Salin objek.
              CopyObjectResult result = ossClient.copyObject(sourceBucketName, sourceKey, destinationBucketName, destinationKey);
              System.out.println("ETag: " + result.getETag() + " LastModified: " + result.getLastModified());
          } catch (OSSException oe) {
              System.out.println("Tangkap OSSException, yang berarti permintaan Anda mencapai OSS, "
                      + "tetapi ditolak dengan respons kesalahan karena alasan tertentu.");
              System.out.println("Pesan Kesalahan:" + oe.getErrorMessage());
              System.out.println("Kode Kesalahan:" + oe.getErrorCode());
              System.out.println("ID Permintaan:" + oe.getRequestId());
              System.out.println("ID Host:" + oe.getHostId());
          } catch (ClientException ce) {
              System.out.println("Tangkap 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();
              }
          }
      }
  }                   

• Gunakan CopyObjectRequest untuk Menyalin Objek

  Kode berikut memberikan contoh cara menggunakan CopyObjectRequest untuk menyalin objek bernama srcexampleobject.txt dari bucket srcexamplebucket ke objek bernama desexampleobject.txt di bucket desexamplebucket:

  import com.aliyun.oss.*;
  import com.aliyun.oss.common.auth.*;
  import com.aliyun.oss.common.comm.SignVersion;
  import com.aliyun.oss.model.*;
  
  public class Demo {
      public static void main(String[] args) throws Exception {
          // Dalam contoh ini, titik akhir wilayah China (Hangzhou) digunakan. Tentukan titik akhir aktual Anda.
          String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
          // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode sampel, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi.
          EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
          // Tentukan nama bucket sumber.
          String sourceBucketName = "srcexamplebucket";
          // Tentukan jalur lengkap objek sumber. Jangan sertakan nama bucket dalam jalur lengkap.
          String sourceKey = "srcexampleobject.txt";
          // Tentukan nama bucket tujuan. Bucket tujuan harus berada di wilayah yang sama dengan bucket sumber.
          String destinationBucketName = "desexamplebucket";
          // Tentukan jalur lengkap objek tujuan. Jangan sertakan nama bucket dalam jalur lengkap.
          String destinationKey = "desexampleobject.txt";
          // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur wilayah ke cn-hangzhou.
          String region = "cn-hangzhou";
  
          // Buat instance OSSClient.
          // Panggil metode shutdown untuk melepaskan sumber daya ketika OSSClient tidak lagi digunakan.
          ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
          clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
          OSS ossClient = OSSClientBuilder.create()
          .endpoint(endpoint)
          .credentialsProvider(credentialsProvider)
          .clientConfiguration(clientBuilderConfiguration)
          .region(region)               
          .build();
  
          try {
              // Buat objek CopyObjectRequest.
              CopyObjectRequest copyObjectRequest = new CopyObjectRequest(sourceBucketName, sourceKey, destinationBucketName, destinationKey);
  
              // Konfigurasikan metadata baru untuk objek.
              ObjectMetadata meta = new ObjectMetadata();
              meta.setContentType("text/plain");
              // Tentukan apakah operasi CopyObject menimpa objek dengan nama yang sama. Dalam contoh ini, parameter ini diatur ke true, yang menentukan bahwa operasi tidak menimpa objek dengan nama yang sama.
              // meta.setHeader("x-oss-forbid-overwrite", "true");
              // Tentukan jalur objek sumber.
              // meta.setHeader(OSSHeaders.COPY_OBJECT_SOURCE, "/examplebucket/recode-test.txt");
              // Jika nilai ETag objek sumber sama dengan nilai ETag yang ditentukan dalam permintaan, OSS menyalin objek dan mengembalikan 200 OK.
              // meta.setHeader(OSSHeaders.COPY_OBJECT_SOURCE_IF_MATCH, "5B3C1A2E053D763E1B002CC607C5****");
              // Jika nilai ETag objek sumber berbeda dari nilai ETag yang ditentukan dalam permintaan, OSS menyalin objek dan mengembalikan 200 OK.
              // meta.setHeader(OSSHeaders.COPY_OBJECT_SOURCE_IF_NONE_MATCH, "5B3C1A2E053D763E1B002CC607C5****");
              // Jika waktu yang ditentukan dalam permintaan lebih baru atau sama dengan waktu modifikasi objek, OSS menyalin objek dan mengembalikan 200 OK.
              // meta.setHeader(OSSHeaders.COPY_OBJECT_SOURCE_IF_UNMODIFIED_SINCE, "2021-12-09T07:01:56.000Z");
              // Jika objek sumber dimodifikasi setelah waktu yang ditentukan dalam permintaan, OSS menyalin objek.
              // meta.setHeader(OSSHeaders.COPY_OBJECT_SOURCE_IF_MODIFIED_SINCE, "2021-12-09T07:01:56.000Z");
              // Tentukan metode yang digunakan untuk mengonfigurasi metadata objek tujuan. Dalam contoh ini, metode diatur ke COPY, yang menentukan bahwa metadata objek sumber disalin ke objek tujuan.
              // meta.setHeader(OSSHeaders.COPY_OBJECT_METADATA_DIRECTIVE, "COPY");
              // Tentukan algoritma enkripsi sisi server yang digunakan untuk mengenkripsi objek tujuan saat objek dibuat.
              // meta.setHeader(OSSHeaders.OSS_SERVER_SIDE_ENCRYPTION, ObjectMetadata.KMS_SERVER_SIDE_ENCRYPTION);
              // Tentukan kunci master pelanggan (CMK) yang dikelola oleh Key Management Service (KMS). Parameter ini hanya berlaku jika Anda mengatur x-oss-server-side-encryption ke KMS.
              // meta.setHeader(OSSHeaders.OSS_SERVER_SIDE_ENCRYPTION_KEY_ID, "9468da86-3509-4f8d-a61e-6eab1eac****");
              // Tentukan daftar kontrol akses (ACL) objek tujuan. Dalam contoh ini, ACL diatur ke private, yang menentukan bahwa hanya pemilik objek dan pengguna yang berwenang yang memiliki izin baca dan tulis pada objek.
              // meta.setHeader(OSSHeaders.OSS_OBJECT_ACL, CannedAccessControlList.Private);
              // Tentukan kelas penyimpanan objek tujuan. Dalam contoh ini, kelas penyimpanan diatur ke Standard.
              // meta.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard);
              // Tentukan tag untuk objek tujuan. Anda dapat menentukan beberapa tag untuk objek sekaligus.
              // meta.setHeader(OSSHeaders.OSS_TAGGING, "a:1");
              // Tentukan metode yang digunakan untuk mengonfigurasi tag untuk objek tujuan. Dalam contoh ini, metode diatur ke COPY, yang menentukan bahwa tag objek sumber disalin ke objek tujuan.
              // meta.setHeader(OSSHeaders.COPY_OBJECT_TAGGING_DIRECTIVE, "COPY");
              copyObjectRequest.setNewObjectMetadata(meta);
  
              // Salin objek sumber.
              CopyObjectResult result = ossClient.copyObject(copyObjectRequest);
              System.out.println("ETag: " + result.getETag() + " LastModified: " + result.getLastModified());
          } catch (OSSException oe) {
              System.out.println("Tangkap OSSException, yang berarti permintaan Anda mencapai OSS, "
                      + "tetapi ditolak dengan respons kesalahan karena alasan tertentu.");
              System.out.println("Pesan Kesalahan:" + oe.getErrorMessage());
              System.out.println("Kode Kesalahan:" + oe.getErrorCode());
              System.out.println("ID Permintaan:" + oe.getRequestId());
              System.out.println("ID Host:" + oe.getHostId());
          } catch (ClientException ce) {
              System.out.println("Tangkap 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();
              }
          }
      }
  }                 

Menyalin objek besar

Untuk menyalin objek yang ukurannya lebih besar dari 1 GB, Anda harus membagi objek menjadi bagian-bagian dan secara berurutan menyalin bagian-bagian tersebut menggunakan UploadPartCopy. Untuk mengimplementasikan penyalinan multipart, lakukan langkah-langkah berikut:

1. Gunakan ossClient.initiateMultipartUpload untuk memulai tugas penyalinan multipart.

2. Gunakan ossClient.uploadPartCopy untuk menyalin bagian-bagian. Semua bagian kecuali bagian terakhir harus lebih besar dari 100 KB.

3. Gunakan ossClient.completeMultipartUpload untuk menyelesaikan tugas penyalinan multipart.

Kode berikut memberikan contoh cara menggunakan penyalinan multipart untuk menyalin objek bernama srcexampleobject.txt dari bucket srcexamplebucket ke objek bernama desexampleobject.txt di bucket desexamplebucket:

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 Demo {
    public static void main(String[] args) throws Exception {
        // Dalam contoh ini, titik akhir wilayah China (Hangzhou) digunakan. Tentukan titik akhir aktual Anda.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode sampel, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Tentukan nama bucket sumber.
        String sourceBucketName = "srcexamplebucket";
        // Tentukan jalur lengkap objek sumber. Jangan sertakan nama bucket dalam jalur lengkap.
        String sourceKey = "srcexampleobject.txt";
        // Tentukan nama bucket tujuan. Bucket tujuan harus berada di wilayah yang sama dengan bucket sumber.
        String destinationBucketName = "desexamplebucket";
        // Tentukan jalur lengkap objek tujuan. Jangan sertakan nama bucket dalam jalur lengkap.
        String destinationKey = "desexampleobject.txt";
        // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur wilayah ke cn-hangzhou.
        String region = "cn-hangzhou";

        // Buat instance OSSClient.
        // Panggil metode shutdown untuk melepaskan sumber daya ketika OSSClient tidak lagi digunakan.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();

        try {  
            ObjectMetadata objectMetadata = ossClient.getObjectMetadata(sourceBucketName, sourceKey);
            // Query ukuran objek yang ingin Anda salin.
            long contentLength = objectMetadata.getContentLength();

            // Atur ukuran setiap bagian menjadi 10 MB. Unit: byte.
            long partSize = 1024 * 1024 * 10;

            // Hitung jumlah total bagian.
            int partCount = (int) (contentLength / partSize);
            if (contentLength % partSize != 0) {
                partCount++;
            }
            System.out.println("total part count:" + partCount);

            // Mulai tugas penyalinan multipart. Anda dapat memanggil operasi InitiateMultipartUploadRequest untuk menentukan metadata objek tujuan.
            InitiateMultipartUploadRequest initiateMultipartUploadRequest = new InitiateMultipartUploadRequest(destinationBucketName, destinationKey);
            // Salin nilai ContentType dan UserMetadata objek sumber. Secara default, nilai ContentType dan UserMetadata objek sumber tidak disalin saat Anda menggunakan penyalinan multipart.
            ObjectMetadata metadata = new ObjectMetadata();
            metadata.setContentType(objectMetadata.getContentType());
            metadata.setUserMetadata(objectMetadata.getUserMetadata());
            initiateMultipartUploadRequest.setObjectMetadata(metadata);
            InitiateMultipartUploadResult initiateMultipartUploadResult = ossClient.initiateMultipartUpload(initiateMultipartUploadRequest);
            String uploadId = initiateMultipartUploadResult.getUploadId();

            // Mulai tugas penyalinan multipart.
            List<PartETag> partETags = new ArrayList<PartETag>();
            for (int i = 0; i < partCount; i++) {
                // Hitung ukuran setiap bagian.
                long skipBytes = partSize * i;
                long size = partSize < contentLength - skipBytes ? partSize : contentLength - skipBytes;

                // Buat objek UploadPartCopyRequest. Anda dapat memanggil operasi UploadPartCopyRequest untuk menentukan kondisi.
                UploadPartCopyRequest uploadPartCopyRequest =
                        new UploadPartCopyRequest(sourceBucketName, sourceKey, destinationBucketName, destinationKey);
                uploadPartCopyRequest.setUploadId(uploadId);
                uploadPartCopyRequest.setPartSize(size);
                uploadPartCopyRequest.setBeginIndex(skipBytes);
                uploadPartCopyRequest.setPartNumber(i + 1);
                //Map headers = new HashMap();
                // Tentukan jalur objek sumber.
                // headers.put(OSSHeaders.COPY_OBJECT_SOURCE, "/examplebucket/desexampleobject.txt");
                // Tentukan rentang data yang ingin Anda salin. Misalnya, jika Anda mengatur bytes ke 0~1023, 1.024 byte pertama objek sumber disalin.
                // headers.put(OSSHeaders.COPY_SOURCE_RANGE, "bytes=0~1023");
                // Jika nilai ETag objek sumber sama dengan nilai ETag yang ditentukan dalam permintaan, OSS menyalin objek dan mengembalikan 200 OK.
                // headers.put(OSSHeaders.COPY_OBJECT_SOURCE_IF_MATCH, "5B3C1A2E053D763E1B002CC607C5****");
                // Jika nilai ETag objek sumber berbeda dari nilai ETag yang ditentukan dalam permintaan, OSS menyalin objek dan mengembalikan 200 OK.
                // headers.put(OSSHeaders.COPY_OBJECT_SOURCE_IF_NONE_MATCH, "5B3C1A2E053D763E1B002CC607C5****");
                // Jika waktu yang ditentukan dalam permintaan lebih baru atau sama dengan waktu modifikasi objek, OSS menyalin objek dan mengembalikan 200 OK.
                // headers.put(OSSHeaders.COPY_OBJECT_SOURCE_IF_UNMODIFIED_SINCE, "2021-12-09T07:01:56.000Z");
                // Jika objek sumber dimodifikasi setelah waktu yang ditentukan dalam permintaan, OSS menyalin objek.
                // headers.put(OSSHeaders.COPY_OBJECT_SOURCE_IF_MODIFIED_SINCE, "2021-12-09T07:01:56.000Z");
                // uploadPartCopyRequest.setHeaders(headers);
                UploadPartCopyResult uploadPartCopyResult = ossClient.uploadPartCopy(uploadPartCopyRequest);

                // Simpan PartETags yang dikembalikan dalam partETags.
               partETags.add(uploadPartCopyResult.getPartETag());
            }

            // Selesaikan tugas penyalinan multipart.
            CompleteMultipartUploadRequest completeMultipartUploadRequest = new CompleteMultipartUploadRequest(
                    destinationBucketName, destinationKey, uploadId, partETags);
            ossClient.completeMultipartUpload(completeMultipartUploadRequest);
        } catch (OSSException oe) {
            System.out.println("Tangkap OSSException, yang berarti permintaan Anda mencapai OSS, "
                    + "tetapi ditolak dengan respons kesalahan karena alasan tertentu.");
            System.out.println("Pesan Kesalahan:" + oe.getErrorMessage());
            System.out.println("Kode Kesalahan:" + oe.getErrorCode());
            System.out.println("ID Permintaan:" + oe.getRequestId());
            System.out.println("ID Host:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Tangkap 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

• Menyalin Objek Kecil

  Untuk informasi lebih lanjut tentang operasi API yang dapat Anda panggil untuk menyalin objek kecil, lihat CopyObject.

• Menyalin Objek Besar

  • Untuk informasi lebih lanjut tentang kode contoh lengkap yang digunakan untuk menyalin objek besar, kunjungi GitHub.

  • Untuk informasi lebih lanjut tentang operasi API yang dapat Anda panggil untuk menyalin objek besar, lihat UploadPartCopy.