Bläddra i källkod

modify readme to meet standard

wenzuochao 6 år sedan
förälder
incheckning
d79ec311a5

+ 15 - 0
CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing to the Alibaba Cloud SDK for Go
+
+We work hard to provide a high-quality and useful SDK for Alibaba Cloud, and we greatly value feedback and contributions from our community. Please submit your [issues][issues] or [pull requests][pull-requests] through GitHub.
+
+## Tips
+
+- The SDK is released under the [Apache license][license]. Any code you submit will be released under that license. For substantial contributions, we may ask you to sign a [Alibaba Documentation Corporate Contributor License Agreement (CLA)][cla].
+- We maintain a high percentage of code coverage in our unit tests. If you make changes to the code, please add, update, and/or remove tests as appropriate.
+- If your code does not conform to the PSR standards, does not include adequate tests, we may ask you to update your pull requests before we accept them. We also reserve the right to deny any pull requests that do not align with our standards or goals.
+
+
+[issues]: https://github.com/aliyun/alibaba-cloud-sdk-go/issues
+[pull-requests]: https://github.com/aliyun/alibaba-cloud-sdk-go/pulls
+[license]: http://www.apache.org/licenses/LICENSE-2.0
+[cla]: https://alibaba-cla-2018.oss-cn-beijing.aliyuncs.com/Alibaba_Documentation_Open_Source_Corporate_CLA.pdf

+ 141 - 276
README.md

