1English | [简体中文](./README-CN.md)
2
3<p align="center">
4<a href="https://www.alibabacloud.com"><img src="https://aliyunsdk-pages.alicdn.com/icons/AlibabaCloud.svg"></a>
5</p>
6
7<h1 align="center">Alibaba Cloud SDK for C++</h1>
8
9<p align="center">
10<a href="https://travis-ci.org/aliyun/aliyun-openapi-cpp-sdk"><img src="https://travis-ci.org/aliyun/aliyun-openapi-cpp-sdk.svg?branch=master" alt="Travis Build Status"></a>
11<a href="https://codecov.io/gh/aliyun/aliyun-openapi-cpp-sdk"><img src="https://codecov.io/gh/aliyun/aliyun-openapi-cpp-sdk/branch/master/graph/badge.svg" alt="codecov"></a>
12</p>
13
14Alibaba Cloud SDK for C++ allows you to access Alibaba Cloud services such as Elastic Compute Service (ECS), Server Load Balancer (SLB), and CloudMonitor. You can access Alibaba Cloud services without the need to handle API related tasks, such as signing and constructing your requests.
15
16This document introduces how to obtain and call this SDK.
17
18If you have any problem while using Alibaba Cloud SDK for C++, please submit an [issue](https://github.com/aliyun/aliyun-openapi-cpp-sdk/issues/new).
19
20## Troubleshoot
21[Troubleshoot](https://troubleshoot.api.aliyun.com/?source=github_sdk) Provide OpenAPI diagnosis service to help developers locate quickly and provide solutions for developers through `RequestID` or `error message`.
22
23## Requirements
24
25- To use this SDK, you must have an Alibaba Cloud account and an AccessKey.
26
27  The AccessKey is required when initializing the client. You can create an AccessKey in the Alibaba Cloud console. For more information, see [Create an AccessKey](https://usercenter.console.aliyun.com/?spm=5176.doc52740.2.3.QKZk8w#/manage/ak).
28
29  >**Note:** To increase the security of your account, we recommend that you use the AccessKey of the RAM user to access Alibaba Cloud services.
30
31- To use this SDK to access the APIs of a product, you must first activate the product on the [Alibaba Cloud console](https://home.console.aliyun.com/?spm=5176.doc52740.2.4.QKZk8w) if required.
32
33- C++11 supported compiler installed
34  - Windows: Visual Studio 2015 or newer
35  - Linux: GCC 4.9 or newer
36- CMake 3.0 or newer
37- 4G memory or more
38
39## Installation
40
41### Linux
42
431. Install third-party libraries on the Linux platform, including `libcurl`, `libopenssl`, `libuuid`, and `libjsoncpp`.
44
45- Run the following commands on the `Redhat/Fedora` system
46
47```bash
48# use yum
49yum install jsoncpp-devel openssl-devel uuid-devel libcurl-devel
50
51# use dnf
52sudo dnf install libcurl-devel openssl-devel libuuid-devel libjsoncpp-devel
53```
54
55- Run the following commands on the `Debian/Ubuntu` system
56
57```bash
58sudo apt-get install libcurl4-openssl-dev libssl-dev uuid-dev libjsoncpp-dev
59```
60
612. Run the following commands to clone source codes from GitHub.
62
63```bash
64git clone https://github.com/aliyun/aliyun-openapi-cpp-sdk.git
65```
66
673. Build and install SDK
68
69- Manually build and install
70
71```bash
72cd aliyun-openapi-cpp-sdk
73mkdir sdk_build
74cd sdk_build
75cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr ..
76make
77sudo make install
78```
79
80- Or you may do this with `easyinstall.sh` in the source directory
81
82```bash
83cd aliyun-openapi-cpp-sdk
84sudo sh easyinstall.sh <lower name of product (like 'ecs')>
85
86# example
87sudo sh easyinstall.sh core
88sudo sh easyinstall.sh ecs
89```
90
91**The Alibaba Cloud SDK for C++ will be installed to `/usr`.**
92
93### Windows
94
951. Install [perl](https://www.perl.org/get.html#win32).
96
972. Run the following command to clone code from Github via git-bash:
98
99```bash
100git clone https://github.com/aliyun/aliyun-openapi-cpp-sdk.git
101```
102
1033. Build Visual Studio solution
104
105- Change directory to source code and make directory sdk_build
106
107- Open CMake UI and
108
109  - `Browse Source` to open source code directory.
110
111  - `Browse build`  to open the created `sdk_build` directory
112
113  - `Configure`
114
115  - use the lower name of product to set the value of `BUILD_PRODUCT`
116
117  - `Generate`
118
1194. Build and Install C++ SDK
120
121- Open `aliyun-openapi-cpp-sdk\\sdk_build\\alibabacloud-sdk.sln` with Visual Studio
122
123- Select  `Release`
124
125- Check INSTALL option from Build -> Configuration Manager
126
127- Build->Build Solutions to build.
128
129**Alibaba Cloud SDK for C++ will be installed to `C:\Program File (x86)\alibabacloud-sdk`**
130
131---
132
133## Quick Examples
134
135Before using this SDK, you must first configure the preprocessor to define `ALIBABACLOUD_SHARED` to achieve dynamic linking with the SDK shared libraries. Then you must create a client instance, specify the region of cloud services and provide authentication parameters before sending API requests.
136
137The following code shows how to call the [DescribeInstances](~~25506~~) API of ECS to query detailed information of all ECS instances in a specific region.
138
139```cpp
140#include <iostream>
141#include <alibabacloud/core/AlibabaCloud.h>
142#include <alibabacloud/ecs/EcsClient.h>
143
144using namespace AlibabaCloud;
145using namespace AlibabaCloud::Ecs;
146
147int main(int argc, char** argv) {
148  // Initialize the SDK
149  AlibabaCloud::InitializeSdk();
150
151  // Configure the ECS instance
152  ClientConfiguration configuration("<your-region-id>");
153  EcsClient client("<your-access-key-id>", "<your-access-key-secret>", configuration);
154
155  // Create an API request and set parameters
156  Model::DescribeInstancesRequest request;
157  request.setPageSize(10);
158
159  auto outcome = client.describeInstances(request);
160  if (!outcome.isSuccess()) {
161    // Handle exceptions
162    std::cout << outcome.error().errorCode() << std::endl;
163    AlibabaCloud::ShutdownSdk();
164    return -1;
165  }
166
167  std::cout << "totalCount: " << outcome.result().getTotalCount() << std::endl;
168
169  // Close the SDK
170  AlibabaCloud::ShutdownSdk();
171  return 0;
172}
173```
174
175Copy the above to ecs_test.cc, then build with the following command.
176
177```bash
178~$ g++ -o ecstest ecs_test.cc --std=c++11 -lalibabacloud-sdk-core -l alibabacloud-sdk-ecs
179~$ ./ecstest
180# Result or error message will be shown here.
181~$
182```
183
184## Timeout Configuration
185
186CPP SDK uses libcurl to do HTTP transfer.
187
188- The following timeout parameters are used to for libcurl.
189
190 - `connectTimeout`: timeout for the connect phase. [Refer](https://curl.haxx.se/libcurl/c/CURLOPT_CONNECTTIMEOUT_MS.html).
191 - `readTimeout`: maximum time the request is allowed to take, [Refer](https://curl.haxx.se/libcurl/c/CURLOPT_TIMEOUT_MS.html)
192
193- Default Value
194 - `connectTimeout`: 5000ms
195 - `readTimeout`: 10000ms
196
197- You may specify `timeout` parameters when create a client or make a request.
198
199- Request timeout has higher priority than client timeout.
200
201- If you want to disable timeout feature, deliver `0` or `-1` to `setConnectTimeout` and `setReadTimeout`.
202
203The following code shows hot to specify `timeout` parameters, and the final connectTimeout is 1000ms and readTimeout 6000ms.
204
205```cpp
206#include <iostream>
207#include <alibabacloud/core/AlibabaCloud.h>
208#include <alibabacloud/ecs/EcsClient.h>
209
210using namespace AlibabaCloud;
211using namespace AlibabaCloud::Ecs;
212
213int main(int argc, char** argv) {
214  // Initialize the SDK
215  AlibabaCloud::InitializeSdk();
216
217  // Configure the ECS instance
218  ClientConfiguration configuration("<your-region-id>");
219  // specify timeout when create client.
220  configuration.setConnectTimeout(1500);
221  configuration.setReadTimeout(4000);
222
223  EcsClient client("<your-access-key-id>", "<your-access-key-secret>", configuration);
224
225  // Create an API request and set parameters
226  Model::DescribeInstancesRequest request;
227  request.setPageSize(10);
228  // specify timeout when request
229  request.setConnectTimeout(1000);
230  request.setReadTimeout(6000);
231
232  auto outcome = client.describeInstances(request);
233  if (!outcome.isSuccess()) {
234    // Handle exceptions
235    std::cout << outcome.error().errorCode() << std::endl;
236    AlibabaCloud::ShutdownSdk();
237    return -1;
238  }
239
240  std::cout << "totalCount: " << outcome.result().getTotalCount() << std::endl;
241
242  // Close the SDK
243  AlibabaCloud::ShutdownSdk();
244  return 0;
245}
246
247```
248
249**More [examples](https://github.com/aliyun/aliyun-openapi-cpp-sdk/tree/master/examples)**
250
251## Issues
252[Opening an Issue](https://github.com/aliyun/aliyun-openapi-cpp-sdk/issues/new/choose), Issues not conforming to the guidelines may be closed immediately.
253
254## Changelog
255Detailed changes for each release are documented in the [release notes](CHANGELOG).
256
257## Contribution
258Please make sure to read the [Contributing Guide](CONTRIBUTING.md) before making a pull request.
259
260## License
261[Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0)
262
263Copyright 1999-2019 Alibaba Group Holding Ltd.
264