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

Catatan penggunaan

• Pada topik ini, digunakan titik akhir publik wilayah China (Hangzhou). Jika Anda mengakses OSS dari layanan Alibaba Cloud lainnya dalam wilayah yang sama dengan OSS, gunakan titik akhir internal. Untuk informasi selengkapnya tentang wilayah dan titik akhir OSS, lihat Wilayah dan titik akhir.

• Pada topik ini, instans OSSClient dibuat menggunakan titik akhir OSS. Jika Anda ingin membuat OSSClient menggunakan nama domain kustom atau Security Token Service (STS), lihat Buat instans OssClient.

• Untuk menyelesaikan seluruh proses unggah multi-bagian—yang mencakup operasi InitiateMultipartUpload, UploadPart, dan CompleteMultipartUpload—Anda harus memiliki izin oss:PutObject. Untuk informasi selengkapnya, lihat Berikan izin kustom kepada RAM user.

Prosedur

Unggah multi-bagian melibatkan tiga langkah berikut:

1. Mulai unggah multi-bagian.

   Panggil operasi InitiateMultipartUpload untuk mendapatkan upload ID yang unik secara global dari OSS.

2. Unggah bagian-bagian.

   Panggil operasi UploadPart untuk mengunggah data setiap bagian.

   Catatan

   • Untuk uploadId tertentu, nomor bagian menentukan posisi bagian tersebut dalam objek lengkap. Jika Anda mengunggah bagian baru dengan nomor bagian yang sama seperti 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 cocok, OSS mengembalikan kode kesalahan InvalidDigest.

3. Selesaikan unggah multi-bagian.

   Setelah semua bagian diunggah, panggil operasi CompleteMultipartUpload untuk menggabungkan bagian-bagian tersebut menjadi satu objek utuh.

Kode contoh untuk unggah multi-bagian

Contoh berikut menunjukkan proses unggah multi-bagian secara lengkap:

#include <alibabacloud/oss/OssClient.h>
#include <fstream>

int64_t getFileSize(const std::string& file)
{
    std::fstream f(file, std::ios::in | std::ios::binary);
    f.seekg(0, f.end);
    int64_t size = f.tellg();
    f.close();
    return size;
}

using namespace AlibabaCloud::OSS;

int main(void)
{
    /* Inisialisasi informasi akun OSS. */
    
    /* Tetapkan Endpoint ke titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan endpoint ke https://oss-cn-hangzhou.aliyuncs.com. */
    std::string Endpoint = "yourEndpoint";
    /* Tetapkan Region ke wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan Region ke cn-hangzhou. */
    std::string Region = "yourRegion";
    /* Tentukan nama bucket. Contoh: examplebucket. */
    std::string BucketName = "examplebucket";
    /* Tentukan path lengkap objek. Path lengkap tidak boleh mengandung nama bucket. Contoh: exampledir/exampleobject.txt. */
    std::string ObjectName = "exampledir/exampleobject.txt";

    /* Inisialisasi sumber daya jaringan. */
    InitializeSdk();

    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;
    /* Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);
  
    InitiateMultipartUploadRequest initUploadRequest(BucketName, ObjectName);
    /* (Opsional) Tetapkan kelas penyimpanan seperti pada contoh berikut. */
    //initUploadRequest.MetaData().addHeader("x-oss-storage-class", "Standard");

    /* Mulai event unggah multi-bagian. */
    auto uploadIdResult = client.InitiateMultipartUpload(initUploadRequest);
    /* Anda dapat membatalkan event unggah multi-bagian atau mencantumkan bagian yang telah diunggah berdasarkan upload ID. */
    /* Untuk membatalkan event unggah multi-bagian berdasarkan upload ID, dapatkan upload ID setelah memanggil InitiateMultipartUpload untuk memulai event tersebut. */
    /* Untuk mencantumkan bagian yang telah diunggah berdasarkan upload ID, dapatkan upload ID setelah memanggil InitiateMultipartUpload tetapi sebelum memanggil CompleteMultipartUpload. */ 
    auto uploadId = uploadIdResult.result().UploadId();
    std::string fileToUpload = "yourLocalFilename";
    /* Ukuran bagian minimum adalah 100 KB dan ukuran maksimum adalah 5 GB. Ukuran bagian terakhir dapat kurang dari 100 KB. */
    int64_t partSize = 100 * 1024;
    PartList partETagList;
    auto fileSize = getFileSize(fileToUpload);
    int partCount = static_cast<int>(fileSize / partSize);
    /* Hitung jumlah bagian. */
    if (fileSize % partSize != 0) {
        partCount++;
    }

    /* Unggah setiap bagian. */
    for (int i = 1; i <= partCount; i++) {
        auto skipBytes = partSize * (i - 1);
        auto size = (partSize < fileSize - skipBytes) ? partSize : (fileSize - skipBytes);
        std::shared_ptr<std::iostream> content = std::make_shared<std::fstream>(fileToUpload, std::ios::in|std::ios::binary);
        content->seekg(skipBytes, std::ios::beg);

        UploadPartRequest uploadPartRequest(BucketName, ObjectName, content);
        uploadPartRequest.setContentLength(size);
        uploadPartRequest.setUploadId(uploadId);
        uploadPartRequest.setPartNumber(i);
        auto uploadPartOutcome = client.UploadPart(uploadPartRequest);
        if (uploadPartOutcome.isSuccess()) {
            Part part(i, uploadPartOutcome.result().ETag());
            partETagList.push_back(part);
        }
        else {
            std::cout << "uploadPart gagal" <<
            ",kode:" << uploadPartOutcome.error().Code() <<
            ",pesan:" << uploadPartOutcome.error().Message() <<
            ",requestId:" << uploadPartOutcome.error().RequestId() << std::endl;
        }

    }

    /* Selesaikan unggah multi-bagian. */
    /* Saat menyelesaikan unggah multi-bagian, Anda harus menyediakan semua partETag yang valid. Setelah OSS menerima partETag tersebut, OSS memverifikasi setiap bagian. Setelah semua bagian diverifikasi, OSS menggabungkannya menjadi satu objek utuh. */
    CompleteMultipartUploadRequest request(BucketName, ObjectName);
    request.setUploadId(uploadId);
    request.setPartList(partETagList);
    /* (Opsional) Tetapkan daftar kontrol akses (ACL) seperti pada contoh berikut. */
    //request.setAcl(CannedAccessControlList::Private);

    auto outcome = client.CompleteMultipartUpload(request);

    if (!outcome.isSuccess()) {
        /* Tangani pengecualian. */
        std::cout << "CompleteMultipartUpload gagal" <<
        ",kode:" << outcome.error().Code() <<
        ",pesan:" << outcome.error().Message() <<
        ",requestId:" << outcome.error().RequestId() << std::endl;
        return -1;
    }

    /* Lepaskan sumber daya jaringan. */
    ShutdownSdk();
    return 0;
}