@@ -1,276 +1,141 @@
-# Alibaba Cloud Go Software Development Kit
-
-[![Version Badge](https://badge.fury.io/gh/aliyun%2Falibaba-cloud-sdk-go.svg)](https://badge.fury.io/gh/aliyun%2Falibaba-cloud-sdk-go)
-[![Travis Build Status](https://travis-ci.org/aliyun/alibaba-cloud-sdk-go.svg?branch=master)](https://travis-ci.org/aliyun/alibaba-cloud-sdk-go)
-[![Appveyor Build status](https://ci.appveyor.com/api/projects/status/1hiuo3ppx5j49psv/branch/master?svg=true)](https://ci.appveyor.com/project/aliyun/alibaba-cloud-sdk-go/branch/master)
-[![codecov](https://codecov.io/gh/aliyun/alibaba-cloud-sdk-go/branch/master/graph/badge.svg)](https://codecov.io/gh/aliyun/alibaba-cloud-sdk-go)
-[![Codacy Badge](https://api.codacy.com/project/badge/Grade/291a39e242364b04ad442f0cce0e30d5)](https://app.codacy.com/app/aliyun/alibaba-cloud-sdk-go?utm_source=github.com&utm_medium=referral&utm_content=aliyun/alibaba-cloud-sdk-go&utm_campaign=Badge_Grade_Dashboard)
-[![Go Report Card](https://goreportcard.com/badge/github.com/aliyun/alibaba-cloud-sdk-go)](https://goreportcard.com/report/github.com/aliyun/alibaba-cloud-sdk-go)
-[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Faliyun%2Falibaba-cloud-sdk-go.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Faliyun%2Falibaba-cloud-sdk-go?ref=badge_shield)
-
-See [中文文档](./README_zh.md)
-
-The Alibaba Cloud Go Software Development Kit (SDK) 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.
-
-This document introduces how to obtain and call Alibaba Cloud Go SDK.
-
-If you have any problem while using Go SDK, please [submit an issue](https://github.com/aliyun/alibaba-cloud-sdk-go/issues/new).
-
-
-## Online Demo
-
-**[API Explorer](https://api.aliyun.com)** provides the ability to call the cloud product OpenAPI online, and dynamically generate SDK Example code and quick retrieval interface, which can significantly reduce the difficulty of using the cloud API. **It is highly recommended**.
-
-<a href="https://api.aliyun.com" target="api_explorer">
-  <img src="https://img.alicdn.com/tfs/TB12GX6zW6qK1RjSZFmXXX0PFXa-744-122.png" width="180" />
-</a>
-
-
-## Prerequisites
-
-- To use Alibaba Cloud Go SDK, you must have an Alibaba Cloud account as well as an AccessKey.
-
-	The AccessKey is required when initializing `AcsClient`. 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).
-
-	> **Note:** To increase the security of your account, we recommend that you use the AccessKey of the RAM user to access Alibaba Cloud services.
-
-- To use Alibaba Cloud Go 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.
-
-
-## Installation
-
-Use `go get` to install SDK:
-
-```sh
-$ go get -u github.com/aliyun/alibaba-cloud-sdk-go/sdk
-```
-
-If you have used glide to manage dependence, you can also use glide to install Alibaba Cloud Go SDK:
-
-```powershell
-glide get github.com/aliyun/alibaba-cloud-sdk-go
-```
-## Using
-
-The following code example shows the three main steps to use Alibaba Cloud Go SDK:
-
-1. Create the client.
-2. Create an API request and set parameters.
-3. Initiate the request and handle exceptions.
-
-```go
-package main
-
-import (
-	"fmt"
-
-	"github.com/aliyun/alibaba-cloud-sdk-go/sdk/requests"
-	"github.com/aliyun/alibaba-cloud-sdk-go/services/ecs"
-)
-
-func main() {
-	// Create an ECS client
-	ecsClient, err := ecs.NewClientWithAccessKey(
-		"<your-region-id>",         // Your Region ID
-		"<your-access-key-id>",     // Your AccessKey ID
-		"<your-access-key-secret>") // Your AccessKey Secret
-	if err != nil {
-		// Handle exceptions
-		panic(err)
-	}
-	// Create an API request and set parameters
-	request := ecs.CreateDescribeInstancesRequest()
-	// Set the request.PageSize to "10"
-	request.PageSize = requests.NewInteger(10)
-	// Initiate the request and handle exceptions
-	response, err := ecsClient.DescribeInstances(request)
-	if err != nil {
-		// Handle exceptions
-		panic(err)
-	}
-	fmt.Println(response)
-}
-```
-
-When you create an instance of client, you need to fill out three parameters: `Region ID`、`Access Key ID` and `Access Key Secret`. You can get `Access Key ID` and `Access Key Secret` from console, and get `Region ID` from [region list](https://help.aliyun.com/document_detail/40654.html?spm=5176.doc52740.2.8.FogWrd)
-
-## Debug
-
-If the request has occured an error, you can view the HTTP request process by adding the environment variable `DEBUG=sdk`.
-
-## Ignore certificate validation
-
-When you send a https request, it may be fail due to certificate validation. At this moment, you can use the way below to ignore certificate validation.
-
-```go
-// You can set HTTPSInsecure as true to ignore certificate validation.
-// Request HTTPSInsecure has a higher priority than client HTTPSInsecure.
-// If you don't set any HTTPSInsecure, the default HTTPSInsecure is false.
-
-// Set request HTTPSInsecure(Only the request is effected.)
-request.SetHTTPSInsecure(true)                           // Set request HTTPSInsecure to true.
-isInsecure := request.GetHTTPSInsecure()                 // Get request HTTPSInsecure.
-
-// Set client HTTPSInsecure(For all requests which is sent by the client.)
-client.SetHTTPSInsecure(true)                         // Set client HTTPSInsecure to true .
-isInsecure := client.GetHTTPSInsecure()               // Get client HTTPSInsecure.
-```
-
-## HTTP Proxy
-
-If you want to use http proxy,  https proxy or no proxy, you can set environment variables `HTTP_PROXY`, `HTTPS_PROXY` or `NO_PROXY`, or you can set them by client.
-
-```go
-// client proxy has a high priority than environment variables.
-client.SetHttpProxy("http://127.0.0.1:8080")   // Set Http Proxy.
-client.GetHttpProxy()                          // Get Http Proxy.
-
-client.SetHttpsProxy("https://127.0.0.1:8080")   // Set Https Proxy.
-client.GetHttpsProxy()                           // Get Https Proxy.
-
-client.SetNoProxy("127.0.0.1,localhost")     // Set No Proxy.
-client.GetNoProxy()                          // Get No Proxy.
-```
-
-## Keep-alive
-
-Alibaba Cloud Go SDK uses primordial `net/http` of Go language to send and accept requests,so it's  configuration is the same as `net/http`'s,you can use config to deliver configuration to the bottomed httpClient.
-
-```go
-httpTransport := http.Transport{
-    // set http client options
-}
-config := sdk.NewConfig()
-            .WithHttpTransport(&httpTransport)
-            .WithTimeout(timeout)
-ecsClient, err := ecs.NewClientWithOptions(config)
-```
-
-## Concurrent Request
-
-* Due to the concurrency nature of the Go language, we recommend that you control the concurrent requests for the SDK at the application level.
-* In order to facilitate your use, we also provide a direct use of concurrent invocation mode, the relevant concurrency control by the SDK internal implementation.
-
-### Timeout
-
-```go
-// Request Timeout has a higher priority than client Timeout.
-// If you don't set any timeout, the default ReadTimeout is 10 second, and the default ConnectTimeout is 5 second.
-
-// Set request Timeout(Only the request is effected.)
-request.SetReadTimeout(10 * time.Second)             // Set request ReadTimeout to 10 second.
-readTimeout := request.GetReadTimeout()              // Get request ReadTimeout.
-request.SetConnectTimeout(5 * time.Second)           // Set request ConnectTimeout to 5 second.
-connectTimeout := request.GetConnectTimeout()        // Get request ConnectTimeout.
-
-// Set client Timeout(For all requests which is sent by the client.)
-client.SetReadTimeout(10 * time.Second)              // Set client ReadTimeout to 10 second.
-readTimeout := client.GetReadTimeout()               // Get client ReadTimeout.
-client.SetConnectTimeout(5 * time.Second)            // Set client ConnectTimeout to 5 second.
-connectTimeout := client.GetConnectTimeout()         // Get client ConnectTimeout.
-```
-
-### Open SDK Client's concurrent function.
-
-```go
-// Maximum Running Vusers
-poolSize := 2
-// The maximum number of requests that can be cached
-maxTaskQueueSize := 5
-
-// Enable asynchronous functionality at creation time
-config := sdk.NewConfig()
-            .WithEnableAsync(true)
-            .WithGoRoutinePoolSize(poolSize)            // Optional,default:5
-            .WithMaxTaskQueueSize(maxTaskQueueSize)     // Optional,default:1000
-ecsClient, err := ecs.NewClientWithOptions(config)
-
-// It can also be opened after client is initialized
-client.EnableAsync(poolSize, maxTaskQueueSize)
-```
-
-##### Make an asynchronous call
-Alibaba Cloud Go SDK supports asynchronous calls in two ways:
-
-1. Using channel as return values
-    ```go
-    responseChannel, errChannel := client.FooWithChan(request)
-
-    // this will block
-    response := <-responseChannel
-    err = <-errChannel
-    ```
-
-2. Use callback to control the callback
-
-    ```go
-    blocker := client.FooWithCallback(request, func(response *FooResponse, err error) {
-        // handle the response and err
-    })
-
-    // blocker which is type of (chan int),is used to control synchronization,when returning 1 means success,and returning 0 means failure.
-    // When <-blocker returns failure,err also will be handled by afferent callback.
-    result := <-blocker
-    ```
-
-## Generalize the call interface(CommonAPI)
-
-### What is CommonAPI
-
-CommonAPI which is launched by Alibaba Cloud Go SDK,is an universal grid way to call API. CommonAPI has the following characteristics: :
-1. Lightweight: only the Core package is required to initiate the call, without the need to download and install the SDK of each product line.
-2. Easy: call the newly released API without updating the SDK.
-3. Iterating fast 
-
-### Start to use
-
-CommonAPI needs to be used in conjunction with the corresponding API documentation to query information about the API.
-
-You can query the API documentation for all products at[Document Center](https://help.aliyun.com/?spm=5176.8142029.388261.173.23896dfaav2hEF).
-
-Launching a CommonAPI request requires you to query the following parameters:
-* Domain name: the generic domain name for the product, which can be viewed in the "call mode" page.
-* API version: the version number of the API, in the form of 'yyyy-mm-dd', which can be found in the "public parameters" page.
-* Interface name (apiName) : the name of the API
-
-We take ECS [DescribeInstanceStatus API](https://help.aliyun.com/document_detail/25505.html?spm=5176.doc25506.6.820.VbHnW6) as an example.
-
-```go
-package main
-
-import (
-	"fmt"
-	"os"
-
-	"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
-	"github.com/aliyun/alibaba-cloud-sdk-go/sdk/requests"
-)
-
-func main() {
-
-	client, err := sdk.NewClientWithAccessKey("cn-hangzhou", os.Getenv("ACCESS_KEY_ID"), os.Getenv("ACCESS_KEY_SECRET"))
-	if err != nil {
-		// Handle exceptions
-		panic(err)
-	}
-
-	request := requests.NewCommonRequest()
-	request.Domain = "ecs.aliyuncs.com"
-	request.Version = "2014-05-26"
-	request.ApiName = "DescribeInstanceStatus"
-
-	request.QueryParams["PageNumber"] = "1"
-	request.QueryParams["PageSize"] = "30"
-
-	response, err := client.ProcessCommonRequest(request)
-	if err != nil {
-		// Handle exceptions
-		panic(err)
-	}
-
-	fmt.Print(response.GetHttpContentString())
-}
-```
-
-## License
-[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Faliyun%2Falibaba-cloud-sdk-go.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Faliyun%2Falibaba-cloud-sdk-go?ref=badge_large)
+English | [简体中文](./README_zh.md)
+
+
+<p align="center">
+<a href=" https://www.alibabacloud.com"><img src="https://aliyunsdk-pages.alicdn.com/icons/AlibabaCloud.svg"></a>
+</p>
+
+<h1 align="center">Alibaba Cloud Client for Go</h1>
+
+<p align="center">
+<a href="https://badge.fury.io/gh/aliyun%2Falibaba-cloud-sdk-go"><img src="https://badge.fury.io/gh/aliyun%2Falibaba-cloud-sdk-go.svg" alt="Latest Stable Version"></a>
+<a href="https://app.fossa.io/projects/git%2Bgithub.com%2Faliyun%2Falibaba-cloud-sdk-go?ref=badge_shield"><img src="https://app.fossa.io/api/projects/git%2Bgithub.com%2Faliyun%2Falibaba-cloud-sdk-go.svg?type=shield" alt="License"></a>
+<br/>
+<a href="https://codecov.io/gh/aliyun/alibaba-cloud-sdk-go"><img src="https://codecov.io/gh/aliyun/alibaba-cloud-sdk-go/branch/master/graph/badge.svg" alt="codecov"></a>
+<a href="https://travis-ci.org/aliyun/alibaba-cloud-sdk-go"><img src="https://travis-ci.org/aliyun/alibaba-cloud-sdk-go.svg?branch=master" alt="Travis Build Status"></a>
+<a href="https://ci.appveyor.com/project/aliyun/alibaba-cloud-sdk-go/branch/master"><img src="https://ci.appveyor.com/api/projects/status/1hiuo3ppx5j49psv/branch/master?svg=true" alt="Appveyor Build Status"></a>
+<a href="https://app.codacy.com/app/aliyun/alibaba-cloud-sdk-go?utm_source=github.com&utm_medium=referral&utm_content=aliyun/alibaba-cloud-sdk-go&utm_campaign=Badge_Grade_Dashboard"><img src="https://api.codacy.com/project/badge/Grade/291a39e242364b04ad442f0cce0e30d5" alt="Codacy Badge"></a>
+<a href="https://goreportcard.com/report/github.com/aliyun/alibaba-cloud-sdk-go"><img src="https://goreportcard.com/badge/github.com/aliyun/alibaba-cloud-sdk-go" alt="Go Report Card"></a>
+</p>
+
+
+Alibaba Cloud Client for Go is a client tool that helps Go developers manage credentials and send requests, [Alibaba Cloud SDK for Go][SDK] dependency on this tool.
+
+
+## Online Demo
+[API Explorer][open-api] provides the ability to call the cloud product OpenAPI online, and dynamically generate SDK Example code and quick retrieval interface, which can significantly reduce the difficulty of using the cloud API.
+
+
+## Requirements
+- It's necessary for you to make sure your system meet the [Requirements][Requirements], such as installing a Go environment which is new than 1.10.x.
+
+## Installation
+Use `go get` to install SDK:
+
+```sh
+$ go get -u github.com/aliyun/alibaba-cloud-sdk-go/sdk
+```
+
+If you have used glide to manage dependence,you can also use glide to install Alibaba Cloud Go SDK:
+
+```sh
+$ glide get github.com/aliyun/alibaba-cloud-sdk-go
+```
+
+## Quick Examples
+Before you begin, you need to sign up for an Alibaba Cloud account and retrieve your [Credentials](https://usercenter.console.aliyun.com/#/manage/ak).
+
+### Create Client
+```go
+package main
+
+import "github.com/aliyun/alibaba-cloud-sdk-go/sdk"
+
+func main() {
+
+	client, err := sdk.NewClientWithAccessKey("REGION_ID", "ACCESS_KEY_ID", "ACCESS_KEY_SECRET")
+	if err != nil {
+		// Handle exceptions
+		panic(err)
+	}
+}
+```
+
+### ROA Request
+```go
+package main
+
+import "github.com/aliyun/alibaba-cloud-sdk-go/sdk/requests"
+
+func main() {
+	request := requests.NewCommonRequest()        // Make a common request
+	request.Method = "GET"                        // Set request method
+	request.Product = "CS"                        // Specify product
+	request.Domain = "cs.aliyuncs.com"            // Location Service will not be enabled if the host is specified. For example, service with a Certification type-Bearer Token should be specified
+	request.Version = "2015-12-15"                // Specify product version
+	request.PathPattern = "/clusters/[ClusterId]" // Specify path rule with ROA-style
+	request.Scheme = "https"                      // Set request scheme. Default: http
+	request.ApiName = "DescribeCluster"           // Specify product interface
+	request.QueryParams["ClusterId"] = "123456"   // Assign values to parameters in the path
+	request.QueryParams["RegionId"] = "region_id" // Specify the requested regionId, if not specified, use the client regionId, then default regionId
+	request.TransToAcsRequest()                   // Trans commonrequest to acsRequest, which is used by client.
+}
+```
+
+### RPC Request
+```go
+package main
+
+import "github.com/aliyun/alibaba-cloud-sdk-go/sdk/requests"
+
+func main() {
+	request := requests.NewCommonRequest()                // Make a common request
+	request.Method = "POST"                               // Set request method
+	request.Product = "Ecs"                               // Specify product
+	request.Domain = "ecs.aliyuncs.com"                   // Location Service will not be enabled if the host is specified. For example, service with a Certification type-Bearer Token should be specified
+	request.Version = "2014-05-26"                        // Specify product version
+	request.Scheme = "https"                              // Set request scheme. Default: http
+	request.ApiName = "CreateInstance"                    // Specify product interface
+	request.QueryParams["InstanceType"] = "ecs.g5.large"  // Assign values to parameters in the path
+	request.QueryParams["RegionId"] = "region_id"         // Specify the requested regionId, if not specified, use the client regionId, then default regionId
+	request.TransToAcsRequest()                           // Trans commonrequest to acsRequest, which is used by client.
+}
+```
+
+
+## Documentation
+* [Requirements](docs/0-Requirements-EN.md)
+* [Installation](docs/1-Installation-EN.md)
+* [Client](docs/2-Client-EN.md)
+* [SSL Verify](docs/3-Verify-EN.md)
+* [Proxy](docs/4-Proxy-EN.md)
+* [Timeout](docs/5-Timeout-EN.md)
+* [Debug](docs/6-Debug-EN.md)
+* [Concurrent](docs/7-Concurrent-EN.md)
+* [Asynchronous Call](docs/8-Asynchronous-EN.md)
+
+
+## Issues
+[Opening an Issue][issue], Issues not conforming to the guidelines may be closed immediately.
+
+
+## Contribution
+Please make sure to read the [Contributing Guide](CONTRIBUTING.md) before making a pull request.
+
+
+## References
+* [Alibaba Cloud Regions & Endpoints][endpoints]
+* [OpenAPI Explorer][open-api]
+* [Go][go]
+* [Latest Release][latest-release]
+
+
+## License
+[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Faliyun%2Falibaba-cloud-sdk-go.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Faliyun%2Falibaba-cloud-sdk-go?ref=badge_large)
+
+[SDK]: https://github.com/aliyun/alibaba-cloud-sdk-go
+[issue]: https://github.com/aliyun/alibaba-cloud-sdk-go/issues/new
+[open-api]: https://api.aliyun.com/#/
+[latest-release]: https://github.com/aliyun/alibaba-cloud-sdk-go/releases
+[go]: https://golang.org/dl/
+[endpoints]: https://developer.aliyun.com/endpoints

+ 86 - 212
README_zh.md

@@ -1,35 +1,34 @@
-# 阿里云开发者 Go 工具套件
+[English](./README.md) | 简体中文
 
-[![Version Badge](https://badge.fury.io/gh/aliyun%2Falibaba-cloud-sdk-go.svg)](https://badge.fury.io/gh/aliyun%2Falibaba-cloud-sdk-go)
-[![Travis Build Status](https://travis-ci.org/aliyun/alibaba-cloud-sdk-go.svg?branch=master)](https://travis-ci.org/aliyun/alibaba-cloud-sdk-go)
-[![Appveyor Build status](https://ci.appveyor.com/api/projects/status/1hiuo3ppx5j49psv/branch/master?svg=true)](https://ci.appveyor.com/project/aliyun/alibaba-cloud-sdk-go/branch/master)
-[![codecov](https://codecov.io/gh/aliyun/alibaba-cloud-sdk-go/branch/master/graph/badge.svg)](https://codecov.io/gh/aliyun/alibaba-cloud-sdk-go)
-[![Codacy Badge](https://api.codacy.com/project/badge/Grade/291a39e242364b04ad442f0cce0e30d5)](https://app.codacy.com/app/aliyun/alibaba-cloud-sdk-go?utm_source=github.com&utm_medium=referral&utm_content=aliyun/alibaba-cloud-sdk-go&utm_campaign=Badge_Grade_Dashboard)
-[![Go Report Card](https://goreportcard.com/badge/github.com/aliyun/alibaba-cloud-sdk-go)](https://goreportcard.com/report/github.com/aliyun/alibaba-cloud-sdk-go)
-[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Faliyun%2Falibaba-cloud-sdk-go.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Faliyun%2Falibaba-cloud-sdk-go?ref=badge_shield)
+<p align="center">
+<a href=" https://www.alibabacloud.com"><img src="https://aliyunsdk-pages.alicdn.com/icons/Aliyun.svg"></a>
+</p>
 
-See [英文文档](./README.md)
+<h1 align="center">Alibaba Cloud Client for Go</h1>
 
-欢迎使用阿里云开发者工具套件(SDK)。阿里云 Go SDK 让您不用复杂编程即可访问云服务器、云监控等多个阿里云服务。这里向您介绍如何获取阿里云 Go SDK 并开始调用。
+<p align="center">
+<a href="https://badge.fury.io/gh/aliyun%2Falibaba-cloud-sdk-go"><img src="https://badge.fury.io/gh/aliyun%2Falibaba-cloud-sdk-go.svg" alt="Latest Stable Version"></a>
+<a href="https://app.fossa.io/projects/git%2Bgithub.com%2Faliyun%2Falibaba-cloud-sdk-go?ref=badge_shield"><img src="https://app.fossa.io/api/projects/git%2Bgithub.com%2Faliyun%2Falibaba-cloud-sdk-go.svg?type=shield" alt="License"></a>
+<br/>
+<a href="https://codecov.io/gh/aliyun/alibaba-cloud-sdk-go"><img src="https://codecov.io/gh/aliyun/alibaba-cloud-sdk-go/branch/master/graph/badge.svg" alt="codecov"></a>
+<a href="https://travis-ci.org/aliyun/alibaba-cloud-sdk-go"><img src="https://travis-ci.org/aliyun/alibaba-cloud-sdk-go.svg?branch=master" alt="Travis Build Status"></a>
+<a href="https://ci.appveyor.com/project/aliyun/alibaba-cloud-sdk-go/branch/master"><img src="https://ci.appveyor.com/api/projects/status/1hiuo3ppx5j49psv/branch/master?svg=true" alt="Appveyor Build Status"></a>
+<a href="https://app.codacy.com/app/aliyun/alibaba-cloud-sdk-go?utm_source=github.com&utm_medium=referral&utm_content=aliyun/alibaba-cloud-sdk-go&utm_campaign=Badge_Grade_Dashboard"><img src="https://api.codacy.com/project/badge/Grade/291a39e242364b04ad442f0cce0e30d5" alt="Codacy Badge"></a>
+<a href="https://goreportcard.com/report/github.com/aliyun/alibaba-cloud-sdk-go"><img src="https://goreportcard.com/badge/github.com/aliyun/alibaba-cloud-sdk-go" alt="Go Report Card"></a>
+</p>
 
-如果您在使用 SDK 的过程中遇到任何问题,欢迎前往[阿里云 SDK 问答社区](https://yq.aliyun.com/tags/type_ask-tagid_23350)提问,提问前请阅读[提问引导](https://help.aliyun.com/document_detail/93957.html)。亦可在当前 GitHub 提交 Issues。
 
+Alibaba Cloud Client for Go 是帮助 Go 开发者管理凭据、发送请求的客户端工具, [Alibaba Cloud SDK for Go][SDK] 由本工具提供底层支持。
 
-## 在线示例
-
-**[API Explorer](https://api.aliyun.com)** 提供在线调用云产品 OpenAPI、并动态生成 SDK Example 代码和快速检索接口等能力,能显著降低使用云 API 的难度,强烈推荐使用
-
-<a href="https://api.aliyun.com" target="api_explorer">
-  <img src="https://img.alicdn.com/tfs/TB12GX6zW6qK1RjSZFmXXX0PFXa-744-122.png" width="180" />
-</a>
 
+## 在线示例
+[API Explorer][open-api] 提供在线调用阿里云产品,并动态生成 SDK 代码和快速检索接口等能力,能显著降低使用云 API 的难度。
 
-## 环境准备
-1. 要使用阿里云 Go SDK,您需要一个云账号以及一对 `Access Key ID` 和 `Access Key Secret`。 请在阿里云控制台中的 [AccessKey 管理页面](https://usercenter.console.aliyun.com/?spm=5176.doc52740.2.3.QKZk8w#/manage/ak) 上创建和查看您的 AccessKey,或者联系您的系统管理员
-2. 要使用阿里云 SDK 访问某个产品的 API ,您需要事先在[阿里云控制台](https://home.console.aliyun.com/?spm=5176.doc52740.2.4.QKZk8w)中开通这个产品。
 
-## SDK 获取和安装
+## 环境要求
+- 您的系统需要达到 [环境要求][Requirements], 例如,安装了不低于 1.10.x 版本的 Go 环境。
 
+## Installation
 使用 `go get` 下载安装 SDK
 
 ```sh
@@ -44,223 +43,98 @@ $ glide get github.com/aliyun/alibaba-cloud-sdk-go
 
 另外,阿里云 Go SDK 也会发布在 https://develop.aliyun.com/tools/sdk#/go 这个地址。
 
-## 开始调用
-
-以下这个代码示例向您展示了调用阿里云 GO SDK 的 3 个主要步骤:
-
-1. 创建 Client 实例
-2. 创建 API 请求并设置参数
-3. 发起请求并处理异常
+## 快速使用
+在您开始之前,您需要注册阿里云帐户并获取您的[凭证](https://usercenter.console.aliyun.com/#/manage/ak)。
 
+### 创建客户端
 ```go
 package main
 
-import (
-    "github.com/aliyun/alibaba-cloud-sdk-go/services/ecs"
-    "fmt"
-)
+import "github.com/aliyun/alibaba-cloud-sdk-go/sdk"
 
 func main() {
-    // 创建ecsClient实例
-    ecsClient, err := ecs.NewClientWithAccessKey(
-        "<your-region-id>",             // 您的可用区ID
-        "<your-access-key-id>",         // 您的Access Key ID
-        "<your-access-key-secret>")     // 您的Access Key Secret
-    if err != nil {
-        // 异常处理
-        panic(err)
-    }
-    // 创建API请求并设置参数
-    request := ecs.CreateDescribeInstancesRequest()
-    request.PageSize = "10"
-    // 发起请求并处理异常
-    response, err := ecsClient.DescribeInstances(request)
-    if err != nil {
-        // 异常处理
-        panic(err)
-    }
-    fmt.Println(response)
-}
-```
-
-在创建Client实例时,您需要填写3个参数:`Region ID`、`Access Key ID`和`Access Key Secret`。`Access Key ID`和`Access Key Secret`可以从控制台获得;而`Region ID`可以从[地域列表](https://help.aliyun.com/document_detail/40654.html?spm=5176.doc52740.2.8.FogWrd)中获得
-
-## 调试
-
-如果您发送的请求出错,您可以通过添加环境变量 `DEBUG=sdk` 来查看 HTTP 请求过程。
-
-## 忽略安全证书校验
-
-当您发送 https 请求时,它可能由于证书校验而失败。此时,可以使用下面的方法来忽略证书校验。
-
-```go
-// 您可以将 HTTPSInsecure 设置为 true 以忽略证书验证
-// 请求 HTTPSInsecure 具有比客户端 HTTPSInsecure 更高的优先级
-// 如果不设置任何 HTTPSInsecure,则默认 HTTPSInsecure 为 false
-
-// 设置请求 HTTPSInsecure (只影响当前)
-request.SetHTTPSInsecure(true)                           // 设置请求 HTTPSInsecure 为 true
-isInsecure := request.GetHTTPSInsecure()                 // 获取请求 HTTPSInsecure
 
-// 设置客户端 HTTPSInsecure (用于客户端发送的所有请求)。
-client.SetHTTPSInsecure(true)                         // 设置客户端 HTTPSInsecure 为 true
-isInsecure := client.GetHTTPSInsecure()               // 获取客户端 HTTPSInsecure
+	client, err := sdk.NewClientWithAccessKey("REGION_ID", "ACCESS_KEY_ID", "ACCESS_KEY_SECRET")
+	if err != nil {
+		// Handle exceptions
+		panic(err)
+	}
+}
 ```
 
-## HTTP 代理
-
-如果您想使用 http 代理, https 代理或者代理白名单,您可以设置环境变量 `HTTP_PROXY` 或者 `HTTPS_PROXY`或者 `NO_PROXY`,您也可以通过客户端来配置。
-
+### ROA 请求
 ```go
-// 客户端设置代理优先级比环境变量高
-client.SetHttpProxy("http://127.0.0.1:8080")   // 设置 Http 代理
-client.GetHttpProxy()                          // 获取 Http 代理.
-
-client.SetHttpsProxy("https://127.0.0.1:8080")   // 设置 Https 代理.
-client.GetHttpsProxy()                           // 获取 Https 代理.
-
-client.SetNoProxy("127.0.0.1,localhost")     // 设置代理白名单.
-client.GetNoProxy()                          // 获取代理白名单
-```
+package main
 
-## Keep-alive
-阿里云 Go SDK 底层使用 Go 语言原生的 `net/http` 收发请求,因此配置方式与 `net/http` 相同,您可以通过 config 直接将配置传递给底层的 httpClient
+import "github.com/aliyun/alibaba-cloud-sdk-go/sdk/requests"
 
-```go
-httpTransport := http.Transport{
-    // set http client options
+func main() {
+	request := requests.NewCommonRequest()        // 构造一个公共请求
+	request.Method = "GET"                        // 设置请求方式
+	request.Product = "CS"                        // 指定产品
+	request.Domain = "cs.aliyuncs.com"            // 指定域名则不会寻址,如认证方式为 Bearer Token 的服务则需要指定
+	request.Version = "2015-12-15"                // 指定产品版本
+	request.PathPattern = "/clusters/[ClusterId]" // 指定ROA风格路径规则
+	request.ApiName = "DescribeCluster"           // 指定接口名
+	request.QueryParams["ClusterId"] = "123456"   // 设置参数值
+	request.QueryParams["RegionId"] = "region_id" // 指定请求的区域,不指定则使用客户端区域、默认区域
+	request.TransToAcsRequest()                   // 把公共请求转化为acs请求
 }
-config := sdk.NewConfig()
-            .WithHttpTransport(&httpTransport)
-            .WithTimeout(timeout)
-ecsClient, err := ecs.NewClientWithOptions(config)
 ```
 
-## 并发请求
-
-* 因 Go 语言的并发特性,我们建议您在应用层面控制 SDK 的并发请求。
-* 为了方便您的使用,我们也提供了可直接使用的并发调用方式,相关的并发控制由 SDK 内部实现。
-
-### 超时机制
-
+### RPC 请求
 ```go
-// 请求设置的超时优先级高于客户端设置的超时.
-// 当您未设置任何超时时,则默认读超时为10秒,连接超时为5秒
-
-// 设置请求超时(仅对当前请求有效)
-request.SetReadTimeout(10 * time.Second)              // 设置请求读超时为10秒
-readTimeout := request.GetReadTimeout()              // 获取请求读超时
-request.SetConnectTimeout(5 * time.Second)           // 设置请求连接超时为5秒
-connectTimeout := request.GetConnectTimeout()        // 获取请求连接超时
-
-// 设置客户端超时(对所有通过该客户端发送的请求生效)
-client.SetReadTimeout(10 * time.Second)              // 设置客户端读超时为10秒
-readTimeout := client.GetReadTimeout()              // 获取客户端读超时
-client.SetConnectTimeout(5 * time.Second)           // 设置客户端连接超时为5秒
-connectTimeout := client.GetConnectTimeout()        // 获取客户端连接超时
-```
+package main
 
-### 开启 SDK Client 的并发功能
+import "github.com/aliyun/alibaba-cloud-sdk-go/sdk/requests"
 
-```go
-// 最大并发数
-poolSize := 2
-// 可缓存的最大请求数
-maxTaskQueueSize := 5
-
-// 在创建时开启异步功能
-config := sdk.NewConfig()
-            .WithEnableAsync(true)
-            .WithGoRoutinePoolSize(poolSize)            // 可选,默认5
-            .WithMaxTaskQueueSize(maxTaskQueueSize)     // 可选,默认1000
-ecsClient, err := ecs.NewClientWithOptions(config)
-
-// 也可以在client初始化后再开启
-client.EnableAsync(poolSize, maxTaskQueueSize)
+func main() {
+	request := requests.NewCommonRequest()                // 构造一个公共请求
+	request.Method = "POST"                               // 设置请求方式
+	request.Product = "Ecs"                               // 指定产品
+	request.Domain = "ecs.aliyuncs.com"                   // 指定域名则不会寻址,如认证方式为 Bearer Token 的服务则需要指定
+	request.Version = "2014-05-26"                        // 指定产品版本
+	request.ApiName = "CreateInstance"                    // 指定接口名
+	request.QueryParams["InstanceType"] = "ecs.g5.large"  // 设置参数值
+	request.QueryParams["RegionId"] = "region_id"         // 指定请求的区域,不指定则使用客户端区域、默认区域
+	request.TransToAcsRequest()                           // 把公共请求转化为acs请求
+}
 ```
 
-##### 发起异步调用
-阿里云Go SDK支持两种方式的异步调用:
-
-1. 使用channel作为返回值
-    ```go
-    responseChannel, errChannel := client.FooWithChan(request)
-
-    // this will block
-    response := <-responseChannel
-    err = <-errChannel
-    ```
-
-2. 使用 callback 控制回调
-
-    ```go
-    blocker := client.FooWithCallback(request, func(response *FooResponse, err error) {
-        // handle the response and err
-    })
 
-    // blocker 为(chan int),用于控制同步,返回1为成功,0为失败
-    // 在<-blocker返回失败时,err依然会被传入的callback处理
-    result := <-blocker
-    ```
+## 文档
+* [Requirements](docs/0-Requirements-CN.md)
+* [Installation](docs/1-Installation-CN.md)
+* [Client](docs/2-Client-CN.md)
+* [SSL Verify](docs/3-Verify-CN.md)
+* [Proxy](docs/4-Proxy-CN.md)
+* [Timeout](docs/5-Timeout-CN.md)
+* [Debug](docs/6-Debug-CN.md)
+* [Concurrent](docs/7-Concurrent-CN.md)
+* [Asynchronous Call](docs/8-Asynchronous-CN.md)
 
-## 泛化调用接口(CommonAPI)
 
-### 什么是 CommonAPI
+## 问题
+[提交 Issue][issue] 不符合指南的问题可能会立即关闭。
 
-CommonAPI 是阿里云 SDK 推出的,泛用型的 API 调用方式。CommonAPI 具有以下几个特点:
-1. 轻量:只需 Core 包即可发起调用,无需下载安装各产品线 SDK。
-2. 简便:无需更新 SDK 即可调用最新发布的 API。
-3. 快速迭代
 
-### 开始使用
+## 贡献
+提交 Pull Request 之前请阅读[贡献指南](CONTRIBUTING.md)。
 
-CommonAPI,需要配合相应的 API 文档使用,以查询 API 的相关信息。
+## 相关
+* [阿里云服务 Regions & Endpoints][endpoints]
+* [OpenAPI Explorer][open-api]
+* [Go][go]
+* [最新发行版本][latest-release]
 
-您可以在 [文档中心](https://help.aliyun.com/?spm=5176.8142029.388261.173.23896dfaav2hEF) 查询到所有产品的 API 文档。
-
-发起一次 CommonAPI 请求,需要您查询到以下几个参数:
-* 域名(domain):即该产品的通用访问域名,一般可以在"调用方式"页查看到
-* API 版本(version):即该 API 的版本号,以’YYYY-MM-DD’的形式表现,一般可以在"公共参数"页面查到
-* 接口名称(apiName):即该 API 的名称
-
-我们以 ECS 产品的 [DescribeInstanceStatus API](https://help.aliyun.com/document_detail/25505.html?spm=5176.doc25506.6.820.VbHnW6) 为例
-
-```go
-package main
-
-import (
-	"fmt"
-	"os"
-
-	"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
-	"github.com/aliyun/alibaba-cloud-sdk-go/sdk/requests"
-)
-
-func main() {
-
-	client, err := sdk.NewClientWithAccessKey("cn-hangzhou", os.Getenv("ACCESS_KEY_ID"), os.Getenv("ACCESS_KEY_SECRET"))
-	if err != nil {
-		// 异常处理
-		panic(err)
-	}
-
-	request := requests.NewCommonRequest()
-	request.Domain = "ecs.aliyuncs.com"
-	request.Version = "2014-05-26"
-	request.ApiName = "DescribeInstanceStatus"
-
-	request.QueryParams["PageNumber"] = "1"
-	request.QueryParams["PageSize"] = "30"
-
-	response, err := client.ProcessCommonRequest(request)
-	if err != nil {
-		// 异常处理
-		panic(err)
-	}
-
-	fmt.Print(response.GetHttpContentString())
-}
-```
 
 ## 许可证
 [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Faliyun%2Falibaba-cloud-sdk-go.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Faliyun%2Falibaba-cloud-sdk-go?ref=badge_large)
+
+[SDK]: https://github.com/aliyun/alibaba-cloud-sdk-go
+[apache]: http://www.apache.org/licenses/LICENSE-2.0
+[issue]: https://github.com/aliyun/alibaba-cloud-sdk-go/issues/new
+[open-api]: https://api.aliyun.com/
+[latest-release]: https://github.com/aliyun/alibaba-cloud-sdk-go/releases
+[go]: https://golang.org/dl/
+[endpoints]: https://developer.aliyun.com/endpoints

+ 11 - 0
docs/0-Requirements-CN.md

@@ -0,0 +1,11 @@
+[← 首页](../README_zh.md) | 环境要求[(English)](0-Requirements-EN.md) | [安装 →](1-Installation-CN.md)
+***
+
+## 要求
+- Go 环境版本必须不低于 1.10.x.
+
+## 建议
+- 请确保您的项目中没有其他依赖跟 Alibaba Cloud SDK for Go 存在冲突。你可以在[Gopkg.toml](../Gopkg.toml)查看相关的约束。
+
+***
+[← 首页](../README_zh.md) | 环境要求[(English)](0-Requirements-EN.md) | [安装 →](1-Installation-CN.md)

+ 11 - 0
docs/0-Requirements-EN.md

@@ -0,0 +1,11 @@
+[← Home](../README.md) | Requirements[(中文)](0-Requirements-CN.md) | [Installation →](1-Installation-EN.md)
+***
+
+## Requirements
+- You must use Go 1.10.x or later.
+
+## Recommendations
+- Please make sure there will be no conflict between Alibaba Cloud SDK for Go and other. You can see specific constraints in [Gopkg.toml](../Gopkg.toml).
+
+***
+[← Home](../README.md) | Requirements[(中文)](0-Requirements-CN.md) | [Installation →](1-Installation-EN.md)

+ 24 - 0
docs/1-Installation-CN.md

@@ -0,0 +1,24 @@
+[← 环境要求](0-Requirements-CN.md) | 安装[(English)](1-Installation-EN.md) | [客户端 →](2-Client-CN.md)
+***
+
+## 通过命令安装
+使用 `go get` 下载安装 SDK
+
+```sh
+$ go get -u github.com/aliyun/alibaba-cloud-sdk-go/sdk
+```
+
+如果您使用了 glide 管理依赖,您也可以使用 glide 来安装阿里云GO SDK
+
+```sh
+$ glide get github.com/aliyun/alibaba-cloud-sdk-go
+```
+
+## 通过压缩文件安装
+Alibaba Cloud SDK for Go 中的一个 ZIP 文件包含运行开发工具包所需的所有类和依赖项。
+下载这个 [文件][Go-release], 然后在项目中的选定位置进行解压缩。
+
+***
+[← 环境要求](0-Requirements-CN.md) | 安装[(English)](1-Installation-EN.md) | [客户端 →](2-Client-CN.md)
+
+[Go-release]: https://github.com/aliyun/alibaba-cloud-sdk-go/releases

+ 25 - 0
docs/1-Installation-EN.md

@@ -0,0 +1,25 @@
+[← Requirements](0-Requirements-EN.md) | Installation[(中文)](1-Installation-CN.md) | [Client →](2-Client-EN.md)
+***
+
+## Installation by Using command
+Use `go get` to install SDK:
+
+```sh
+$ go get -u github.com/aliyun/alibaba-cloud-sdk-go/sdk
+```
+
+If you have used glide to manage dependence,you can also use glide to install Alibaba Cloud Go SDK:
+
+```sh
+$ glide get github.com/aliyun/alibaba-cloud-sdk-go
+```
+
+## Installing by Using the ZIP file
+The Alibaba Cloud SDK for Go includes a ZIP file containing all the classes and dependencies you need to run.
+
+Download the [file][Go-release], and then extract it into your project at a location you choose.
+
+***
+[← Requirements](0-Requirements-EN.md) | Installation[(中文)](1-Installation-CN.md) | [Client →](2-Client-EN.md)
+
+[Go-release]: https://github.com/aliyun/alibaba-cloud-sdk-go/releases

+ 112 - 0
docs/2-Client-CN.md

@@ -0,0 +1,112 @@
+[← 安装](1-Installation-CN.md) | 客户端[(English)](2-Client-EN.md) | [SSL 验证 →](3-Verify-CN.md)
+***
+
+# 客户端
+您可以同时创建多个不同的客户端,每个客户端都可以有独立的配置,每一个请求都可以指定发送的客户端,如果不指定则使用默认客户端。客户端可以通过配置文件自动加载创建,也可以手动创建、管理。不同类型的客户端需要不同的凭证 `Credential`,内部也选取不同的签名算法 `Signature`,您也可以自定义客户端:即传入自定义的凭证和签名。
+## 客户端类型
+
+### AccessKey 客户端
+通过[用户信息管理][ak]设置AccessKey,它们具有该账户完全的权限,请妥善保管。有时出于安全考虑,您不能把具有完全访问权限的主账户 AccessKey 交于一个项目的开发者使用,您可以[创建RAM子账户][ram]并为子账户[授权][permissions],使用RAM子用户的 AccessKey 来进行API调用。 
+
+```go
+client, err := sdk.NewClientWithAccessKey("regionId", "accessKeyId", "accessKeySecret")
+
+```
+
+
+### STS 客户端
+通过安全令牌服务(Security Token Service,简称 STS),申请临时安全凭证(Temporary Security Credentials,简称 TSC),创建临时安全客户端。
+
+```go
+client, err := sdk.NewClientWithStsToken("regionId", "subaccessKeyId", "subaccessKeySecret", "stsToken")
+```
+
+
+### RamRoleArn 客户端
+通过指定[RAM角色][RAM Role],让客户端在发起请求前自动申请维护 STS Token,自动转变为一个有时限性的STS客户端。您也可以自行申请维护 STS Token,再创建 `STS客户端`。  
+> 示例代码:创建一个 RamRoleArn 方式认证的客户端。
+
+```go
+client, err := sdk.NewClientWithRamRoleArn("regionId", "subaccessKeyId", "subaccessKeySecret", "roleArn", "roleSession")
+```
+
+
+### EcsRamRole 客户端
+通过指定角色名称,让客户端在发起请求前自动申请维护 STS Token,自动转变为一个有时限性的STS客户端。您也可以自行申请维护 STS Token,再创建 `STS客户端`。  
+> 示例代码:创建一个 EcsRamRole 方式认证的客户端。
+
+```go
+client, err := NewClientWithEcsRamRole("regionid", "roleName")
+```
+
+
+### Bearer Token 客户端
+如呼叫中心(CCC)需用此类认证方式的客户端,请自行申请维护 Bearer Token。  
+> 示例代码:创建一个 Bearer Token 方式认证的客户端。
+
+```go
+client, err := NewClientWithBearerToken("regionId", "bearerToken")
+```
+
+
+### RsaKeyPair 客户端
+通过指定公钥ID和私钥文件,让客户端在发起请求前自动申请维护 AccessKey,自动转变成为一个有时限性的AccessKey客户端,仅支持日本站。  
+> 示例代码:创建一个 RsaKeyPair 方式认证的客户端。
+
+
+```go
+client, err := NewClientWithRsaKeyPair("regionid", "publicKey", "privateKey", 3600)
+```
+
+## 自动创建客户端
+在发送请求前,如果没有创建任何客户端,将使用默认凭证提供程序链创建客户端,也可以自定义程序链。
+
+### 默认凭证提供程序链
+默认凭证提供程序链查找可用的客户端,寻找顺序如下:
+
+#### 1. 环境凭证
+程序首先会在环境变量里寻找环境凭证,如果定义了 `ALIBABA_CLOUD_ACCESS_KEY_ID`  和 `ALIBABA_CLOUD_ACCESS_KEY_SECRET` 环境变量且不为空,程序将使用他们创建默认客户端。如果请求指定的客户端不是默认客户端,程序会在配置文件中加载和寻找客户端。
+
+#### 2. 配置文件
+> 如果用户主目录存在默认文件 `~/.alibabacloud/credentials` (Windows 为 `C:\Users\USER_NAME\.alibabacloud\credentials`),程序会自动创建指定类型和名称的客户端。默认文件可以不存在,但解析错误会抛出异常。  客户端名称不分大小写,若客户端同名,后者会覆盖前者。也可以手动加载指定文件: `AlibabaCloud::load('/data/credentials', 'vfs://AlibabaCloud/credentials', ...);` 不同的项目、工具之间可以共用这个配置文件,因为超出项目之外,也不会被意外提交到版本控制。Windows 上可以使用环境变量引用到主目录 %UserProfile%。类 Unix 的系统可以使用环境变量 $HOME 或 ~ (tilde)。 可以通过定义 `ALIBABA_CLOUD_CREDENTIALS_FILE` 环境变量修改默认文件的路径。
+
+```ini
+[default]                          # 默认客户端
+type = access_key                  # 认证方式为 access_key
+access_key_id = foo                # Key
+access_key_secret = bar            # Secret
+
+[client1]                          # 命名为 `client1` 的客户端
+type = ecs_ram_role                # 认证方式为 ecs_ram_role
+role_name = EcsRamRoleTest         # Role Name
+
+[client2]                          # 命名为 `client2` 的客户端
+type = ram_role_arn                # 认证方式为 ram_role_arn
+access_key_id = foo
+access_key_secret = bar
+role_arn = role_arn
+role_session_name = session_name
+
+[client3]                          # 命名为 `client3` 的客户端
+type = rsa_key_pair                # 认证方式为 rsa_key_pair
+public_key_id = publicKeyId        # Public Key ID
+private_key_file = /your/pk.pem    # Private Key 文件
+
+```
+
+#### 3. 实例 RAM 角色
+如果定义了环境变量 `ALIBABA_CLOUD_ECS_METADATA` 且不为空,程序会将该环境变量的值作为角色名称,请求 `http://100.100.100.200/latest/meta-data/ram/security-credentials/` 获取临时安全凭证,再创建一个默认客户端。
+
+### 自定义凭证提供程序链
+可通过自定义程序链代替默认程序链的寻找顺序,也可以自行编写闭包传入提供者。
+```go
+client, err := sdk.NewClientWithProvider("regionId", ProviderInstance, ProviderProfile, ProviderEnv)
+```
+
+***
+[← 安装](1-Installation-CN.md) | 客户端[(English)](2-Client-EN.md) | [SSL 验证 →](3-Verify-CN.md)
+
+[ak]: https://usercenter.console.aliyun.com/#/manage/ak
+[ram]: https://ram.console.aliyun.com/users
+[permissions]: https://ram.console.aliyun.com/permissions
+[RAM Role]: https://ram.console.aliyun.com/#/role/list

+ 115 - 0
docs/2-Client-EN.md

@@ -0,0 +1,115 @@
+[← Installation](1-Installation-EN.md) | Client[(中文)](2-Client-CN.md) | [SSL Verify →](3-Verify-EN.md)
+***
+
+# Client
+You may create multiple different clients simultaneously. Each client can have its own configuration, and each request can be sent by specified client. Use the Default Client if it is not specified. The client can be created by auto-loading of the configuration files, or created and managed manually. Different types of clients require different `Credential`,and different `Signature` algorithms that are selected. You may also customize the client: that is, pass in custom credentials and signatures.
+
+## Client Type
+
+### AccessKey Client
+Setup AccessKey through [User Information Management][ak], they have full authority over the account, please keep them safe. Sometimes for security reasons, you cannot hand over a primary account AccessKey with full access to the developer of a project. You may create a sub-account [RAM Sub-account][ram] , grant its [authorization][permissions],and use the AccessKey of RAM Sub-account to make API calls.
+> Sample Code: Create a client with a certification type AccessKey.
+
+```go
+client, err := sdk.NewClientWithAccessKey("regionId", "accessKeyId", "accessKeySecret")
+
+```
+
+
+### STS Client
+Create a temporary security client by applying Temporary Security Credentials (TSC) through the Security Token Service (STS).
+> Sample Code: Create a client with a certification type StsToken.
+
+```go
+client, err := sdk.NewClientWithStsToken("regionId", "subaccessKeyId", "subaccessKeySecret", "stsToken")
+```
+
+
+### RamRoleArn Client
+By specifying [RAM Role][RAM Role], the client will be able to automatically request maintenance of STS Token before making a request, and be automatically converted to a time-limited STS client. You may also apply for Token maintenance by yourself before creating `STS Client`.  
+> Sample Code: Create a client with a certification type RamRoleArn.
+
+```go
+client, err := sdk.NewClientWithRamRoleArn("regionId", "subaccessKeyId", "subaccessKeySecret", "roleArn", "roleSession")
+```
+
+
+### EcsRamRole Client
+By specifying the role name, the client will be able to automatically request maintenance of STS Token before making a request, and be automatically converted to a time-limited STS client. You may also apply for Token maintenance by yourself before creating `STS Client`.  
+> Sample Code: Create a client with a certification type EcsRamRole.
+
+```go
+client, err := NewClientWithEcsRamRole("regionid", "roleName")
+```
+
+
+### Bearer Token Client
+If clients with this certification type are required by the Cloud Call Centre (CCC), please apply for Bearer Token maintenance by yourself.
+> Sample Code: Create a client with a certification type Bearer Token.
+
+```go
+client, err := NewClientWithBearerToken("regionId", "bearerToken")
+```
+
+
+### RsaKeyPair Client
+By specifying the public key ID and the private key file, the client will be able to automatically request maintenance of the AccessKey before sending the request, and be automatically converted to a time-limited AccessKey client. Only Japan station is supported. 
+> Sample Code: Create a client with a certification type RsaKeyPair.
+
+```go
+client, err := NewClientWithRsaKeyPair("regionid", "publicKey", "privateKey", 3600)
+```
+
+## Create the client automatically
+If no client is created before the request is sent, the client will be created using the default credential provider chain, or the program chain can be customized.
+
+### Default Credential Provider Chain
+The default credential provider chain looks for available clients, looking in the following order:
+
+#### 1. Environment Credentials
+The program first looks for environment credentials in the environment variable. If the `ALIBABA_CLOUD_ACCESS_KEY_ID` and `ALIBABA_CLOUD_ACCESS_KEY_SECRET` environment variables are defined and are not empty, the program will use them to create the default client. If the client specified by the request is not the default client, the program loads and looks for the client in the configuration file.
+
+#### 2. Credentials File
+> If there is `~/.alibabacloud/credentials` default file (Windows shows `C:\Users\USER_NAME\.alibabacloud\credentials`), the program will automatically create clients with the specified type and name. The default file may not exist, but a parse error throws an exception. The client name is case-insensitive, and if the clients have the same name, the latter will override the former. The specified files can also be loaded indefinitely: `AlibabaCloud::load('/data/credentials', 'vfs://AlibabaCloud/credentials', ...);` This configuration file can be shared between different projects and between different tools.  Because it is outside the project and will not be accidentally committed to the version control. Environment variables can be used on Windows to refer to the home directory %UserProfile%. Unix-like systems can use the environment variable $HOME or ~ (tilde). The path to the default file can be modified by defining the `ALIBABA_CLOUD_CREDENTIALS_FILE` environment variable.
+
+```ini
+[default]                          # Default client
+type = access_key                  # Certification type: access_key
+access_key_id = foo                # Key
+access_key_secret = bar            # Secret
+
+[client1]                          # Client that is named as `client1`
+type = ecs_ram_role                # Certification type: ecs_ram_role
+role_name = EcsRamRoleTest         # Role Name
+
+[client2]                          # Client that is named as `client2` 
+type = ram_role_arn                # Certification type: ram_role_arn
+access_key_id = foo
+access_key_secret = bar
+role_arn = role_arn
+role_session_name = session_name
+
+
+[client3]                          # Client that is named as `client3`
+type = rsa_key_pair                # Certification type: rsa_key_pair
+public_key_id = publicKeyId        # Public Key ID
+private_key_file = /your/pk.pem    # Private Key file
+
+```
+
+#### 3. Instance RAM Role
+If the environment variable `ALIBABA_CLOUD_ECS_METADATA` is defined and not empty, the program will take the value of the environment variable as the role name and request `http://100.100.100.200/latest/meta-data/ram/security-credentials/` to get the temporary Security credentials, then create a default client.
+
+### Custom Credential Provider Chain
+You can replace the default order of the program chain by customizing the program chain, or you can write the closure to the provider.
+```go
+client, err := sdk.NewClientWithProvider("regionId", ProviderInstance, ProviderProfile, ProviderEnv)
+```
+
+***
+[← Installation](1-Installation-EN.md) | Client[(中文)](2-Client-CN.md) | [SSL Verify →](3-Verify-EN.md)
+
+[ak]: https://usercenter.console.aliyun.com/#/manage/ak
+[ram]: https://ram.console.aliyun.com/users
+[permissions]: https://ram.console.aliyun.com/permissions
+[RAM Role]: https://ram.console.aliyun.com/#/role/list

+ 32 - 0
docs/3-Verify-CN.md

@@ -0,0 +1,32 @@
+[← 客户端](2-Client-CN.md) | SSL 验证[(English)](3-Verify-EN.md) | [代理 →](4-Proxy-CN.md)
+***
+
+# SSL 验证
+
+## 摘要
+请求时验证SSL证书行为。
+- 设置成 `false` 禁用证书验证,(这是不安全的,请设置证书!)。
+- 设置成 `true` 启用SSL证书验证,默认使用操作系统提供的CA包。
+
+## 默认值
+- `false` 
+
+## 设置
+### 通过请求设置
+```go
+// 设置请求 HTTPSInsecure (只影响当前)
+request.SetHTTPSInsecure(true)                           // 设置请求 HTTPSInsecure 为 true
+isInsecure := request.GetHTTPSInsecure()                 // 获取请求 HTTPSInsecure
+```
+
+### 通过客户端设置
+> 当请求未设置时,客户端设置才能生效.
+
+```go
+// 设置客户端 HTTPSInsecure (用于客户端发送的所有请求)。
+client.SetHTTPSInsecure(true)                         // 设置客户端 HTTPSInsecure 为 true
+isInsecure := client.GetHTTPSInsecure()               // 获取客户端 HTTPSInsecure
+```
+
+***
+[← 客户端](2-Client-CN.md) | SSL 验证[(English)](3-Verify-EN.md) | [代理 →](4-Proxy-CN.md)

+ 32 - 0
docs/3-Verify-EN.md

@@ -0,0 +1,32 @@
+[← Client](2-Client-EN.md) | SSL Verify[(中文)](3-Verify-CN.md) | [Proxy →](4-Proxy-EN.md)
+***
+
+# SSL Verify
+
+## Summary
+Describes the SSL certificate verification behavior of a request.
+- Set `false` to disable certificate validation, (This is not safe, please set certificates! )
+- Set to `true` to enable SSL certificate verification and use the default CA bundle provided by operating system.
+
+## Default
+- `false` 
+
+## Setting
+### Setting on Request
+```go
+// Set request HTTPSInsecure(Only the request is effected.)
+request.SetHTTPSInsecure(true)                           // Set request HTTPSInsecure to true.
+isInsecure := request.GetHTTPSInsecure()                 // Get request HTTPSInsecure.
+```
+
+### Setting on Client
+> When the request is not set, the client settings are used.
+
+```go
+// Set client HTTPSInsecure(For all requests which is sent by the client.)
+client.SetHTTPSInsecure(true)                         // Set client HTTPSInsecure to true.
+isInsecure := client.GetHTTPSInsecure()               // Get client HTTPSInsecure.
+```
+
+***
+[← Client](2-Client-EN.md) | SSL Verify[(中文)](3-Verify-CN.md) | [Proxy →](4-Proxy-EN.md)

+ 31 - 0
docs/4-Proxy-CN.md

@@ -0,0 +1,31 @@
+[← SSL 验证](3-Verify-CN.md) | 代理[(English)](4-Proxy-EN.md) | [超时 →](5-Timeout-CN.md)
+***
+
+# 代理
+
+## 描述
+当你需要使用代理来发送你的请求时,你可以通过设置环境变量或者通过客户端来设置代理。
+`HTTP_PROXY`: 仅对 http 请求有效。
+`HTTPS_PROXY`: 仅对 https 请求有效。
+`NO_PROXY`: NO_PROXY 中的 ip 或者域名不使用代理。
+
+## 设置
+
+### 通过环境变量设置
+你可以设置环境变量 `HTTP_PROXY`, `HTTPS_PROXY` 或者 `NO_PROXY` 。
+
+### 通过客户端设置
+```go
+// 客户端设置代理优先级比环境变量高
+client.SetHttpProxy("http://127.0.0.1:8080")   // 设置 Http 代理
+client.GetHttpProxy()                          // 获取 Http 代理.
+
+client.SetHttpsProxy("https://127.0.0.1:8080")   // 设置 Https 代理.
+client.GetHttpsProxy()                           // 获取 Https 代理.
+
+client.SetNoProxy("127.0.0.1,localhost")     // 设置代理白名单.
+client.GetNoProxy()                          // 获取代理白名单
+```
+
+***
+[← SSL 验证](3-Verify-CN.md) | 代理[(English)](4-Proxy-EN.md) | [超时 →](5-Timeout-CN.md)

+ 31 - 0
docs/4-Proxy-EN.md

@@ -0,0 +1,31 @@
+[← SSL Verify](3-Verify-EN.md) | Proxy[(中文)](4-Proxy-CN.md) | [Timeout →](5-Timeout-EN.md)
+***
+
+# Proxy
+
+## Description
+When you need to use proxy to send your request, you can set environment variables or you can set them by client:
+`HTTP_PROXY`: Only the HTTP request to take effect.
+`HTTPS_PROXY`: Only the HTTPS request to take effect.
+`NO_PROXY`: The Ips or domains in it will not use proxy.
+
+## Setting
+
+### Setting by environment variables
+You can set environment variables `HTTP_PROXY`, `HTTPS_PROXY` or `NO_PROXY`
+
+### Setting by client
+```go
+// client proxy has a high priority than environment variables.
+client.SetHttpProxy("http://127.0.0.1:8080")   // Set Http Proxy.
+client.GetHttpProxy()                          // Get Http Proxy.
+
+client.SetHttpsProxy("https://127.0.0.1:8080")   // Set Https Proxy.
+client.GetHttpsProxy()                           // Get Https Proxy.
+
+client.SetNoProxy("127.0.0.1,localhost")     // Set No Proxy.
+client.GetNoProxy()                          // Get No Proxy.
+```
+
+***
+[← SSL Verify](3-Verify-EN.md) | Proxy[(中文)](4-Proxy-CN.md) | [Timeout →](5-Timeout-EN.md)

+ 35 - 0
docs/5-Timeout-CN.md

@@ -0,0 +1,35 @@
+[← 代理](4-Proxy-CN.md) | 超时[(English)](5-Timeout-EN.md) | [调试 →](6-Debug-CN.md)
+***
+
+# 超时
+
+## 描述
+如果你想限制请求花费的时间,你可以通过请求或者客户端设置 `ReadTimeout` 和 `ConnectTimeout`。
+
+## 默认值
+- `defaultConnectTimeout`: 5 秒
+- `defaultReadTimeout`: 10 秒
+
+## 设置
+### 通过请求设置
+```go
+// 设置请求超时(仅对当前请求有效)
+request.SetReadTimeout(10 * time.Second)             // 设置请求读超时为10秒
+readTimeout := request.GetReadTimeout()              // 获取请求读超时
+request.SetConnectTimeout(5 * time.Second)           // 设置请求连接超时为5秒
+connectTimeout := request.GetConnectTimeout()        // 获取请求连接超时
+```
+
+### 通过客户端设置
+> 当请求未设置超时时,客户端设置的超时才会生效。
+
+```go
+// 设置客户端超时(对所有通过该客户端发送的请求生效)
+client.SetReadTimeout(10 * time.Second)             // 设置客户端读超时为10秒
+readTimeout := client.GetReadTimeout()              // 获取客户端读超时
+client.SetConnectTimeout(5 * time.Second)           // 设置客户端连接超时为5秒
+connectTimeout := client.GetConnectTimeout()        // 获取客户端连接超时
+```
+
+***
+[← 代理](4-Proxy-CN.md) | 超时[(English)](5-Timeout-EN.md) | [调试 →](6-Debug-CN.md)

+ 35 - 0
docs/5-Timeout-EN.md

@@ -0,0 +1,35 @@
+[← Proxy](4-Proxy-EN.md) | Timeout[(中文)](5-Timeout-CN.md) | [Debug →](6-Debug-EN.md)
+***
+
+# Timeout
+
+## Description
+When you want to limit the time of request costing, you can set `ReadTimeout` and `ConnectTimeout` by request or client:
+
+## Default
+- `defaultConnectTimeout`: 5 * time.Second
+- `defaultReadTimeout`: 10 * time.Second
+
+## Setting
+### Setting on Request
+```go
+// Set request Timeout(Only the request is effected.)
+request.SetReadTimeout(10 * time.Second)             // Set request ReadTimeout to 10 second.
+readTimeout := request.GetReadTimeout()              // Get request ReadTimeout.
+request.SetConnectTimeout(5 * time.Second)           // Set request ConnectTimeout to 5 second.
+connectTimeout := request.GetConnectTimeout()        // Get request ConnectTimeout.
+```
+
+### Setting on Client
+> When the request is not set, the client settings are used.
+
+```go
+// Set client Timeout(For all requests which is sent by the client.)
+client.SetReadTimeout(10 * time.Second)              // Set client ReadTimeout to 10 second.
+readTimeout := client.GetReadTimeout()               // Get client ReadTimeout.
+client.SetConnectTimeout(5 * time.Second)            // Set client ConnectTimeout to 5 second.
+connectTimeout := client.GetConnectTimeout()         // Get client ConnectTimeout.
+```
+
+***
+[← Proxy](4-Proxy-EN.md) | Timeout[(中文)](5-Timeout-CN.md) | [Debug →](6-Debug-EN.md)

+ 8 - 0
docs/6-Debug-CN.md

@@ -0,0 +1,8 @@
+[← 超时](5-Timeout-CN.md) | 调试[(English)](6-Debug-EN.md) | [并发 →](7-Concurrent-CN.md)
+***
+
+# 调试
+如果环境变量 `DEBUG=sdk` 存在, 所有的请求都将启用调试模式。
+
+***
+[← 超时](5-Timeout-CN.md) | 调试[(English)](6-Debug-EN.md) | [并发 →](7-Concurrent-CN.md)

+ 8 - 0
docs/6-Debug-EN.md

@@ -0,0 +1,8 @@
+[← Timeout](5-Timeout-EN.md) | Debug[(中文)](6-Debug-CN.md) | [Concurrent →](7-Concurrent-EN.md)
+***
+
+# Debugging
+If there is an environment variable `DEBUG=sdk` , all requests will enable debug mode.
+
+***
+[← Timeout](5-Timeout-EN.md) | Debug[(中文)](6-Debug-CN.md) | [Concurrent →](7-Concurrent-EN.md)

+ 29 - 0
docs/7-Concurrent-CN.md

@@ -0,0 +1,29 @@
+[← 调试](6-Debug-CN.md) | 并发[(English)](7-Concurrent-EN.md) | [异步调用 →](8-Asynchronous-CN.md)
+***
+
+## 并发请求
+
+* 因 Go 语言的并发特性,我们建议您在应用层面控制 SDK 的并发请求。
+* 为了方便您的使用,我们也提供了可直接使用的并发调用方式,相关的并发控制由 SDK 内部实现。
+
+### 开启 SDK Client 的并发功能
+
+```go
+// 最大并发数
+poolSize := 2
+// 可缓存的最大请求数
+maxTaskQueueSize := 5
+
+// 在创建时开启异步功能
+config := sdk.NewConfig()
+            .WithEnableAsync(true)
+            .WithGoRoutinePoolSize(poolSize)            // 可选,默认5
+            .WithMaxTaskQueueSize(maxTaskQueueSize)     // 可选,默认1000
+ecsClient, err := ecs.NewClientWithOptions(config)
+
+// 也可以在client初始化后再开启
+client.EnableAsync(poolSize, maxTaskQueueSize)
+```
+
+***
+[← 调试](6-Debug-CN.md) | 并发[(English)](7-Concurrent-EN.md) | [异步调用 →](8-Asynchronous-CN.md)

+ 29 - 0
docs/7-Concurrent-EN.md

@@ -0,0 +1,29 @@
+[← Debug](6-Debug-EN.md) | Concurrent[(中文)](7-Concurrent-CN.md) | [Asynchronous Call →](8-Asynchronous-EN.md)
+***
+
+## Concurrent Request
+
+* Due to the concurrency nature of the Go language, we recommend that you control the concurrent requests for the SDK at the application level.
+* In order to facilitate your use, we also provide a direct use of concurrent invocation mode, the relevant concurrency control by the SDK internal implementation.
+
+### Open SDK Client's concurrent function.
+
+```go
+// Maximum Running Vusers
+poolSize := 2
+// The maximum number of requests that can be cached
+maxTaskQueueSize := 5
+
+// Enable asynchronous functionality at creation time
+config := sdk.NewConfig()
+            .WithEnableAsync(true)
+            .WithGoRoutinePoolSize(poolSize)            // Optional,default:5
+            .WithMaxTaskQueueSize(maxTaskQueueSize)     // Optional,default:1000
+ecsClient, err := ecs.NewClientWithOptions(config)
+
+// It can also be opened after client is initialized
+client.EnableAsync(poolSize, maxTaskQueueSize)
+```
+
+***
+[← Debug](6-Debug-EN.md) | Concurrent[(中文)](7-Concurrent-CN.md) | [Asynchronous Call →](8-Asynchronous-EN.md)

+ 30 - 0
docs/8-Asynchronous-CN.md

@@ -0,0 +1,30 @@
+[← 并发](7-Concurrent-CN.md) | 异步调用[(English)](8-Asynchronous-EN.md) | [首页 →](../README_zh.md)
+***
+## 异步调用
+
+### 发起异步调用
+阿里云Go SDK支持两种方式的异步调用:
+
+1. 使用channel作为返回值
+    ```go
+    responseChannel, errChannel := client.FooWithChan(request)
+
+    // this will block
+    response := <-responseChannel
+    err = <-errChannel
+    ```
+
+2. 使用 callback 控制回调
+
+    ```go
+    blocker := client.FooWithCallback(request, func(response *FooResponse, err error) {
+        // handle the response and err
+    })
+
+    // blocker 为(chan int),用于控制同步,返回1为成功,0为失败
+    // 在<-blocker返回失败时,err依然会被传入的callback处理
+    result := <-blocker
+    ```
+
+***
+[← 并发](7-Concurrent-CN.md) | 异步调用[(English)](8-Asynchronous-EN.md) | [首页 →](../README_zh.md)

+ 30 - 0
docs/8-Asynchronous-EN.md

@@ -0,0 +1,30 @@
+[← Concurrent](7-Concurrent-EN.md) | Asynchronous Call[(中文)](8-Asynchronous-CN.md) | [Home →](../README.md)
+***
+## Asynchronous Call
+
+### Make an asynchronous call
+Alibaba Cloud Go SDK supports asynchronous calls in two ways:
+
+1. Using channel as return values
+    ```go
+    responseChannel, errChannel := client.FooWithChan(request)
+
+    // this will block
+    response := <-responseChannel
+    err = <-errChannel
+    ```
+
+2. Use callback to control the callback
+
+    ```go
+    blocker := client.FooWithCallback(request, func(response *FooResponse, err error) {
+        // handle the response and err
+    })
+
+    // blocker which is type of (chan int),is used to control synchronization,when returning 1 means success,and returning 0 means failure.
+    // When <-blocker returns failure,err also will be handled by afferent callback.
+    result := <-blocker
+    ```
+
+***
+[← Concurrent](7-Concurrent-EN.md) | Asynchronous Call[(中文)](8-Asynchronous-CN.md) | [Home →](../README.md)