restic/vendor/github.com/minio/minio-go/docs/zh_CN/API.md

Minio Go Client API文档

初使化Minio Client对象。

Minio

package main

import (
    "fmt"

    "github.com/minio/minio-go"
)

func main() {
        // 使用ssl
        ssl := true

        // 初使化minio client对象。
        minioClient, err := minio.New("play.minio.io:9000", "Q3AM3UQ867SPQQA43P2F", "zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ssl)
        if err != nil {
                fmt.Println(err)
                return
        }
}

AWS S3

package main

import (
    "fmt"

    "github.com/minio/minio-go"
)

func main() {
        // 使用ssl
        ssl := true

        // 初使化minio client对象。
        s3Client, err := minio.New("s3.amazonaws.com", "YOUR-ACCESSKEYID", "YOUR-SECRETACCESSKEY", ssl)
        if err != nil {
                fmt.Println(err)
                return
        }
}

操作存储桶	操作对象	操作加密对象	Presigned操作	存储桶策略/通知	客户端自定义设置
MakeBucket	GetObject	NewSymmetricKey	PresignedGetObject	SetBucketPolicy	SetAppInfo
ListBuckets	PutObject	NewAsymmetricKey	PresignedPutObject	GetBucketPolicy	SetCustomTransport
BucketExists	CopyObject	GetEncryptedObject	PresignedPostPolicy	ListBucketPolicies	TraceOn
RemoveBucket	StatObject	PutEncryptedObject		SetBucketNotification	TraceOff
ListObjects	RemoveObject	NewSSEInfo		GetBucketNotification	SetS3TransferAccelerate
ListObjectsV2	RemoveObjects	FPutEncryptedObject		RemoveAllBucketNotification
ListIncompleteUploads	RemoveIncompleteUpload			ListenBucketNotification
	FPutObject
	FGetObject
	ComposeObject
	NewSourceInfo
	NewDestinationInfo
	PutObjectWithContext
	GetObjectWithContext
	FPutObjectWithContext
	FGetObjectWithContext

1. 构造函数

New(endpoint, accessKeyID, secretAccessKey string, ssl bool) (*Client, error)

初使化一个新的client对象。

参数

参数	类型	描述
endpoint	string	S3兼容对象存储服务endpoint
accessKeyID	string	对象存储的Access key
secretAccessKey	string	对象存储的Secret key
ssl	bool	true代表使用HTTPS

NewWithRegion(endpoint, accessKeyID, secretAccessKey string, ssl bool, region string) (*Client, error)

初使化minio client,带有region配置。和New()不同的是，NewWithRegion避免了bucket-location操作，所以会快那么一丢丢。如果你的应用只使用一个region的话可以用这个方法。

参数

参数	类型	描述
endpoint	string	S3兼容对象存储服务endpoint
accessKeyID	string	对象存储的Access key
secretAccessKey	string	对象存储的Secret key
ssl	bool	true代表使用HTTPS
region	string	对象存储的region

2. 操作存储桶

MakeBucket(bucketName, location string) error

创建一个存储桶。

参数

参数	类型	描述
bucketName	string	存储桶名称
location	string	存储桶被创建的region(地区)，默认是us-east-1(美国东一区)，下面列举的是其它合法的值。注意：如果用的是minio服务的话，resion是在它的配置文件中，（默认是us-east-1）。
		us-east-1
		us-west-1
		us-west-2
		eu-west-1
		eu-central-1
		ap-southeast-1
		ap-northeast-1
		ap-southeast-2
		sa-east-1

示例

err = minioClient.MakeBucket("mybucket", "us-east-1")
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println("Successfully created mybucket.")

ListBuckets() ([]BucketInfo, error)

列出所有的存储桶。

参数	类型	描述
bucketList	[]minio.BucketInfo	所有存储桶的list。

minio.BucketInfo

参数	类型	描述
bucket.Name	string	存储桶名称
bucket.CreationDate	time.Time	存储桶的创建时间

示例

buckets, err := minioClient.ListBuckets()
if err != nil {
    fmt.Println(err)
    return
}
for _, bucket := range buckets {
    fmt.Println(bucket)
}

BucketExists(bucketName string) (found bool, err error)

检查存储桶是否存在。

参数

参数	类型	描述
bucketName	string	存储桶名称

返回值

参数	类型	描述
found	bool	存储桶是否存在
err	error	标准Error

示例

found, err := minioClient.BucketExists("mybucket")
if err != nil {
    fmt.Println(err)
    return
}
if found {
    fmt.Println("Bucket found")
}

RemoveBucket(bucketName string) error

删除一个存储桶，存储桶必须为空才能被成功删除。

参数

参数	类型	描述
bucketName	string	存储桶名称

示例

err = minioClient.RemoveBucket("mybucket")
if err != nil {
    fmt.Println(err)
    return
}

ListObjects(bucketName, prefix string, recursive bool, doneCh chan struct{}) <-chan ObjectInfo

列举存储桶里的对象。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectPrefix	string	要列举的对象前缀
recursive	bool	true代表递归查找，false代表类似文件夹查找，以'/'分隔，不查子文件夹。
doneCh	chan struct{}	在该channel上结束ListObjects iterator的一个message。

返回值

参数	类型	描述
objectInfo	chan minio.ObjectInfo	存储桶中所有对象的read channel，对象的格式如下：

minio.ObjectInfo

属性	类型	描述
objectInfo.Key	string	对象的名称
objectInfo.Size	int64	对象的大小
objectInfo.ETag	string	对象的MD5校验码
objectInfo.LastModified	time.Time	对象的最后修改时间

// Create a done channel to control 'ListObjects' go routine.
doneCh := make(chan struct{})

// Indicate to our routine to exit cleanly upon return.
defer close(doneCh)

isRecursive := true
objectCh := minioClient.ListObjects("mybucket", "myprefix", isRecursive, doneCh)
for object := range objectCh {
    if object.Err != nil {
        fmt.Println(object.Err)
        return
    }
    fmt.Println(object)
}

ListObjectsV2(bucketName, prefix string, recursive bool, doneCh chan struct{}) <-chan ObjectInfo

使用listing API v2版本列举存储桶中的对象。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectPrefix	string	要列举的对象前缀
recursive	bool	true代表递归查找，false代表类似文件夹查找，以'/'分隔，不查子文件夹。
doneCh	chan struct{}	在该channel上结束ListObjects iterator的一个message。

返回值

参数	类型	描述
objectInfo	chan minio.ObjectInfo	存储桶中所有对象的read channel

// Create a done channel to control 'ListObjectsV2' go routine.
doneCh := make(chan struct{})

// Indicate to our routine to exit cleanly upon return.
defer close(doneCh)

isRecursive := true
objectCh := minioClient.ListObjectsV2("mybucket", "myprefix", isRecursive, doneCh)
for object := range objectCh {
    if object.Err != nil {
        fmt.Println(object.Err)
        return
    }
    fmt.Println(object)
}

ListIncompleteUploads(bucketName, prefix string, recursive bool, doneCh chan struct{}) <- chan ObjectMultipartInfo

列举存储桶中未完整上传的对象。

参数

参数	类型	描述
bucketName	string	存储桶名称
prefix	string	不完整上传的对象的前缀
recursive	bool	true代表递归查找，false代表类似文件夹查找，以'/'分隔，不查子文件夹。
doneCh	chan struct{}	在该channel上结束ListIncompleteUploads iterator的一个message。

返回值

参数	类型	描述
multiPartInfo	chan minio.ObjectMultipartInfo	multipart对象格式如下：

minio.ObjectMultipartInfo

属性	类型	描述
multiPartObjInfo.Key	string	未完整上传的对象的名称
multiPartObjInfo.UploadID	string	未完整上传的对象的Upload ID
multiPartObjInfo.Size	int64	未完整上传的对象的大小

示例

// Create a done channel to control 'ListObjects' go routine.
doneCh := make(chan struct{})

// Indicate to our routine to exit cleanly upon return.
defer close(doneCh)

isRecursive := true // Recursively list everything at 'myprefix'
multiPartObjectCh := minioClient.ListIncompleteUploads("mybucket", "myprefix", isRecursive, doneCh)
for multiPartObject := range multiPartObjectCh {
    if multiPartObject.Err != nil {
        fmt.Println(multiPartObject.Err)
        return
    }
    fmt.Println(multiPartObject)
}

3. 操作对象

GetObject(bucketName, objectName string, opts GetObjectOptions) (*Object, error)

返回对象数据的流，error是读流时经常抛的那些错。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectName	string	对象的名称
opts	minio.GetObjectOptions	GET请求的一些额外参数，像encryption，If-Match

minio.GetObjectOptions

参数	类型	描述
opts.Materials	encrypt.Materials	encrypt包提供的对流加密的接口，(更多信息，请看https://godoc.org/github.com/minio/minio-go)

返回值

参数	类型	描述
object	*minio.Object	_minio.Object_代表了一个object reader。它实现了io.Reader, io.Seeker, io.ReaderAt and io.Closer接口。

示例

object, err := minioClient.GetObject("mybucket", "myobject", minio.GetObjectOptions{})
if err != nil {
    fmt.Println(err)
    return
}
localFile, err := os.Create("/tmp/local-file.jpg")
if err != nil {
    fmt.Println(err)
    return
}
if _, err = io.Copy(localFile, object); err != nil {
    fmt.Println(err)
    return
}

FGetObject(bucketName, objectName, filePath string, opts GetObjectOptions) error

下载并将文件保存到本地文件系统。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectName	string	对象的名称
filePath	string	下载后保存的路径
opts	minio.GetObjectOptions	GET请求的一些额外参数，像encryption，If-Match

示例

err = minioClient.FGetObject("mybucket", "myobject", "/tmp/myobject", minio.GetObjectOptions{})
if err != nil {
    fmt.Println(err)
    return
}

GetObjectWithContext(ctx context.Context, bucketName, objectName string, opts GetObjectOptions) (*Object, error)

和GetObject操作是一样的，不过传入了取消请求的context。

参数

参数	类型	描述
ctx	context.Context	请求上下文（Request context）
bucketName	string	存储桶名称
objectName	string	对象的名称
opts	minio.GetObjectOptions	GET请求的一些额外参数，像encryption，If-Match

返回值

参数	类型	描述
object	*minio.Object	_minio.Object_代表了一个object reader。它实现了io.Reader, io.Seeker, io.ReaderAt and io.Closer接口。

示例

ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second)
defer cancel()

object, err := minioClient.GetObjectWithContext(ctx, "mybucket", "myobject", minio.GetObjectOptions{})
if err != nil {
    fmt.Println(err)
    return
}

localFile, err := os.Create("/tmp/local-file.jpg")
if err != nil {
    fmt.Println(err)
    return
}

if _, err = io.Copy(localFile, object); err != nil {
    fmt.Println(err)
    return
}

FGetObjectWithContext(ctx context.Context, bucketName, objectName, filePath string, opts GetObjectOptions) error

和FGetObject操作是一样的，不过允许取消请求。

参数

参数	类型	描述
ctx	context.Context	请求上下文
bucketName	string	存储桶名称
objectName	string	对象的名称
filePath	string	下载后保存的路径
opts	minio.GetObjectOptions	GET请求的一些额外参数，像encryption，If-Match

示例

ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second)
defer cancel()

