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

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

• MakeBucket
• ListBuckets
• BucketExists
• RemoveBucket
• ListObjects
• ListIncompleteUploads

Object operations

• GetObject
• PutObject
• CopyObject
• StatObject
• RemoveObject
• RemoveIncompleteUpload

File operations.

• FPutObject
• FGetObject

Bucket policy operations.

• SetBucketPolicy
• GetBucketPolicy
• RemoveBucketPolicy

Presigned operations

• PresignedGetObject
• PresignedPutObject
• PresignedPostPolicy

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

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.

bucketList lists bucket in the format:

• bucket.Name string: bucket name
• bucket.CreationDate time.Time : date when bucket was created

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

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

Example

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

---

#### GetBucketPolicy(bucketName string, objectPrefix string) error Get access permissions on a bucket or a prefix.

Parameters

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

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

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

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 Value

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

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

• object *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

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) (n int, err 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.

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

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

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

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

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

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

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

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)