Object Storage Service:OSS C++ SDK V2

Pré-requisitos

• Um compilador compatível com C++17 ou superior (GCC 7+, Clang 5+ ou MSVC 2017+).

• CMake 3.15 ou superior.

Execute o comando cmake --version para verifique sua versão do CMake. Caso o CMake não esteja instalado ou a versão seja anterior à 3.15, baixe e instale o CMake .

Instale o SDK

Recomendamos o uso do vcpkg como método de instalação.

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]

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

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

Adicione a dependência ao arquivo CMakeLists.txt do seu projeto:

cmake_minimum_required(VERSION 3.15)
project(my-app)

find_package(alibabacloud_oss_v2 REQUIRED)

add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE alibabacloud_oss_v2::oss)

Configure credenciais de acesso

Defina variáveis de ambiente com o par de AccessKey do seu usuário RAM.

No RAM console , crie um usuário RAM e gere uma AccessKey permanente . Salve a AccessKey e, em seguida, conceda a permissão AliyunOSSFullAccess ao usuário.

Inicializar o client

O sdk oferece suporte a três modos de requisição: OSSClient (síncrono), OSSClient (assíncrono) (baseado em pool de threads) e OSSAsyncClient (assíncrono) (async nativo). Os exemplos a seguir usam ListBuckets para demonstrar cada modo.

#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;
}

#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;
}

#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;
}

Usar um domínio personalizado

Um custom domain permite visualização de arquivos via navegador e entrega acelerada por cdn.

Antes de execute o código de exemplo, substitua <region-id> por um id de região real da lista region and endpoint , como 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.endpoint = "https://your-custom-domain.com";
    conf.useCName = true;
    conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();

    oss::OSSClient client(conf);

    // Perform operations using the custom domain.
    auto outcome = client.putObject(
        oss::models::PutObjectRequest()
            .setBucket("your-bucket")
            .setKey("your-key")
            .setBody(oss::RequestBody::fromString("Hello, OSS!")));

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

    std::cout << "Upload successful" << std::endl;
    return 0;
}

Controle de timeout

Use connectTimeout e readWriteTimeout para configure os tempos limite de conexão e leitura/gravação em milissegundos.

auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
// Set the connection timeout to 10 seconds.
conf.connectTimeout = 10000;
// Set the read/write timeout to 30 seconds.
conf.readWriteTimeout = 30000;

oss::OSSClient client(conf);

Política de nova tentativa

O StandardRetryer integrado usa uma estratégia FullJitterBackoff com no máximo 3 tentativas por padrão. Use retryMaxAttempts para ajustar esse valor.

auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
// Set the maximum number of retries to 5.
conf.retryMaxAttempts = 5;

oss::OSSClient client(conf);

Exemplo de estratégia de nova tentativa personalizada: CustomRetryStrategy.cpp.

Protocolo http/HTTPS

O protocolo HTTPS é usado por padrão. Para usar o protocolo http, defina disableSsl como true.

auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
// Use the HTTP protocol.
conf.disableSsl = true;

oss::OSSClient client(conf);

Usar um endpoint interno

Ao implantar no ECS, use um endpoint interno para evitar custos de tráfego de rede pública.

auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
// Use an internal endpoint.
conf.useInternalEndpoint = true;

oss::OSSClient client(conf);

Usar um endpoint de aceleração de transferência

Use um endpoint de aceleração de transferência para transferências de dados de longa distância.

auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
// Use a transfer acceleration endpoint.
conf.useAccelerateEndpoint = true;

oss::OSSClient client(conf);

Usar um domínio personalizado (CNAME)

Acesse o OSS usando um domínio personalizado (CNAME).

auto conf = oss::ClientConfiguration::loadDefault();
conf.region = "<region-id>";
conf.credentialsProvider = std::make_shared<oss::EnvironmentVariableCredentialsProvider>();
conf.endpoint = "https://your-custom-domain.com";
conf.useCName = true;