Saat memanggil operasi CompleteMultipartUpload, Anda harus menyediakan nilai ETag setiap bagian. Nilai ETag tersebut dapat diperoleh dengan salah satu cara berikut:

• Saat mengunggah suatu bagian, respons menyertakan nilai ETag-nya. Anda dapat menyimpan dan menggunakan nilai tersebut. Metode ini digunakan dalam kode contoh di atas.

• Panggil operasi ListParts untuk menanyakan nilai ETag semua bagian yang telah diunggah.

Cantumkan bagian yang diunggah

Panggil operasi ListParts untuk mencantumkan semua bagian yang berhasil diunggah untuk upload ID tertentu.

#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* Inisialisasi informasi akun OSS. */
    
    /* Tetapkan Endpoint ke titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan endpoint ke https://oss-cn-hangzhou.aliyuncs.com. */
    std::string Endpoint = "yourEndpoint";
    /* Tetapkan Region ke wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan Region ke cn-hangzhou. */
    std::string Region = "yourRegion";
    /* Tentukan nama bucket. Contoh: examplebucket. */
    std::string BucketName = "examplebucket";
    /* Tentukan path lengkap objek. Path lengkap tidak boleh mengandung nama bucket. Contoh: exampledir/exampleobject.txt. */
    std::string ObjectName = "exampledir/exampleobject.txt";
    /* Tentukan upload ID. Upload ID diperoleh dari respons operasi InitiateMultipartUpload. Anda harus mendapatkan upload ID sebelum memanggil operasi CompleteMultipartUpload. */
    std::string UploadId = "yourUploadId";

    /* Inisialisasi sumber daya jaringan. */
    InitializeSdk();

    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;
    /* Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);

    /* Cantumkan bagian yang diunggah. Secara default, maksimal 1.000 bagian dicantumkan. */
    ListPartsRequest listuploadrequest(BucketName, ObjectName);
    listuploadrequest.setUploadId(UploadId);

    bool IsTruncated = false;

    do {
        auto listUploadResult = client.ListParts(listuploadrequest);
        if (!listUploadResult.isSuccess()) {
            /* Tangani pengecualian. */
            std::cout << "ListParts gagal" <<
            ",kode:" << listUploadResult.error().Code() <<
            ",pesan:" << listUploadResult.error().Message() <<
            ",requestId:" << listUploadResult.error().RequestId() << std::endl;
            break;
        }
        else {
            for (const auto& part : listUploadResult.result().PartList()) {
                std::cout << "bagian"<<
                ",nomor:" << part.PartNumber() <<
                ",ukuran:" << part.Size() <<
                ",etag:" << part.ETag() <<
                ",waktu modifikasi terakhir:" << part.LastModified() << std::endl;
            }
        }
        listuploadrequest.setPartNumberMarker(listUploadResult.result().NextPartNumberMarker());
        IsTruncated = listUploadResult.result().IsTruncated();
    } while (IsTruncated);

    /* Lepaskan sumber daya jaringan. */
    ShutdownSdk();
    return 0;
}

