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() {
    s3Client, err := minio.New("s3.amazonaws.com", "YOUR-ACCESSKEYID", "YOUR-SECRETACCESSKEY", false)
    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, location) Create a new bucket.

Arguments

• 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() List all buckets.

bucketList emits bucket with 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) Check if bucket exists.

Arguments

• bucketName string : name of the bucket

Example

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

---

#### RemoveBucket(bucketName) Remove a bucket.

Arguments

• bucketName string : name of the bucket

Example

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

---

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

Arguments

• 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, objectPrefix, policy) Set access permissions on bucket or an object prefix.

Arguments

• bucketName string: name of the bucket
• objectPrefix string : name of the object prefix
• policy BucketPolicy: policy can be non, readonly, readwrite, writeonly

Example

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

---

#### RemoveBucketPolicy(bucketname, objectPrefix) Remove existing permissions on bucket or an object prefix.

Arguments

• 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, prefix, recursive, doneCh) List objects in a bucket.

Arguments

• 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, prefix, recursive) List partially uploaded objects in a bucket.

Arguments

• 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, objectName) Download an object.

Arguments

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

Return Value

• object *minio.Object : minio.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, objectName, filePath) Callback is called with `error` in case of error or `null` in case of success

Arguments

• 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, objectName, reader, contentType) Upload an object.

Uploading a stream Arguments

• 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, objectName, objectSource, conditions) Copy a source object into a new object with the provided name in the provided bucket.

Arguments

• 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, objectName, filePath, contentType) Uploads the object using contents from a file

Arguments

• 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, objectName) Get metadata of an object.

Arguments

• 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, objectName) Remove an object.

Arguments

• 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, objectName) Remove an partially uploaded object.

Arguments

• 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, expiry) Generate a presigned URL for GET.

Arguments

• 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, objectName, expiry) Generate a presigned URL for PUT.

NOTE: you can upload to S3 only with specified object name.

Arguments

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

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("https://my-bucketname.s3.amazonaws.com\n")