Inisialisasi (C++ SDK) - Object Storage Service

Kelas OssClient digunakan untuk mengelola sumber daya Object Storage Service (OSS), seperti bucket dan objek. Sebelum mengirim permintaan OSS menggunakan kit pengembangan perangkat lunak (SDK) C++, Anda harus menginisialisasi instans OssClient dan, jika diperlukan, menyesuaikan pengaturan ClientConfiguration default.

Buat instans OssClient

Penting

Kelas OssClient bersifat thread-safe, sehingga memungkinkan penggunaan instans yang sama oleh beberapa thread. Anda dapat menggunakan kembali instans OssClient yang sama atau membuat beberapa instans sesuai kebutuhan.
InitializeSdk() dan ShutdownSdk() adalah fungsi global yang hanya boleh dipanggil satu kali selama siklus hidup program.

(Direkomendasikan) Tanda tangan V4

Kami menyarankan penggunaan algoritma signature V4 yang lebih aman. Saat menginisialisasi instans dengan signature V4, Anda harus menentukan titik akhir (endpoint) dan ID wilayah Alibaba Cloud untuk permintaan tersebut. Contohnya, ID wilayah dapat berupa cn-hangzhou. Anda juga harus mendeklarasikan SignatureVersionType::V4. SDK C++ versi 1.10.0 dan yang lebih baru mendukung signature V4.

Kode berikut menunjukkan contoh cara membuat instans OssClient menggunakan nama domain OSS dan signature V4. Untuk menggunakan nama domain kustom atau kredensial Security Token Service (STS), sesuaikan contoh tersebut sesuai kebutuhan.

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

