Object Storage Service:OSS C++ SDK V2

vcpkg

Use the vcpkg package manager to install the SDK:

vcpkg install alibabacloud-oss-cpp-sdk-v2[curl]

# On Windows, you can use WinHTTP as the HTTP transport layer instead.
vcpkg install alibabacloud-oss-cpp-sdk-v2[winhttp]

You can also install from source code by using an overlay port:

git clone https://github.com/aliyun/alibabacloud-oss-cpp-sdk-v2.git
vcpkg install alibabacloud-oss-cpp-sdk-v2[curl] --overlay-ports=alibabacloud-oss-cpp-sdk-v2/vcpkg --head

Optional features:

Complete definitions: vcpkg/vcpkg.json.

Source code

Download the latest version of the OSS C++ SDK V2 from GitHub, then build and install it with CMake:

git clone https://github.com/aliyun/alibabacloud-oss-cpp-sdk-v2.git
cd alibabacloud-oss-cpp-sdk-v2
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local
cmake --build . --target install

Available CMake options:

Linux

1. In the command-line interface, run the following commands to add the environment variables to your ~/.bashrc file.

   echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
   echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

   1. Run the following command to apply the changes.

      source ~/.bashrc

   2. Run the following commands to verify that the environment variables are set.

      echo $OSS_ACCESS_KEY_ID
      echo $OSS_ACCESS_KEY_SECRET

macOS

1. In the terminal, run the following command to check your default shell.

   echo $SHELL

   1. The following steps depend on your default shell.

      Zsh

      1. Run the following commands to add the environment variables to your ~/.zshrc file.

         echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
         echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

      2. Run the following command to apply the changes.

         source ~/.zshrc

      3. Run the following commands to verify that the environment variables are set.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

      Bash

      1. Run the following commands to add the environment variables to your ~/.bash_profile file.

         echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
         echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

      2. Run the following command to apply the changes.

         source ~/.bash_profile

      3. Run the following commands to verify that the environment variables are set.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

Windows

OSSClient (synchronous)

Use the OSSClient synchronous mode when you need to wait for an operation to complete before proceeding.

Before you run the sample code, replace <region-id> with an actual region and endpoint, such as ap-southeast-1.

#include <iostream>
#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"

namespace oss = alibabacloud::oss2;

int main() {
    auto conf = oss::ClientConfiguration::loadDefault();
    conf.region = "<region-id>";
    conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();

    oss::OSSClient client(conf);

    auto outcome = client.listBuckets(
        oss::models::ListBucketsRequest());

    if (!outcome.has_value()) {
        auto& err = outcome.error();
        std::cerr << "Error Code: " << err.getCode() << std::endl;
        std::cerr << "Error Message: " << err.getMessage() << std::endl;
        std::cerr << "Request ID: " << err.getRequestId() << std::endl;
        return 1;
    }

    auto& result = outcome.value();
    for (auto& bucket : result.getBuckets()) {
        std::cout << "bucket: name:" << bucket.name
                  << ", region:" << bucket.region
                  << ", storageClass:" << bucket.storageClass
                  << std::endl;
    }

    return 0;
}

OSSClient (asynchronous)

This thread-pool-based asynchronous mode still uses OSSClient. After setting conf.executor (a thread pool), you call asyncCall() to dispatch a synchronous request to the thread pool for concurrent execution. The call returns a std::future, and the caller waits for the result with get().

If conf.executor is not set, asyncCall() returns a NoExecutor error.

#include <future>
#include <iostream>
#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"
#include "alibabacloud/oss2/utils/DefaultExecutor.h"

namespace oss = alibabacloud::oss2;