err = minioClient.FGetObjectWithContext(ctx, "mybucket", "myobject", "/tmp/myobject", minio.GetObjectOptions{})
if err != nil {
    fmt.Println(err)
    return
}

FGetEncryptedObject(bucketName, objectName, filePath string, materials encrypt.Materials) error

和FGetObject操作是一样的，不过会对加密请求进行解密。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectName	string	对象的名称
filePath	string	下载后保存的路径
materials	encrypt.Materials	encrypt包提供的对流加密的接口，(更多信息，请看https://godoc.org/github.com/minio/minio-go)

示例

// Generate a master symmetric key
key := encrypt.NewSymmetricKey([]byte("my-secret-key-00"))

// Build the CBC encryption material
cbcMaterials, err := encrypt.NewCBCSecureMaterials(key)
if err != nil {
    fmt.Println(err)
    return
}

err = minioClient.FGetEncryptedObject("mybucket", "myobject", "/tmp/myobject", cbcMaterials)
if err != nil {
    fmt.Println(err)
    return
}

PutObject(bucketName, objectName string, reader io.Reader, objectSize int64,opts PutObjectOptions) (n int, err error)

当对象小于64MiB时，直接在一次PUT请求里进行上传。当大于64MiB时，根据文件的实际大小，PutObject会自动地将对象进行拆分成64MiB一块或更大一些进行上传。对象的最大大小是5TB。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectName	string	对象的名称
reader	io.Reader	任意实现了io.Reader的GO类型
objectSize	int64	上传的对象的大小，-1代表未知。
opts	minio.PutObjectOptions	允许用户设置可选的自定义元数据，内容标题，加密密钥和用于分段上传操作的线程数量。

minio.PutObjectOptions

属性	类型	描述
opts.UserMetadata	map[string]string	用户元数据的Map
opts.Progress	io.Reader	获取上传进度的Reader
opts.ContentType	string	对象的Content type， 例如"application/text"
opts.ContentEncoding	string	对象的Content encoding，例如"gzip"
opts.ContentDisposition	string	对象的Content disposition, "inline"
opts.CacheControl	string	指定针对请求和响应的缓存机制，例如"max-age=600"
opts.EncryptMaterials	encrypt.Materials	encrypt包提供的对流加密的接口，(更多信息，请看https://godoc.org/github.com/minio/minio-go)

示例

file, err := os.Open("my-testfile")
if err != nil {
    fmt.Println(err)
    return
}
defer file.Close()

fileStat, err := file.Stat()
if err != nil {
    fmt.Println(err)
    return
}

n, err := minioClient.PutObject("mybucket", "myobject", file, fileStat.Size(), minio.PutObjectOptions{ContentType:"application/octet-stream"})
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println("Successfully uploaded bytes: ", n)

API方法在minio-go SDK版本v3.0.3中提供的PutObjectWithSize，PutObjectWithMetadata，PutObjectStreaming和PutObjectWithProgress被替换为接受指向PutObjectOptions struct的指针的新的PutObject调用变体。

PutObjectWithContext(ctx context.Context, bucketName, objectName string, reader io.Reader, objectSize int64, opts PutObjectOptions) (n int, err error)

和PutObject是一样的，不过允许取消请求。

参数

参数	类型	描述
ctx	context.Context	请求上下文
bucketName	string	存储桶名称
objectName	string	对象的名称
reader	io.Reader	任何实现io.Reader的Go类型
objectSize	int64	上传的对象的大小，-1代表未知
opts	minio.PutObjectOptions	允许用户设置可选的自定义元数据，content-type，content-encoding，content-disposition以及cache-control headers，传递加密模块以加密对象，并可选地设置multipart put操作的线程数量。

示例

ctx, cancel := context.WithTimeout(context.Background(), 10 * time.Second)
defer cancel()

file, err := os.Open("my-testfile")
if err != nil {
    fmt.Println(err)
    return
}
defer file.Close()

fileStat, err := file.Stat()
if err != nil {
    fmt.Println(err)
    return
}

n, err := minioClient.PutObjectWithContext(ctx, "my-bucketname", "my-objectname", file, fileStat.Size(), minio.PutObjectOptions{
	ContentType: "application/octet-stream",
})
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println("Successfully uploaded bytes: ", n)

CopyObject(dst DestinationInfo, src SourceInfo) error

通过在服务端对已存在的对象进行拷贝，实现新建或者替换对象。它支持有条件的拷贝，拷贝对象的一部分，以及在服务端的加解密。请查看SourceInfo和DestinationInfo两个类型来了解更多细节。

拷贝多个源文件到一个目标对象，请查看ComposeObject API。

参数

参数	类型	描述
dst	minio.DestinationInfo	目标对象
src	minio.SourceInfo	源对象

示例

// Use-case 1: Simple copy object with no conditions.
// Source object
src := minio.NewSourceInfo("my-sourcebucketname", "my-sourceobjectname", nil)

// Destination object
dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil)
if err != nil {
    fmt.Println(err)
    return
}

// Copy object call
err = minioClient.CopyObject(dst, src)
if err != nil {
    fmt.Println(err)
    return
}

// Use-case 2:
// Copy object with copy-conditions, and copying only part of the source object.
// 1. that matches a given ETag
// 2. and modified after 1st April 2014
// 3. but unmodified since 23rd April 2014
// 4. copy only first 1MiB of object.

// Source object
src := minio.NewSourceInfo("my-sourcebucketname", "my-sourceobjectname", nil)

// Set matching ETag condition, copy object which matches the following ETag.
src.SetMatchETagCond("31624deb84149d2f8ef9c385918b653a")

// Set modified condition, copy object modified since 2014 April 1.
src.SetModifiedSinceCond(time.Date(2014, time.April, 1, 0, 0, 0, 0, time.UTC))

// Set unmodified condition, copy object unmodified since 2014 April 23.
src.SetUnmodifiedSinceCond(time.Date(2014, time.April, 23, 0, 0, 0, 0, time.UTC))

// Set copy-range of only first 1MiB of file.
src.SetRange(0, 1024*1024-1)

// Destination object
dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil)
if err != nil {
    fmt.Println(err)
    return
}

