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

Golang 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	Presigned operations	Bucket Policy/Notification Operations
MakeBucket	GetObject	PresignedGetObject	SetBucketPolicy
ListBuckets	PutObject	PresignedPutObject	GetBucketPolicy
BucketExists	CopyObject	PresignedPostPolicy	SetBucketNotification
RemoveBucket	StatObject		GetBucketNotification
ListObjects	RemoveObject		DeleteBucketNotification
ListObjectsV2	RemoveIncompleteUpload
ListIncompleteUploads	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 object storage endpoint.
accessKeyID	string	Access key for the object storage endpoint.
secretAccessKey	string	Secret key for the object storage endpoint.
ssl	bool	Set this value to 'true' to enable secure (HTTPS) access.

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	Default value is us-east-1 Region where the bucket is created. Valid values are listed below:
		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 bucket in following format shown below:

Param	Type	Description
bucket.Name	string	bucket name.
bucket.CreationDate	time.Time	date when bucket was created.

Example

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

BucketExists(bucketName string) error

Checks if a bucket exists.

Parameters

Param	Type	Description
bucketName	string	name of the bucket.

Example

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

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	the prefix of the objects that should be listed.
recursive	bool	true indicates recursive style listing and false indicates directory style listing delimited by '/'.
doneCh	chan struct{}	Set this value to 'true' to enable secure (HTTPS) access.

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	etag of the object.
objectInfo.LastModified	time.Time	modified time stamp.

// 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 recommanded listing API v2

Parameters

Param	Type	Description
bucketName	string	name of the bucket.
objectPrefix	string	the prefix of the objects that should be listed.
recursive	bool	true indicates recursive style listing and false indicates directory style listing delimited by '/'.
doneCh	chan struct{}	Set this value to 'true' to enable secure (HTTPS) access.

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	etag of the object.
objectInfo.LastModified	time.Time	modified time stamp.

// 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 the object names that are partially uploaded
recursive	bool	true indicates recursive style listing and false indicates directory style listing delimited by '/'.
doneCh	chan struct{}	Set this value to 'true' to enable secure (HTTPS) access.

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 the incomplete object.
multiPartObjInfo.UploadID	string	upload ID of the incomplete object.
multiPartObjInfo.Size	int64	size of the 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 which the object data will be written 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 golang object implementing io.Reader.
contentType	string	content type of the object.

Example

Uploads objects that are less than 5MiB in a single PUT operation. For objects that are greater than the 5MiB in size, PutObject seamlessly uploads the object in chunks of 5MiB 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 object source.
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	file path of the file to be uploaded.
contentType	string	content type of the object.

Example

FPutObject uploads objects that are less than 5MiB in a single PUT operation. For objects that are greater than the 5MiB in size, FPutObject seamlessly uploads the object in chunks of 5MiB 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 info for format listed below:

Param	Type	Description
objInfo.LastModified	time.Time	modified time stamp.
objInfo.ETag	string	etag 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
}

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 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 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 BucketPolicy) error

Set access permissions on bucket or an object prefix.

Parameters

Param	Type	Description
bucketName	string	name of the bucket.
objectPrefix	string	name of the object prefix.
policy	BucketPolicy	policy can be:
		BucketPolicyNone
		BucketPolicyReadOnly
		BucketPolicyReadWrite
		BucketPolicyWriteOnly

Return Values

Param	Type	Description
err	error	standard error

Example

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

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

Get access permissions on a bucket or a prefix.

Parameters

Param	Type	Description
bucketName	string	name of the bucket.
objectPrefix	string	name of the object prefix

Return Values

Param	Type	Description
bucketPolicy	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)

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 {
    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	bucket notification.

Return Values

Param	Type	Description
err	error	standard error

Example

topicArn := NewArn("aws", "s3", "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("Cannot 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("Cannot remove bucket notifications.")
}

ListenBucketNotification(bucketName string, accountArn Arn, 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 from.
accountArn	Arn	Unique account ID to listen notifications for.
doneCh	chan struct{}	A message on this channel ends the ListenBucketNotification loop.

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)

// Fetch the bucket location.
location, err := minioClient.GetBucketLocation("YOUR-BUCKET")
if err != nil {
	log.Fatalln(err)
}

// Construct a new account Arn.
accountArn := minio.NewArn("minio", "sns", location, "your-account-id", "listen")
topicConfig := minio.NewNotificationConfig(accountArn)
topicConfig.AddEvents(minio.ObjectCreatedAll, minio.ObjectRemovedAll)
topicConfig.AddFilterPrefix("photos/")
topicConfig.AddFilterSuffix(".jpg")

// Now, set all previously created notification configs
bucketNotification := minio.BucketNotification{}
bucketNotification.AddTopic(topicConfig)
err = s3Client.SetBucketNotification("YOUR-BUCKET", bucketNotification)
if err != nil {
	log.Fatalln("Error: " + err.Error())
}
log.Println("Success")

// Listen for bucket notifications on "mybucket" filtered by accountArn "arn:minio:sns:<location>:<your-account-id>:listen".
for notificationInfo := range s3Client.ListenBucketNotification("mybucket", accountArn, doneCh) {
       if notificationInfo.Err != nil {
               fmt.Println(notificationInfo.Err)
                return
       }
       fmt.Println(notificationInfo)
}

6. Explore Further

• Build your own Go Music Player App example