Skip to content

Latest commit

 

History

History
1036 lines (671 loc) · 26 KB

API.md

File metadata and controls

1036 lines (671 loc) · 26 KB
Raw

Golang 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
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", "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("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