Alexander Neumann 2b39f9f4b2 Update dependencies

Among others, this updates minio-go, so that the new "eu-west-3" zone
for AWS is supported.

2018-01-23 19:40:42 +01:00

53 KiB

Raw Blame History

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)

注意：你可以通过只指定对象名称上传到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)

参数

参数	类型	描述
`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

示例

// 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示例

53 KiB Raw Blame History

Minio Go Client API文档

初使化Minio Client对象。

Minio

AWS S3

1. 构造函数

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

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

2. 操作存储桶

MakeBucket(bucketName, location string) error

ListBuckets() ([]BucketInfo, error)

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

RemoveBucket(bucketName string) error

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

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

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

3. 操作对象

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

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

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

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

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

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

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

CopyObject(dst DestinationInfo, src SourceInfo) error

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

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

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

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

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

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

RemoveObject(bucketName, objectName string) error

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

RemoveIncompleteUpload(bucketName, objectName string) error

4. 操作加密对象

NewSymmetricKey(key []byte) *encrypt.SymmetricKey

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

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

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

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

NewSSEInfo(key []byte, algo string) SSEInfo

5. Presigned操作

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

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

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

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

6. 存储桶策略/通知

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

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

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

GetBucketNotification(bucketName string) (BucketNotification, error)

SetBucketNotification(bucketName string, bucketNotification BucketNotification) error

RemoveAllBucketNotification(bucketName string) error

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

7. 客户端自定义设置

SetAppInfo(appName, appVersion string)

SetCustomTransport(customHTTPTransport http.RoundTripper)

TraceOn(outputStream io.Writer)

TraceOff()

SetS3TransferAccelerate(acceleratedEndpoint string)

8. 了解更多

53 KiB

Raw Blame History