#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* Inisialisasi informasi akun OSS. */
    
    /* Tetapkan Endpoint ke titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan endpoint ke https://oss-cn-hangzhou.aliyuncs.com. */
    std::string Endpoint = "yourEndpoint";
    /* Tetapkan Region ke wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan Region ke cn-hangzhou. */
    std::string Region = "yourRegion";
    /* Tentukan nama bucket. Contoh: examplebucket. */
    std::string BucketName = "examplebucket";
    /* Tentukan path lengkap objek. Path lengkap tidak boleh mengandung nama bucket. Contoh: exampledir/exampleobject.txt. */
    std::string ObjectName = "exampledir/exampleobject.txt";
    /* Tentukan upload ID. Upload ID diperoleh dari respons operasi InitiateMultipartUpload. Anda harus mendapatkan upload ID sebelum memanggil operasi CompleteMultipartUpload. */
    std::string UploadId = "yourUploadId";

    /* Inisialisasi sumber daya jaringan. */
    InitializeSdk();

    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;
    /* Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);

    /* Cantumkan semua bagian yang diunggah per halaman. */
    /* Tetapkan jumlah maksimum bagian yang dikembalikan per halaman. */
    ListPartsRequest listuploadrequest(BucketName, ObjectName);
    listuploadrequest.setMaxParts(50);
    listuploadrequest.setUploadId(UploadId);
    bool IsTruncated = false;
    do {
        auto listuploadresult = client.ListParts(listuploadrequest);
        if (!listuploadresult.isSuccess()) {
            /* Tangani pengecualian. */
            std::cout << "ListParts gagal" <<
            ",kode:" << listuploadresult.error().Code() <<
            ",pesan:" << listuploadresult.error().Message() <<
            ",requestId:" << listuploadresult.error().RequestId() << std::endl;
            break;
        }
        else {
            for (const auto& part : listuploadresult.result().PartList()) {
                std::cout << "bagian"<<
                ",nomor:" << part.PartNumber() <<
                ",ukuran:" << part.Size() <<
                ",etag:" << part.ETag() <<
                ",waktu modifikasi terakhir:" << part.LastModified() << std::endl;
            }
        }  
        listuploadrequest.setPartNumberMarker(listuploadresult.result().NextPartNumberMarker());
        IsTruncated = listuploadresult.result().IsTruncated();
    } while (IsTruncated);

    /* Lepaskan sumber daya jaringan. */
    ShutdownSdk();
    return 0;
}

Cantumkan event unggah multi-bagian

Panggil operasi ListMultipartUploads untuk mencantumkan semua event unggah multi-bagian yang sedang berlangsung, yaitu event yang telah dimulai tetapi belum diselesaikan atau dibatalkan.

#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* Inisialisasi informasi akun OSS. */
    
    /* Tetapkan Endpoint ke titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan endpoint ke https://oss-cn-hangzhou.aliyuncs.com. */
    std::string Endpoint = "yourEndpoint";
    /* Tetapkan Region ke wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan Region ke cn-hangzhou. */
    std::string Region = "yourRegion";
    /* Tentukan nama bucket. Contoh: examplebucket. */
    std::string BucketName = "examplebucket";    

    /* Inisialisasi sumber daya jaringan. */
    InitializeSdk();

    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;
    /* Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);

    /* Cantumkan event unggah. Secara default, maksimal 1.000 event dicantumkan. */
    ListMultipartUploadsRequest listmultiuploadrequest(BucketName);
	bool IsTruncated = false;
    do {
        auto listresult = client.ListMultipartUploads(listmultiuploadrequest);
        if (!listresult.isSuccess()) {
            /* Tangani pengecualian. */
            std::cout << "ListMultipartUploads gagal" <<
            ",kode:" << listresult.error().Code() <<
            ",pesan:" << listresult.error().Message() <<
            ",requestId:" << listresult.error().RequestId() << std::endl;
            break;
        }
        else {
            for (const auto& part : listresult.result().MultipartUploadList()) {
                std::cout << "bagian"<<
                ",nama:" << part.Key <<
                ",uploadid:" << part.UploadId <<
                ",waktu dimulai:" << part.Initiated << std::endl;
            }
        }
        listmultiuploadrequest.setKeyMarker(listresult.result().NextKeyMarker()); 
        listmultiuploadrequest.setUploadIdMarker(listresult.result().NextUploadIdMarker());
        IsTruncated = listresult.result().IsTruncated();
    } while (IsTruncated);

    /* Lepaskan sumber daya jaringan. */
    ShutdownSdk();
    return 0;
}