oss::OSSClient client(conf);

Personalizar o transporte http

O sdk usa curl por padrão. Substitua-o via httpTransport. O WinHTTP também é suportado no Windows.

Exemplos de transporte personalizado: CurlCustomConfig.cpp e WinHttpCustomConfig.cpp.

Access key de usuário RAM

Use a access key de um usuário RAM para aplicações em ambientes seguros e não expostos à internet.

#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;
}

Credencial temporária STS

Credenciais temporárias STS consistem em um id de access key, segredo da access key e token de segurança. Gerencie e atualize o token manualmente.

#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;
}

RAMRoleARN, ECSRAMRole ou OIDCRoleARN

Para métodos de credencial como RAMRoleARN, ECSRAMRole e OIDCRoleARN, recomendamos o uso da biblioteca alibabacloud-credentials-cpp com CredentialsProviderFunc.

1. Instale a dependência.

   vcpkg install alibabacloud-credentials-cpp

2. Adicione a dependência no seu arquivo CMakeLists.txt.

   find_package(alibabacloud_credentials REQUIRED)

3. Integre a biblioteca usando CredentialsProviderFunc.

   RAMRoleARN

   #include "alibabacloud/oss2/ClientConfiguration.h"
   #include "alibabacloud/oss2/OSSClient.h"
   #include "alibabacloud/oss2/credentials/CredentialsProvider.h"
   #include <darabonba/core/Client.hpp>
   #include <alibabacloud/credential.hpp>
   
   namespace oss = alibabacloud::oss2;
   
   int main() {
       auto credConfig = std::make_shared<Alibabacloud_Credential::Config>();
       // The credential type must be ram_role_arn.
       credConfig->type = std::make_shared<std::string>("ram_role_arn");
       // The access key ID of the RAM user. To avoid hardcoding, we recommend injecting this value through the ALIBABA_CLOUD_ACCESS_KEY_ID environment variable.
       credConfig->accessKeyId = std::make_shared<std::string>("YOUR_ACCESS_KEY_ID");
       // The access key secret of the RAM user. To avoid hardcoding, we recommend injecting this value through the ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variable.
       credConfig->accessKeySecret = std::make_shared<std::string>("YOUR_ACCESS_KEY_SECRET");
       // The ARN of the RAM role to assume. Example: acs:ram::123456789012****:role/adminrole
       // You can also set this value by using the ALIBABA_CLOUD_ROLE_ARN environment variable.
       credConfig->roleArn = std::make_shared<std::string>("YOUR_ROLE_ARN");
       // The role session name, used for auditing purposes. You can also set this value by using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
       credConfig->roleSessionName = std::make_shared<std::string>("your-session-name");
       // (Optional) Further restrict permissions with a policy. This parameter is not required.
       // Example: {"Statement":[{"Action":["oss:GetObject"],"Effect":"Allow","Resource":["*"]}],"Version":"1"}
       // credConfig->policy = std::make_shared<std::string>("<Policy>");
       // (Optional) The role session duration in seconds. Default: 3600 (1 hour). This parameter is not required.
       // credConfig->roleSessionExpiration = std::make_shared<long>(3600);
   
       auto credClient = std::make_shared<Alibabacloud_Credential::Client>(credConfig);
   
       auto conf = oss::ClientConfiguration::loadDefault();
       conf.region = "<region-id>";
       conf.credentialsProvider = std::make_shared<oss::CredentialsProviderFunc>(
           [credClient]() -> oss::Credentials {
               auto cred = credClient->getCredential();
               auto ak = cred.getAccessKeyId();
               auto sk = cred.getAccessKeySecret();
               if (ak.empty() || sk.empty()) {
                   return oss::Credentials::withRetryableError(
                       "failed to get credentials from alibabacloud-credentials-cpp");
               }
               auto token = cred.getSecurityToken();
               return oss::Credentials(std::move(ak), std::move(sk), std::move(token));
           });
   
       oss::OSSClient client(conf);
       // Use the client to perform operations.
       return 0;
   }

   ECSRAMRole

   #include "alibabacloud/oss2/ClientConfiguration.h"
   #include "alibabacloud/oss2/OSSClient.h"
   #include "alibabacloud/oss2/credentials/CredentialsProvider.h"
   #include <darabonba/core/Client.hpp>
   #include <alibabacloud/credential.hpp>
   
   namespace oss = alibabacloud::oss2;
   
   int main() {
       auto credConfig = std::make_shared<Alibabacloud_Credential::Config>();
       // The credential type must be ecs_ram_role.
       credConfig->type = std::make_shared<std::string>("ecs_ram_role");
       // The name of the RAM role granted to the ECS instance. This parameter is optional.
       // If you do not set it, the SDK automatically retrieves it from the metadata service.
       // We strongly recommend setting this parameter explicitly to reduce requests to the metadata service.
       credConfig->roleName = std::make_shared<std::string>("YOUR_ECS_ROLE_NAME");
   
       auto credClient = std::make_shared<Alibabacloud_Credential::Client>(credConfig);
   
       auto conf = oss::ClientConfiguration::loadDefault();
       conf.region = "<region-id>";
       conf.credentialsProvider = std::make_shared<oss::CredentialsProviderFunc>(
           [credClient]() -> oss::Credentials {
               auto cred = credClient->getCredential();
               auto ak = cred.getAccessKeyId();
               auto sk = cred.getAccessKeySecret();
               if (ak.empty() || sk.empty()) {
                   return oss::Credentials::withRetryableError(
                       "failed to get credentials from alibabacloud-credentials-cpp");
               }
               auto token = cred.getSecurityToken();
               return oss::Credentials(std::move(ak), std::move(sk), std::move(token));
           });
   
       oss::OSSClient client(conf);
       // Use the client to perform operations.
       return 0;
   }

   OIDCRoleARN

   #include "alibabacloud/oss2/ClientConfiguration.h"
   #include "alibabacloud/oss2/OSSClient.h"
   #include "alibabacloud/oss2/credentials/CredentialsProvider.h"
   #include <darabonba/core/Client.hpp>
   #include <alibabacloud/credential.hpp>
   
   namespace oss = alibabacloud::oss2;
   
   int main() {
       auto credConfig = std::make_shared<Alibabacloud_Credential::Config>();
       // The credential type must be oidc_role_arn.
       credConfig->type = std::make_shared<std::string>("oidc_role_arn");
       // The ARN of the RAM role to assume. You can also set this value by using the ALIBABA_CLOUD_ROLE_ARN environment variable.
       credConfig->roleArn = std::make_shared<std::string>("YOUR_ROLE_ARN");
       // The ARN of the OIDC identity provider. You can also set this value by using the ALIBABA_CLOUD_OIDC_PROVIDER_ARN environment variable.
       credConfig->oidcProviderArn = std::make_shared<std::string>("YOUR_OIDC_PROVIDER_ARN");
       // The path to the OIDC token file, which is automatically mounted into the pod by RRSA. You can also set this value by using the ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variable.
       credConfig->oidcTokenFilePath = std::make_shared<std::string>("/var/run/secrets/tokens/oidc-token");
       // The role session name, used for auditing purposes. You can also set this value by using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
       credConfig->roleSessionName = std::make_shared<std::string>("your-session-name");
       // (Optional) Further restrict permissions with a policy. This parameter is not required.
       // credConfig->policy = std::make_shared<std::string>("<Policy>");
   
       auto credClient = std::make_shared<Alibabacloud_Credential::Client>(credConfig);
   
       auto conf = oss::ClientConfiguration::loadDefault();
       conf.region = "<region-id>";
       conf.credentialsProvider = std::make_shared<oss::CredentialsProviderFunc>(
           [credClient]() -> oss::Credentials {
               auto cred = credClient->getCredential();
               auto ak = cred.getAccessKeyId();
               auto sk = cred.getAccessKeySecret();
               if (ak.empty() || sk.empty()) {
                   return oss::Credentials::withRetryableError(
                       "failed to get credentials from alibabacloud-credentials-cpp");
               }
               auto token = cred.getSecurityToken();
               return oss::Credentials(std::move(ak), std::move(sk), std::move(token));
           });
   
       oss::OSSClient client(conf);
       // Use the client to perform operations.
       return 0;
   }

   Mais exemplos de credenciais: exemplos de credenciais.

