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

Minio Go Client API Reference

Initialize Minio Client object.

Minio

package main

import (
    "fmt"

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

func main() {
        // Use a secure connection.
        ssl := true

        // Initialize minio client object.
        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() {
        // Use a secure connection.
        ssl := true

        // Initialize minio client object.
        s3Client, err := minio.New("s3.amazonaws.com", "YOUR-ACCESSKEYID", "YOUR-SECRETACCESSKEY", ssl)
        if err != nil {
                fmt.Println(err)
                return
        }
}

Bucket operations	Object operations	Encrypted Object operations	Presigned operations	Bucket Policy/Notification Operations	Client custom settings
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. Constructor

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

Initializes a new client object.

Parameters

Param	Type	Description
endpoint	string	S3 compatible object storage endpoint
accessKeyID	string	Access key for the object storage
secretAccessKey	string	Secret key for the object storage
ssl	bool	If 'true' API requests will be secure (HTTPS), and insecure (HTTP) otherwise

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

Initializes minio client, with region configured. Unlike New(), NewWithRegion avoids bucket-location lookup operations and it is slightly faster. Use this function when your application deals with a single region.

Parameters

Param	Type	Description
endpoint	string	S3 compatible object storage endpoint
accessKeyID	string	Access key for the object storage
secretAccessKey	string	Secret key for the object storage
ssl	bool	If 'true' API requests will be secure (HTTPS), and insecure (HTTP) otherwise
region	string	Region for the object storage

2. Bucket operations

MakeBucket(bucketName, location string) error

Creates a new bucket.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
location	string	Region where the bucket is to be created. Default value is us-east-1. Other valid values are listed below. Note: When used with minio server, use the region specified in its config file (defaults to 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

Example

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

ListBuckets() ([]BucketInfo, error)

Lists all buckets.

Param	Type	Description
bucketList	[]minio.BucketInfo	Lists of all buckets

minio.BucketInfo

Field	Type	Description
bucket.Name	string	Name of the bucket
bucket.CreationDate	time.Time	Date of bucket creation

Example

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)

Checks if a bucket exists.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket

Return Values

Param	Type	Description
found	bool	Indicates whether bucket exists or not
err	error	Standard Error

Example

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

RemoveBucket(bucketName string) error

Removes a bucket, bucket should be empty to be successfully removed.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket

Example

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

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

Lists objects in a bucket.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectPrefix	string	Prefix of objects to be listed
recursive	bool	true indicates recursive style listing and false indicates directory style listing delimited by '/'.
doneCh	chan struct{}	A message on this channel ends the ListObjects iterator.

Return Value

Param	Type	Description
objectInfo	chan minio.ObjectInfo	Read channel for all objects in the bucket, the object is of the format listed below:

minio.ObjectInfo

Field	Type	Description
objectInfo.Key	string	Name of the object
objectInfo.Size	int64	Size of the object
objectInfo.ETag	string	MD5 checksum of the object
objectInfo.LastModified	time.Time	Time when object was last modified

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

Lists objects in a bucket using the recommended listing API v2

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectPrefix	string	Prefix of objects to be listed
recursive	bool	true indicates recursive style listing and false indicates directory style listing delimited by '/'.
doneCh	chan struct{}	A message on this channel ends the ListObjectsV2 iterator.

Return Value

Param	Type	Description
objectInfo	chan minio.ObjectInfo	Read channel for all the objects in the bucket, the object is of the format listed below:

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

Lists partially uploaded objects in a bucket.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
prefix	string	Prefix of objects that are partially uploaded
recursive	bool	true indicates recursive style listing and false indicates directory style listing delimited by '/'.
doneCh	chan struct{}	A message on this channel ends the ListenIncompleteUploads iterator.

Return Value

Param	Type	Description
multiPartInfo	chan minio.ObjectMultipartInfo	Emits multipart objects of the format listed below:

minio.ObjectMultipartInfo

Field	Type	Description
multiPartObjInfo.Key	string	Name of incompletely uploaded object
multiPartObjInfo.UploadID	string	Upload ID of incompletely uploaded object
multiPartObjInfo.Size	int64	Size of incompletely uploaded object

Example

// 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. Object operations

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

Returns a stream of the object data. Most of the common errors occur when reading the stream.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectName	string	Name of the object
opts	minio.GetObjectOptions	Options for GET requests specifying additional options like encryption, If-Match

minio.GetObjectOptions

Field	Type	Description
opts.Materials	encrypt.Materials	Interface provided by encrypt package to encrypt a stream of data (For more information see https://godoc.org/github.com/minio/minio-go)

Return Value

Param	Type	Description
object	*minio.Object	minio.Object represents object reader. It implements io.Reader, io.Seeker, io.ReaderAt and io.Closer interfaces.

Example

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

Downloads and saves the object as a file in the local filesystem.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectName	string	Name of the object
filePath	string	Path to download object to
opts	minio.GetObjectOptions	Options for GET requests specifying additional options like encryption, If-Match

Example

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)

Identical to GetObject operation, but accepts a context for request cancellation.

Parameters

Param	Type	Description
ctx	context.Context	Request context
bucketName	string	Name of the bucket
objectName	string	Name of the object
opts	minio.GetObjectOptions	Options for GET requests specifying additional options like encryption, If-Match

Return Value

Param	Type	Description
object	*minio.Object	minio.Object represents object reader. It implements io.Reader, io.Seeker, io.ReaderAt and io.Closer interfaces.

Example

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

Identical to FGetObject operation, but allows request cancellation.

Parameters

Param	Type	Description
ctx	context.Context	Request context
bucketName	string	Name of the bucket
objectName	string	Name of the object
filePath	string	Path to download object to
opts	minio.GetObjectOptions	Options for GET requests specifying additional options like encryption, If-Match

Example

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

Identical to FGetObject operation, but decrypts an encrypted request

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectName	string	Name of the object
filePath	string	Path to download object to
materials	encrypt.Materials	Interface provided by encrypt package to encrypt a stream of data (For more information see https://godoc.org/github.com/minio/minio-go)

Example

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

Uploads objects that are less than 64MiB in a single PUT operation. For objects that are greater than 64MiB in size, PutObject seamlessly uploads the object as parts of 64MiB or more depending on the actual file size. The max upload size for an object is 5TB.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectName	string	Name of the object
reader	io.Reader	Any Go type that implements io.Reader
objectSize	int64	Size of the object being uploaded. Pass -1 if stream size is unknown
opts	minio.PutObjectOptions	Allows user to set optional custom metadata, content headers, encryption keys and number of threads for multipart upload operation.

minio.PutObjectOptions

Field	Type	Description
opts.UserMetadata	map[string]string	Map of user metadata
opts.Progress	io.Reader	Reader to fetch progress of an upload
opts.ContentType	string	Content type of object, e.g "application/text"
opts.ContentEncoding	string	Content encoding of object, e.g "gzip"
opts.ContentDisposition	string	Content disposition of object, "inline"
opts.CacheControl	string	Used to specify directives for caching mechanisms in both requests and responses e.g "max-age=600"
opts.EncryptMaterials	encrypt.Materials	Interface provided by encrypt package to encrypt a stream of data (For more information see https://godoc.org/github.com/minio/minio-go)
opts.StorageClass	string	Specify storage class for the object. Supported values for Minio server are REDUCED_REDUNDANCY and STANDARD

Example

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 methods PutObjectWithSize, PutObjectWithMetadata, PutObjectStreaming, and PutObjectWithProgress available in minio-go SDK release v3.0.3 are replaced by the new PutObject call variant that accepts a pointer to PutObjectOptions struct.

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

Identical to PutObject operation, but allows request cancellation.

Parameters

Param	Type	Description
ctx	context.Context	Request context
bucketName	string	Name of the bucket
objectName	string	Name of the object
reader	io.Reader	Any Go type that implements io.Reader
objectSize	int64	size of the object being uploaded. Pass -1 if stream size is unknown
opts	minio.PutObjectOptions	Pointer to struct that allows user to set optional custom metadata, content-type, content-encoding,content-disposition and cache-control headers, pass encryption module for encrypting objects, and optionally configure number of threads for multipart put operation.

Example

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

Create or replace an object through server-side copying of an existing object. It supports conditional copying, copying a part of an object and server-side encryption of destination and decryption of source. See the SourceInfo and DestinationInfo types for further details.

To copy multiple source objects into a single destination object see the ComposeObject API.

Parameters

Param	Type	Description
dst	minio.DestinationInfo	Argument describing the destination object
src	minio.SourceInfo	Argument describing the source object

Example

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

Create an object by concatenating a list of source objects using server-side copying.

Parameters

Param	Type	Description
dst	minio.DestinationInfo	Struct with info about the object to be created.
srcs	[]minio.SourceInfo	Slice of struct with info about source objects to be concatenated in order.

Example

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

Construct a SourceInfo object that can be used as the source for server-side copying operations like CopyObject and ComposeObject. This object can be used to set copy-conditions on the source.

Parameters

Param	Type	Description
bucket	string	Name of the source bucket
object	string	Name of the source object
decryptSSEC	*minio.SSEInfo	Decryption info for the source object (nil without encryption)

Example

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

Construct a DestinationInfo object that can be used as the destination object for server-side copying operations like CopyObject and ComposeObject.

Parameters

Param	Type	Description
bucket	string	Name of the destination bucket
object	string	Name of the destination object
encryptSSEC	*minio.SSEInfo	Encryption info for the source object (nil without encryption)
userMeta	map[string]string	User metadata to be set on the destination. If nil, with only one source, user-metadata is copied from source.

Example

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

Uploads contents from a file to objectName.

FPutObject uploads objects that are less than 64MiB in a single PUT operation. For objects that are greater than the 64MiB in size, FPutObject seamlessly uploads the object in chunks of 64MiB or more depending on the actual file size. The max upload size for an object is 5TB.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectName	string	Name of the object
filePath	string	Path to file to be uploaded
opts	minio.PutObjectOptions	Pointer to struct that allows user to set optional custom metadata, content-type, content-encoding,content-disposition and cache-control headers, pass encryption module for encrypting objects, and optionally configure number of threads for multipart put operation.

Example

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)

Identical to FPutObject operation, but allows request cancellation.

Parameters

Param	Type	Description
ctx	context.Context	Request context
bucketName	string	Name of the bucket
objectName	string	Name of the object
filePath	string	Path to file to be uploaded
opts	minio.PutObjectOptions	Pointer to struct that allows user to set optional custom metadata, content-type, content-encoding,content-disposition and cache-control headers, pass encryption module for encrypting objects, and optionally configure number of threads for multipart put operation.

Example

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)

Fetch metadata of an object.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectName	string	Name of the object
opts	minio.StatObjectOptions	Options for GET info/stat requests specifying additional options like encryption, If-Match

Return Value

Param	Type	Description
objInfo	minio.ObjectInfo	Object stat information

minio.ObjectInfo

Field	Type	Description
objInfo.LastModified	time.Time	Time when object was last modified
objInfo.ETag	string	MD5 checksum of the object
objInfo.ContentType	string	Content type of the object
objInfo.Size	int64	Size of the object

Example

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

RemoveObject(bucketName, objectName string) error

Removes an object.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectName	string	Name of the object

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

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

Removes a list of objects obtained from an input channel. The call sends a delete request to the server up to 1000 objects at a time. The errors observed are sent over the error channel.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectsCh	chan string	Channel of objects to be removed

Return Values

Param	Type	Description
errorCh	<-chan minio.RemoveObjectError	Receive-only channel of errors observed during deletion.

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

Removes a partially uploaded object.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectName	string	Name of the object

Example

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

4. Encrypted object operations

NewSymmetricKey(key []byte) *encrypt.SymmetricKey

Parameters

Param	Type	Description
key	string	Name of the bucket

Return Value

Param	Type	Description
symmetricKey	*encrypt.SymmetricKey	represents a symmetric key structure which can be used to encrypt and decrypt data

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)

Parameters

Param	Type	Description
privateKey	[]byte	Private key data
publicKey	[]byte	Public key data

Return Value

Param	Type	Description
asymmetricKey	*encrypt.AsymmetricKey	represents an asymmetric key structure which can be used to encrypt and decrypt data
err	error	Standard 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)