#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* Inisialisasi informasi akun OSS. */
    
    /* Tetapkan Endpoint ke titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan endpoint ke https://oss-cn-hangzhou.aliyuncs.com. */
    std::string Endpoint = "yourEndpoint";
    /* Tetapkan Region ke wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan Region ke cn-hangzhou. */
    std::string Region = "yourRegion";
    /* Tentukan nama bucket. Contoh: examplebucket. */
    std::string BucketName = "examplebucket"; 

    /* Inisialisasi sumber daya jaringan. */
    InitializeSdk();

    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;
    /* Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);

    /* Cantumkan semua event unggah per halaman. */
    /* Tetapkan jumlah maksimum event unggah yang dikembalikan per halaman. */
    ListMultipartUploadsRequest  listmultiuploadrequest(BucketName);
    listmultiuploadrequest.setMaxUploads(50);
    bool IsTruncated = false;
    do {
        auto listresult = client.ListMultipartUploads(listmultiuploadrequest);
        if (!listresult.isSuccess()) {
            /* Tangani pengecualian. */
            std::cout << "ListMultipartUploads gagal" <<
            ",kode:" << listresult.error().Code() <<
            ",pesan:" << listresult.error().Message() <<
            ",requestId:" << listresult.error().RequestId() << std::endl;
            break;
        }
        else {
            for (const auto& part : listresult.result().MultipartUploadList()) {
                std::cout << "bagian"<<
                ",nama:" << part.Key <<
                ",uploadid:" << part.UploadId <<
                ",waktu dimulai:" << part.Initiated << std::endl;
            }
        }  
        listmultiuploadrequest.setKeyMarker(listresult.result().NextKeyMarker()); 
        listmultiuploadrequest.setUploadIdMarker(listresult.result().NextUploadIdMarker());
        IsTruncated = listresult.result().IsTruncated();
    } while (IsTruncated);

    /* Lepaskan sumber daya jaringan. */
    ShutdownSdk();
    return 0;
}

Batalkan event unggah multi-bagian

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

#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* Inisialisasi informasi akun OSS. */
    
    /* Tetapkan Endpoint ke titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan endpoint ke https://oss-cn-hangzhou.aliyuncs.com. */
    std::string Endpoint = "yourEndpoint";
    /* Tetapkan Region ke wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan Region ke cn-hangzhou. */
    std::string Region = "yourRegion";
    /* Tentukan nama bucket. Contoh: examplebucket. */
    std::string BucketName = "examplebucket";
    /* Tentukan path lengkap objek. Path lengkap tidak boleh mengandung nama bucket. Contoh: exampledir/exampleobject.txt. */
    std::string ObjectName = "exampledir/exampleobject.txt";
    /* Tentukan upload ID. Upload ID diperoleh dari respons operasi InitiateMultipartUpload. */
    std::string UploadId = "yourUploadId";

    /* Inisialisasi sumber daya jaringan. */
    InitializeSdk();

    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;
    /* Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);
  
    InitiateMultipartUploadRequest initUploadRequest(BucketName, ObjectName);

    /* Mulai event unggah multi-bagian. */
    auto uploadIdResult = client.InitiateMultipartUpload(initUploadRequest);
    auto uploadId = uploadIdResult.result().UploadId();

    /* Batalkan event unggah multi-bagian. */
    AbortMultipartUploadRequest  abortUploadRequest(BucketName, ObjectName, uploadId);
    auto outcome = client.AbortMultipartUpload(abortUploadRequest);

    if (!outcome.isSuccess()) {
        /* Tangani pengecualian. */
        std::cout << "AbortMultipartUpload gagal" <<
        ",kode:" << outcome.error().Code() <<
        ",pesan:" << outcome.error().Message() <<
        ",requestId:" << outcome.error().RequestId() << std::endl;
        return -1;
    }

    /* Lepaskan sumber daya jaringan. */
    ShutdownSdk();
    return 0;
}

Referensi

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

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

  • InitiateMultipartUpload

  • UploadPart

  • CompleteMultipartUpload

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

• Untuk informasi selengkapnya tentang operasi API yang digunakan untuk mencantumkan bagian yang diunggah, lihat ListUploadedParts.

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