int main() {
    auto conf = oss::ClientConfiguration::loadDefault();
    conf.region = "<region-id>";
    conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
    // Key: Configure a thread pool to enable asyncCall() support for OSSClient.
    conf.executor = std::make_shared<oss::DefaultExecutor>();

    oss::OSSClient client(conf);

    // Asynchronous call that returns a std::future.
    auto future = client.asyncCall(oss::models::ListBucketsRequest());

    // Wait for the result by using get() (future pattern).
    auto outcome = future.get();
    if (!outcome.has_value()) {
        auto& err = outcome.error();
        std::cerr << "Error Code: " << err.getCode() << std::endl;
        std::cerr << "Error Message: " << err.getMessage() << std::endl;
        return 1;
    }

    auto& result = outcome.value();
    for (auto& bucket : result.getBuckets()) {
        std::cout << "bucket: name:" << bucket.name
                  << ", region:" << bucket.region << std::endl;
    }
    return 0;
}

Concurrent upload and download examples: AsyncCallOnSyncClient.cpp and AsyncCallbackOnSyncClient.cpp.

OSSAsyncClient (asynchronous)

This native asynchronous mode uses OSSAsyncClient. Each operation has a corresponding operationNameAsync() method that receives the result through a callback, eliminating the need to configure a thread pool. This mode is ideal for scenarios that require a high volume of concurrent operations.

Before you run the sample code, replace <region-id> with an actual region and endpoint, such as ap-southeast-1.

#include <iostream>
#include <thread>
#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSAsyncClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"

namespace oss = alibabacloud::oss2;

int main() {
    auto conf = oss::ClientConfiguration::loadDefault();
    conf.region = "<region-id>";
    conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();

    auto client = std::make_shared<oss::OSSAsyncClient>(conf);

    client->listBucketsAsync(
        oss::models::ListBucketsRequest(),
        oss::ListBucketsAsyncCallback([](oss::ListBucketsOutcome outcome) {
            if (!outcome.has_value()) {
                auto& err = outcome.error();
                std::cerr << "Error Code: " << err.getCode() << std::endl;
                std::cerr << "Error Message: " << err.getMessage() << std::endl;
                return;
            }

            auto& result = outcome.value();
            for (auto& bucket : result.getBuckets()) {
                std::cout << "bucket: name:" << bucket.name
                          << ", region:" << bucket.region
                          << ", storageClass:" << bucket.storageClass
                          << std::endl;
            }
        }));

    // Wait for the asynchronous operation to complete.
    std::this_thread::sleep_for(std::chrono::seconds(5));

    return 0;
}

Environment variables (Recommended)

Obtain credentials from the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.

1. Set the environment variables by using the access key of a RAM user.

   Linux

   1. From the command line, run the following commands to append the environment variable settings to the ~/.bashrc file.

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
      echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

   2. Run the following command to apply the changes.

      source ~/.bashrc

   3. Run the following commands to verify that the environment variables are set.

      echo $OSS_ACCESS_KEY_ID
      echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. In the terminal, run the following command to check your default shell type.

      echo $SHELL

   2. Follow the steps based on your default shell type.

      Zsh

      1. Run the following commands to append the environment variable settings to the ~/.zshrc file.

         echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
         echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

      2. Run the following command to apply the changes.

         source ~/.zshrc

      3. Run the following commands to verify that the environment variables are set.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

      Bash

      1. Run the following commands to append the environment variable settings to the ~/.bash_profile file.

         echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
         echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

      2. Run the following command to apply the changes.

         source ~/.bash_profile

      3. Run the following commands to verify that the environment variables are set.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   Windows

   CMD

   1. In CMD, run the following commands.

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

   2. Reopen CMD and run the following commands to verify that the environment variables are set.

      echo %OSS_ACCESS_KEY_ID%
      echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   1. In PowerShell, run the following commands.

      [System.Environment]::SetEnvironmentVariable('OSS_ACCESS_KEY_ID', 'YOUR_ACCESS_KEY_ID', [System.EnvironmentVariableTarget]::User)
      [System.Environment]::SetEnvironmentVariable('OSS_ACCESS_KEY_SECRET', 'YOUR_ACCESS_KEY_SECRET', [System.EnvironmentVariableTarget]::User)

   2. Reopen PowerShell and run the following commands to verify that the environment variables are set.

      [System.Environment]::GetEnvironmentVariable('OSS_ACCESS_KEY_ID', [System.EnvironmentVariableTarget]::User)
      [System.Environment]::GetEnvironmentVariable('OSS_ACCESS_KEY_SECRET', [System.EnvironmentVariableTarget]::User)