int main(void)
{
    /* Inisialisasi informasi akun OSS. */
            
    /* Tetapkan yourEndpoint ke endpoint 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 yourRegion ke wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan wilayah ke cn-hangzhou. */
    std::string Region = "yourRegion";
    
    /* Inisialisasi sumber daya, seperti sumber daya jaringan. */
    InitializeSdk();

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

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

(Tidak direkomendasikan) Signature V1

Penting

Mulai 1 Maret 2025, algoritma signature V1 OSS tidak lagi tersedia untuk pelanggan baru dengan UID baru. Mulai 1 September 2025, OSS tidak lagi memperbarui dan memelihara algoritma signature V1, serta algoritma tersebut tidak lagi tersedia untuk bucket baru. Segera tingkatkan dari signature V1 ke signature V4 untuk mencegah dampak terhadap bisnis Anda.

Buat instans OssClient menggunakan nama domain OSS

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

int main(void)
{
    /* Inisialisasi informasi akun OSS. */
            
    /* Tetapkan yourEndpoint ke endpoint 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";
    
    /* Inisialisasi sumber daya, seperti sumber daya jaringan. */
    InitializeSdk();

    ClientConfiguration conf;
    /* Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah ditetapkan. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);   

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

Buat instans OssClient menggunakan nama domain kustom

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

int main(void)
{
    /* Inisialisasi informasi akun OSS. */
            
    /* Tetapkan yourEndpoint ke nama domain kustom. */
    std::string Endpoint = "yourEndpoint";
    
    /* Inisialisasi sumber daya, seperti sumber daya jaringan. */
    InitializeSdk();

    ClientConfiguration conf;
    conf.isCname = true;
    /* Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah ditetapkan. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);   

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

Buat instans OssClient menggunakan STS

Kredensial akses temporary yang disediakan oleh Security Token Service (STS) terdiri atas pasangan AccessKey temporary (ID AccessKey dan Rahasia AccessKey) serta token keamanan. Untuk informasi selengkapnya tentang cara memperoleh kredensial akses temporary dari STS, lihat Gunakan kredensial temporary yang disediakan oleh STS untuk mengakses OSS.

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

int main(void)
{
    /* Tetapkan yourEndpoint ke endpoint 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";
        
    /* Inisialisasi sumber daya, seperti sumber daya jaringan. */
    InitializeSdk();

    ClientConfiguration conf;
    /* Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode ini, pastikan pasangan AccessKey temporary dan token keamanan telah ditetapkan sebagai variabel lingkungan. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf); 

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

Konfigurasi OssClient

ClientConfiguration adalah kelas yang digunakan untuk mengonfigurasi OssClient. Anda dapat menggunakannya untuk mengatur parameter seperti server proxy, timeout koneksi, dan jumlah maksimum koneksi.

Parameter berikut dapat dikonfigurasi untuk OssClient:

Parameter	Deskripsi
isCname	Menentukan apakah akan menggunakan CNAME sebagai endpoint. Secara default, fitur ini tidak didukung.
userAgent	User agent, yaitu header User-Agent dalam HTTP. Nilai default-nya adalah aliyun-sdk-cpp/1.X.X.
maxConnections	Ukuran kolam koneksi. Nilai default-nya adalah 16.
requestTimeoutMs	Periode timeout permintaan dalam milidetik. Jika tidak ada data yang diterima dalam periode timeout tersebut, koneksi akan ditutup. Nilai default-nya adalah 10.000 ms.
connectTimeoutMs	Periode timeout untuk membuat koneksi. Nilai default-nya adalah 5.000 ms.
retryStrategy	Kebijakan retry kustom untuk permintaan yang gagal.
proxyScheme	Protokol proxy. Nilai default-nya adalah HTTP.
proxyPort	Port server proxy.
proxyPassword	Password untuk autentikasi server proxy.
proxyUserName	Username untuk autentikasi server proxy.
verifySSL	Menentukan apakah verifikasi sertifikat SSL diaktifkan. Secara default, fitur ini dinonaktifkan. Catatan Secara default, verifikasi sertifikat SSL diaktifkan pada C++ SDK versi 1.8.2 dan yang lebih baru.
caPath	Jalur root sertifikat CA. Parameter ini hanya berlaku ketika verifySSL diatur ke true. Secara default, parameter ini kosong.
caFile	Jalur sertifikat CA. Parameter ini hanya berlaku ketika verifySSL diatur ke true. Secara default, parameter ini kosong.
enableCrc64	Menentukan apakah verifikasi Pemeriksaan redundansi siklik 64-bit (CRC64) diaktifkan. Secara default, fitur ini diaktifkan.
enableDateSkewAdjustment	Menentukan apakah koreksi otomatis untuk time skew permintaan HTTP diaktifkan. Secara default, fitur ini diaktifkan.
sendRateLimiter	Batas laju unggah dalam KB/s.
recvRateLimiter	Batas laju unduh dalam KB/s.

Tetapkan periode timeout

Kode berikut menunjukkan contoh cara menetapkan periode timeout:

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

int main(void)
{
    /* Inisialisasi informasi akun OSS. */
            
    /* Tetapkan yourEndpoint ke endpoint 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 yourRegion ke wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan wilayah ke cn-hangzhou. */
    std::string Region = "yourRegion";
    
    /* Inisialisasi sumber daya, seperti sumber daya jaringan. */
    InitializeSdk();
    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;

    /* Tetapkan ukuran kolam koneksi. Nilai default-nya adalah 16. */
    conf.maxConnections = 20;

    /* Tetapkan periode timeout permintaan. Jika tidak ada data yang diterima dalam periode ini, koneksi akan ditutup. Nilai default-nya adalah 10.000 ms. */
    conf.requestTimeoutMs = 8000;

    /* Tetapkan periode timeout untuk membuat koneksi. Nilai default-nya adalah 5.000 ms. */
    conf.connectTimeoutMs = 8000;

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

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

Tetapkan verifikasi sertifikat SSL

C++ SDK versi 1.8.2 dan yang lebih baru mengaktifkan verifikasi sertifikat SSL secara default. Jika verifikasi sertifikat SSL gagal, Anda dapat menetapkan jalur sertifikat yang benar atau menonaktifkan verifikasi sertifikat SSL.

Kode berikut menunjukkan cara menetapkan verifikasi sertifikat SSL:

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

int main(void)
{
    /* Inisialisasi informasi akun OSS. */
            
    /* Tetapkan yourEndpoint ke endpoint 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 yourRegion ke wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan wilayah ke cn-hangzhou. */
    std::string Region = "yourRegion";
    
    /* Inisialisasi sumber daya, seperti sumber daya jaringan. */
    InitializeSdk();
    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;

    /* Tetapkan sakelar untuk verifikasi sertifikat SSL. Nilai default-nya adalah true, yang mengaktifkan verifikasi. */
    conf.verifySSL = true;

    /* Tetapkan jalur root sertifikat CA. Parameter ini hanya berlaku ketika verifySSL diatur ke true. Secara default, parameter ini kosong. */
    conf.caPath = "/etc/ssl/certs/";

    /* Tetapkan jalur sertifikat CA. Parameter ini hanya berlaku ketika verifySSL diatur ke true. Secara default, parameter ini kosong. */
    conf.caFile = "/etc/ssl/certs/ca-certificates.crt";;

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

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

Tetapkan batas laju

Kode berikut menunjukkan cara menetapkan batas laju untuk unggah atau unduh:

#include <alibabacloud/oss/OssClient.h>
#include <alibabacloud/oss/client/RateLimiter.h>

using namespace AlibabaCloud::OSS;

class UserRateLimiter : public RateLimiter
{
public:
    UserRateLimiter() : rate_(0) {};
    ~UserRateLimiter() {};
    virtual void setRate(int rate) { rate_ = rate; };
    virtual int Rate() const { return rate_; };
private:
    int rate_;
};

int main(void)
{
    /* Inisialisasi informasi akun OSS. */
            
    /* Tetapkan yourEndpoint ke endpoint 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 yourRegion ke wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan wilayah ke cn-hangzhou. */
    std::string Region = "yourRegion";
    /* Masukkan nama bucket. Contoh: examplebucket. */
    std::string BucketName = "examplebucket";
    /* Masukkan jalur lengkap objek. Jalur tidak boleh mencakup nama bucket. Contoh: exampledir/exampleobject.txt. */
    std::string ObjectName = "exampledir/exampleobject.txt";

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

    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;

    auto sendrateLimiter = std::make_shared<UserRateLimiter>();
    auto recvrateLimiter = std::make_shared<UserRateLimiter>();
    conf.sendRateLimiter = sendrateLimiter;
    conf.recvRateLimiter = recvrateLimiter;

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

    /* Tetapkan batas laju unduh dalam KB/s. */
    recvrateLimiter->setRate(256);

    /* Tetapkan batas laju unggah dalam KB/s. */
    sendrateLimiter->setRate(256);

    /* Unggah file. Tetapkan yourLocalFilename ke jalur lengkap file lokal. */
    auto outcome = client.PutObject(BucketName, ObjectName, "yourLocalFilename");  

    /* Perbarui batas laju unggah dalam KB/s selama proses unggah. */
    sendrateLimiter->setRate(300);

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

Tetapkan kebijakan retry

Kode berikut menetapkan kebijakan retry:

#include <alibabacloud/oss/OssClient.h>
#include <alibabacloud/oss/client/RetryStrategy.h>

using namespace AlibabaCloud::OSS;

class UserRetryStrategy : public RetryStrategy
{
public:

    /* maxRetries menentukan jumlah maksimum retry. scaleFactor adalah faktor penskalaan interval retry. */
    UserRetryStrategy(long maxRetries = 3, long scaleFactor = 300) :
        m_scaleFactor(scaleFactor), m_maxRetries(maxRetries)  
    {}

    /* Anda dapat menyesuaikan fungsi shouldRetry untuk menentukan apakah permintaan perlu diulang. */
    bool shouldRetry(const Error & error, long attemptedRetries) const;

    /* Anda dapat menyesuaikan fungsi calcDelayTimeMs untuk menghitung penundaan sebelum retry. */
    long calcDelayTimeMs(const Error & error, long attemptedRetries) const;

private:
    long m_scaleFactor;
    long m_maxRetries;
};

bool UserRetryStrategy::shouldRetry(const Error & error, long attemptedRetries) const
{    
    if (attemptedRetries >= m_maxRetries)
        return false;

    long responseCode = error.Status();

    //kode http
    if ((responseCode == 403 && error.Message().find("RequestTimeTooSkewed") != std::string::npos) ||
        (responseCode > 499 && responseCode < 599)) {
        return true;
    }
    else {
        switch (responseCode)
        {
        //kode error curl
        case (ERROR_CURL_BASE + 7):  //CURLE_COULDNT_CONNECT
        case (ERROR_CURL_BASE + 18): //CURLE_PARTIAL_FILE
        case (ERROR_CURL_BASE + 23): //CURLE_WRITE_ERROR
        case (ERROR_CURL_BASE + 28): //CURLE_OPERATION_TIMEDOUT
        case (ERROR_CURL_BASE + 52): //CURLE_GOT_NOTHING
        case (ERROR_CURL_BASE + 55): //CURLE_SEND_ERROR
        case (ERROR_CURL_BASE + 56): //CURLE_RECV_ERROR
        case (ERROR_CURL_BASE + 65): //CURLE_SEND_FAIL_REWIND
            return true;
        default:
            break;
        };
    }

    return false;
}

long UserRetryStrategy::calcDelayTimeMs(const Error & error, long attemptedRetries) const
{
    return (1 << attemptedRetries) * m_scaleFactor;
}

int main(void)
{
    /* Inisialisasi informasi akun OSS. */
            
   /* Tetapkan yourEndpoint ke endpoint 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 yourRegion ke wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan wilayah ke cn-hangzhou. */
    std::string Region = "yourRegion";
    
    /* Inisialisasi sumber daya, seperti sumber daya jaringan. */
    InitializeSdk();
    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;

    /* Tetapkan jumlah retry untuk permintaan yang gagal. Nilai default-nya adalah 3. */
    auto defaultRetryStrategy = std::make_shared<UserRetryStrategy>(5);
    conf.retryStrategy = defaultRetryStrategy;

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

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

Tetapkan server proxy

Gunakan kode berikut untuk menetapkan server proxy:

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

int main(void)
{
    /* Inisialisasi informasi akun OSS. */
            
    /* Tetapkan yourEndpoint ke endpoint 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 yourRegion ke wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), tetapkan wilayah ke cn-hangzhou. */
    std::string Region = "yourRegion";
    
    /* Inisialisasi sumber daya, seperti sumber daya jaringan. */
    InitializeSdk();
    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;

    /* Tetapkan alamat server proxy. */
    conf.proxyHost = "yourProxyHost";

    /* Tetapkan port server proxy. */
    conf.proxyPort = 1234;

    /* Opsional. Tetapkan username untuk autentikasi server proxy. */
    conf.proxyUserName = "yourProxyUserName";

    /* Opsional. Tetapkan password untuk autentikasi server proxy. */
    conf.proxyPassword = "yourProxyPassword";

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

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