Returns the decrypted stream of the object data based of the given encryption materials. Most of the common errors occur when reading the stream.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectName	string	Name of the object
encryptMaterials	encrypt.Materials	Interface provided by encrypt package to encrypt a stream of data (For more information see https://godoc.org/github.com/minio/minio-go)

Return Value

Param	Type	Description
stream	io.ReadCloser	Returns the deciphered object reader, caller should close after reading.
err	_error	Returns errors.

Example

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

Encrypt and upload an object.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectName	string	Name of the object
reader	io.Reader	Any Go type that implements io.Reader
encryptMaterials	encrypt.Materials	Interface provided by encrypt package to encrypt a stream of data (For more information see https://godoc.org/github.com/minio/minio-go)

Example

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

Encrypt and upload an object from a file.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectName	string	Name of the object
filePath	string	Path to file to be uploaded
encryptMaterials	encrypt.Materials	Interface provided by encrypt package to encrypt a stream of data (For more information see https://godoc.org/github.com/minio/minio-go)The module that encrypts data

Example

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

Create a key object for use as encryption or decryption parameter in operations involving server-side-encryption with customer provided key (SSE-C).

Parameters

Param	Type	Description
key	[]byte	Byte-slice of the raw, un-encoded binary key
algo	string	Algorithm to use in encryption or decryption with the given key. Can be empty (defaults to AES256)

5. Presigned operations

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

Generates a presigned URL for HTTP GET operations. Browsers/Mobile clients may point to this URL to directly download objects even if the bucket is private. This presigned URL can have an associated expiration time in seconds after which it is no longer operational. The default expiry is set to 7 days.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectName	string	Name of the object
expiry	time.Duration	Expiry of presigned URL in seconds
reqParams	url.Values	Additional response header overrides supports response-expires, response-content-type, response-cache-control, response-content-disposition.

Example

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

Generates a presigned URL for HTTP PUT operations. Browsers/Mobile clients may point to this URL to upload objects directly to a bucket even if it is private. This presigned URL can have an associated expiration time in seconds after which it is no longer operational. The default expiry is set to 7 days.

NOTE: you can upload to S3 only with specified object name.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectName	string	Name of the object
expiry	time.Duration	Expiry of presigned URL in seconds

Example

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

Generates a presigned URL for HTTP HEAD operations. Browsers/Mobile clients may point to this URL to directly get metadata from objects even if the bucket is private. This presigned URL can have an associated expiration time in seconds after which it is no longer operational. The default expiry is set to 7 days.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectName	string	Name of the object
expiry	time.Duration	Expiry of presigned URL in seconds
reqParams	url.Values	Additional response header overrides supports response-expires, response-content-type, response-cache-control, response-content-disposition.

Example

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

Allows setting policy conditions to a presigned URL for POST operations. Policies such as bucket name to receive object uploads, key name prefixes, expiry policy may be set.

// 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. Bucket policy/notification operations

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

Set access permissions on bucket or an object prefix.

Importing github.com/minio/minio-go/pkg/policy package is needed.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectPrefix	string	Name of the object prefix
policy	policy.BucketPolicy	Policy can be one of the following,
		policy.BucketPolicyNone
		policy.BucketPolicyReadOnly
		policy.BucketPolicyReadWrite
		policy.BucketPolicyWriteOnly

Return Values

Param	Type	Description
err	error	Standard Error

Example

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

Get access permissions on a bucket or a prefix.

Importing github.com/minio/minio-go/pkg/policy package is needed.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectPrefix	string	Prefix matching objects under the bucket

Return Values

Param	Type	Description
bucketPolicy	policy.BucketPolicy	string that contains: none, readonly, readwrite, or writeonly
err	error	Standard Error

Example

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)

Get access permissions rules associated to the specified bucket and prefix.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
objectPrefix	string	Prefix matching objects under the bucket

Return Values

Param	Type	Description
bucketPolicies	map[string]minio.BucketPolicy	Map of object resource paths and their permissions
err	error	Standard Error

Example

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)

Get notification configuration on a bucket.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket

Return Values

Param	Type	Description
bucketNotification	minio.BucketNotification	structure which holds all notification configurations
err	error	Standard Error

Example

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

Set a new bucket notification on a bucket.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket
bucketNotification	minio.BucketNotification	Represents the XML to be sent to the configured web service

Return Values

Param	Type	Description
err	error	Standard Error

Example

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

Remove all configured bucket notifications on a bucket.

Parameters

Param	Type	Description
bucketName	string	Name of the bucket

Return Values

Param	Type	Description
err	error	Standard Error

Example

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 receives bucket notification events through the notification channel. The returned notification channel has two fields 'Records' and 'Err'.

• 'Records' holds the notifications received from the server.
• 'Err' indicates any error while processing the received notifications.

NOTE: Notification channel is closed at the first occurrence of an error.

Parameters

Param	Type	Description
bucketName	string	Bucket to listen notifications on
prefix	string	Object key prefix to filter notifications for
suffix	string	Object key suffix to filter notifications for
events	[]string	Enables notifications for specific event types
doneCh	chan struct{}	A message on this channel ends the ListenBucketNotification iterator

Return Values

Param	Type	Description
notificationInfo	chan minio.NotificationInfo	Channel of bucket notifications

minio.NotificationInfo

|Field |Type |Description | |notificationInfo.Records | []minio.NotificationEvent | Collection of notification events | |notificationInfo.Err | error | Carries any error occurred during the operation (Standard Error) |

Example

// 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. Client custom settings

SetAppInfo(appName, appVersion string)

Add custom application details to User-Agent.

Parameters

Param	Type	Description
appName	string	Name of the application performing the API requests.
appVersion	string	Version of the application performing the API requests.

Example

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

SetCustomTransport(customHTTPTransport http.RoundTripper)

Overrides default HTTP transport. This is usually needed for debugging or for adding custom TLS certificates.

Parameters

Param	Type	Description
customHTTPTransport	http.RoundTripper	Custom transport e.g, to trace API requests and responses for debugging purposes.

TraceOn(outputStream io.Writer)

Enables HTTP tracing. The trace is written to the io.Writer provided. If outputStream is nil, trace is written to os.Stdout.

Parameters

Param	Type	Description
outputStream	io.Writer	HTTP trace is written into outputStream.

TraceOff()

Disables HTTP tracing.

SetS3TransferAccelerate(acceleratedEndpoint string)

Set AWS S3 transfer acceleration endpoint for all API requests hereafter. NOTE: This API applies only to AWS S3 and is a no operation for S3 compatible object storage services.

Parameters

Param	Type	Description
acceleratedEndpoint	string	Set to new S3 transfer acceleration endpoint.

8. Explore Further

• Build your own Go Music Player App example