// Copy object call
err = minioClient.CopyObject(dst, src)
if err != nil {
    fmt.Println(err)
    return
}

ComposeObject(dst minio.DestinationInfo, srcs []minio.SourceInfo) error

通过使用服务端拷贝实现钭多个源对象合并创建成一个新的对象。

参数

参数	类型	描述
dst	minio.DestinationInfo	要被创建的目标对象
srcs	[]minio.SourceInfo	要合并的多个源对象

示例

// Prepare source decryption key (here we assume same key to
// decrypt all source objects.)
decKey := minio.NewSSEInfo([]byte{1, 2, 3}, "")

// Source objects to concatenate. We also specify decryption
// key for each
src1 := minio.NewSourceInfo("bucket1", "object1", &decKey)
src1.SetMatchETagCond("31624deb84149d2f8ef9c385918b653a")

src2 := minio.NewSourceInfo("bucket2", "object2", &decKey)
src2.SetMatchETagCond("f8ef9c385918b653a31624deb84149d2")

src3 := minio.NewSourceInfo("bucket3", "object3", &decKey)
src3.SetMatchETagCond("5918b653a31624deb84149d2f8ef9c38")

// Create slice of sources.
srcs := []minio.SourceInfo{src1, src2, src3}

// Prepare destination encryption key
encKey := minio.NewSSEInfo([]byte{8, 9, 0}, "")