Acesso anônimo

Acesse buckets e objetos com leitura pública sem necessidade de credenciais.

#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::AnonymousCredentialsProvider>();

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

Provedor de credenciais personalizado

Implemente lógica personalizada de obtenção de credenciais com CredentialsProviderFunc.

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

#include <cstdlib>

namespace oss = alibabacloud::oss2;

// Example: Load credentials from custom environment variables or a configuration file.
static oss::Credentials loadCredentialsFromCustomSource() {
    // In a real-world application, you can retrieve credentials from various sources:
    //   - A configuration file (such as ~/.ossrc)
    //   - A key management service (such as HashiCorp Vault or KMS)
    //   - A metadata service
    //   - A database
    const char* ak = std::getenv("MY_APP_ACCESS_KEY_ID");
    const char* sk = std::getenv("MY_APP_ACCESS_KEY_SECRET");
    const char* token = std::getenv("MY_APP_SESSION_TOKEN");

    if (!ak || !sk) {
        // The error message propagates to OperationError::getMessage().
        return oss::Credentials::withError(
            "MY_APP_ACCESS_KEY_ID and MY_APP_ACCESS_KEY_SECRET must be set");
        // For transient failures, such as network timeouts, use withRetryableError.
        // The SDK automatically retries credential retrieval.
        // return oss::Credentials::withRetryableError("...");
    }

    return oss::Credentials(ak, sk, token ? token : "");
}

