Cara melakukan unduhan rentang menggunakan Java SDK - Object Storage Service

Jika Anda hanya memerlukan sebagian file, Anda dapat melakukan range download untuk mengambil rentang data tertentu.

Perhatian

Pada topik ini, titik akhir publik wilayah China (Hangzhou) digunakan. Untuk mengakses OSS dari layanan Alibaba Cloud lainnya di wilayah yang sama, gunakan titik akhir internal. Untuk detail wilayah dan titik akhir yang didukung, lihat Regions and endpoints.
Pada topik ini, kredensial akses diperoleh dari variabel lingkungan. Untuk informasi lebih lanjut tentang cara mengonfigurasi kredensial akses, lihat Configure access credentials.
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 Configuration examples for common scenarios.
Untuk melakukan range download, Anda harus memiliki izin oss:GetObject. Untuk informasi lebih lanjut, lihat Grant custom permissions to a RAM user.

Tentukan rentang unduhan normal

Kode berikut menunjukkan cara menentukan rentang unduhan yang valid untuk mengunduh file.

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.GetObjectRequest;
import com.aliyun.oss.model.OSSObject;
import java.io.InputStream;

public class Demo {
    public static void main(String[] args) throws Exception {
        // Titik akhir China (Hangzhou) digunakan sebagai contoh. Tentukan titik akhir yang sebenarnya.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Peroleh 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. Contoh: examplebucket.
        String bucketName = "examplebucket";
        // Tentukan path lengkap objek. Contoh: exampledir/exampleobject.txt. Path lengkap tidak boleh mencakup nama bucket.
        String objectName = "exampledir/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.
        // Saat instans OSSClient tidak lagi digunakan, panggil metode shutdown untuk melepaskan sumber daya.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();
        
        InputStream in = null;
        try {
            GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, objectName);
            // Untuk file berukuran 1.000 byte, rentang byte normal adalah 0 hingga 999.
            // Ambil data dalam rentang 0 hingga 999 byte, yang mencakup byte 0 dan byte 999, total 1.000 byte. Jika rentang yang ditentukan tidak valid, misalnya posisi awal atau akhir bernilai negatif atau lebih besar dari ukuran file, seluruh file akan diunduh.
            getObjectRequest.setRange(0, 999);

            // Lakukan range download.
            OSSObject ossObject = ossClient.getObject(getObjectRequest);

            // Baca data.
            byte[] buf = new byte[1024];
            in = ossObject.getObjectContent();
            for (int n = 0; n != -1; ) {
                n = in.read(buf, 0, buf.length);
            }
            ossObject.close();
        } catch (OSSException oe) {
            System.out.println("Terjadi OSSException, yang berarti permintaan Anda berhasil mencapai 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 client mengalami "
                    + "masalah internal serius saat mencoba berkomunikasi dengan OSS, "
                    + "misalnya tidak dapat mengakses jaringan.");
            System.out.println("Pesan Kesalahan:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
            // Setelah data dibaca, Anda harus menutup aliran. Jika tidak, kebocoran koneksi dapat terjadi. Hal ini dapat menghabiskan koneksi yang tersedia dan menyebabkan program berhenti bekerja.
            if (in != null) {
                in.close();
            }
        }
    }
}

Pembacaan aliran tunggal mungkin tidak mengambil semua data. Untuk membaca data sebesar 64 KB dari aliran, Anda harus membaca aliran tersebut beberapa kali hingga 64 KB data terbaca atau akhir file tercapai. Untuk informasi lebih lanjut, lihat InputStream.read.

byte[] buf = new byte[1024];
InputStream in = ossObject.getObjectContent();
for (int n = 0; n != -1; ) {
    n = in.read(buf, 0, buf.length);
}
in.close();

Tentukan rentang unduhan tidak valid

Asumsikan Anda memiliki objek berukuran 1.000 byte. Rentang unduhan yang valid adalah 0 hingga 999. Jika Anda menentukan rentang di luar interval valid ini, header Range tidak berpengaruh. OSS mengembalikan kode status 200 dan mengirim seluruh objek. Contoh berikut menunjukkan permintaan tidak valid dan tanggapannya:

Jika Anda menentukan Range: bytes=500-2000, akhir rentang berada di luar interval valid. OSS mengembalikan seluruh objek dan kode status HTTP 200.
Jika Anda menentukan Range: bytes=1000-2000, awal rentang berada di luar interval valid. OSS mengembalikan seluruh objek dan kode status HTTP 200.

Perilaku standar untuk range download

Anda dapat menambahkan header x-oss-range-behavior: standard ke permintaan untuk mengubah perilaku unduhan OSS pada rentang yang berada di luar interval valid. Asumsikan Anda memiliki objek berukuran 1.000 byte:

Jika Anda menentukan Range: bytes=500-2000, akhir rentang berada di luar interval valid. OSS mengembalikan konten dari byte 500 hingga byte 999 dan kode status HTTP 206.
Jika Anda menentukan Range: bytes=1000-2000, awal rentang berada di luar interval valid. OSS mengembalikan kode status HTTP 416 dan kode kesalahan InvalidRange.

Kode berikut menunjukkan cara melakukan range download dengan perilaku standar.

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

public class Demo {

    public static void main(String[] args) throws Exception {
        // Titik akhir China (Hangzhou) digunakan sebagai contoh. Tentukan titik akhir yang sebenarnya.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Peroleh 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. Contoh: examplebucket.
        String bucketName = "examplebucket";
        // Tentukan path lengkap objek. Contoh: exampledir/exampleobject.txt. Path lengkap tidak boleh mencakup nama bucket.
        String objectName = "exampledir/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.
        // Saat instans OSSClient tidak lagi digunakan, panggil metode shutdown untuk melepaskan sumber daya.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        // Nyatakan secara eksplisit penggunaan algoritma signature V4.
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .region(region)
                .build();

        try {
            // Akhir rentang berada di luar interval valid. OSS mengembalikan konten dari byte 500 hingga byte 999 dan kode status HTTP 206.
            GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, objectName);
            getObjectRequest.setRange(500, 2000);
            getObjectRequest.addHeader("x-oss-range-behavior", "standard");
            OSSObject ossObject = ossClient.getObject(getObjectRequest);
            ossObject.close();

            System.out.println("standard get " + "500~2000 "+ "statusCode:"  + ossObject.getResponse().getStatusCode());
            System.out.println("standard get " + "500~2000 " + "contentLength:" + ossObject.getResponse().getContentLength());

            // Awal rentang berada di luar interval valid. Kode berikut melemparkan pengecualian. OSS mengembalikan kode status HTTP 416 dan kode kesalahan InvalidRange.
            getObjectRequest = new GetObjectRequest(bucketName, objectName);
            getObjectRequest.setRange(1000, 2000);
            getObjectRequest.addHeader("x-oss-range-behavior", "standard");
            OSSObject ossObject2 = ossClient.getObject(getObjectRequest);
            ossObject2.close();
        } catch (OSSException oe) {
            System.out.println("Terjadi OSSException, yang berarti permintaan Anda berhasil mencapai 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 client mengalami "
                    + "masalah internal serius saat mencoba berkomunikasi dengan OSS, "
                    + "misalnya tidak dapat mengakses jaringan.");
            System.out.println("Pesan Kesalahan:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

Referensi

Untuk informasi lebih lanjut tentang operasi API untuk range download, lihat GetObject.