Minio Go Client API Reference Gitter

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 Presigned operations Bucket Policy/Notification Operations Client custom settings
MakeBucket GetObject PresignedGetObject SetBucketPolicy SetAppInfo
ListBuckets PutObject PresignedPutObject GetBucketPolicy SetCustomTransport
BucketExists CopyObject PresignedPostPolicy ListBucketPolicies TraceOn
RemoveBucket StatObject SetBucketNotification TraceOff
ListObjects RemoveObject GetBucketNotification SetS3TransferAccelerate
ListObjectsV2 RemoveObjects RemoveAllBucketNotification
ListIncompleteUploads RemoveIncompleteUpload ListenBucketNotification
FPutObject
FGetObject

1. Constructor

New(endpoint string, accessKeyID string, 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

2. Bucket operations

MakeBucket(bucketName string, 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 []BucketInfo Lists of all buckets
Param 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.

Parameters

Param Type Description
bucketName string Name of the bucket

Example


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

ListObjects(bucketName string, 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
chan ObjectInfo chan ObjectInfo Read channel for all objects in the bucket, the object is of the format listed below:
Param 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 string, 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
chan ObjectInfo chan ObjectInfo Read channel for all the objects in the bucket, the object is of the format listed below:
Param 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 '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 string, 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
chan ObjectMultipartInfo chan ObjectMultipartInfo Emits multipart objects of the format listed below:

Return Value

Param 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 string, objectName string) (*Object, error)

Downloads an object.

Parameters

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

Return Value

Param Type Description
object *minio.Object minio.Object represents object reader

Example


object, err := minioClient.GetObject("mybucket", "photo.jpg")
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 string, objectName string, filePath string) 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

Example


err := minioClient.FGetObject("mybucket", "photo.jpg", "/tmp/photo.jpg")
if err != nil {
    fmt.Println(err)
    return
}

PutObject(bucketName string, objectName string, reader io.Reader, contentType string) (n int, err error)

Uploads 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
contentType string Content type of the object

Example

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 in chunks of 64MiB or more depending on the actual file size. The max upload size for an object is 5TB.

In the event that PutObject fails to upload an object, the user may attempt to re-upload the same object. If the same object is being uploaded, PutObject API examines the previous partial attempt to upload this object and resumes automatically from where it left off.


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

n, err := minioClient.PutObject("mybucket", "myobject", file, "application/octet-stream")
if err != nil {
    fmt.Println(err)
    return
}

CopyObject(bucketName string, objectName string, objectSource string, conditions CopyConditions) error

Copy a source object into a new object with the provided name in the provided bucket.

Parameters

Param Type Description
bucketName string Name of the bucket
objectName string Name of the object
objectSource string Name of the source object
conditions CopyConditions Collection of supported CopyObject conditions. [x-amz-copy-source, x-amz-copy-source-if-match, x-amz-copy-source-if-none-match, x-amz-copy-source-if-unmodified-since, x-amz-copy-source-if-modified-since]

Example


// All following conditions are allowed and can be combined together.

// Set copy conditions.
var copyConds = minio.NewCopyConditions()
// Set modified condition, copy object modified since 2014 April.
copyConds.SetModified(time.Date(2014, time.April, 0, 0, 0, 0, 0, time.UTC))

// Set unmodified condition, copy object unmodified since 2014 April.
// copyConds.SetUnmodified(time.Date(2014, time.April, 0, 0, 0, 0, 0, time.UTC))

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

// Set matching ETag except condition, copy object which does not match the following ETag.
// copyConds.SetMatchETagExcept("31624deb84149d2f8ef9c385918b653a")

err := minioClient.CopyObject("mybucket", "myobject", "/my-sourcebucketname/my-sourceobjectname", copyConds)
if err != nil {
    fmt.Println(err)
    return
}

FPutObject(bucketName string, objectName string, filePath string, contentType string) error

Uploads contents from a file to objectName.

Parameters

Param Type Description
bucketName string Name of the bucket
objectName string Name of the object
filePath string Path to file to be uploaded
contentType string Content type of the object

Example

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.

In the event that FPutObject fails to upload an object, the user may attempt to re-upload the same object. If the same object is being uploaded, FPutObject API examines the previous partial attempt to upload this object and resumes automatically from where it left off.


n, err := minioClient.FPutObject("mybucket", "myobject.csv", "/tmp/otherobject.csv", "application/csv")
if err != nil {
    fmt.Println(err)
    return
}

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

Gets metadata of an object.

Parameters

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

Return Value

Param Type Description
objInfo ObjectInfo Object stat information
Param 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", "photo.jpg")
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println(objInfo)

RemoveObject(bucketName string, 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", "photo.jpg")
if err != nil {
    fmt.Println(err)
    return
}

RemoveObjects(bucketName string, objectsCh chan string) errorCh chan minio.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 Prefix of objects to be removed

Return Values

Param Type Description
errorCh _chan minio.RemoveObjectError Channel of errors observed during deletion.

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

RemoveIncompleteUpload(bucketName string, 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", "photo.jpg")
if err != nil {
    fmt.Println(err)
    return
}

4. Presigned operations

PresignedGetObject(bucketName string, 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
}

PresignedPutObject(bucketName string, 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(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.

Create policy :


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)

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

5. Bucket policy/notification operations

SetBucketPolicy(bucketname string, 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


err := minioClient.SetBucketPolicy("mybucket", "myprefix", policy.BucketPolicyReadWrite)
if err != nil {
    fmt.Println(err)
    return
}

GetBucketPolicy(bucketName string, 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 string, 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]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 all notification configurations related to the specified bucket.

Parameters

Param Type Description
bucketName string Name of the bucket

Return Values

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

Example

bucketNotification, err := minioClient.GetBucketNotification("mybucket")
if err != nil {
    log.Fatalf("Failed to get bucket notification configurations for mybucket - %v", err)
}
for _, topicConfig := range bucketNotification.TopicConfigs {
    for _, e := range topicConfig.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 BucketNotification Represents the XML to be sent to the configured web service

Return Values

Param Type Description
err error Standard Error

Example

topicArn := NewArn("aws", "sns", "us-east-1", "804605494417", "PhotoUpdate")

topicConfig := NewNotificationConfig(topicArn)
topicConfig.AddEvents(minio.ObjectCreatedAll, minio.ObjectRemovedAll)
lambdaConfig.AddFilterPrefix("photos/")
lambdaConfig.AddFilterSuffix(".jpg")

bucketNotification := BucketNotification{}
bucketNotification.AddTopic(topicConfig)
err := c.SetBucketNotification(bucketName, bucketNotification)
if err != nil {
    fmt.Println("Unable to set the bucket notification: " + err)
}

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 := c.RemoveAllBucketNotification(bucketName)
if err != nil {
    fmt.Println("Unable to remove bucket notifications.", err)
}

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'.

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
chan NotificationInfo chan Read channel for all notificatons on bucket
NotificationInfo object Notification object represents events info
notificationInfo.Records []NotificationEvent Collection of notification events
notificationInfo.Err error Carries any error occurred during the operation

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("YOUR-BUCKET", "PREFIX", "SUFFIX", []string{
    "s3:ObjectCreated:*",
    "s3:ObjectRemoved:*",
    }, doneCh) {
    if notificationInfo.Err != nil {
        log.Fatalln(notificationInfo.Err)
    }
    log.Println(notificationInfo)
}

6. Client custom settings

SetAppInfo(appName string, appVersion string)

Adds 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 ignored with other S3 compatible object storage services.

Parameters

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

7. Explore Further