After comparing JSON C++ SDK and XML C++ SDK documents, you may find XML C++ SDK not only increased the document numbers, but also improved in terms of architecture, availability, security, usability, robustness and transmission. The following instructions can help you upgrade to XML C++ SDK.
Feature Comparison
The following table compares the main features of XML C++ SDK and JSON C++ SDK:
SDK | XML C++ SDK | JSON C++ SDK |
Uploading objects | Supports uploading local files, byte streams, and input streams. Overwriting files with the same name Simple uploads support up to 5 GB. Multipart upload supports a maximum size of 48.82 TB (50,000 GB). | Supports uploading local files; files larger than 8 MB must be uploaded in chunks. Manual configuration required for overwriting files with the same name Simple upload supports a maximum of 20MB. Multipart upload supports up to 64 GB. |
Basic bucket operations | Create a bucket. Retrieving Buckets Deleting a bucket | Unavailable |
Bucket ACL operations | Setting bucket ACL Retrieving and setting bucket ACLs Deleting and setting bucket ACLs | Unavailable |
Bucket Lifecycle | Creating bucket lifecycle Get the bucket lifecycle Delete the bucket lifecycle | Unavailable |
Directory Operations | No separate API provided. | Create a directory Querying directories Deleting a Directory |
Upgrade Steps
Upgrade C++ SDK by following the 4 steps below.
1. Update C++ SDK
XML C++ SDK replaces curl libraries in JSON C++ SDK with Poco libraries. Download the complete edition of Poco from Poco official website, and execute the following command to install Poco libraries and header files.
./configure --omit=Data/ODBC,Data/MySQLmakemake install
2. Change the SDK configuration file
XML C++ SDK and JSON C++ SDK are the same in terms of initialization, but differ in the configuration file "config.json". Make the following modifications in the XML C++ SDK configuration file:
Remove the "APPID" configuration item from the JSON C++ SDK.
The
ConnectTimeoutInms replaces both CurlConnectTimeoutInms and CurlGlobalConnectTimeoutInms. A new ReceiveTimeoutInms has been added, and corresponding setting interfaces have been implemented in the Request base class, allowing modifications for different operations.The default initialization parameters for XML C++ SDK are detailed in the "cos_sys_config.cpp" file.
JSON C++ SDK and XML C++ SDK have different descriptions for Regions. For detailed differences, please refer to "Changing Bucket Names and Availability Zone Abbreviations" below.
3. Modify the bucket name and the abbreviation of the available region
The bucket name and the abbreviations of available regions in XML C++ SDK are different from those in JSON C++ SDK. You need to make changes accordingly.
Bucket
The name of an XML C++ SDK bucket consists of a user-defined string and an APPID that are connected by a dash ("-"). For example,
mybucket1-1250000000, where mybucket1 is a user-defined string and 1250000000 is an APPID.Note
APPID is one of the identifiers for a Tencent Cloud account, used to associate cloud resources. Upon successful registration of a Tencent Cloud account, the system automatically assigns an APPID to the user. You can log in to the Tencent Cloud Console and view the APPID under Account Information.
Refer to the following sample code to set a bucket:
qcloud_cos::CosConfig config("./config.json");qcloud_cos::CosAPI cos(config);// In JSON C++ SDK, the AppID is written in the configuration file, and the Bucket is defined as: string bucket = "mybucket1";string bucket = "mybucket1-1250000000";qcloud_cos::HeadBucketReq req(bucket_name);qcloud_cos::HeadBucketResp resp;qcloud_cos::CosResult result = cos.HeadBucket(req, &resp);
Abbreviations of available regions for buckets
The abbreviations of available regions for XML C++ SDK buckets have changed. During initialization, set the abbreviation of the bucket region to
Region in the configuration file. See the following table for region abbreviations in JSON C++ SDK and XML C++ SDK:Regions | Abbreviation in XML C++ SDK | Abbreviation in JSON C++ SDK |
Beijing Zone 1 (North China) | ap-beijing-1 | tj |
Beijing | ap-beijing | bj |
Shanghai (East China) | ap-shanghai | sh |
Guangzhou (South China) | ap-guangzhou | gz |
Chengdu (Southwest China) | ap-chengdu | cd |
Chongqing | ap-chongqing | - |
Hong Kong (China) | ap-hongkong | hk |
Singapore | ap-singapore | sgp |
Toronto | na-toronto | ca |
Frankfurt | eu-frankfurt | ger |
Mumbai | ap-mumbai | - |
Seoul | ap-seoul | - |
Silicon Valley | na-siliconvalley | - |
Virginia | na-ashburn | - |
Bangkok | ap-bangkok | - |
4. Modifying APIs
After upgrading to XML C++ SDK, some API operations have changed. Please make corresponding modifications based on your requirements. We have also encapsulated the SDK to make it more user-friendly. For more information, refer to our examples and Quick Start guide.
Here are the main changes:
(1) No separate directory interface
In the XML SDK, there is no separate directory interface. Object storage does not have the concept of folders and directories, and uploading an object like project/a.txt will not create a project folder. To accommodate user habits, object storage simulates the display of folders or directories in the console, COS browser, and other graphical tools. This is achieved by creating an object with a key value of
project/ and an empty content, which mimics the traditional folder display.For example, when uploading an object
project/doc/a.txt, the delimiter / simulates the folder display. In the console, you can see folders project and doc, where doc is a sub-folder of project containing the a.txt file.Therefore, in a use case for file upload only, you can directly upload files without creating a folder first. If a folder is allowed in a use case, the feature of creating a folder should be supported. You can upload a 0 KB file whose path ends with '/'. When you call the API GetBucket, you can use the file as a folder.
(2) Multi-threaded upload and download operations
In XML C++ SDK, we have encapsulated multi-threaded multipart upload and download operations for
MultiUploadObjectReq and MultiGetObjectReq interfaces, optimizing both API design and transmission performance.Main features:
Configurable chunk size for multi-threaded uploads and downloads
The
MultiUploadObjectReq interface encapsulates all multipart upload operations, including Init, Upload, Complete, and Abort actions.Sample code using
MultiUploadObjectReq for uploading:qcloud_cos::CosConfig config("./config.json");qcloud_cos::CosAPI cos(config);string bucket_name = "alangz-1253960400";string object_name = "object_key";string local_file = "/data/test";qcloud_cos::MultiUploadObjectReq req(bucket_name,object_name, local_file);req.SetRecvTimeoutInms(1000 * 60);qcloud_cos::MultiUploadObjectResp resp;qcloud_cos::CosResult result = cos.MultiUploadObject(req, &resp);if (result.IsSucc()) {std::cout << "MultiUpload Succ." << std::endl;std::cout << resp.GetLocation() << std::endl;std::cout << resp.GetKey() << std::endl;std::cout << resp.GetBucket() << std::endl;std::cout << resp.GetEtag() << std::endl;} else {std::cout << "MultiUpload Fail." << std::endl;// Determine the specific step where the failure occurredstd::string resp_tag = resp.GetRespTag();if ("Init" == resp_tag) {// print result} else if ("Upload" == resp_tag) {// print result} else if ("Complete" == resp_tag) {// print result}}
The sample code of download using
MultiGetObjectReq:qcloud_cos::CosConfig config("./config.json");qcloud_cos::CosAPI cos(config);string bucket_name = "alangz-1253960400";string object_name = "object_key";string file_path = "/data/test";qcloud_cos::MultiGetObjectReq req(bucket_name,object_name, file_path);qcloud_cos::MultiGetObjectResp resp;qcloud_cos::CosResult result = cos.GetObject(req, &resp);
(3) Different signature algorithms
Generally, you do not need to compute a signature manually. However, if you return an SDK signature to the frontend, note that the signature algorithm has changed. One-time signatures and multiple-time signatures are no longer used. Instead, you can set a validity period of the signature to ensure security. For more information, see XML Request Signature.
(4) Adding a New API
The following APIs are added in XML C++ SDK, which can be called as needed:
Bucket operations, such as PutBucketReq, GetBucketReq, etc.
Bucket ACL operations, such as PutBucketACLReq and GetBucketACLReq.
Bucket lifecycle operations, such as PutBucketLifecycleReq, GetBucketLifecycleReq, etc.