// Create destination info
dst, err := minio.NewDestinationInfo("bucket", "object", &encKey, nil)
if err != nil {
    fmt.Println(err)
    return
}

// Compose object call by concatenating multiple source files.
err = minioClient.ComposeObject(dst, srcs)
if err != nil {
    fmt.Println(err)
    return
}

fmt.Println("Composed object successfully.")

NewSourceInfo(bucket, object string, decryptSSEC *SSEInfo) SourceInfo

构建一个可用于服务端拷贝操作（像CopyObject和ComposeObject）的SourceInfo对象。该对象可用于给源对象设置拷贝条件。

参数

参数	类型	描述
bucket	string	源存储桶
object	string	源对象
decryptSSEC	*minio.SSEInfo	源对象的解密信息 (nil代表不用解密)

示例

// No decryption parameter.
src := minio.NewSourceInfo("bucket", "object", nil)

// Destination object
dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil)
if err != nil {
    fmt.Println(err)
    return
}

// Copy object call
err = minioClient.CopyObject(dst, src)
if err != nil {
    fmt.Println(err)
    return
}

// With decryption parameter.
decKey := minio.NewSSEInfo([]byte{1,2,3}, "")
src := minio.NewSourceInfo("bucket", "object", &decKey)

// Destination object
dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil)
if err != nil {
    fmt.Println(err)
    return
}

// Copy object call
err = minioClient.CopyObject(dst, src)
if err != nil {
    fmt.Println(err)
    return
}

NewDestinationInfo(bucket, object string, encryptSSEC *SSEInfo, userMeta map[string]string) (DestinationInfo, error)

构建一个用于服务端拷贝操作（像CopyObject和ComposeObject）的用作目标对象的DestinationInfo。

参数

参数	类型	描述
bucket	string	目标存储桶名称
object	string	目标对象名称
encryptSSEC	*minio.SSEInfo	源对象的加密信息 (nil代表不用加密)
userMeta	map[string]string	给目标对象的用户元数据，如果是nil,并只有一个源对象，则将源对象的用户元数据拷贝给目标对象。

示例

// No encryption parameter.
src := minio.NewSourceInfo("bucket", "object", nil)
dst, err := minio.NewDestinationInfo("bucket", "object", nil, nil)
if err != nil {
    fmt.Println(err)
    return
}

// Copy object call
err = minioClient.CopyObject(dst, src)
if err != nil {
    fmt.Println(err)
    return
}