int main() {
    // The custom credential provider function is called every time credentials are required,
    // allowing you to implement rotation, refresh, or caching logic.
    auto provider = std::make_shared<oss::CredentialsProviderFunc>(
        loadCredentialsFromCustomSource);

    auto conf = oss::ClientConfiguration::loadDefault();
    conf.region = "<region-id>";
    conf.credentialsProvider = provider;

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

Convenção de nomenclatura de API

Os nomes dos métodos usam o estilo camelCase. Cada operação recebe um parâmetro <OperationName>Request e retorna um <OperationName>Outcome (Outcome<Result, Error>).

OSSClient (síncrono):

OutcomeType operationName(const models::OperationNameRequest& request, const OperationOptions* options = nullptr)

OSSAsyncClient (assíncrono nativo):

void operationNameAsync(const models::OperationNameRequest& request, const OperationNameAsyncCallback& callback, const OperationOptions* options = nullptr)

Modos de chamada

Cancele uma requisição

Para cancele operações longas com um CancellationToken, passe um cancellationToken em OperationOptions. O OSS C++ SDK V2 oferece dois modos de cancelamento:

// 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();

// 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);

Tratamento de erros

O OSS C++ SDK V2 usa Outcome<Result, Error>, compatível com std::expected. Chame has_value() para verifique o sucesso. Em caso de sucesso, recupere o resultado com value() ou desreferenciando o objeto outcome (*outcome). Caso contrário, obtenha o objeto de erro com error().

auto outcome = client.putObject(request);

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 << "EC: " << err.getEC() << std::endl;
    std::cerr << "Request ID: " << err.getRequestId() << std::endl;
    std::cerr << "Request target: " << err.getRequestTarget() << std::endl;
}

Ao compilar com a flag -DUSE_STD_EXPECTED=ON (C++23), Outcome torna-se um alias de tipo para std::expected, suportando operações monádicas como .and_then(), .transform() e .or_else().