Skip to content

Latest commit

 

History

History
1796 lines (1317 loc) · 52.5 KB

golang-client-api-reference.md

File metadata and controls

1796 lines (1317 loc) · 52.5 KB
Raw

MinIO Go Client API文档 Slack

初使化MinIO Client对象。

MinIO

package main

import (
    "fmt"

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

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

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

AWS S3

package main

import (
    "fmt"

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

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 SetBucketNotification TraceOn
RemoveBucket StatObject PutEncryptedObject GetBucketNotification TraceOff
ListObjects RemoveObject NewSSEInfo RemoveAllBucketNotification SetS3TransferAccelerate
ListObjectsV2 RemoveObjects FPutEncryptedObject ListenBucketNotification
ListIncompleteUploads RemoveIncompleteUpload
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-east-2
us-west-1
us-west-2
ca-central-1
eu-west-1
eu-west-2
eu-west-3
eu-central-1
eu-north-1
ap-east-1
ap-south-1
ap-southeast-1
ap-southeast-2
ap-northeast-1
ap-northeast-2
ap-northeast-3
me-south-1
sa-east-1
us-gov-west-1
us-gov-east-1
cn-north-1
cn-northwest-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/v6)

返回值

参数 类型 描述
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/v6)

示例

// 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)

当对象小于128MiB时，直接在一次PUT请求里进行上传。当大于128MiB时，根据文件的实际大小，PutObject会自动地将对象进行拆分成128MiB一块或更大一些进行上传。对象的最大大小是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/v6)

示例

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对应的文件内容上传到一个对象中。

当对象小于128MiB时，FPutObject直接在一次PUT请求里进行上传。当大于128MiB时，根据文件的实际大小，FPutObject会自动地将对象进行拆分成128MiB一块或更大一些进行上传。对象的最大大小是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/v6)

返回值

参数 类型 描述
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/v6)

示例

// 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/v6)

示例

// 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/v6/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/v6/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)

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。