Skip to content

Latest commit

 

History

History
586 lines (490 loc) · 16.2 KB

API.md

File metadata and controls

586 lines (490 loc) · 16.2 KB

API Documentation

Minio client object creation

Minio client object is created using minio-go:

package main

import (
    "fmt"

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

func main() {
    secure := true // Make HTTPS requests by default.
    s3Client, err := minio.New("s3.amazonaws.com", "YOUR-ACCESSKEYID", "YOUR-SECRETACCESSKEY", secure)
    if err != nil {
        fmt.Println(err)
        return
    }
}

s3Client can be used to perform operations on S3 storage. APIs are described below.

Bucket operations

Object operations

File operations.

Bucket policy operations.

Presigned operations

Bucket operations

#### MakeBucket(bucketName string, location string) error Create a new bucket.

Parameters

  • bucketName string - Name of the bucket.
  • location string - region valid values are us-west-1, us-west-2, eu-west-1, eu-central-1, ap-southeast-1, ap-northeast-1, ap-southeast-2, sa-east-1

Return Values

  • err error

Example

err := s3Client.MakeBucket("mybucket", "us-west-1")
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println("Successfully created mybucket.")
 #### ListBuckets() ([]BucketInfo, error) Lists all buckets.

Return Values

  • buckets []BucketInfo : array of BucketInfo objects that contain:
    • Name string : name of the bucket
    • CreationDate time.Time : date the bucket was created
  • err error

Example

buckets, err := s3Client.ListBuckets()
if err != nil {
    fmt.Println(err)
    return
}
for _, bucket := range buckets {
    fmt.Println(bucket)
}
 #### BucketExists(bucketName string) error Check if bucket exists.

Parameters

  • bucketName string : name of the bucket

Return Values

  • err error

Example

err := s3Client.BucketExists("mybucket")
if err != nil {
    fmt.Println(err)
    return
}
 #### RemoveBucket(bucketName string) error Remove a bucket.

Parameters

  • bucketName string : name of the bucket

Return Values

  • err error

Example

err := s3Client.RemoveBucket("mybucket")
if err != nil {
    fmt.Println(err)
    return
}
 #### GetBucketPolicy(bucketName string, objectPrefix string) (BucketPolicy, error) Get access permissions on a bucket or a prefix.

Parameters

  • bucketName string : name of the bucket
  • objectPrefix string : name of the object prefix

Return Values

  • bucketPolicy BucketPolicy : string that contains: 'none', 'readonly', 'readwrite', or 'writeonly'
  • err error

Example

bucketPolicy, err := s3Client.GetBucketPolicy("mybucket", "")
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println("Access permissions for mybucket is", bucketPolicy)
 #### SetBucketPolicy(bucketname string, objectPrefix string, policy BucketPolicy) error Set access permissions on bucket or an object prefix.

Parameters

  • bucketName string: name of the bucket
  • objectPrefix string : name of the object prefix
  • policy BucketPolicy: policy can be BucketPolicyNone, BucketPolicyReadOnly, BucketPolicyReadWrite, BucketPolicyWriteOnly

Return Values

  • err error

Example

err := s3Client.SetBucketPolicy("mybucket", "myprefix", BucketPolicyReadWrite)
if err != nil {
    fmt.Println(err)
    return
}
 #### RemoveBucketPolicy(bucketname string, objectPrefix string) error Remove existing permissions on bucket or an object prefix.

Parameters

  • bucketName string: name of the bucket
  • objectPrefix string : name of the object prefix

Return Values

  • err error

Example

err := s3Client.RemoveBucketPolicy("mybucket", "myprefix")
if err != nil {
    fmt.Println(err)
    return
}
 #### ListObjects(bucketName string, prefix string, recursive bool, doneCh chan struct{}) <-chan ObjectInfo List objects in a bucket.

Parameters

  • 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{} : channel for pro-actively closing the internal go routine

Return Values

  • <-chan ObjectInfo chan ObjectInfo: Read channel for all the objects in the bucket, the object is of the format:
    • 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

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
objectCh := s3Client.ListObjects("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 List partially uploaded objects in a bucket.

Parameters

  • bucketname string: name of the bucket
  • prefix string: prefix of the object names that are partially uploaded
  • recursive bool: directory style listing when false, recursive listing when true
  • doneCh chan struct{} : channel for pro-actively closing the internal go routine

Return Values

  • <-chan ObjectMultipartInfo chan ObjectMultipartInfo : emits multipart objects of the format:
    • 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
multiPartObjectCh := s3Client.ListIncompleteUploads("mybucket", "myprefix", isRecursive, doneCh)
for multiPartObject := range multiPartObjectCh {
    if multiPartObject.Err != nil {
        fmt.Println(multiPartObject.Err)
        return
    }
    fmt.Println(multiPartObject)
}

Object operations

#### GetObject(bucketName string, objectName string) *Object Download an object.

Parameters

  • bucketName string: name of the bucket
  • objectName string: name of the object

Return Values

  • object *Object : represents object reader.

Example

object, err := s3Client.GetObject("mybucket", "photo.jpg")
if err != nil {
    fmt.Println(err)
    return
}
localFile _ := os.Open("/tmp/local-file")
if _, err := io.Copy(localFile, object); err != nil {
    fmt.Println(err)
    return
}
 #### FGetObject(bucketName string, objectName string, filePath string) error Callback is called with `error` in case of error or `null` in case of success

Parameters

  • bucketName string: name of the bucket
  • objectName string: name of the object
  • filePath string: path to which the object data will be written to

Return Values

  • err error

Example

err := s3Client.FGetObject("mybucket", "photo.jpg", "/tmp/photo.jpg")
if err != nil {
    fmt.Println(err)
    return
}
 #### PutObject(bucketName string, objectName string, reader io.Reader, contentType string) (int64, error) Upload contents from `io.Reader` to objectName.

Parameters

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

Return Values

  • totalUploadedSize int64: Size in bytes of uploaded file
  • err error

Example

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

n, err := s3Client.PutObject("my-bucketname", "my-objectname", object, "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

  • 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']

Return Values

  • err error

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 := s3Client.CopyObject("my-bucketname", "my-objectname", "/my-sourcebucketname/my-sourceobjectname", copyConds)
if err != nil {
    fmt.Println(err)
    return
}
 #### FPutObject(bucketName string, objectName string, filePath string, contentType string) (int64, error) Uploads the object using contents from a file

Parameters

  • 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

Return Values

  • totalUploadedSize int64: Size in bytes of uploaded file
  • err: error

Example

n, err := s3Client.FPutObject("my-bucketname", "my-objectname", "/tmp/my-filename.csv", "application/csv")
if err != nil {
    fmt.Println(err)
    return
}
 #### StatObject(bucketName string, objectName string) (ObjectInfo, error) Get metadata of an object.

Parameters

  • bucketName string: name of the bucket
  • objectName string: name of the object

Return Values

  • objInfo ObjectInfo : object stat info for following format:
    • objInfo.Size int64: size of the object
    • objInfo.ETag string: etag of the object
    • objInfo.ContentType string: Content-Type of the object
    • objInfo.LastModified string: modified time stamp
  • err error

Example

objInfo, err := s3Client.StatObject("mybucket", "photo.jpg")
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println(objInfo)
 #### RemoveObject(bucketName string, objectName string) error Remove an object.

Parameters

  • bucketName string: name of the bucket
  • objectName string: name of the object

Return Values

  • err error

Example

err := s3Client.RemoveObject("mybucket", "photo.jpg")
if err != nil {
    fmt.Println(err)
    return
}
 #### RemoveIncompleteUpload(bucketName string, objectName string) error Remove an partially uploaded object.

Parameters

  • bucketName string: name of the bucket
  • objectName string: name of the object

Return Values

  • err error

Example

err := s3Client.RemoveIncompleteUpload("mybucket", "photo.jpg")
if err != nil {
    fmt.Println(err)
    return
}

Presigned operations

#### PresignedGetObject(bucketName, objectName string, expiry time.Duration, reqParams url.Values) (*url.URL, error) Generate a presigned URL for GET.

Parameters

  • 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

Return Values

  • url *url.URL : Presigned URL for GET on an object
  • err error

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 := s3Client.PresignedGetObject("mybucket", "photo.jpg", time.Second * 24 * 60 * 60, reqParams)
if err != nil {
    fmt.Println(err)
    return
}
 #### PresignedPutObject(bucketName string, objectName string, expiry time.Duration) (*url.URL, error) Generate a presigned URL for PUT.
NOTE: you can upload to S3 only with specified object name.

Parameters

  • bucketName string: name of the bucket
  • objectName string: name of the object
  • expiry time.Duration: expiry in seconds

Return Values

  • url *url.URL : Presigned URL for PUT on an object
  • err _error

Example

// Generates a url which expires in a day.
presignedURL, err := s3Client.PresignedPutObject("mybucket", "photo.jpg", time.Second * 24 * 60 * 60)
if err != nil {
    fmt.Println(err)
    return
}
 #### PresignedPostPolicy(policy PostPolicy) (*url.URL, map[string]string, error) PresignedPostPolicy we can provide policies specifying conditions restricting what you want to allow in a POST request, such as bucket name where objects can be uploaded, key name prefixes that you want to allow for the object being created and more.

We need to create our policy first:

policy := minio.NewPostPolicy()

Apply upload policy restrictions:

policy.SetBucket("my-bucketname")
policy.SetKey("my-objectname")
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 := s3Client.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 m {
    fmt.Printf("-F %s=%s ", k, v)
}
fmt.Printf("-F file=@/etc/bash.bashrc ")
fmt.Printf("%s\n", url)