repository·master·Indexed 21 days ago
https://github.com/aliyun/aliyun-oss-go-sdkA programmatic interface for interacting with Alibaba Cloud Object Storage Service (OSS) using Go 1.5 or above. The SDK provides a Client for bucket-level management (creation, deletion, ACL, lifecycle, and WORM configuration) and a Bucket abstraction for object-level operations including uploading, downloading, and deleting files. It supports advanced features such as transfer acceleration, server-side encryption, and custom domain mapping via CNAME.
This repository contains the V1 SDK (aliyun-oss-go-sdk).
A newer version, OSS SDK for Go V2 (alibabacloud-oss-go-sdk-v2), has been released. V2 is a major rewrite that simplifies authentication, automatic retries, and error handling, and introduces advanced features like paginators and a transport manager.
If you are starting a new project or looking to upgrade, consider using the V2 SDK.
A major rewrite, OSS SDK for Go V2 (alibabacloud-oss-go-sdk-v2), is available. It is recommended for new projects as it simplifies:
It also provides advanced features like paginators, transmission managers, and File-like operations. If you are using the current repository (V1), consider migrating to V2 for improved development efficiency.
To perform operations on specific files (objects), first obtain a bucket instance using client.Bucket("bucket-name"). Then, use the bucket instance to upload, download, list, or delete objects.
bucket, err := client.Bucket("my-bucket")
// Upload a file (Put Object)
err = bucket.PutObjectFromFile("my-object", "LocalFile")
// Download a file (Get Object)
err = bucket.GetObjectToFile("my-object", "LocalFile")
// List objects in the bucket
lsRes, err := bucket.ListObjects()
for _, object := range lsRes.Objects {
fmt.Println("Objects:", object.Key)
}
// Delete an object
err = bucket.DeleteObject("my-object")To install the SDK, use the go get command to fetch the remote package. You can then import the package into your Go project using the github.com/aliyun/aliyun-oss-go-sdk/oss path.
Requirements:
go get github.com/aliyun/aliyun-oss-go-sdk/ossimport "github.com/aliyun/aliyun-oss-go-sdk/oss"Use the client instance to perform bucket-level operations such as listing, creating, and deleting buckets.
// List all buckets
lsRes, err := client.ListBuckets()
for _, bucket := range lsRes.Buckets {
fmt.Println("Buckets:", bucket.Name)
}
// Create a bucket
err = client.CreateBucket("my-bucket")
// Delete a bucket
err = client.DeleteBucket("my-bucket")To install the SDK, run the following command to fetch the remote package via GitHub:
go get github.com/aliyun/aliyun-oss-go-sdkIn your Go code, import the package using:
import "github.com/aliyun/aliyun-oss-go-sdk/oss"Requirements:
To interact with Alibaba Cloud OSS, you must first create a client using oss.New. You will need your OSS Endpoint, AccessKeyId, and AccessKeySecret.
client, err := oss.New("Endpoint", "AccessKeyId", "AccessKeySecret")
if err != nil {
// Handle error
}The SDK is organized into two primary abstractions:
Client: Manages the connection to the OSS service and handles bucket-level management tasks such as creating, deleting, or listing buckets, and configuring bucket-wide settings (ACL, Lifecycle, Website, etc.).Bucket: Represents a specific bucket. It is obtained from a Client using the Bucket(bucketName string) method. This object is used for object-related operations (uploading, downloading, deleting files within that bucket).Workflow:
Client using oss.New().client.Bucket("my-bucket") to get a Bucket instance for file operations.client directly for bucket management (e.g., client.CreateBucket(...)).// 1. Create Client
client, _ := oss.New(endpoint, ak, sk)
// 2. Get Bucket for object operations
bucket, _ := client.Bucket("my-bucket")
// 3. Use Client for bucket management
err := client.CreateBucket("my-bucket")The OSS Go SDK uses a functional options pattern to configure the Client. You can pass these options during client initialization or to specific API calls to modify behavior such as timeouts, proxies, security settings, and connection pooling.
Commonly used options include:
Timeout(connectTimeoutSec, readWriteTimeout int64): Sets HTTP connection and read/write timeouts in seconds.Proxy(proxyHost string): Sets a proxy in host:port format.AuthProxy(proxyHost, proxyUser, proxyPassword string): Sets a proxy with authentication.SecurityToken(token string): Sets the STS temporary security token.EnableMD5(isEnableMD5 bool): Enables or disables MD5 validation.EnableCRC(isEnableCRC bool): Enables or disables CRC checksum (default is true).Region(region string): Sets the service region.MaxConns(maxIdleConns, maxIdleConnsPerHost, maxConnsPerHost int): Configures HTTP connection pooling limits.To manage files (objects), first obtain a bucket instance using client.Bucket("bucket-name"). You can then perform operations like uploading, downloading, listing, and deleting objects.
bucket, err := client.Bucket("my-bucket")
// Upload a file from local disk
err = bucket.PutObjectFromFile("my-object", "LocalFile")
// Download an object to local disk
err = bucket.GetObjectToFile("my-object", "LocalFile")
// List objects in the bucket
lsRes, err := bucket.ListObjects()
for _, object := range lsRes.Objects {
fmt.Println("Objects:", object.Key)
}
// Delete an object
err = bucket.DeleteObject("my-object")You can configure, retrieve, and delete server-side encryption settings for an OSS bucket using the following methods. Encryption settings are managed via ServerEncryptionRule objects.
// Set bucket encryption config
err := client.SetBucketEncryption(bucketName, encryptionRule, options...)
// Get bucket encryption
result, err := client.GetBucketEncryption(bucketName, options...)
// Delete bucket encryption config
err := client.DeleteBucketEncryption(bucketName, options...)CNAME allows you to bind a custom domain name to your OSS bucket. You can create tokens for CNAME, list existing bindings, and map a domain to a bucket.
// Create a token for a custom domain
result, err := client.CreateBucketCnameToken(bucketName, cname, options...)
// List bucket's binding CNAMEs
result, err := client.ListBucketCname(bucketName, options...)
// Map a custom domain name to a bucket
err := client.PutBucketCname(bucketName, cname, options...)