src := minio.NewSourceInfo("bucket", "object", nil)

// With encryption parameter.
encKey := minio.NewSSEInfo([]byte{1,2,3}, "")
dst, err := minio.NewDestinationInfo("bucket", "object", &encKey, nil)
if err != nil {
    fmt.Println(err)
    return
}

// Copy object call
err = minioClient.CopyObject(dst, src)
if err != nil {
    fmt.Println(err)
    return
}

FPutObject(bucketName, objectName, filePath, opts PutObjectOptions) (length int64, err error)

将filePath对应的文件内容上传到一个对象中。

当对象小于64MiB时，FPutObject直接在一次PUT请求里进行上传。当大于64MiB时，根据文件的实际大小，FPutObject会自动地将对象进行拆分成64MiB一块或更大一些进行上传。对象的最大大小是5TB。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectName	string	对象的名称
filePath	string	要上传的文件的路径
opts	minio.PutObjectOptions	允许用户设置可选的自定义元数据，content-type，content-encoding，content-disposition以及cache-control headers，传递加密模块以加密对象，并可选地设置multipart put操作的线程数量。

示例

n, err := minioClient.FPutObject("my-bucketname", "my-objectname", "my-filename.csv", minio.PutObjectOptions{
	ContentType: "application/csv",
});
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println("Successfully uploaded bytes: ", n)

FPutObjectWithContext(ctx context.Context, bucketName, objectName, filePath, opts PutObjectOptions) (length int64, err error)

和FPutObject操作是一样的，不过允许取消请求。

参数

参数	类型	描述
ctx	context.Context	请求上下文
bucketName	string	存储桶名称
objectName	string	对象的名称
filePath	string	要上传的文件的路径
opts	minio.PutObjectOptions	允许用户设置可选的自定义元数据，content-type，content-encoding，content-disposition以及cache-control headers，传递加密模块以加密对象，并可选地设置multipart put操作的线程数量。

示例

ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second)
defer cancel()

n, err := minioClient.FPutObjectWithContext(ctx, "mybucket", "myobject.csv", "/tmp/otherobject.csv", minio.PutObjectOptions{ContentType:"application/csv"})
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println("Successfully uploaded bytes: ", n)

StatObject(bucketName, objectName string, opts StatObjectOptions) (ObjectInfo, error)

获取对象的元数据。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectName	string	对象的名称
opts	minio.StatObjectOptions	GET info/stat请求的一些额外参数，像encryption，If-Match

返回值

参数	类型	描述
objInfo	minio.ObjectInfo	对象stat信息

minio.ObjectInfo

属性	类型	描述
objInfo.LastModified	time.Time	对象的最后修改时间
objInfo.ETag	string	对象的MD5校验码
objInfo.ContentType	string	对象的Content type
objInfo.Size	int64	对象的大小

示例

objInfo, err := minioClient.StatObject("mybucket", "myobject", minio.StatObjectOptions{})
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println(objInfo)

RemoveObject(bucketName, objectName string) error

删除一个对象。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectName	string	对象的名称

err = minioClient.RemoveObject("mybucket", "myobject")
if err != nil {
    fmt.Println(err)
    return
}

RemoveObjects(bucketName string, objectsCh chan string) (errorCh <-chan RemoveObjectError)

从一个input channel里删除一个对象集合。一次发送到服务端的删除请求最多可删除1000个对象。通过error channel返回的错误信息。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectsCh	chan string	要删除的对象的channel

返回值

参数	类型	描述
errorCh	<-chan minio.RemoveObjectError	删除时观察到的错误的Receive-only channel。

objectsCh := make(chan string)

// Send object names that are needed to be removed to objectsCh
go func() {
	defer close(objectsCh)
	// List all objects from a bucket-name with a matching prefix.
	for object := range minioClient.ListObjects("my-bucketname", "my-prefixname", true, nil) {
		if object.Err != nil {
			log.Fatalln(object.Err)
		}
		objectsCh <- object.Key
	}
}()

for rErr := range minioClient.RemoveObjects("mybucket", objectsCh) {
    fmt.Println("Error detected during deletion: ", rErr)
}

RemoveIncompleteUpload(bucketName, objectName string) error

删除一个未完整上传的对象。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectName	string	对象的名称

示例

err = minioClient.RemoveIncompleteUpload("mybucket", "myobject")
if err != nil {
    fmt.Println(err)
    return
}

4. 操作加密对象

NewSymmetricKey(key []byte) *encrypt.SymmetricKey

参数

参数	类型	描述
key	string	存储桶名称

返回值

参数	类型	描述
symmetricKey	*encrypt.SymmetricKey	加密解密的对称秘钥

symKey := encrypt.NewSymmetricKey([]byte("my-secret-key-00"))

// Build the CBC encryption material with symmetric key.
cbcMaterials, err := encrypt.NewCBCSecureMaterials(symKey)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println("Successfully initialized Symmetric key CBC materials", cbcMaterials)

object, err := minioClient.GetEncryptedObject("mybucket", "myobject", cbcMaterials)
if err != nil {
    fmt.Println(err)
    return
}
defer object.Close()

NewAsymmetricKey(privateKey []byte, publicKey[]byte) (*encrypt.AsymmetricKey, error)

参数

参数	类型	描述
privateKey	[]byte	Private key数据
publicKey	[]byte	Public key数据