2. After modifying system environment variables, restart your IDE and terminal for changes to take effect.

3. Use the environment variables to pass the credentials.

   Before you run the sample code, replace <region-id> with an actual region ID, such as cn-hangzhou.

   #include "alibabacloud/oss2/ClientConfiguration.h"
   #include "alibabacloud/oss2/OSSClient.h"
   #include "alibabacloud/oss2/credentials/CredentialsProvider.h"
   
   namespace oss = alibabacloud::oss2;
   
   int main() {
       auto conf = oss::ClientConfiguration::loadDefault();
       conf.region = "<region-id>";
       conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
   
       oss::OSSClient client(conf);
       // Use the client to perform operations.
       return 0;
   }

Explicitly in code

You can explicitly provide the access key ID and access key secret by using StaticCredentialsProvider.

#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"

namespace oss = alibabacloud::oss2;

int main() {
    auto conf = oss::ClientConfiguration::loadDefault();
    conf.region = "<region-id>";
    conf.credentialsProvider = std::make_shared<oss::StaticCredentialsProvider>(
        "YOUR_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_SECRET");

    oss::OSSClient client(conf);
    // Use the client to perform operations.
    return 0;
}

Environment variables (Recommended)

Obtain temporary credentials by using the OSS_ACCESS_KEY_ID, OSS_ACCESS_KEY_SECRET, and OSS_SESSION_TOKEN environment variables.

1. Set the environment variables by using the temporary credentials.

   macOS, Linux, or Unix

   export OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
   export OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
   export OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>

   Windows

   set OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
   set OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
   set OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>

2. Use the environment variables to pass the credentials. The SDK's EnvironmentVariableCredentialsProvider automatically reads these three environment variables.

   Before you run the sample code, replace <region-id> with an actual region ID, such as cn-hangzhou.

   #include "alibabacloud/oss2/ClientConfiguration.h"
   #include "alibabacloud/oss2/OSSClient.h"
   #include "alibabacloud/oss2/credentials/CredentialsProvider.h"
   
   namespace oss = alibabacloud::oss2;
   
   int main() {
       auto conf = oss::ClientConfiguration::loadDefault();
       conf.region = "<region-id>";
       // Automatically reads OSS_ACCESS_KEY_ID, OSS_ACCESS_KEY_SECRET, and OSS_SESSION_TOKEN.
       conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
   
       oss::OSSClient client(conf);
       // Use the client to perform operations.
       return 0;
   }

Explicitly in code

You can explicitly provide the temporary access key ID, access key secret, and security token by using StaticCredentialsProvider.

#include "alibabacloud/oss2/ClientConfiguration.h"
#include "alibabacloud/oss2/OSSClient.h"
#include "alibabacloud/oss2/credentials/CredentialsProvider.h"

namespace oss = alibabacloud::oss2;

int main() {
    auto conf = oss::ClientConfiguration::loadDefault();
    conf.region = "<region-id>";
    conf.credentialsProvider = std::make_shared<oss::StaticCredentialsProvider>(
        "STS_ACCESS_KEY_ID", "STS_ACCESS_KEY_SECRET", "STS_SECURITY_TOKEN");

    oss::OSSClient client(conf);
    // Use the client to perform operations.
    return 0;
}

Cancel immediately

Call CancellationTokenSource::cancel() from another thread to interrupt an in-progress request.

// Cancel the request from another thread.
auto cts = oss::CancellationTokenSource::create();

oss::OperationOptions opts;
opts.cancellationToken = cts->getToken();

// Start the request in another thread.
auto future = std::async([&]() {
    return client.getObject(request, &opts);
});

// Cancel from the current thread.
cts->cancel();

Cancel by deadline

Call cancelAfter() to set a timeout. The SDK automatically cancels the request when the timeout expires.

// Set a 30-second timeout for automatic cancellation.
auto cts = oss::CancellationTokenSource::create();
cts->cancelAfter(std::chrono::seconds(30));

oss::OperationOptions opts;
opts.cancellationToken = cts->getToken();

auto outcome = client.getObject(request, &opts);