README-CN.md
1# Aliyun OSS SDK for Go
2
3[](https://badge.fury.io/gh/aliyun%2Faliyun-oss-go-sdk)
4[](https://travis-ci.org/aliyun/aliyun-oss-go-sdk)
5[](https://coveralls.io/github/aliyun/aliyun-oss-go-sdk?branch=master)
6
7## [README of English](https://github.com/aliyun/aliyun-oss-go-sdk/blob/master/README.md)
8
9## 关于
10> - 此Go SDK基于[阿里云对象存储服务](http://www.aliyun.com/product/oss/)官方API构建。
11> - 阿里云对象存储（Object Storage Service，简称OSS），是阿里云对外提供的海量，安全，低成本，高可靠的云存储服务。
12> - OSS适合存放任意文件类型，适合各种网站、开发企业及开发者使用。
13> - 使用此SDK，用户可以方便地在任何应用、任何时间、任何地点上传，下载和管理数据。
14
15## 版本
16> - Current version: v2.0.4
17
18## 运行环境
19> - Go 1.5及以上。
20
21## 安装方法
22### GitHub安装
23> - 执行命令`go get github.com/aliyun/aliyun-oss-go-sdk/oss`获取远程代码包。
24> - 在您的代码中使用`import "github.com/aliyun/aliyun-oss-go-sdk/oss"`引入OSS Go SDK的包。
25
26## 快速使用
27#### 获取存储空间列表（List Bucket）
28```go
29 client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
30 if err != nil {
31 // HandleError(err)
32 }
33
34 lsRes, err := client.ListBuckets()
35 if err != nil {
36 // HandleError(err)
37 }
38
39 for _, bucket := range lsRes.Buckets {
40 fmt.Println("Buckets:", bucket.Name)
41 }
42```
43
44#### 创建存储空间（Create Bucket）
45```go
46 client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
47 if err != nil {
48 // HandleError(err)
49 }
50
51 err = client.CreateBucket("my-bucket")
52 if err != nil {
53 // HandleError(err)
54 }
55```
56
57#### 删除存储空间（Delete Bucket）
58```go
59 client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
60 if err != nil {
61 // HandleError(err)
62 }
63
64 err = client.DeleteBucket("my-bucket")
65 if err != nil {
66 // HandleError(err)
67 }
68```
69
70#### 上传文件（Put Object）
71```go
72 client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
73 if err != nil {
74 // HandleError(err)
75 }
76
77 bucket, err := client.Bucket("my-bucket")
78 if err != nil {
79 // HandleError(err)
80 }
81
82 err = bucket.PutObjectFromFile("my-object", "LocalFile")
83 if err != nil {
84 // HandleError(err)
85 }
86```
87
88#### 下载文件 (Get Object)
89```go
90 client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
91 if err != nil {
92 // HandleError(err)
93 }
94
95 bucket, err := client.Bucket("my-bucket")
96 if err != nil {
97 // HandleError(err)
98 }
99
100 err = bucket.GetObjectToFile("my-object", "LocalFile")
101 if err != nil {
102 // HandleError(err)
103 }
104```
105
106#### 获取文件列表（List Objects）
107```go
108 client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
109 if err != nil {
110 // HandleError(err)
111 }
112
113 bucket, err := client.Bucket("my-bucket")
114 if err != nil {
115 // HandleError(err)
116 }
117
118 lsRes, err := bucket.ListObjects()
119 if err != nil {
120 // HandleError(err)
121 }
122
123 for _, object := range lsRes.Objects {
124 fmt.Println("Objects:", object.Key)
125 }
126```
127
128#### 删除文件(Delete Object)
129```go
130 client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
131 if err != nil {
132 // HandleError(err)
133 }
134
135 bucket, err := client.Bucket("my-bucket")
136 if err != nil {
137 // HandleError(err)
138 }
139
140 err = bucket.DeleteObject("my-object")
141 if err != nil {
142 // HandleError(err)
143 }
144```
145
146#### 其它
147更多的示例程序，请参看OSS Go SDK安装路径（即GOPATH变量中的第一个路径）下的`src\github.com\aliyun\aliyun-oss-go-sdk\sample`，该目录下为示例程序，
148或者参看`https://github.com/aliyun/aliyun-oss-go-sdk`下sample目录中的示例文件。
149
150## 注意事项
151### 运行sample
152> - 拷贝示例文件。到OSS Go SDK的安装路径（即GOPATH变量中的第一个路径），进入OSS Go SDK的代码目录`src\github.com\aliyun\aliyun-oss-go-sdk`，
153把其下的sample目录和sample.go复制到您的测试工程src目录下。
154> - 修改sample/config.go里的endpoint、AccessKeyId、AccessKeySecret、BucketName等配置。
155> - 请在您的工程目录下执行`go run src/sample.go`。
156
157## 联系我们
158> - [阿里云OSS官方网站](http://oss.aliyun.com)
159> - [阿里云OSS官方论坛](http://bbs.aliyun.com)
160> - [阿里云OSS官方文档中心](http://www.aliyun.com/product/oss#Docs)
161> - 阿里云官方技术支持：[提交工单](https://workorder.console.aliyun.com/#/ticket/createIndex)
162
163## 作者
164> - [Yubin Bai](https://github.com/baiyubin)
165> - [Guozhong Han](https://github.com/hangzws)
166
167## License
168> - Apache License 2.0
169
README.md
1# Alibaba Cloud OSS SDK for Go
2
3[](https://badge.fury.io/gh/aliyun%2Faliyun-oss-go-sdk)
4[](https://travis-ci.org/aliyun/aliyun-oss-go-sdk)
5[](https://coveralls.io/github/aliyun/aliyun-oss-go-sdk?branch=master)
6
7## [README of Chinese](https://github.com/aliyun/aliyun-oss-go-sdk/blob/master/README-CN.md)
8
9## About
10> - This Go SDK is based on the official APIs of [Alibaba Cloud OSS](http://www.aliyun.com/product/oss/).
11> - Alibaba Cloud Object Storage Service (OSS) is a cloud storage service provided by Alibaba Cloud, featuring massive capacity, security, a low cost, and high reliability.
12> - The OSS can store any type of files and therefore applies to various websites, development enterprises and developers.
13> - With this SDK, you can upload, download and manage data on any app anytime and anywhere conveniently.
14
15## Version
16> - Current version: v2.0.4
17
18## Running Environment
19> - Go 1.5 or above.
20
21## Installing
22### Install the SDK through GitHub
23> - Run the 'go get github.com/aliyun/aliyun-oss-go-sdk/oss' command to get the remote code package.
24> - Use 'import "github.com/aliyun/aliyun-oss-go-sdk/oss"' in your code to introduce OSS Go SDK package.
25
26## Getting Started
27### List Bucket
28```go
29 client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
30 if err != nil {
31 // HandleError(err)
32 }
33
34 lsRes, err := client.ListBuckets()
35 if err != nil {
36 // HandleError(err)
37 }
38
39 for _, bucket := range lsRes.Buckets {
40 fmt.Println("Buckets:", bucket.Name)
41 }
42```
43
44### Create Bucket
45```go
46 client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
47 if err != nil {
48 // HandleError(err)
49 }
50
51 err = client.CreateBucket("my-bucket")
52 if err != nil {
53 // HandleError(err)
54 }
55```
56
57### Delete Bucket
58```go
59 client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
60 if err != nil {
61 // HandleError(err)
62 }
63
64 err = client.DeleteBucket("my-bucket")
65 if err != nil {
66 // HandleError(err)
67 }
68```
69
70### Put Object
71```go
72 client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
73 if err != nil {
74 // HandleError(err)
75 }
76
77 bucket, err := client.Bucket("my-bucket")
78 if err != nil {
79 // HandleError(err)
80 }
81
82 err = bucket.PutObjectFromFile("my-object", "LocalFile")
83 if err != nil {
84 // HandleError(err)
85 }
86```
87
88### Get Object
89```go
90 client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
91 if err != nil {
92 // HandleError(err)
93 }
94
95 bucket, err := client.Bucket("my-bucket")
96 if err != nil {
97 // HandleError(err)
98 }
99
100 err = bucket.GetObjectToFile("my-object", "LocalFile")
101 if err != nil {
102 // HandleError(err)
103 }
104```
105
106### List Objects
107```go
108 client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
109 if err != nil {
110 // HandleError(err)
111 }
112
113 bucket, err := client.Bucket("my-bucket")
114 if err != nil {
115 // HandleError(err)
116 }
117
118 lsRes, err := bucket.ListObjects()
119 if err != nil {
120 // HandleError(err)
121 }
122
123 for _, object := range lsRes.Objects {
124 fmt.Println("Objects:", object.Key)
125 }
126```
127
128### Delete Object
129```go
130 client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
131 if err != nil {
132 // HandleError(err)
133 }
134
135 bucket, err := client.Bucket("my-bucket")
136 if err != nil {
137 // HandleError(err)
138 }
139
140 err = bucket.DeleteObject("my-object")
141 if err != nil {
142 // HandleError(err)
143 }
144```
145
146## Complete Example
147More example projects can be found at 'src\github.com\aliyun\aliyun-oss-go-sdk\sample' under the installation path of the OSS Go SDK (the first path of the GOPATH variable). The directory contains example projects.
148Or you can refer to the example objects in the sample directory under 'https://github.com/aliyun/aliyun-oss-go-sdk'.
149
150### Running Example
151> - Copy the example file. Go to the installation path of OSS Go SDK (the first path of the GOPATH variable), enter the code directory of the OSS Go SDK, namely 'src\github.com\aliyun\aliyun-oss-go-sdk',
152and copy the sample directory and sample.go to the src directory of your test project.
153> - Modify the endpoint, AccessKeyId, AccessKeySecret and BucketName configuration settings in sample/config.go.
154> - Run 'go run src/sample.go' under your project directory.
155
156## Contacting us
157> - [Alibaba Cloud OSS official website](http://oss.aliyun.com).
158> - [Alibaba Cloud OSS official forum](http://bbs.aliyun.com).
159> - [Alibaba Cloud OSS official documentation center](http://www.aliyun.com/product/oss#Docs).
160> - Alibaba Cloud official technical support: [Submit a ticket](https://workorder.console.aliyun.com/#/ticket/createIndex).
161
162## Author
163> - [Yubin Bai](https://github.com/baiyubin)
164> - [Guozhong Han](https://github.com/hangzws)
165
166## License
167> - Apache License 2.0.
168
){kind=link}
){kind=link}
){kind=link}