返回值

参数	类型	描述
asymmetricKey	*encrypt.AsymmetricKey	加密解密的非对称秘钥
err	error	标准Error

privateKey, err := ioutil.ReadFile("private.key")
if err != nil {
    fmt.Println(err)
    return
}

publicKey, err := ioutil.ReadFile("public.key")
if err != nil {
    fmt.Println(err)
    return
}

// Initialize the asymmetric key
asymmetricKey, err := encrypt.NewAsymmetricKey(privateKey, publicKey)
if err != nil {
    fmt.Println(err)
    return
}

// Build the CBC encryption material for asymmetric key.
cbcMaterials, err := encrypt.NewCBCSecureMaterials(asymmetricKey)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println("Successfully initialized Asymmetric key CBC materials", cbcMaterials)

object, err := minioClient.GetEncryptedObject("mybucket", "myobject", cbcMaterials)
if err != nil {
    fmt.Println(err)
    return
}
defer object.Close()

GetEncryptedObject(bucketName, objectName string, encryptMaterials encrypt.Materials) (io.ReadCloser, error)

返回对象的解密流。读流时的常见错误。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectName	string	对象的名称
encryptMaterials	encrypt.Materials	encrypt包提供的对流加密的接口，(更多信息，请看https://godoc.org/github.com/minio/minio-go)

返回值

参数	类型	描述
stream	io.ReadCloser	返回对象的reader,调用者需要在读取之后进行关闭。
err	_error	错误信息

示例

// Generate a master symmetric key
key := encrypt.NewSymmetricKey([]byte("my-secret-key-00"))

// Build the CBC encryption material
cbcMaterials, err := encrypt.NewCBCSecureMaterials(key)
if err != nil {
    fmt.Println(err)
    return
}

object, err := minioClient.GetEncryptedObject("mybucket", "myobject", cbcMaterials)
if err != nil {
    fmt.Println(err)
    return
}
defer object.Close()

localFile, err := os.Create("/tmp/local-file.jpg")
if err != nil {
    fmt.Println(err)
    return
}
defer localFile.Close()

if _, err = io.Copy(localFile, object); err != nil {
    fmt.Println(err)
    return
}

PutEncryptedObject(bucketName, objectName string, reader io.Reader, encryptMaterials encrypt.Materials) (n int, err error)

加密并上传对象。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectName	string	对象的名称
reader	io.Reader	任何实现io.Reader的Go类型
encryptMaterials	encrypt.Materials	encrypt包提供的对流加密的接口，(更多信息，请看https://godoc.org/github.com/minio/minio-go)

示例

// Load a private key
privateKey, err := ioutil.ReadFile("private.key")
if err != nil {
    fmt.Println(err)
    return
}

// Load a public key
publicKey, err := ioutil.ReadFile("public.key")
if err != nil {
    fmt.Println(err)
    return
}

// Build an asymmetric key
key, err := encrypt.NewAsymmetricKey(privateKey, publicKey)
if err != nil {
    fmt.Println(err)
    return
}

// Build the CBC encryption module
cbcMaterials, err := encrypt.NewCBCSecureMaterials(key)
if err != nil {
    fmt.Println(err)
    return
}

// Open a file to upload
file, err := os.Open("my-testfile")
if err != nil {
    fmt.Println(err)
    return
}
defer file.Close()

// Upload the encrypted form of the file
n, err := minioClient.PutEncryptedObject("mybucket", "myobject", file, cbcMaterials)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println("Successfully uploaded encrypted bytes: ", n)

FPutEncryptedObject(bucketName, objectName, filePath, encryptMaterials encrypt.Materials) (n int, err error)

通过一个文件进行加密并上传到对象。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectName	string	对象的名称
filePath	string	要上传的文件的路径
encryptMaterials	encrypt.Materials	encrypt包提供的对流加密的接口，(更多信息，请看https://godoc.org/github.com/minio/minio-go)

示例

// Load a private key
privateKey, err := ioutil.ReadFile("private.key")
if err != nil {
    fmt.Println(err)
    return
}

// Load a public key
publicKey, err := ioutil.ReadFile("public.key")
if err != nil {
    fmt.Println(err)
    return
}

// Build an asymmetric key
key, err := encrypt.NewAsymmetricKey(privateKey, publicKey)
if err != nil {
    fmt.Println(err)
    return
}

// Build the CBC encryption module
cbcMaterials, err := encrypt.NewCBCSecureMaterials(key)
if err != nil {
    fmt.Println(err)
    return
}

n, err := minioClient.FPutEncryptedObject("mybucket", "myobject.csv", "/tmp/otherobject.csv", cbcMaterials)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println("Successfully uploaded encrypted bytes: ", n)

NewSSEInfo(key []byte, algo string) SSEInfo

创建一个通过用户提供的key(SSE-C),进行服务端加解密操作的key对象。

参数

参数	类型	描述
key	[]byte	未编码的二进制key数组
algo	string	加密算法，可以为空（默认是AES256）

5. Presigned操作

PresignedGetObject(bucketName, objectName string, expiry time.Duration, reqParams url.Values) (*url.URL, error)

生成一个用于HTTP GET操作的presigned URL。浏览器/移动客户端可以在即使存储桶为私有的情况下也可以通过这个URL进行下载。这个presigned URL可以有一个过期时间，默认是7天。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectName	string	对象的名称
expiry	time.Duration	presigned URL的过期时间，单位是秒
reqParams	url.Values	额外的响应头，支持_response-expires_， response-content-type， response-cache-control， response-content-disposition。

示例

// Set request parameters for content-disposition.
reqParams := make(url.Values)
reqParams.Set("response-content-disposition", "attachment; filename=\"your-filename.txt\"")

// Generates a presigned url which expires in a day.
presignedURL, err := minioClient.PresignedGetObject("mybucket", "myobject", time.Second * 24 * 60 * 60, reqParams)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println("Successfully generated presigned URL", presignedURL)

PresignedPutObject(bucketName, objectName string, expiry time.Duration) (*url.URL, error)

生成一个用于HTTP GET操作的presigned URL。浏览器/移动客户端可以在即使存储桶为私有的情况下也可以通过这个URL进行下载。这个presigned URL可以有一个过期时间，默认是7天。

注意：你可以通过只指定对象名称上传到S3。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectName	string	对象的名称
expiry	time.Duration	presigned URL的过期时间，单位是秒

示例

// Generates a url which expires in a day.
expiry := time.Second * 24 * 60 * 60 // 1 day.
presignedURL, err := minioClient.PresignedPutObject("mybucket", "myobject", expiry)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println("Successfully generated presigned URL", presignedURL)

PresignedHeadObject(bucketName, objectName string, expiry time.Duration, reqParams url.Values) (*url.URL, error)

生成一个用于HTTP GET操作的presigned URL。浏览器/移动客户端可以在即使存储桶为私有的情况下也可以通过这个URL进行下载。这个presigned URL可以有一个过期时间，默认是7天。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectName	string	对象的名称
expiry	time.Duration	presigned URL的过期时间，单位是秒
reqParams	url.Values	额外的响应头，支持_response-expires_， response-content-type， response-cache-control， response-content-disposition。

示例

// Set request parameters for content-disposition.
reqParams := make(url.Values)
reqParams.Set("response-content-disposition", "attachment; filename=\"your-filename.txt\"")

// Generates a presigned url which expires in a day.
presignedURL, err := minioClient.PresignedHeadObject("mybucket", "myobject", time.Second * 24 * 60 * 60, reqParams)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println("Successfully generated presigned URL", presignedURL)

PresignedPostPolicy(PostPolicy) (*url.URL, map[string]string, error)

允许给POST操作的presigned URL设置策略条件。这些策略包括比如，接收对象上传的存储桶名称，名称前缀，过期策略。

// Initialize policy condition config.
policy := minio.NewPostPolicy()

// Apply upload policy restrictions:
policy.SetBucket("mybucket")
policy.SetKey("myobject")
policy.SetExpires(time.Now().UTC().AddDate(0, 0, 10)) // expires in 10 days

// Only allow 'png' images.
policy.SetContentType("image/png")

// Only allow content size in range 1KB to 1MB.
policy.SetContentLengthRange(1024, 1024*1024)

// Add a user metadata using the key "custom" and value "user"
policy.SetUserMetadata("custom", "user")

// Get the POST form key/value object:
url, formData, err := minioClient.PresignedPostPolicy(policy)
if err != nil {
    fmt.Println(err)
    return
}

// POST your content from the command line using `curl`
fmt.Printf("curl ")
for k, v := range formData {
    fmt.Printf("-F %s=%s ", k, v)
}
fmt.Printf("-F file=@/etc/bash.bashrc ")
fmt.Printf("%s\n", url)

6. 存储桶策略/通知

SetBucketPolicy(bucketname, objectPrefix string, policy policy.BucketPolicy) error

给存储桶或者对象前缀设置访问权限。

必须引入github.com/minio/minio-go/pkg/policy包。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectPrefix	string	对象的名称前缀
policy	policy.BucketPolicy	Policy的取值如下：
		policy.BucketPolicyNone
		policy.BucketPolicyReadOnly
		policy.BucketPolicyReadWrite
		policy.BucketPolicyWriteOnly

返回值

参数	类型	描述
err	error	标准Error

示例

// Sets 'mybucket' with a sub-directory 'myprefix' to be anonymously accessible for
// both read and write operations.
err = minioClient.SetBucketPolicy("mybucket", "myprefix", policy.BucketPolicyReadWrite)
if err != nil {
    fmt.Println(err)
    return
}

GetBucketPolicy(bucketName, objectPrefix string) (policy.BucketPolicy, error)

获取存储桶或者对象前缀的访问权限。

必须引入github.com/minio/minio-go/pkg/policy包。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectPrefix	string	该存储桶下的对象前缀

返回值

参数	类型	描述
bucketPolicy	policy.BucketPolicy	取值如下： none, readonly, readwrite,或者writeonly
err	error	标准Error

示例

bucketPolicy, err := minioClient.GetBucketPolicy("mybucket", "")
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println("Access permissions for mybucket is", bucketPolicy)

ListBucketPolicies(bucketName, objectPrefix string) (map[string]BucketPolicy, error)

获取指定的存储桶和前缀的访问策略。

参数

参数	类型	描述
bucketName	string	存储桶名称
objectPrefix	string	该存储桶下的对象前缀

返回值

参数	类型	描述
bucketPolicies	map[string]minio.BucketPolicy	对象以及它们的权限的Map
err	error	标准Error

示例

bucketPolicies, err := minioClient.ListBucketPolicies("mybucket", "")
if err != nil {
    fmt.Println(err)
    return
}
for resource, permission := range bucketPolicies {
    fmt.Println(resource, " => ", permission)
}

GetBucketNotification(bucketName string) (BucketNotification, error)

获取存储桶的通知配置

参数

参数	类型	描述
bucketName	string	存储桶名称

返回值

参数	类型	描述
bucketNotification	minio.BucketNotification	含有所有通知配置的数据结构
err	error	标准Error

示例

bucketNotification, err := minioClient.GetBucketNotification("mybucket")
if err != nil {
    fmt.Println("Failed to get bucket notification configurations for mybucket", err)
    return
}

for _, queueConfig := range bucketNotification.QueueConfigs {
    for _, e := range queueConfig.Events {
        fmt.Println(e + " event is enabled")
    }
}

SetBucketNotification(bucketName string, bucketNotification BucketNotification) error

给存储桶设置新的通知

参数

参数	类型	描述
bucketName	string	存储桶名称
bucketNotification	minio.BucketNotification	发送给配置的web service的XML

返回值

参数	类型	描述
err	error	标准Error

示例

queueArn := minio.NewArn("aws", "sqs", "us-east-1", "804605494417", "PhotoUpdate")

queueConfig := minio.NewNotificationConfig(queueArn)
queueConfig.AddEvents(minio.ObjectCreatedAll, minio.ObjectRemovedAll)
queueConfig.AddFilterPrefix("photos/")
queueConfig.AddFilterSuffix(".jpg")

bucketNotification := minio.BucketNotification{}
bucketNotification.AddQueue(queueConfig)

err = minioClient.SetBucketNotification("mybucket", bucketNotification)
if err != nil {
    fmt.Println("Unable to set the bucket notification: ", err)
    return
}

RemoveAllBucketNotification(bucketName string) error

删除存储桶上所有配置的通知

参数

参数	类型	描述
bucketName	string	存储桶名称

返回值

参数	类型	描述
err	error	标准Error

示例

err = minioClient.RemoveAllBucketNotification("mybucket")
if err != nil {
    fmt.Println("Unable to remove bucket notifications.", err)
    return
}

ListenBucketNotification(bucketName, prefix, suffix string, events []string, doneCh <-chan struct{}) <-chan NotificationInfo

ListenBucketNotification API通过notification channel接收存储桶通知事件。返回的notification channel有两个属性，'Records'和'Err'。

• 'Records'持有从服务器返回的通知信息。
• 'Err'表示的是处理接收到的通知时报的任何错误。

注意：一旦报错，notification channel就会关闭。

参数

参数	类型	描述
bucketName	string	被监听通知的存储桶
prefix	string	过滤通知的对象前缀
suffix	string	过滤通知的对象后缀
events	[]string	开启指定事件类型的通知
doneCh	chan struct{}	在该channel上结束ListenBucketNotification iterator的一个message。

返回值

参数	类型	描述
notificationInfo	chan minio.NotificationInfo	存储桶通知的channel

minio.NotificationInfo

|属性 |类型 |描述 | |notificationInfo.Records | []minio.NotificationEvent | 通知事件的集合 | |notificationInfo.Err | error | 操作时报的任何错误(标准Error) |

示例

// Create a done channel to control 'ListenBucketNotification' go routine.
doneCh := make(chan struct{})

// Indicate a background go-routine to exit cleanly upon return.
defer close(doneCh)

// Listen for bucket notifications on "mybucket" filtered by prefix, suffix and events.
for notificationInfo := range minioClient.ListenBucketNotification("mybucket", "myprefix/", ".mysuffix", []string{
    "s3:ObjectCreated:*",
    "s3:ObjectAccessed:*",
    "s3:ObjectRemoved:*",
    }, doneCh) {
    if notificationInfo.Err != nil {
        fmt.Println(notificationInfo.Err)
    }
    fmt.Println(notificationInfo)
}

7. 客户端自定义设置

SetAppInfo(appName, appVersion string)

给User-Agent添加的自定义应用信息。

参数

参数	类型	描述
appName	string	发请求的应用名称
appVersion	string	发请求的应用版本

示例

// Set Application name and version to be used in subsequent API requests.
minioClient.SetAppInfo("myCloudApp", "1.0.0")

SetCustomTransport(customHTTPTransport http.RoundTripper)

重写默认的HTTP transport，通常用于调试或者添加自定义的TLS证书。

参数

参数	类型	描述
customHTTPTransport	http.RoundTripper	自定义的transport，例如：为了调试对API请求响应进行追踪。

TraceOn(outputStream io.Writer)

开启HTTP tracing。追踪信息输出到io.Writer，如果outputstream为nil，则trace写入到os.Stdout标准输出。

参数

参数	类型	描述
outputStream	io.Writer	HTTP trace写入到outputStream

TraceOff()

关闭HTTP tracing。

SetS3TransferAccelerate(acceleratedEndpoint string)

给后续所有API请求设置ASW S3传输加速endpoint。 注意：此API仅对AWS S3有效，对其它S3兼容的对象存储服务不生效。

参数

参数	类型	描述
acceleratedEndpoint	string	设置新的S3传输加速endpoint。

8. 了解更多

• 用Go语言创建属于你的音乐播放器APP示例