Object Storage Service：Unggah multi-bagian (C# SDK V1)

Catatan penggunaan

• Topik ini menggunakan titik akhir publik wilayah China (Hangzhou). Jika Anda mengakses OSS dari layanan Alibaba Cloud lainnya yang berada di wilayah yang sama dengan OSS, gunakan titik akhir internal. Untuk informasi selengkapnya mengenai wilayah dan titik akhir OSS, lihat Wilayah dan titik akhir.

• 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 Inisialisasi.

• Untuk melakukan unggah multi-bagian, Anda harus memiliki izin oss:PutObject. Untuk informasi selengkapnya, lihat Contoh umum kebijakan RAM.

Alur unggah multi-bagian

Unggah multi-bagian terdiri atas tiga langkah berikut:

1. Mulai unggah multi-bagian.

   Panggil metode InitiateMultipartUploadRequest. OSS akan mengembalikan upload ID yang bersifat unik secara global.

2. Unggah bagian-bagian.

   Panggil metode UploadPartRequest untuk mengunggah setiap bagian.

   Catatan

   • Untuk uploadId tertentu, nomor bagian menentukan posisi suatu bagian dalam objek lengkap. Jika Anda mengunggah bagian baru dengan nomor bagian yang sama dengan bagian yang sudah ada, bagian yang sudah ada akan ditimpa.

   • OSS menyertakan hash MD5 dari data bagian yang diterima dalam header ETag pada respons.

   • OSS menghitung hash MD5 dari data yang diunggah dan membandingkannya dengan hash MD5 yang dihitung oleh SDK. Jika kedua hash tidak sesuai, OSS mengembalikan kode kesalahan InvalidDigest.

3. Selesaikan unggah multi-bagian.

   Setelah semua bagian diunggah, panggil metode CompleteMultipartUploadRequest untuk menggabungkannya menjadi satu file utuh.

Contoh lengkap unggah multi-bagian

Kode contoh berikut menunjukkan cara mengimplementasikan tugas unggah multi-bagian sesuai dengan proses unggah multi-bagian:

using Aliyun.OSS;
using Aliyun.OSS.Common;

// Tetapkan yourEndpoint ke titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan titik akhir ke https://oss-cn-hangzhou.aliyuncs.com.
var endpoint = "yourEndpoint";
// Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// Tetapkan nama bucket.
var bucketName = "examplebucket";
// Tetapkan path lengkap objek. Path lengkap tidak boleh mencakup nama bucket.
var objectName = "exampleobject.txt";
// Tetapkan path lengkap file lokal. Jika path lokal tidak ditentukan, file akan diunggah dari path lokal proyek yang berisi program contoh secara default.
var localFilename = "D:\\localpath\\examplefile.txt";
// Tetapkan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan wilayah ke cn-hangzhou.
const string region = "cn-hangzhou";

// Buat instans ClientConfiguration dan ubah parameter default sesuai kebutuhan.
var conf = new ClientConfiguration();

// Tetapkan signature ke V4.
conf.SignatureVersion = SignatureVersion.V4;

// Buat instans OssClient.
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
client.SetRegion(region);

// Inisialisasi unggah multi-bagian dan kembalikan upload ID.
var uploadId = "";
try
{
    // Tentukan nama file yang akan diunggah dan bucket tempat file tersebut berada. Anda dapat menyetel ObjectMeta dalam InitiateMultipartUploadRequest, tetapi tidak perlu menentukan ContentLength.
    var request = new InitiateMultipartUploadRequest(bucketName, objectName);
    var result = client.InitiateMultipartUpload(request);
    uploadId = result.UploadId;
    // Cetak upload ID.
    Console.WriteLine("Init multi part upload succeeded");
    // Gunakan upload ID untuk membatalkan event unggah multi-bagian atau menampilkan daftar bagian yang telah diunggah.
    // Untuk membatalkan event unggah multi-bagian menggunakan upload ID, ambil upload ID setelah memanggil InitiateMultipartUpload untuk menginisialisasi unggah multi-bagian.
    // Untuk menampilkan daftar bagian yang telah diunggah menggunakan upload ID, ambil upload ID setelah memanggil InitiateMultipartUpload untuk menginisialisasi unggah multi-bagian dan sebelum memanggil CompleteMultipartUpload untuk menyelesaikan unggah multi-bagian.
    Console.WriteLine("Upload Id:{0}", result.UploadId);
}
catch (Exception ex)
{
    Console.WriteLine("Init multi part upload failed, {0}", ex.Message);
    Environment.Exit(1);
}
// Hitung jumlah total bagian.
// Ukuran minimum suatu bagian adalah 100 KB, dan ukuran maksimumnya adalah 5 GB. Bagian terakhir dapat lebih kecil dari 100 KB.
var partSize = 100 * 1024;
var fi = new FileInfo(localFilename);
var fileSize = fi.Length;
var partCount = fileSize / partSize;
if (fileSize % partSize != 0)
{
    partCount++;
}
// Saat unggah multi-bagian diinisialisasi, mulai mengunggah bagian-bagian tersebut. PartETags adalah daftar yang menyimpan informasi PartETag. Setelah OSS menerima daftar bagian yang Anda kirimkan, OSS akan memverifikasi validitas setiap bagian. Setelah semua bagian data diverifikasi, OSS akan menggabungkannya menjadi satu file utuh.
var partETags = new List<PartETag>();
try
{
    using (var fs = File.Open(localFilename, FileMode.Open))
    {
        for (var i = 0; i < partCount; i++)
        {
            var skipBytes = (long)partSize * i;
            // Tentukan posisi awal untuk unggahan ini.
            fs.Seek(skipBytes, 0);
            // Hitung ukuran bagian untuk unggahan ini. Bagian terakhir adalah ukuran data yang tersisa.
            var size = (partSize < fileSize - skipBytes) ? partSize : (fileSize - skipBytes);
            var request = new UploadPartRequest(bucketName, objectName, uploadId)
            {
                InputStream = fs,
                PartSize = size,
                PartNumber = i + 1
            };
            // Panggil operasi UploadPart untuk mengunggah bagian ini. Hasilnya berisi nilai ETag dari bagian data ini.
            var result = client.UploadPart(request);
            partETags.Add(result.PartETag);
            Console.WriteLine("finish {0}/{1}", partETags.Count, partCount);
        }
        Console.WriteLine("Put multi part upload succeeded");
    }
}
catch (Exception ex)
{
    Console.WriteLine("Put multi part upload failed, {0}", ex.Message);
    Environment.Exit(1);
}
// Setelah bagian-bagian diunggah, gabungkan bagian-bagian tersebut.
try
{
    var completeMultipartUploadRequest = new CompleteMultipartUploadRequest(bucketName, objectName, uploadId);
    foreach (var partETag in partETags)
    {
        completeMultipartUploadRequest.PartETags.Add(partETag);
    }
    var result = client.CompleteMultipartUpload(completeMultipartUploadRequest);
    Console.WriteLine("complete multi part succeeded");
}
catch (Exception ex)
{
    Console.WriteLine("complete multi part failed, {0}", ex.Message);
    Environment.Exit(1);
}

Membatalkan event unggah multi-bagian

Anda dapat memanggil metode client.AbortMultipartUpload untuk membatalkan unggah multi-bagian. Setelah unggah multi-bagian dibatalkan, Anda tidak dapat lagi menggunakan upload ID-nya untuk operasi apa pun, dan bagian-bagian yang telah diunggah akan dihapus.

Kode berikut memberikan contoh cara membatalkan unggah multi-bagian.

using Aliyun.OSS;
using Aliyun.OSS.Common;

// Tetapkan yourEndpoint ke titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan titik akhir ke https://oss-cn-hangzhou.aliyuncs.com.
var endpoint = "yourEndpoint";
// Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// Tetapkan nama bucket.
var bucketName = "examplebucket";
// Tetapkan path lengkap objek. Path lengkap tidak boleh mencakup nama bucket.
var objectName = "exampleobject.txt";
// Tetapkan upload ID. Upload ID dikembalikan setelah Anda memanggil InitiateMultipartUpload untuk menginisialisasi unggah multi-bagian.
var uploadId = "yourUploadId";
// Tetapkan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan wilayah ke cn-hangzhou.
const string region = "cn-hangzhou";

// Buat instans ClientConfiguration dan ubah parameter default sesuai kebutuhan.
var conf = new ClientConfiguration();

// Tetapkan signature ke V4.
conf.SignatureVersion = SignatureVersion.V4;

// Buat instans OssClient.
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
client.SetRegion(region);
// Inisialisasi unggah multi-bagian.
try
{
    var request = new InitiateMultipartUploadRequest(bucketName, objectName);
    var result = client.InitiateMultipartUpload(request);
    uploadId = result.UploadId;
    // Cetak upload ID.
    Console.WriteLine("Init multi part upload succeeded");
    Console.WriteLine("Upload Id:{0}", result.UploadId);
}
catch (Exception ex)
{
    Console.WriteLine("Init multi part upload failed, {0}", ex.Message);
}
// Batalkan unggah multi-bagian.
try
{
    var request = new AbortMultipartUploadRequest(bucketName, objectName, uploadId);
    client.AbortMultipartUpload(request);
    Console.WriteLine("Abort multi part succeeded, {0}", uploadId);
}
catch (Exception ex)
{
    Console.WriteLine("Abort multi part failed, {0}", ex.Message);
}

Menampilkan daftar bagian yang telah diunggah

Kode berikut memberikan contoh cara menampilkan daftar bagian yang telah diunggah:

using Aliyun.OSS;
using Aliyun.OSS.Common;

// Tetapkan yourEndpoint ke titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan titik akhir ke https://oss-cn-hangzhou.aliyuncs.com.
var endpoint = "yourEndpoint";
// Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// Tetapkan nama bucket.
var bucketName = "examplebucket";
// Tetapkan path lengkap objek. Path lengkap tidak boleh mencakup nama bucket.
var objectName = "exampleobject.txt";
// Tetapkan upload ID. Upload ID dikembalikan setelah Anda memanggil InitiateMultipartUpload untuk menginisialisasi unggah multi-bagian dan sebelum memanggil CompleteMultipartUpload untuk menyelesaikan unggah multi-bagian.
var uploadId = "yourUploadId";
// Tetapkan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan wilayah ke cn-hangzhou.
const string region = "cn-hangzhou";

// Buat instans ClientConfiguration dan ubah parameter default sesuai kebutuhan.
var conf = new ClientConfiguration();

// Tetapkan signature ke V4.
conf.SignatureVersion = SignatureVersion.V4;

// Buat instans OssClient.
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
client.SetRegion(region);
try
{
    PartListing listPartsResult = null;
    var nextMarker = 0;
    do 
    {
        var listPartsRequest = new ListPartsRequest(bucketName, objectName, uploadId) 
        {
            PartNumberMarker = nextMarker,
        };
        // Tampilkan daftar bagian yang telah diunggah.
        listPartsResult = client.ListParts(listPartsRequest);
        Console.WriteLine("List parts succeeded");
        // Telusuri semua bagian.
        var parts = listPartsResult.Parts;
        foreach (var part in parts)
        {
            Console.WriteLine("partNumber: {0}, ETag: {1}, Size: {2}", part.PartNumber, part.ETag, part.Size);
        }
        nextMarker = listPartsResult.NextPartNumberMarker;
    } while (listPartsResult.IsTruncated);
}
catch (Exception ex)
{
    Console.WriteLine("List parts failed, {0}", ex.Message);
}

Menampilkan daftar event unggah multi-bagian

Anda dapat memanggil metode ossClient.listMultipartUploads untuk menampilkan daftar semua unggah multi-bagian yang sedang berlangsung. Unggah multi-bagian yang sedang berlangsung adalah unggahan yang telah diinisialisasi tetapi belum diselesaikan atau dibatalkan. Anda dapat menyetel parameter berikut:

Kode berikut menunjukkan cara menampilkan daftar event unggah multi-bagian.

using Aliyun.OSS;
using Aliyun.OSS.Common;

// Tetapkan yourEndpoint ke titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan titik akhir ke https://oss-cn-hangzhou.aliyuncs.com.
var endpoint = "yourEndpoint";
// Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// Tetapkan nama bucket.
var bucketName = "examplebucket";

// Tetapkan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan wilayah ke cn-hangzhou.
const string region = "cn-hangzhou";

// Buat instans ClientConfiguration dan ubah parameter default sesuai kebutuhan.
var conf = new ClientConfiguration();

// Tetapkan signature ke V4.
conf.SignatureVersion = SignatureVersion.V4;

// Buat instans OssClient.
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
client.SetRegion(region);
try
{
    MultipartUploadListing multipartUploadListing = null;
    var nextMarker = string.Empty;
    do
    {
        // Tampilkan daftar event unggah multi-bagian.
        var request = new ListMultipartUploadsRequest(bucketName)
        {
            KeyMarker = nextMarker,
        };
        multipartUploadListing = client.ListMultipartUploads(request);
        Console.WriteLine("List multi part succeeded");
        // Tampilkan informasi setiap event unggah multi-bagian.
        foreach (var mu in multipartUploadListing.MultipartUploads)
        {
            Console.WriteLine("Key: {0},  UploadId: {1}", mu.Key, mu.UploadId);
        }
        // Jika hasilnya terpotong, nextKeyMarker menentukan titik awal untuk permintaan berikutnya.
        nextMarker = multipartUploadListing.NextKeyMarker;
    } while (multipartUploadListing.IsTruncated);
}
catch (Exception ex)
{
    Console.WriteLine("List multi part uploads failed, {0}", ex.Message);
}

Menentukan awalan dan jumlah maksimum entri yang dikembalikan

Kode berikut memberikan contoh cara menampilkan daftar unggah multi-bagian dengan menentukan awalan dan jumlah maksimum entri yang dikembalikan:

using Aliyun.OSS;
using Aliyun.OSS.Common;

// Tetapkan yourEndpoint ke titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan titik akhir ke https://oss-cn-hangzhou.aliyuncs.com.
var endpoint = "yourEndpoint";
// Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// Tetapkan nama bucket.
var bucketName = "examplebucket";

// Tentukan awalan.
var prefix = "yourObjectPrefix";
// Tentukan jumlah maksimum entri yang dikembalikan sebagai 100.
var maxUploads = 100;
// Tetapkan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan wilayah ke cn-hangzhou.
const string region = "cn-hangzhou";

// Buat instans ClientConfiguration dan ubah parameter default sesuai kebutuhan.
var conf = new ClientConfiguration();

// Tetapkan signature ke V4.
conf.SignatureVersion = SignatureVersion.V4;

// Buat instans OssClient.
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
client.SetRegion(region);
try
{
    MultipartUploadListing multipartUploadListing = null;
    var nextMarker = string.Empty;
    do
    {
        // Tampilkan daftar event unggah multi-bagian. Secara default, 1.000 event ditampilkan.
        var request = new ListMultipartUploadsRequest(bucketName)
        {
            KeyMarker = nextMarker,
            // Tentukan awalan.
            Prefix = prefix,
            // Tentukan jumlah maksimum entri yang dikembalikan.
            MaxUploads = maxUploads,
        };
        multipartUploadListing = client.ListMultipartUploads(request);
        Console.WriteLine("List multi part succeeded");
        // Tampilkan informasi setiap event unggah multi-bagian.
        foreach (var mu in multipartUploadListing.MultipartUploads)
        {
            Console.WriteLine("Key: {0},  UploadId: {1}", mu.Key, mu.UploadId);
        }
        nextMarker = multipartUploadListing.NextKeyMarker;
    } while (multipartUploadListing.IsTruncated);
}
catch (Exception ex)
{
    Console.WriteLine("List multi part uploads failed, {0}", ex.Message);
}

Referensi

• Untuk kode contoh lengkap unggah multi-bagian, lihat contoh GitHub.

• Unggah multi-bagian melibatkan tiga operasi API. Untuk informasi selengkapnya mengenai operasi tersebut, lihat topik berikut:

  • InitiateMultipartUpload

  • UploadPart

  • CompleteMultipartUpload

• Untuk informasi selengkapnya mengenai operasi API yang digunakan untuk membatalkan event unggah multi-bagian, lihat AbortMultipartUpload.

• Untuk informasi selengkapnya mengenai operasi API yang digunakan untuk menampilkan daftar bagian yang telah diunggah, lihat ListUploadedParts.

• Untuk informasi selengkapnya mengenai operasi API yang digunakan untuk menampilkan daftar semua event unggah multi-bagian yang sedang berlangsung—yaitu event yang telah diinisialisasi tetapi belum diselesaikan atau dibatalkan—lihat ListMultipartUploads.