diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/API.md | 781 | ||||
| -rw-r--r-- | docs/checker.go.template | 21 | ||||
| -rw-r--r-- | docs/validator.go | 227 | ||||
| -rw-r--r-- | docs/zh_CN/API.md | 1820 | ||||
| -rw-r--r-- | docs/zh_CN/CONTRIBUTING.md | 22 |
5 files changed, 2655 insertions, 216 deletions
diff --git a/docs/API.md b/docs/API.md index e0d0a11..d1026ee 100644 --- a/docs/API.md +++ b/docs/API.md @@ -55,17 +55,19 @@ func main() { | [`MakeBucket`](#MakeBucket) | [`GetObject`](#GetObject) | [`NewSymmetricKey`](#NewSymmetricKey) | [`PresignedGetObject`](#PresignedGetObject) | [`SetBucketPolicy`](#SetBucketPolicy) | [`SetAppInfo`](#SetAppInfo) | | [`ListBuckets`](#ListBuckets) | [`PutObject`](#PutObject) | [`NewAsymmetricKey`](#NewAsymmetricKey) | [`PresignedPutObject`](#PresignedPutObject) | [`GetBucketPolicy`](#GetBucketPolicy) | [`SetCustomTransport`](#SetCustomTransport) | | [`BucketExists`](#BucketExists) | [`CopyObject`](#CopyObject) | [`GetEncryptedObject`](#GetEncryptedObject) | [`PresignedPostPolicy`](#PresignedPostPolicy) | [`ListBucketPolicies`](#ListBucketPolicies) | [`TraceOn`](#TraceOn) | -| [`RemoveBucket`](#RemoveBucket) | [`StatObject`](#StatObject) | [`PutObjectStreaming`](#PutObjectStreaming) | | [`SetBucketNotification`](#SetBucketNotification) | [`TraceOff`](#TraceOff) | -| [`ListObjects`](#ListObjects) | [`RemoveObject`](#RemoveObject) | [`PutEncryptedObject`](#PutEncryptedObject) | | [`GetBucketNotification`](#GetBucketNotification) | [`SetS3TransferAccelerate`](#SetS3TransferAccelerate) | -| [`ListObjectsV2`](#ListObjectsV2) | [`RemoveObjects`](#RemoveObjects) | [`NewSSEInfo`](#NewSSEInfo) | | [`RemoveAllBucketNotification`](#RemoveAllBucketNotification) | | +| [`RemoveBucket`](#RemoveBucket) | [`StatObject`](#StatObject) | [`PutEncryptedObject`](#PutEncryptedObject) | | [`SetBucketNotification`](#SetBucketNotification) | [`TraceOff`](#TraceOff) | +| [`ListObjects`](#ListObjects) | [`RemoveObject`](#RemoveObject) | [`NewSSEInfo`](#NewSSEInfo) | | [`GetBucketNotification`](#GetBucketNotification) | [`SetS3TransferAccelerate`](#SetS3TransferAccelerate) | +| [`ListObjectsV2`](#ListObjectsV2) | [`RemoveObjects`](#RemoveObjects) | [`FPutEncryptedObject`](#FPutEncryptedObject) | | [`RemoveAllBucketNotification`](#RemoveAllBucketNotification) | | | [`ListIncompleteUploads`](#ListIncompleteUploads) | [`RemoveIncompleteUpload`](#RemoveIncompleteUpload) | | | [`ListenBucketNotification`](#ListenBucketNotification) | | | | [`FPutObject`](#FPutObject) | | | | | | | [`FGetObject`](#FGetObject) | | | | | | | [`ComposeObject`](#ComposeObject) | | | | | | | [`NewSourceInfo`](#NewSourceInfo) | | | | | | | [`NewDestinationInfo`](#NewDestinationInfo) | | | | | - - +| | [`PutObjectWithContext`](#PutObjectWithContext) | | | | +| | [`GetObjectWithContext`](#GetObjectWithContext) | | | | +| | [`FPutObjectWithContext`](#FPutObjectWithContext) | | | | +| | [`FGetObjectWithContext`](#FGetObjectWithContext) | | | | ## 1. Constructor <a name="Minio"></a> @@ -82,7 +84,7 @@ __Parameters__ |`ssl` | _bool_ | If 'true' API requests will be secure (HTTPS), and insecure (HTTP) otherwise | ### NewWithRegion(endpoint, accessKeyID, secretAccessKey string, ssl bool, region string) (*Client, error) -Initializes minio client, with region configured. Unlike New(), NewWithRegion avoids bucket-location lookup operations and it is slightly faster. Use this function when if your application deals with single region. +Initializes minio client, with region configured. Unlike New(), NewWithRegion avoids bucket-location lookup operations and it is slightly faster. Use this function when your application deals with a single region. __Parameters__ @@ -121,7 +123,7 @@ __Example__ ```go -err := minioClient.MakeBucket("mybucket", "us-east-1") +err = minioClient.MakeBucket("mybucket", "us-east-1") if err != nil { fmt.Println(err) return @@ -131,15 +133,16 @@ fmt.Println("Successfully created mybucket.") <a name="ListBuckets"></a> ### ListBuckets() ([]BucketInfo, error) - Lists all buckets. | Param | Type | Description | |---|---|---| -|`bucketList` | _[]BucketInfo_ | Lists of all buckets | +|`bucketList` | _[]minio.BucketInfo_ | Lists of all buckets | -| Param | Type | Description | +__minio.BucketInfo__ + +| Field | Type | Description | |---|---|---| |`bucket.Name` | _string_ | Name of the bucket | |`bucket.CreationDate` | _time.Time_ | Date of bucket creation | @@ -150,7 +153,7 @@ __Example__ ```go buckets, err := minioClient.ListBuckets() - if err != nil { +if err != nil { fmt.Println(err) return } @@ -161,7 +164,6 @@ for _, bucket := range buckets { <a name="BucketExists"></a> ### BucketExists(bucketName string) (found bool, err error) - Checks if a bucket exists. __Parameters__ @@ -196,8 +198,7 @@ if found { <a name="RemoveBucket"></a> ### RemoveBucket(bucketName string) error - -Removes a bucket. +Removes a bucket, bucket should be empty to be successfully removed. __Parameters__ @@ -210,7 +211,7 @@ __Example__ ```go -err := minioClient.RemoveBucket("mybucket") +err = minioClient.RemoveBucket("mybucket") if err != nil { fmt.Println(err) return @@ -219,7 +220,6 @@ if err != nil { <a name="ListObjects"></a> ### ListObjects(bucketName, prefix string, recursive bool, doneCh chan struct{}) <-chan ObjectInfo - Lists objects in a bucket. __Parameters__ @@ -237,9 +237,11 @@ __Return Value__ |Param |Type |Description | |:---|:---| :---| -|`chan ObjectInfo` | _chan ObjectInfo_ |Read channel for all objects in the bucket, the object is of the format listed below: | +|`objectInfo` | _chan minio.ObjectInfo_ |Read channel for all objects in the bucket, the object is of the format listed below: | -|Param |Type |Description | +__minio.ObjectInfo__ + +|Field |Type |Description | |:---|:---| :---| |`objectInfo.Key` | _string_ |Name of the object | |`objectInfo.Size` | _int64_ |Size of the object | @@ -268,7 +270,6 @@ for object := range objectCh { <a name="ListObjectsV2"></a> ### ListObjectsV2(bucketName, prefix string, recursive bool, doneCh chan struct{}) <-chan ObjectInfo - Lists objects in a bucket using the recommended listing API v2 __Parameters__ @@ -286,14 +287,7 @@ __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_ |MD5 checksum of the object | -|`objectInfo.LastModified` | _time.Time_ |Time when object was last modified | +|`objectInfo` | _chan minio.ObjectInfo_ |Read channel for all the objects in the bucket, the object is of the format listed below: | ```go @@ -316,7 +310,6 @@ for object := range objectCh { <a name="ListIncompleteUploads"></a> ### ListIncompleteUploads(bucketName, prefix string, recursive bool, doneCh chan struct{}) <- chan ObjectMultipartInfo - Lists partially uploaded objects in a bucket. @@ -335,11 +328,11 @@ __Return Value__ |Param |Type |Description | |:---|:---| :---| -|`chan ObjectMultipartInfo` | _chan ObjectMultipartInfo_ |Emits multipart objects of the format listed below: | +|`multiPartInfo` | _chan minio.ObjectMultipartInfo_ |Emits multipart objects of the format listed below: | -__Return Value__ +__minio.ObjectMultipartInfo__ -|Param |Type |Description | +|Field |Type |Description | |:---|:---| :---| |`multiPartObjInfo.Key` | _string_ |Name of incompletely uploaded object | |`multiPartObjInfo.UploadID` | _string_ |Upload ID of incompletely uploaded object | @@ -369,8 +362,7 @@ for multiPartObject := range multiPartObjectCh { ## 3. Object operations <a name="GetObject"></a> -### GetObject(bucketName, objectName string) (*Object, error) - +### GetObject(bucketName, objectName string, opts GetObjectOptions) (*Object, error) Returns a stream of the object data. Most of the common errors occur when reading the stream. @@ -381,7 +373,14 @@ __Parameters__ |:---|:---| :---| |`bucketName` | _string_ |Name of the bucket | |`objectName` | _string_ |Name of the object | +|`opts` | _minio.GetObjectOptions_ | Options for GET requests specifying additional options like encryption, If-Match | + +__minio.GetObjectOptions__ + +|Field | Type | Description | +|:---|:---|:---| +| `opts.Materials` | _encrypt.Materials_ | Interface provided by `encrypt` package to encrypt a stream of data (For more information see https://godoc.org/github.com/minio/minio-go) | __Return Value__ @@ -395,7 +394,7 @@ __Example__ ```go -object, err := minioClient.GetObject("mybucket", "photo.jpg") +object, err := minioClient.GetObject("mybucket", "myobject", minio.GetObjectOptions{}) if err != nil { fmt.Println(err) return @@ -412,34 +411,146 @@ if _, err = io.Copy(localFile, object); err != nil { ``` <a name="FGetObject"></a> -### FGetObject(bucketName, objectName, filePath string) error - Downloads and saves the object as a file in the local filesystem. +### FGetObject(bucketName, objectName, filePath string, opts GetObjectOptions) 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 download object to | +|`opts` | _minio.GetObjectOptions_ | Options for GET requests specifying additional options like encryption, If-Match | + + +__Example__ + + +```go +err = minioClient.FGetObject("mybucket", "myobject", "/tmp/myobject", minio.GetObjectOptions{}) +if err != nil { + fmt.Println(err) + return +} +``` +<a name="GetObjectWithContext"></a> +### GetObjectWithContext(ctx context.Context, bucketName, objectName string, opts GetObjectOptions) (*Object, error) +Identical to GetObject operation, but accepts a context for request cancellation. + +__Parameters__ +|Param |Type |Description | +|:---|:---| :---| +|`ctx` | _context.Context_ |Request context | +|`bucketName` | _string_ |Name of the bucket | +|`objectName` | _string_ |Name of the object | +|`opts` | _minio.GetObjectOptions_ | Options for GET requests specifying additional options like encryption, If-Match | + + +__Return Value__ + + +|Param |Type |Description | +|:---|:---| :---| +|`object` | _*minio.Object_ |_minio.Object_ represents object reader. It implements io.Reader, io.Seeker, io.ReaderAt and io.Closer interfaces. | + + +__Example__ + + +```go +ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second) +defer cancel() + +object, err := minioClient.GetObjectWithContext(ctx, "mybucket", "myobject", minio.GetObjectOptions{}) +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 +} +``` + +<a name="FGetObjectWithContext"></a> +### FGetObjectWithContext(ctx context.Context, bucketName, objectName, filePath string, opts GetObjectOptions) error +Identical to FGetObject operation, but allows request cancellation. + __Parameters__ |Param |Type |Description | |:---|:---| :---| +|`ctx` | _context.Context_ |Request context | |`bucketName` | _string_ |Name of the bucket | |`objectName` | _string_ |Name of the object | |`filePath` | _string_ |Path to download object to | +|`opts` | _minio.GetObjectOptions_ | Options for GET requests specifying additional options like encryption, If-Match | __Example__ ```go -err := minioClient.FGetObject("mybucket", "photo.jpg", "/tmp/photo.jpg") +ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second) +defer cancel() + +err = minioClient.FGetObjectWithContext(ctx, "mybucket", "myobject", "/tmp/myobject", minio.GetObjectOptions{}) if err != nil { fmt.Println(err) return } ``` -<a name="PutObject"></a> -### PutObject(bucketName, objectName string, reader io.Reader, contentType string) (n int, err error) +<a name="FGetEncryptedObject"></a> +### FGetEncryptedObject(bucketName, objectName, filePath string, materials encrypt.Materials) error +Identical to FGetObject operation, but decrypts an encrypted request + +__Parameters__ + + +|Param |Type |Description | +|:---|:---| :---| +|`bucketName` | _string_ |Name of the bucket | +|`objectName` | _string_ |Name of the object | +|`filePath` | _string_ |Path to download object to | +|`materials` | _encrypt.Materials_ | Interface provided by `encrypt` package to encrypt a stream of data (For more information see https://godoc.org/github.com/minio/minio-go) | + +__Example__ + + +```go +// Generate a master symmetric key +key := encrypt.NewSymmetricKey([]byte("my-secret-key-00")) + +// Build the CBC encryption material +cbcMaterials, err := encrypt.NewCBCSecureMaterials(key) +if err != nil { + fmt.Println(err) + return +} + +err = minioClient.FGetEncryptedObject("mybucket", "myobject", "/tmp/myobject", cbcMaterials) +if err != nil { + fmt.Println(err) + return +} +``` + +<a name="PutObject"></a> +### PutObject(bucketName, objectName string, reader io.Reader, objectSize int64,opts PutObjectOptions) (n int, err error) Uploads objects that are less than 64MiB in a single PUT operation. For objects that are greater than 64MiB in size, PutObject seamlessly uploads the object as parts of 64MiB or more depending on the actual file size. The max upload size for an object is 5TB. __Parameters__ @@ -450,7 +561,20 @@ __Parameters__ |`bucketName` | _string_ |Name of the bucket | |`objectName` | _string_ |Name of the object | |`reader` | _io.Reader_ |Any Go type that implements io.Reader | -|`contentType` | _string_ |Content type of the object | +|`objectSize`| _int64_ |Size of the object being uploaded. Pass -1 if stream size is unknown | +|`opts` | _minio.PutObjectOptions_ | Allows user to set optional custom metadata, content headers, encryption keys and number of threads for multipart upload operation. | + +__minio.PutObjectOptions__ + +|Field | Type | Description | +|:--- |:--- | :--- | +| `opts.UserMetadata` | _map[string]string_ | Map of user metadata| +| `opts.Progress` | _io.Reader_ | Reader to fetch progress of an upload | +| `opts.ContentType` | _string_ | Content type of object, e.g "application/text" | +| `opts.ContentEncoding` | _string_ | Content encoding of object, e.g "gzip" | +| `opts.ContentDisposition` | _string_ | Content disposition of object, "inline" | +| `opts.CacheControl` | _string_ | Used to specify directives for caching mechanisms in both requests and responses e.g "max-age=600"| +| `opts.EncryptMaterials` | _encrypt.Materials_ | Interface provided by `encrypt` package to encrypt a stream of data (For more information see https://godoc.org/github.com/minio/minio-go) | __Example__ @@ -464,32 +588,46 @@ if err != nil { } defer file.Close() -n, err := minioClient.PutObject("mybucket", "myobject", file, "application/octet-stream") +fileStat, err := file.Stat() if err != nil { fmt.Println(err) return } -``` -<a name="PutObjectStreaming"></a> -### PutObjectStreaming(bucketName, objectName string, reader io.Reader) (n int, err error) +n, err := minioClient.PutObject("mybucket", "myobject", file, fileStat.Size(), minio.PutObjectOptions{ContentType:"application/octet-stream"}) +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Successfully uploaded bytes: ", n) +``` -Uploads an object as multiple chunks keeping memory consumption constant. It is similar to PutObject in how objects are broken into multiple parts. Each part in turn is transferred as multiple chunks with constant memory usage. However resuming previously failed uploads from where it was left is not supported. +API methods PutObjectWithSize, PutObjectWithMetadata, PutObjectStreaming, and PutObjectWithProgress available in minio-go SDK release v3.0.3 are replaced by the new PutObject call variant that accepts a pointer to PutObjectOptions struct. +<a name="PutObjectWithContext"></a> +### PutObjectWithContext(ctx context.Context, bucketName, objectName string, reader io.Reader, objectSize int64, opts PutObjectOptions) (n int, err error) +Identical to PutObject operation, but allows request cancellation. __Parameters__ |Param |Type |Description | -|:---|:---|:---| +|:---|:---| :---| +|`ctx` | _context.Context_ |Request context | |`bucketName` | _string_ |Name of the bucket | |`objectName` | _string_ |Name of the object | |`reader` | _io.Reader_ |Any Go type that implements io.Reader | +|`objectSize`| _int64_ | size of the object being uploaded. Pass -1 if stream size is unknown | +|`opts` | _minio.PutObjectOptions_ |Pointer to struct that allows user to set optional custom metadata, content-type, content-encoding,content-disposition and cache-control headers, pass encryption module for encrypting objects, and optionally configure number of threads for multipart put operation. | + __Example__ ```go +ctx, cancel := context.WithTimeout(context.Background(), 10 * time.Second) +defer cancel() + file, err := os.Open("my-testfile") if err != nil { fmt.Println(err) @@ -497,50 +635,63 @@ if err != nil { } defer file.Close() -n, err := minioClient.PutObjectStreaming("mybucket", "myobject", file) +fileStat, err := file.Stat() if err != nil { fmt.Println(err) return } -``` +n, err := minioClient.PutObjectWithContext(ctx, "my-bucketname", "my-objectname", file, fileStat.Size(), minio.PutObjectOptions{ + ContentType: "application/octet-stream", +}) +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Successfully uploaded bytes: ", n) +``` <a name="CopyObject"></a> ### CopyObject(dst DestinationInfo, src SourceInfo) error - Create or replace an object through server-side copying of an existing object. It supports conditional copying, copying a part of an object and server-side encryption of destination and decryption of source. See the `SourceInfo` and `DestinationInfo` types for further details. To copy multiple source objects into a single destination object see the `ComposeObject` API. - __Parameters__ |Param |Type |Description | |:---|:---| :---| -|`dst` | _DestinationInfo_ |Argument describing the destination object | -|`src` | _SourceInfo_ |Argument describing the source object | +|`dst` | _minio.DestinationInfo_ |Argument describing the destination object | +|`src` | _minio.SourceInfo_ |Argument describing the source object | __Example__ ```go -// Use-case 1: Simple copy object with no conditions, etc +// Use-case 1: Simple copy object with no conditions. // Source object src := minio.NewSourceInfo("my-sourcebucketname", "my-sourceobjectname", nil) // Destination object -dst := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) +dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) +if err != nil { + fmt.Println(err) + return +} -/ Copy object call -err = s3Client.CopyObject(dst, src) +// Copy object call +err = minioClient.CopyObject(dst, src) if err != nil { fmt.Println(err) return } +``` -// Use-case 2: Copy object with copy-conditions, and copying only part of the source object. +```go +// Use-case 2: +// Copy object with copy-conditions, and copying only part of the source object. // 1. that matches a given ETag // 2. and modified after 1st April 2014 // 3. but unmodified since 23rd April 2014 @@ -562,10 +713,14 @@ src.SetUnmodifiedSinceCond(time.Date(2014, time.April, 23, 0, 0, 0, 0, time.UTC) src.SetRange(0, 1024*1024-1) // Destination object -dst := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) +dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) +if err != nil { + fmt.Println(err) + return +} -/ Copy object call -err = s3Client.CopyObject(dst, src) +// Copy object call +err = minioClient.CopyObject(dst, src) if err != nil { fmt.Println(err) return @@ -573,10 +728,8 @@ if err != nil { ``` <a name="ComposeObject"></a> -### ComposeObject(dst DestinationInfo, srcs []SourceInfo) error - -Create an object by concatenating a list of source objects using -server-side copying. +### ComposeObject(dst minio.DestinationInfo, srcs []minio.SourceInfo) error +Create an object by concatenating a list of source objects using server-side copying. __Parameters__ @@ -597,14 +750,14 @@ decKey := minio.NewSSEInfo([]byte{1, 2, 3}, "") // Source objects to concatenate. We also specify decryption // key for each -src1 := minio.NewSourceInfo("bucket1", "object1", decKey) -src1.SetMatchETag("31624deb84149d2f8ef9c385918b653a") +src1 := minio.NewSourceInfo("bucket1", "object1", &decKey) +src1.SetMatchETagCond("31624deb84149d2f8ef9c385918b653a") -src2 := minio.NewSourceInfo("bucket2", "object2", decKey) -src2.SetMatchETag("f8ef9c385918b653a31624deb84149d2") +src2 := minio.NewSourceInfo("bucket2", "object2", &decKey) +src2.SetMatchETagCond("f8ef9c385918b653a31624deb84149d2") -src3 := minio.NewSourceInfo("bucket3", "object3", decKey) -src3.SetMatchETag("5918b653a31624deb84149d2f8ef9c38") +src3 := minio.NewSourceInfo("bucket3", "object3", &decKey) +src3.SetMatchETagCond("5918b653a31624deb84149d2f8ef9c38") // Create slice of sources. srcs := []minio.SourceInfo{src1, src2, src3} @@ -613,19 +766,24 @@ srcs := []minio.SourceInfo{src1, src2, src3} encKey := minio.NewSSEInfo([]byte{8, 9, 0}, "") // Create destination info -dst := minio.NewDestinationInfo("bucket", "object", encKey, nil) -err = s3Client.ComposeObject(dst, srcs) +dst, err := minio.NewDestinationInfo("bucket", "object", &encKey, nil) +if err != nil { + fmt.Println(err) + return +} + +// Compose object call by concatenating multiple source files. +err = minioClient.ComposeObject(dst, srcs) if err != nil { - log.Println(err) - return + fmt.Println(err) + return } -log.Println("Composed object successfully.") +fmt.Println("Composed object successfully.") ``` <a name="NewSourceInfo"></a> ### NewSourceInfo(bucket, object string, decryptSSEC *SSEInfo) SourceInfo - Construct a `SourceInfo` object that can be used as the source for server-side copying operations like `CopyObject` and `ComposeObject`. This object can be used to set copy-conditions on the source. __Parameters__ @@ -638,18 +796,47 @@ __Parameters__ __Example__ -``` go +```go // No decryption parameter. -src := NewSourceInfo("bucket", "object", nil) +src := minio.NewSourceInfo("bucket", "object", nil) + +// Destination object +dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) +if err != nil { + fmt.Println(err) + return +} + +// Copy object call +err = minioClient.CopyObject(dst, src) +if err != nil { + fmt.Println(err) + return +} +``` +```go // With decryption parameter. -decKey := NewSSEKey([]byte{1,2,3}, "") -src := NewSourceInfo("bucket", "object", decKey) +decKey := minio.NewSSEInfo([]byte{1,2,3}, "") +src := minio.NewSourceInfo("bucket", "object", &decKey) + +// Destination object +dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) +if err != nil { + fmt.Println(err) + return +} + +// Copy object call +err = minioClient.CopyObject(dst, src) +if err != nil { + fmt.Println(err) + return +} ``` <a name="NewDestinationInfo"></a> -### NewDestinationInfo(bucket, object string, encryptSSEC *SSEInfo, userMeta map[string]string) DestinationInfo - +### NewDestinationInfo(bucket, object string, encryptSSEC *SSEInfo, userMeta map[string]string) (DestinationInfo, error) Construct a `DestinationInfo` object that can be used as the destination object for server-side copying operations like `CopyObject` and `ComposeObject`. __Parameters__ @@ -663,24 +850,48 @@ __Parameters__ __Example__ -``` go +```go // No encryption parameter. -src := NewDestinationInfo("bucket", "object", nil, nil) +src := minio.NewSourceInfo("bucket", "object", nil) +dst, err := minio.NewDestinationInfo("bucket", "object", nil, nil) +if err != nil { + fmt.Println(err) + return +} -// With encryption parameter. -encKey := NewSSEKey([]byte{1,2,3}, "") -src := NewDecryptionInfo("bucket", "object", encKey, nil) +// Copy object call +err = minioClient.CopyObject(dst, src) +if err != nil { + fmt.Println(err) + return +} ``` +```go +src := minio.NewSourceInfo("bucket", "object", nil) + +// With encryption parameter. +encKey := minio.NewSSEInfo([]byte{1,2,3}, "") +dst, err := minio.NewDestinationInfo("bucket", "object", &encKey, nil) +if err != nil { + fmt.Println(err) + return +} -<a name="FPutObject"></a> -### FPutObject(bucketName, objectName, filePath, contentType string) (length int64, err error) +// Copy object call +err = minioClient.CopyObject(dst, src) +if err != nil { + fmt.Println(err) + return +} +``` +<a name="FPutObject"></a> +### FPutObject(bucketName, objectName, filePath, opts PutObjectOptions) (length int64, err error) Uploads contents from a file to objectName. FPutObject uploads objects that are less than 64MiB in a single PUT operation. For objects that are greater than the 64MiB in size, FPutObject seamlessly uploads the object in chunks of 64MiB or more depending on the actual file size. The max upload size for an object is 5TB. - __Parameters__ @@ -689,25 +900,56 @@ __Parameters__ |`bucketName` | _string_ |Name of the bucket | |`objectName` | _string_ |Name of the object | |`filePath` | _string_ |Path to file to be uploaded | -|`contentType` | _string_ |Content type of the object | +|`opts` | _minio.PutObjectOptions_ |Pointer to struct that allows user to set optional custom metadata, content-type, content-encoding,content-disposition and cache-control headers, pass encryption module for encrypting objects, and optionally configure number of threads for multipart put operation. | __Example__ ```go -n, err := minioClient.FPutObject("mybucket", "myobject.csv", "/tmp/otherobject.csv", "application/csv") +n, err := minioClient.FPutObject("my-bucketname", "my-objectname", "my-filename.csv", minio.PutObjectOptions{ + ContentType: "application/csv", +}); if err != nil { fmt.Println(err) return } +fmt.Println("Successfully uploaded bytes: ", n) ``` -<a name="StatObject"></a> -### StatObject(bucketName, objectName string) (ObjectInfo, error) +<a name="FPutObjectWithContext"></a> +### FPutObjectWithContext(ctx context.Context, bucketName, objectName, filePath, opts PutObjectOptions) (length int64, err error) +Identical to FPutObject operation, but allows request cancellation. + +__Parameters__ + + +|Param |Type |Description | +|:---|:---| :---| +|`ctx` | _context.Context_ |Request context | +|`bucketName` | _string_ |Name of the bucket | +|`objectName` | _string_ |Name of the object | +|`filePath` | _string_ |Path to file to be uploaded | +|`opts` | _minio.PutObjectOptions_ |Pointer to struct that allows user to set optional custom metadata, content-type, content-encoding,content-disposition and cache-control headers, pass encryption module for encrypting objects, and optionally configure number of threads for multipart put operation. | -Gets metadata of an object. +__Example__ + + +```go +ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second) +defer cancel() + +n, err := minioClient.FPutObjectWithContext(ctx, "mybucket", "myobject.csv", "/tmp/otherobject.csv", minio.PutObjectOptions{ContentType:"application/csv"}) +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Successfully uploaded bytes: ", n) +``` +<a name="StatObject"></a> +### StatObject(bucketName, objectName string, opts StatObjectOptions) (ObjectInfo, error) +Fetch metadata of an object. __Parameters__ @@ -716,16 +958,19 @@ __Parameters__ |:---|:---| :---| |`bucketName` | _string_ |Name of the bucket | |`objectName` | _string_ |Name of the object | +|`opts` | _minio.StatObjectOptions_ | Options for GET info/stat requests specifying additional options like encryption, If-Match | __Return Value__ |Param |Type |Description | |:---|:---| :---| -|`objInfo` | _ObjectInfo_ |Object stat information | +|`objInfo` | _minio.ObjectInfo_ |Object stat information | -|Param |Type |Description | +__minio.ObjectInfo__ + +|Field |Type |Description | |:---|:---| :---| |`objInfo.LastModified` | _time.Time_ |Time when object was last modified | |`objInfo.ETag` | _string_ |MD5 checksum of the object| @@ -733,11 +978,11 @@ __Return Value__ |`objInfo.Size` | _int64_ |Size of the object| - __Example__ +__Example__ ```go -objInfo, err := minioClient.StatObject("mybucket", "photo.jpg") +objInfo, err := minioClient.StatObject("mybucket", "myobject", minio.StatObjectOptions{}) if err != nil { fmt.Println(err) return @@ -747,10 +992,8 @@ fmt.Println(objInfo) <a name="RemoveObject"></a> ### RemoveObject(bucketName, objectName string) error - Removes an object. - __Parameters__ @@ -761,46 +1004,54 @@ __Parameters__ ```go -err := minioClient.RemoveObject("mybucket", "photo.jpg") +err = minioClient.RemoveObject("mybucket", "myobject") if err != nil { fmt.Println(err) return } ``` -<a name="RemoveObjects"></a> -### RemoveObjects(bucketName string, objectsCh chan string) errorCh chan minio.RemoveObjectError -Removes a list of objects obtained from an input channel. The call sends a delete request to the server up to 1000 objects at a time. -The errors observed are sent over the error channel. +<a name="RemoveObjects"></a> +### RemoveObjects(bucketName string, objectsCh chan string) (errorCh <-chan RemoveObjectError) +Removes a list of objects obtained from an input channel. The call sends a delete request to the server up to 1000 objects at a time. The errors observed are sent over the error channel. __Parameters__ |Param |Type |Description | |:---|:---| :---| |`bucketName` | _string_ |Name of the bucket | -|`objectsCh` | _chan string_ | Prefix of objects to be removed | +|`objectsCh` | _chan string_ | Channel of objects to be removed | __Return Values__ |Param |Type |Description | |:---|:---| :---| -|`errorCh` | _chan minio.RemoveObjectError | Channel of errors observed during deletion. | - +|`errorCh` | _<-chan minio.RemoveObjectError_ | Receive-only channel of errors observed during deletion. | ```go -errorCh := minioClient.RemoveObjects("mybucket", objectsCh) -for e := range errorCh { - fmt.Println("Error detected during deletion: " + e.Err.Error()) +objectsCh := make(chan string) + +// Send object names that are needed to be removed to objectsCh +go func() { + defer close(objectsCh) + // List all objects from a bucket-name with a matching prefix. + for object := range minioClient.ListObjects("my-bucketname", "my-prefixname", true, nil) { + if object.Err != nil { + log.Fatalln(object.Err) + } + objectsCh <- object.Key + } +}() + +for rErr := range minioClient.RemoveObjects("mybucket", objectsCh) { + fmt.Println("Error detected during deletion: ", rErr) } ``` - - <a name="RemoveIncompleteUpload"></a> ### RemoveIncompleteUpload(bucketName, objectName string) error - Removes a partially uploaded object. __Parameters__ @@ -815,7 +1066,7 @@ __Example__ ```go -err := minioClient.RemoveIncompleteUpload("mybucket", "photo.jpg") +err = minioClient.RemoveIncompleteUpload("mybucket", "myobject") if err != nil { fmt.Println(err) return @@ -825,7 +1076,7 @@ if err != nil { ## 4. Encrypted object operations <a name="NewSymmetricKey"></a> -### NewSymmetricKey(key []byte) *minio.SymmetricKey +### NewSymmetricKey(key []byte) *encrypt.SymmetricKey __Parameters__ @@ -838,15 +1089,29 @@ __Return Value__ |Param |Type |Description | |:---|:---| :---| -|`symmetricKey` | _*minio.SymmetricKey_ |_minio.SymmetricKey_ represents a symmetric key structure which can be used to encrypt and decrypt data. | +|`symmetricKey` | _*encrypt.SymmetricKey_ | represents a symmetric key structure which can be used to encrypt and decrypt data | ```go -symKey := minio.NewSymmetricKey([]byte("my-secret-key-00")) -``` +symKey := encrypt.NewSymmetricKey([]byte("my-secret-key-00")) + +// Build the CBC encryption material with symmetric key. +cbcMaterials, err := encrypt.NewCBCSecureMaterials(symKey) +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Successfully initialized Symmetric key CBC materials", cbcMaterials) +object, err := minioClient.GetEncryptedObject("mybucket", "myobject", cbcMaterials) +if err != nil { + fmt.Println(err) + return +} +defer object.Close() +``` <a name="NewAsymmetricKey"></a> -### NewAsymmetricKey(privateKey []byte, publicKey[]byte) (*minio.AsymmetricKey, error) +### NewAsymmetricKey(privateKey []byte, publicKey[]byte) (*encrypt.AsymmetricKey, error) __Parameters__ @@ -860,32 +1125,50 @@ __Return Value__ |Param |Type |Description | |:---|:---| :---| -|`asymmetricKey` | _*minio.AsymmetricKey_ | represents an asymmetric key structure which can be used to encrypt and decrypt data. | -|`err` | _error_ | encountered errors. | +|`asymmetricKey` | _*encrypt.AsymmetricKey_ | represents an asymmetric key structure which can be used to encrypt and decrypt data | +|`err` | _error_ | Standard Error | ```go privateKey, err := ioutil.ReadFile("private.key") if err != nil { - log.Fatal(err) + fmt.Println(err) + return } publicKey, err := ioutil.ReadFile("public.key") if err != nil { - log.Fatal(err) + fmt.Println(err) + return } // Initialize the asymmetric key -asymmetricKey, err := minio.NewAsymmetricKey(privateKey, publicKey) +asymmetricKey, err := encrypt.NewAsymmetricKey(privateKey, publicKey) +if err != nil { + fmt.Println(err) + return +} + +// Build the CBC encryption material for asymmetric key. +cbcMaterials, err := encrypt.NewCBCSecureMaterials(asymmetricKey) +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Successfully initialized Asymmetric key CBC materials", cbcMaterials) + +object, err := minioClient.GetEncryptedObject("mybucket", "myobject", cbcMaterials) if err != nil { - log.Fatal(err) + fmt.Println(err) + return } +defer object.Close() ``` <a name="GetEncryptedObject"></a> -### GetEncryptedObject(bucketName, objectName string, encryptMaterials minio.EncryptionMaterials) (io.ReadCloser, error) +### GetEncryptedObject(bucketName, objectName string, encryptMaterials encrypt.Materials) (io.ReadCloser, error) -Returns the decrypted stream of the object data based of the given encryption materiels. Most of the common errors occur when reading the stream. +Returns the decrypted stream of the object data based of the given encryption materials. Most of the common errors occur when reading the stream. __Parameters__ @@ -893,7 +1176,7 @@ __Parameters__ |:---|:---| :---| |`bucketName` | _string_ | Name of the bucket | |`objectName` | _string_ | Name of the object | -|`encryptMaterials` | _minio.EncryptionMaterials_ | The module to decrypt the object data | +|`encryptMaterials` | _encrypt.Materials_ | Interface provided by `encrypt` package to encrypt a stream of data (For more information see https://godoc.org/github.com/minio/minio-go) | __Return Value__ @@ -909,15 +1192,16 @@ __Example__ ```go // Generate a master symmetric key -key := minio.NewSymmetricKey("my-secret-key-00") +key := encrypt.NewSymmetricKey([]byte("my-secret-key-00")) // Build the CBC encryption material -cbcMaterials, err := NewCBCSecureMaterials(key) +cbcMaterials, err := encrypt.NewCBCSecureMaterials(key) if err != nil { - t.Fatal(err) + fmt.Println(err) + return } -object, err := minioClient.GetEncryptedObject("mybucket", "photo.jpg", cbcMaterials) +object, err := minioClient.GetEncryptedObject("mybucket", "myobject", cbcMaterials) if err != nil { fmt.Println(err) return @@ -929,6 +1213,7 @@ if err != nil { fmt.Println(err) return } +defer localFile.Close() if _, err = io.Copy(localFile, object); err != nil { fmt.Println(err) @@ -938,11 +1223,9 @@ if _, err = io.Copy(localFile, object); err != nil { <a name="PutEncryptedObject"></a> -### PutEncryptedObject(bucketName, objectName string, reader io.Reader, encryptMaterials minio.EncryptionMaterials, metadata map[string][]string, progress io.Reader) (n int, err error) - +### PutEncryptedObject(bucketName, objectName string, reader io.Reader, encryptMaterials encrypt.Materials) (n int, err error) Encrypt and upload an object. - __Parameters__ |Param |Type |Description | @@ -950,10 +1233,7 @@ __Parameters__ |`bucketName` | _string_ |Name of the bucket | |`objectName` | _string_ |Name of the object | |`reader` | _io.Reader_ |Any Go type that implements io.Reader | -|`encryptMaterials` | _minio.EncryptionMaterials_ | The module that encrypts data | -|`metadata` | _map[string][]string_ | Object metadata to be stored | -|`progress` | io.Reader | A reader to update the upload progress | - +|`encryptMaterials` | _encrypt.Materials_ | Interface provided by `encrypt` package to encrypt a stream of data (For more information see https://godoc.org/github.com/minio/minio-go) | __Example__ @@ -961,25 +1241,29 @@ __Example__ // Load a private key privateKey, err := ioutil.ReadFile("private.key") if err != nil { - log.Fatal(err) + fmt.Println(err) + return } // Load a public key publicKey, err := ioutil.ReadFile("public.key") if err != nil { - log.Fatal(err) + fmt.Println(err) + return } // Build an asymmetric key -key, err := NewAssymetricKey(privateKey, publicKey) +key, err := encrypt.NewAsymmetricKey(privateKey, publicKey) if err != nil { - log.Fatal(err) + fmt.Println(err) + return } // Build the CBC encryption module -cbcMaterials, err := NewCBCSecureMaterials(key) +cbcMaterials, err := encrypt.NewCBCSecureMaterials(key) if err != nil { - t.Fatal(err) + fmt.Println(err) + return } // Open a file to upload @@ -991,17 +1275,71 @@ if err != nil { defer file.Close() // Upload the encrypted form of the file -n, err := minioClient.PutEncryptedObject("mybucket", "myobject", file, encryptMaterials, nil, nil) +n, err := minioClient.PutEncryptedObject("mybucket", "myobject", file, cbcMaterials) +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Successfully uploaded encrypted bytes: ", n) +``` + +<a name="FPutEncryptedObject"></a> +### FPutEncryptedObject(bucketName, objectName, filePath, encryptMaterials encrypt.Materials) (n int, err error) +Encrypt and upload an object from a file. + +__Parameters__ + + +|Param |Type |Description | +|:---|:---| :---| +|`bucketName` | _string_ |Name of the bucket | +|`objectName` | _string_ |Name of the object | +|`filePath` | _string_ |Path to file to be uploaded | +|`encryptMaterials` | _encrypt.Materials_ | Interface provided by `encrypt` package to encrypt a stream of data (For more information see https://godoc.org/github.com/minio/minio-go)The module that encrypts data | + +__Example__ + + +```go +// Load a private key +privateKey, err := ioutil.ReadFile("private.key") +if err != nil { + fmt.Println(err) + return +} + +// Load a public key +publicKey, err := ioutil.ReadFile("public.key") +if err != nil { + fmt.Println(err) + return +} + +// Build an asymmetric key +key, err := encrypt.NewAsymmetricKey(privateKey, publicKey) +if err != nil { + fmt.Println(err) + return +} + +// Build the CBC encryption module +cbcMaterials, err := encrypt.NewCBCSecureMaterials(key) +if err != nil { + fmt.Println(err) + return +} + +n, err := minioClient.FPutEncryptedObject("mybucket", "myobject.csv", "/tmp/otherobject.csv", cbcMaterials) if err != nil { fmt.Println(err) return } +fmt.Println("Successfully uploaded encrypted bytes: ", n) ``` <a name="NewSSEInfo"></a> ### NewSSEInfo(key []byte, algo string) SSEInfo - Create a key object for use as encryption or decryption parameter in operations involving server-side-encryption with customer provided key (SSE-C). __Parameters__ @@ -1011,18 +1349,11 @@ __Parameters__ | `key` | _[]byte_ | Byte-slice of the raw, un-encoded binary key | | `algo` | _string_ | Algorithm to use in encryption or decryption with the given key. Can be empty (defaults to `AES256`) | -__Example__ - -``` go -// Key for use in encryption/decryption -keyInfo := NewSSEInfo([]byte{1,2,3}, "") -``` ## 5. Presigned operations <a name="PresignedGetObject"></a> ### PresignedGetObject(bucketName, 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__ @@ -1050,17 +1381,15 @@ if err != nil { fmt.Println(err) return } +fmt.Println("Successfully generated presigned URL", presignedURL) ``` <a name="PresignedPutObject"></a> ### PresignedPutObject(bucketName, 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__ @@ -1082,25 +1411,49 @@ if err != nil { fmt.Println(err) return } -fmt.Println(presignedURL) +fmt.Println("Successfully generated presigned URL", presignedURL) ``` -<a name="PresignedPostPolicy"></a> -### PresignedPostPolicy(PostPolicy) (*url.URL, map[string]string, error) +<a name="PresignedHeadObject"></a> +### PresignedHeadObject(bucketName, objectName string, expiry time.Duration, reqParams url.Values) (*url.URL, error) +Generates a presigned URL for HTTP HEAD operations. Browsers/Mobile clients may point to this URL to directly get metadata from 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. -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. +__Parameters__ + +|Param |Type |Description | +|:---|:---| :---| +|`bucketName` | _string_ |Name of the bucket | +|`objectName` | _string_ |Name of the object | +|`expiry` | _time.Duration_ |Expiry of presigned URL in seconds | +|`reqParams` | _url.Values_ |Additional response header overrides supports _response-expires_, _response-content-type_, _response-cache-control_, _response-content-disposition_. | -Create policy : + +__Example__ ```go -policy := minio.NewPostPolicy() -``` +// Set request parameters for content-disposition. +reqParams := make(url.Values) +reqParams.Set("response-content-disposition", "attachment; filename=\"your-filename.txt\"") -Apply upload policy restrictions: +// Generates a presigned url which expires in a day. +presignedURL, err := minioClient.PresignedHeadObject("mybucket", "myobject", time.Second * 24 * 60 * 60, reqParams) +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Successfully generated presigned URL", presignedURL) +``` +<a name="PresignedPostPolicy"></a> +### 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. ```go +// Initialize policy condition config. +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 @@ -1111,20 +1464,17 @@ 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: +// Add a user metadata using the key "custom" and value "user" +policy.SetUserMetadata("custom", "user") +// 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`: - - -```go +// POST your content from the command line using `curl` fmt.Printf("curl ") for k, v := range formData { fmt.Printf("-F %s=%s ", k, v) @@ -1137,7 +1487,6 @@ fmt.Printf("%s\n", url) <a name="SetBucketPolicy"></a> ### SetBucketPolicy(bucketname, objectPrefix string, policy policy.BucketPolicy) error - Set access permissions on bucket or an object prefix. Importing `github.com/minio/minio-go/pkg/policy` package is needed. @@ -1168,7 +1517,9 @@ __Example__ ```go -err := minioClient.SetBucketPolicy("mybucket", "myprefix", policy.BucketPolicyReadWrite) +// Sets 'mybucket' with a sub-directory 'myprefix' to be anonymously accessible for +// both read and write operations. +err = minioClient.SetBucketPolicy("mybucket", "myprefix", policy.BucketPolicyReadWrite) if err != nil { fmt.Println(err) return @@ -1177,7 +1528,6 @@ if err != nil { <a name="GetBucketPolicy"></a> ### GetBucketPolicy(bucketName, objectPrefix string) (policy.BucketPolicy, error) - Get access permissions on a bucket or a prefix. Importing `github.com/minio/minio-go/pkg/policy` package is needed. @@ -1212,7 +1562,6 @@ fmt.Println("Access permissions for mybucket is", bucketPolicy) <a name="ListBucketPolicies"></a> ### ListBucketPolicies(bucketName, objectPrefix string) (map[string]BucketPolicy, error) - Get access permissions rules associated to the specified bucket and prefix. __Parameters__ @@ -1228,7 +1577,7 @@ __Return Values__ |Param |Type |Description | |:---|:---| :---| -|`bucketPolicies` | _map[string]BucketPolicy_ |Map of object resource paths and their permissions | +|`bucketPolicies` | _map[string]minio.BucketPolicy_ |Map of object resource paths and their permissions | |`err` | _error_ |Standard Error | __Example__ @@ -1247,8 +1596,7 @@ for resource, permission := range bucketPolicies { <a name="GetBucketNotification"></a> ### GetBucketNotification(bucketName string) (BucketNotification, error) - -Get all notification configurations related to the specified bucket. +Get notification configuration on a bucket. __Parameters__ @@ -1262,7 +1610,7 @@ __Return Values__ |Param |Type |Description | |:---|:---| :---| -|`bucketNotification` | _BucketNotification_ |structure which holds all notification configurations| +|`bucketNotification` | _minio.BucketNotification_ |structure which holds all notification configurations| |`err` | _error_ |Standard Error | __Example__ @@ -1271,10 +1619,12 @@ __Example__ ```go bucketNotification, err := minioClient.GetBucketNotification("mybucket") if err != nil { - log.Fatalf("Failed to get bucket notification configurations for mybucket - %v", err) + fmt.Println("Failed to get bucket notification configurations for mybucket", err) + return } -for _, topicConfig := range bucketNotification.TopicConfigs { - for _, e := range topicConfig.Events { + +for _, queueConfig := range bucketNotification.QueueConfigs { + for _, e := range queueConfig.Events { fmt.Println(e + " event is enabled") } } @@ -1282,7 +1632,6 @@ for _, topicConfig := range bucketNotification.TopicConfigs { <a name="SetBucketNotification"></a> ### SetBucketNotification(bucketName string, bucketNotification BucketNotification) error - Set a new bucket notification on a bucket. __Parameters__ @@ -1291,7 +1640,7 @@ __Parameters__ |Param |Type |Description | |:---|:---| :---| |`bucketName` | _string_ |Name of the bucket | -|`bucketNotification` | _BucketNotification_ |Represents the XML to be sent to the configured web service | +|`bucketNotification` | _minio.BucketNotification_ |Represents the XML to be sent to the configured web service | __Return Values__ @@ -1304,24 +1653,25 @@ __Example__ ```go -topicArn := NewArn("aws", "sns", "us-east-1", "804605494417", "PhotoUpdate") +queueArn := minio.NewArn("aws", "sqs", "us-east-1", "804605494417", "PhotoUpdate") + +queueConfig := minio.NewNotificationConfig(queueArn) +queueConfig.AddEvents(minio.ObjectCreatedAll, minio.ObjectRemovedAll) +queueConfig.AddFilterPrefix("photos/") +queueConfig.AddFilterSuffix(".jpg") -topicConfig := NewNotificationConfig(topicArn) -topicConfig.AddEvents(minio.ObjectCreatedAll, minio.ObjectRemovedAll) -lambdaConfig.AddFilterPrefix("photos/") -lambdaConfig.AddFilterSuffix(".jpg") +bucketNotification := minio.BucketNotification{} +bucketNotification.AddQueue(queueConfig) -bucketNotification := BucketNotification{} -bucketNotification.AddTopic(topicConfig) -err := c.SetBucketNotification(bucketName, bucketNotification) +err = minioClient.SetBucketNotification("mybucket", bucketNotification) if err != nil { - fmt.Println("Unable to set the bucket notification: " + err) + fmt.Println("Unable to set the bucket notification: ", err) + return } ``` <a name="RemoveAllBucketNotification"></a> ### RemoveAllBucketNotification(bucketName string) error - Remove all configured bucket notifications on a bucket. __Parameters__ @@ -1342,18 +1692,16 @@ __Example__ ```go -err := c.RemoveAllBucketNotification(bucketName) +err = minioClient.RemoveAllBucketNotification("mybucket") if err != nil { fmt.Println("Unable to remove bucket notifications.", err) + return } ``` <a name="ListenBucketNotification"></a> ### ListenBucketNotification(bucketName, prefix, suffix string, events []string, 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'. +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. @@ -1368,17 +1716,20 @@ __Parameters__ |`bucketName` | _string_ | Bucket to listen notifications on | |`prefix` | _string_ | Object key prefix to filter notifications for | |`suffix` | _string_ | Object key suffix to filter notifications for | -|`events` | _[]string_| Enables notifications for specific event types | +|`events` | _[]string_ | Enables notifications for specific event types | |`doneCh` | _chan struct{}_ | A message on this channel ends the ListenBucketNotification iterator | __Return Values__ |Param |Type |Description | |:---|:---| :---| -|`chan NotificationInfo` | _chan_ | Read channel for all notifications 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 | +|`notificationInfo` | _chan minio.NotificationInfo_ | Channel of bucket notifications | + +__minio.NotificationInfo__ + +|Field |Type |Description | +|`notificationInfo.Records` | _[]minio.NotificationEvent_ | Collection of notification events | +|`notificationInfo.Err` | _error_ | Carries any error occurred during the operation (Standard Error) | __Example__ @@ -1392,15 +1743,15 @@ doneCh := make(chan struct{}) defer close(doneCh) // Listen for bucket notifications on "mybucket" filtered by prefix, suffix and events. -for notificationInfo := range minioClient.ListenBucketNotification("YOUR-BUCKET", "PREFIX", "SUFFIX", []string{ +for notificationInfo := range minioClient.ListenBucketNotification("mybucket", "myprefix/", ".mysuffix", []string{ "s3:ObjectCreated:*", "s3:ObjectAccessed:*", "s3:ObjectRemoved:*", }, doneCh) { if notificationInfo.Err != nil { - log.Fatalln(notificationInfo.Err) + fmt.Println(notificationInfo.Err) } - log.Println(notificationInfo) + fmt.Println(notificationInfo) } ``` @@ -1408,7 +1759,7 @@ for notificationInfo := range minioClient.ListenBucketNotification("YOUR-BUCKET" <a name="SetAppInfo"></a> ### SetAppInfo(appName, appVersion string) -Adds application details to User-Agent. +Add custom application details to User-Agent. __Parameters__ @@ -1428,8 +1779,7 @@ minioClient.SetAppInfo("myCloudApp", "1.0.0") <a name="SetCustomTransport"></a> ### SetCustomTransport(customHTTPTransport http.RoundTripper) -Overrides default HTTP transport. This is usually needed for debugging -or for adding custom TLS certificates. +Overrides default HTTP transport. This is usually needed for debugging or for adding custom TLS certificates. __Parameters__ @@ -1440,8 +1790,7 @@ __Parameters__ <a name="TraceOn"></a> ### TraceOn(outputStream io.Writer) -Enables HTTP tracing. The trace is written to the io.Writer -provided. If outputStream is nil, trace is written to os.Stdout. +Enables HTTP tracing. The trace is written to the io.Writer provided. If outputStream is nil, trace is written to os.Stdout. __Parameters__ @@ -1457,7 +1806,7 @@ Disables HTTP tracing. <a name="SetS3TransferAccelerate"></a> ### SetS3TransferAccelerate(acceleratedEndpoint string) Set AWS S3 transfer acceleration endpoint for all API requests hereafter. -NOTE: This API applies only to AWS S3 and ignored with other S3 compatible object storage services. +NOTE: This API applies only to AWS S3 and is a no operation for S3 compatible object storage services. __Parameters__ diff --git a/docs/checker.go.template b/docs/checker.go.template new file mode 100644 index 0000000..2e0f13a --- /dev/null +++ b/docs/checker.go.template @@ -0,0 +1,21 @@ +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 + } + + {{.Text}} +} diff --git a/docs/validator.go b/docs/validator.go new file mode 100644 index 0000000..7d5cbaa --- /dev/null +++ b/docs/validator.go @@ -0,0 +1,227 @@ +// +build ignore + +/* + * Minio Go Library for Amazon S3 Compatible Cloud Storage + * Copyright 2015-2017 Minio, Inc. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package main + +import ( + "fmt" + "io/ioutil" + "os" + "os/exec" + "path/filepath" + "strings" + "text/template" + + "github.com/a8m/mark" + "github.com/gernest/wow" + "github.com/gernest/wow/spin" + "github.com/minio/cli" +) + +func init() { + // Validate go binary. + if _, err := exec.LookPath("go"); err != nil { + panic(err) + } +} + +var globalFlags = []cli.Flag{ + cli.StringFlag{ + Name: "m", + Value: "API.md", + Usage: "Path to markdown api documentation.", + }, + cli.StringFlag{ + Name: "t", + Value: "checker.go.template", + Usage: "Template used for generating the programs.", + }, + cli.IntFlag{ + Name: "skip", + Value: 2, + Usage: "Skip entries before validating the code.", + }, +} + +func runGofmt(path string) (msg string, err error) { + cmdArgs := []string{"-s", "-w", "-l", path} + cmd := exec.Command("gofmt", cmdArgs...) + stdoutStderr, err := cmd.CombinedOutput() + if err != nil { + return "", err + } + return string(stdoutStderr), nil +} + +func runGoImports(path string) (msg string, err error) { + cmdArgs := []string{"-w", path} + cmd := exec.Command("goimports", cmdArgs...) + stdoutStderr, err := cmd.CombinedOutput() + if err != nil { + return string(stdoutStderr), err + } + return string(stdoutStderr), nil +} + +func runGoBuild(path string) (msg string, err error) { + // Go build the path. + cmdArgs := []string{"build", "-o", "/dev/null", path} + cmd := exec.Command("go", cmdArgs...) + stdoutStderr, err := cmd.CombinedOutput() + if err != nil { + return string(stdoutStderr), err + } + return string(stdoutStderr), nil +} + +func validatorAction(ctx *cli.Context) error { + if !ctx.IsSet("m") || !ctx.IsSet("t") { + return nil + } + docPath := ctx.String("m") + var err error + docPath, err = filepath.Abs(docPath) + if err != nil { + return err + } + data, err := ioutil.ReadFile(docPath) + if err != nil { + return err + } + + templatePath := ctx.String("t") + templatePath, err = filepath.Abs(templatePath) + if err != nil { + return err + } + + skipEntries := ctx.Int("skip") + m := mark.New(string(data), &mark.Options{ + Gfm: true, // Github markdown support is enabled by default. + }) + + t, err := template.ParseFiles(templatePath) + if err != nil { + return err + } + + tmpDir, err := ioutil.TempDir("", "md-verifier") + if err != nil { + return err + } + defer os.RemoveAll(tmpDir) + + entryN := 1 + for i := mark.NodeText; i < mark.NodeCheckbox; i++ { + if mark.NodeCode != mark.NodeType(i) { + m.AddRenderFn(mark.NodeType(i), func(node mark.Node) (s string) { + return "" + }) + continue + } + m.AddRenderFn(mark.NodeCode, func(node mark.Node) (s string) { + p, ok := node.(*mark.CodeNode) + if !ok { + return + } + p.Text = strings.NewReplacer("<", "<", ">", ">", """, `"`, "&", "&").Replace(p.Text) + if skipEntries > 0 { + skipEntries-- + return + } + + testFilePath := filepath.Join(tmpDir, "example.go") + w, werr := os.Create(testFilePath) + if werr != nil { + panic(werr) + } + t.Execute(w, p) + w.Sync() + w.Close() + entryN++ + + msg, err := runGofmt(testFilePath) + if err != nil { + fmt.Printf("Failed running gofmt on %s, with (%s):(%s)\n", testFilePath, msg, err) + os.Exit(-1) + } + + msg, err = runGoImports(testFilePath) + if err != nil { + fmt.Printf("Failed running gofmt on %s, with (%s):(%s)\n", testFilePath, msg, err) + os.Exit(-1) + } + + msg, err = runGoBuild(testFilePath) + if err != nil { + fmt.Printf("Failed running gobuild on %s, with (%s):(%s)\n", testFilePath, msg, err) + fmt.Printf("Code with possible issue in %s:\n%s", docPath, p.Text) + fmt.Printf("To test `go build %s`\n", testFilePath) + os.Exit(-1) + } + + // Once successfully built remove the test file + os.Remove(testFilePath) + return + }) + } + + w := wow.New(os.Stdout, spin.Get(spin.Moon), fmt.Sprintf(" Running validation tests in %s", tmpDir)) + + w.Start() + // Render markdown executes our checker on each code blocks. + _ = m.Render() + w.PersistWith(spin.Get(spin.Runner), " Successfully finished tests") + w.Stop() + + return nil +} + +func main() { + app := cli.NewApp() + app.Action = validatorAction + app.HideVersion = true + app.HideHelpCommand = true + app.Usage = "Validates code block sections inside API.md" + app.Author = "Minio.io" + app.Flags = globalFlags + // Help template for validator + app.CustomAppHelpTemplate = `NAME: + {{.Name}} - {{.Usage}} + +USAGE: + {{.Name}} {{if .VisibleFlags}}[FLAGS] {{end}}COMMAND{{if .VisibleFlags}} [COMMAND FLAGS | -h]{{end}} [ARGUMENTS...] + +COMMANDS: + {{range .VisibleCommands}}{{join .Names ", "}}{{ "\t" }}{{.Usage}} + {{end}}{{if .VisibleFlags}} +FLAGS: + {{range .VisibleFlags}}{{.}} + {{end}}{{end}} +TEMPLATE: + Validator uses Go's 'text/template' formatting so you need to ensure + your template is formatted correctly, check 'docs/checker.go.template' + +USAGE: + go run docs/validator.go -m docs/API.md -t /tmp/mycode.go.template + +` + app.Run(os.Args) + +} diff --git a/docs/zh_CN/API.md b/docs/zh_CN/API.md new file mode 100644 index 0000000..d20ca10 --- /dev/null +++ b/docs/zh_CN/API.md @@ -0,0 +1,1820 @@ +# Minio Go Client API文档 [](https://slack.minio.io) + +## 初使化Minio Client对象。 + +## Minio + +```go +package main + +import ( + "fmt" + + "github.com/minio/minio-go" +) + +func main() { + // 使用ssl + ssl := true + + // 初使化minio client对象。 + minioClient, err := minio.New("play.minio.io:9000", "Q3AM3UQ867SPQQA43P2F", "zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ssl) + if err != nil { + fmt.Println(err) + return + } +} +``` + +## AWS S3 + +```go +package main + +import ( + "fmt" + + "github.com/minio/minio-go" +) + +func main() { + // 使用ssl + ssl := true + + // 初使化minio client对象。 + s3Client, err := minio.New("s3.amazonaws.com", "YOUR-ACCESSKEYID", "YOUR-SECRETACCESSKEY", ssl) + if err != nil { + fmt.Println(err) + return + } +} +``` + +| 操作存储桶 | 操作对象 | 操作加密对象 | Presigned操作 | 存储桶策略/通知 | 客户端自定义设置 | +| :--- | :--- | :--- | :--- | :--- | :--- | +| [`MakeBucket`](#MakeBucket) | [`GetObject`](#GetObject) | [`NewSymmetricKey`](#NewSymmetricKey) | [`PresignedGetObject`](#PresignedGetObject) | [`SetBucketPolicy`](#SetBucketPolicy) | [`SetAppInfo`](#SetAppInfo) | +| [`ListBuckets`](#ListBuckets) | [`PutObject`](#PutObject) | [`NewAsymmetricKey`](#NewAsymmetricKey) | [`PresignedPutObject`](#PresignedPutObject) | [`GetBucketPolicy`](#GetBucketPolicy) | [`SetCustomTransport`](#SetCustomTransport) | +| [`BucketExists`](#BucketExists) | [`CopyObject`](#CopyObject) | [`GetEncryptedObject`](#GetEncryptedObject) | [`PresignedPostPolicy`](#PresignedPostPolicy) | [`ListBucketPolicies`](#ListBucketPolicies) | [`TraceOn`](#TraceOn) | +| [`RemoveBucket`](#RemoveBucket) | [`StatObject`](#StatObject) | [`PutEncryptedObject`](#PutEncryptedObject) | | [`SetBucketNotification`](#SetBucketNotification) | [`TraceOff`](#TraceOff) | +| [`ListObjects`](#ListObjects) | [`RemoveObject`](#RemoveObject) | [`NewSSEInfo`](#NewSSEInfo) | | [`GetBucketNotification`](#GetBucketNotification) | [`SetS3TransferAccelerate`](#SetS3TransferAccelerate) | +| [`ListObjectsV2`](#ListObjectsV2) | [`RemoveObjects`](#RemoveObjects) | [`FPutEncryptedObject`](#FPutEncryptedObject) | | [`RemoveAllBucketNotification`](#RemoveAllBucketNotification) | | +| [`ListIncompleteUploads`](#ListIncompleteUploads) | [`RemoveIncompleteUpload`](#RemoveIncompleteUpload) | | | [`ListenBucketNotification`](#ListenBucketNotification) | | +| | [`FPutObject`](#FPutObject) | | | | | +| | [`FGetObject`](#FGetObject) | | | | | +| | [`ComposeObject`](#ComposeObject) | | | | | +| | [`NewSourceInfo`](#NewSourceInfo) | | | | | +| | [`NewDestinationInfo`](#NewDestinationInfo) | | | | | +| | [`PutObjectWithContext`](#PutObjectWithContext) | | | | +| | [`GetObjectWithContext`](#GetObjectWithContext) | | | | +| | [`FPutObjectWithContext`](#FPutObjectWithContext) | | | | +| | [`FGetObjectWithContext`](#FGetObjectWithContext) | | | | +## 1. 构造函数 +<a name="Minio"></a> + +### New(endpoint, accessKeyID, secretAccessKey string, ssl bool) (*Client, error) +初使化一个新的client对象。 + +__参数__ + +|参数 | 类型 |描述 | +|:---|:---| :---| +|`endpoint` | _string_ |S3兼容对象存储服务endpoint | +|`accessKeyID` |_string_ |对象存储的Access key | +|`secretAccessKey` | _string_ |对象存储的Secret key | +|`ssl` | _bool_ |true代表使用HTTPS | + +### NewWithRegion(endpoint, accessKeyID, secretAccessKey string, ssl bool, region string) (*Client, error) +初使化minio client,带有region配置。和New()不同的是，NewWithRegion避免了bucket-location操作，所以会快那么一丢丢。如果你的应用只使用一个region的话可以用这个方法。 + +__参数__ + +|参数 |类型 |描述 | +|:---|:---| :---| +|`endpoint` | _string_ |S3兼容对象存储服务endpoint | +|`accessKeyID` |_string_ |对象存储的Access key | +|`secretAccessKey` | _string_ |对象存储的Secret key | +|`ssl` | _bool_ |true代表使用HTTPS | +|`region`| _string_ | 对象存储的region | + +## 2. 操作存储桶 + +<a name="MakeBucket"></a> +### MakeBucket(bucketName, location string) error +创建一个存储桶。 + +__参数__ + +| 参数 | 类型 | 描述 | +|---|---|---| +|`bucketName` | _string_ | 存储桶名称 | +| `location` | _string_ | 存储桶被创建的region(地区)，默认是us-east-1(美国东一区)，下面列举的是其它合法的值。注意：如果用的是minio服务的话，resion是在它的配置文件中，（默认是us-east-1）。| +| | |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| + + +__示例__ + + +```go +err = minioClient.MakeBucket("mybucket", "us-east-1") +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Successfully created mybucket.") +``` + +<a name="ListBuckets"></a> +### ListBuckets() ([]BucketInfo, error) +列出所有的存储桶。 + +| 参数 | 类型 | 描述 | +|---|---|---| +|`bucketList` | _[]minio.BucketInfo_ | 所有存储桶的list。 | + + +__minio.BucketInfo__ + +| 参数 | 类型 | 描述 | +|---|---|---| +|`bucket.Name` | _string_ | 存储桶名称 | +|`bucket.CreationDate` | _time.Time_ | 存储桶的创建时间 | + + +__示例__ + + +```go +buckets, err := minioClient.ListBuckets() +if err != nil { + fmt.Println(err) + return +} +for _, bucket := range buckets { + fmt.Println(bucket) +} +``` + +<a name="BucketExists"></a> +### BucketExists(bucketName string) (found bool, err error) +检查存储桶是否存在。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | + + +__返回值__ + +|参数 |类型 |描述 | +|:---|:---| :---| +|`found` | _bool_ | 存储桶是否存在 | +|`err` | _error_ | 标准Error | + + +__示例__ + + +```go +found, err := minioClient.BucketExists("mybucket") +if err != nil { + fmt.Println(err) + return +} +if found { + fmt.Println("Bucket found") +} +``` + +<a name="RemoveBucket"></a> +### RemoveBucket(bucketName string) error +删除一个存储桶，存储桶必须为空才能被成功删除。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | + +__示例__ + + +```go +err = minioClient.RemoveBucket("mybucket") +if err != nil { + fmt.Println(err) + return +} +``` + +<a name="ListObjects"></a> +### ListObjects(bucketName, prefix string, recursive bool, doneCh chan struct{}) <-chan ObjectInfo +列举存储桶里的对象。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`objectPrefix` |_string_ | 要列举的对象前缀 | +|`recursive` | _bool_ |`true`代表递归查找，`false`代表类似文件夹查找，以'/'分隔，不查子文件夹。 | +|`doneCh` | _chan struct{}_ | 在该channel上结束ListObjects iterator的一个message。 | + + +__返回值__ + +|参数 |类型 |描述 | +|:---|:---| :---| +|`objectInfo` | _chan minio.ObjectInfo_ |存储桶中所有对象的read channel，对象的格式如下： | + +__minio.ObjectInfo__ + +|属性 |类型 |描述 | +|:---|:---| :---| +|`objectInfo.Key` | _string_ |对象的名称 | +|`objectInfo.Size` | _int64_ |对象的大小 | +|`objectInfo.ETag` | _string_ |对象的MD5校验码 | +|`objectInfo.LastModified` | _time.Time_ |对象的最后修改时间 | + + +```go +// 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) +} +``` + + +<a name="ListObjectsV2"></a> +### ListObjectsV2(bucketName, prefix string, recursive bool, doneCh chan struct{}) <-chan ObjectInfo +使用listing API v2版本列举存储桶中的对象。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +| `objectPrefix` |_string_ | 要列举的对象前缀 | +| `recursive` | _bool_ |`true`代表递归查找，`false`代表类似文件夹查找，以'/'分隔，不查子文件夹。 | +|`doneCh` | _chan struct{}_ | 在该channel上结束ListObjects iterator的一个message。 | + + +__返回值__ + +|参数 |类型 |描述 | +|:---|:---| :---| +|`objectInfo` | _chan minio.ObjectInfo_ |存储桶中所有对象的read channel | + + +```go +// 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) +} +``` + +<a name="ListIncompleteUploads"></a> +### ListIncompleteUploads(bucketName, prefix string, recursive bool, doneCh chan struct{}) <- chan ObjectMultipartInfo +列举存储桶中未完整上传的对象。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +| `prefix` |_string_ | 不完整上传的对象的前缀 | +| `recursive` | _bool_ |`true`代表递归查找，`false`代表类似文件夹查找，以'/'分隔，不查子文件夹。 | +|`doneCh` | _chan struct{}_ | 在该channel上结束ListIncompleteUploads iterator的一个message。 | + + +__返回值__ + +|参数 |类型 |描述 | +|:---|:---| :---| +|`multiPartInfo` | _chan minio.ObjectMultipartInfo_ |multipart对象格式如下： | + +__minio.ObjectMultipartInfo__ + +|属性 |类型 |描述 | +|:---|:---| :---| +|`multiPartObjInfo.Key` | _string_ |未完整上传的对象的名称 | +|`multiPartObjInfo.UploadID` | _string_ |未完整上传的对象的Upload ID | +|`multiPartObjInfo.Size` | _int64_ |未完整上传的对象的大小 | + +__示例__ + + +```go +// 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. 操作对象 + +<a name="GetObject"></a> +### GetObject(bucketName, objectName string, opts GetObjectOptions) (*Object, error) +返回对象数据的流，error是读流时经常抛的那些错。 + + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`objectName` | _string_ |对象的名称 | +|`opts` | _minio.GetObjectOptions_ | GET请求的一些额外参数，像encryption，If-Match | + + +__minio.GetObjectOptions__ + +|参数 | 类型 | 描述 | +|:---|:---|:---| +| `opts.Materials` | _encrypt.Materials_ | `encrypt`包提供的对流加密的接口，(更多信息，请看https://godoc.org/github.com/minio/minio-go) | + +__返回值__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`object` | _*minio.Object_ |_minio.Object_代表了一个object reader。它实现了io.Reader, io.Seeker, io.ReaderAt and io.Closer接口。 | + + +__示例__ + + +```go +object, err := minioClient.GetObject("mybucket", "myobject", minio.GetObjectOptions{}) +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 +} +``` + +<a name="FGetObject"></a> +### FGetObject(bucketName, objectName, filePath string, opts GetObjectOptions) error +下载并将文件保存到本地文件系统。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`objectName` | _string_ |对象的名称 | +|`filePath` | _string_ |下载后保存的路径 | +|`opts` | _minio.GetObjectOptions_ | GET请求的一些额外参数，像encryption，If-Match | + + +__示例__ + + +```go +err = minioClient.FGetObject("mybucket", "myobject", "/tmp/myobject", minio.GetObjectOptions{}) +if err != nil { + fmt.Println(err) + return +} +``` +<a name="GetObjectWithContext"></a> +### GetObjectWithContext(ctx context.Context, bucketName, objectName string, opts GetObjectOptions) (*Object, error) +和GetObject操作是一样的，不过传入了取消请求的context。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`ctx` | _context.Context_ |请求上下文（Request context） | +|`bucketName` | _string_ |存储桶名称 | +|`objectName` | _string_ |对象的名称 | +|`opts` | _minio.GetObjectOptions_ | GET请求的一些额外参数，像encryption，If-Match | + + +__返回值__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`object` | _*minio.Object_ |_minio.Object_代表了一个object reader。它实现了io.Reader, io.Seeker, io.ReaderAt and io.Closer接口。 | + + +__示例__ + + +```go +ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second) +defer cancel() + +object, err := minioClient.GetObjectWithContext(ctx, "mybucket", "myobject", minio.GetObjectOptions{}) +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 +} +``` + +<a name="FGetObjectWithContext"></a> +### FGetObjectWithContext(ctx context.Context, bucketName, objectName, filePath string, opts GetObjectOptions) error +和FGetObject操作是一样的，不过允许取消请求。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`ctx` | _context.Context_ |请求上下文 | +|`bucketName` | _string_ |存储桶名称 | +|`objectName` | _string_ |对象的名称 | +|`filePath` | _string_ |下载后保存的路径 | +|`opts` | _minio.GetObjectOptions_ | GET请求的一些额外参数，像encryption，If-Match | + + +__示例__ + + +```go +ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second) +defer cancel() + +err = minioClient.FGetObjectWithContext(ctx, "mybucket", "myobject", "/tmp/myobject", minio.GetObjectOptions{}) +if err != nil { + fmt.Println(err) + return +} +``` + +<a name="FGetEncryptedObject"></a> +### FGetEncryptedObject(bucketName, objectName, filePath string, materials encrypt.Materials) error +和FGetObject操作是一样的，不过会对加密请求进行解密。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`objectName` | _string_ |对象的名称 | +|`filePath` | _string_ |下载后保存的路径| +|`materials` | _encrypt.Materials_ | `encrypt`包提供的对流加密的接口，(更多信息，请看https://godoc.org/github.com/minio/minio-go) | + + +__示例__ + + +```go +// Generate a master symmetric key +key := encrypt.NewSymmetricKey([]byte("my-secret-key-00")) + +// Build the CBC encryption material +cbcMaterials, err := encrypt.NewCBCSecureMaterials(key) +if err != nil { + fmt.Println(err) + return +} + +err = minioClient.FGetEncryptedObject("mybucket", "myobject", "/tmp/myobject", cbcMaterials) +if err != nil { + fmt.Println(err) + return +} +``` + +<a name="PutObject"></a> +### PutObject(bucketName, objectName string, reader io.Reader, objectSize int64,opts PutObjectOptions) (n int, err error) +当对象小于64MiB时，直接在一次PUT请求里进行上传。当大于64MiB时，根据文件的实际大小，PutObject会自动地将对象进行拆分成64MiB一块或更大一些进行上传。对象的最大大小是5TB。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`objectName` | _string_ |对象的名称 | +|`reader` | _io.Reader_ |任意实现了io.Reader的GO类型 | +|`objectSize`| _int64_ |上传的对象的大小，-1代表未知。 | +|`opts` | _minio.PutObjectOptions_ | 允许用户设置可选的自定义元数据，内容标题，加密密钥和用于分段上传操作的线程数量。 | + +__minio.PutObjectOptions__ + +|属性 | 类型 | 描述 | +|:--- |:--- | :--- | +| `opts.UserMetadata` | _map[string]string_ | 用户元数据的Map| +| `opts.Progress` | _io.Reader_ | 获取上传进度的Reader | +| `opts.ContentType` | _string_ | 对象的Content type， 例如"application/text" | +| `opts.ContentEncoding` | _string_ | 对象的Content encoding，例如"gzip" | +| `opts.ContentDisposition` | _string_ | 对象的Content disposition, "inline" | +| `opts.CacheControl` | _string_ | 指定针对请求和响应的缓存机制，例如"max-age=600"| +| `opts.EncryptMaterials` | _encrypt.Materials_ | `encrypt`包提供的对流加密的接口，(更多信息，请看https://godoc.org/github.com/minio/minio-go) | + + +__示例__ + + +```go +file, err := os.Open("my-testfile") +if err != nil { + fmt.Println(err) + return +} +defer file.Close() + +fileStat, err := file.Stat() +if err != nil { + fmt.Println(err) + return +} + +n, err := minioClient.PutObject("mybucket", "myobject", file, fileStat.Size(), minio.PutObjectOptions{ContentType:"application/octet-stream"}) +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Successfully uploaded bytes: ", n) +``` + +API方法在minio-go SDK版本v3.0.3中提供的PutObjectWithSize，PutObjectWithMetadata，PutObjectStreaming和PutObjectWithProgress被替换为接受指向PutObjectOptions struct的指针的新的PutObject调用变体。 + +<a name="PutObjectWithContext"></a> +### PutObjectWithContext(ctx context.Context, bucketName, objectName string, reader io.Reader, objectSize int64, opts PutObjectOptions) (n int, err error) +和PutObject是一样的，不过允许取消请求。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`ctx` | _context.Context_ |请求上下文 | +|`bucketName` | _string_ |存储桶名称 | +|`objectName` | _string_ |对象的名称 | +|`reader` | _io.Reader_ |任何实现io.Reader的Go类型 | +|`objectSize`| _int64_ | 上传的对象的大小，-1代表未知 | +|`opts` | _minio.PutObjectOptions_ |允许用户设置可选的自定义元数据，content-type，content-encoding，content-disposition以及cache-control headers，传递加密模块以加密对象，并可选地设置multipart put操作的线程数量。| + + +__示例__ + + +```go +ctx, cancel := context.WithTimeout(context.Background(), 10 * time.Second) +defer cancel() + +file, err := os.Open("my-testfile") +if err != nil { + fmt.Println(err) + return +} +defer file.Close() + +fileStat, err := file.Stat() +if err != nil { + fmt.Println(err) + return +} + +n, err := minioClient.PutObjectWithContext(ctx, "my-bucketname", "my-objectname", file, fileStat.Size(), minio.PutObjectOptions{ + ContentType: "application/octet-stream", +}) +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Successfully uploaded bytes: ", n) +``` + +<a name="CopyObject"></a> +### CopyObject(dst DestinationInfo, src SourceInfo) error +通过在服务端对已存在的对象进行拷贝，实现新建或者替换对象。它支持有条件的拷贝，拷贝对象的一部分，以及在服务端的加解密。请查看`SourceInfo`和`DestinationInfo`两个类型来了解更多细节。 + +拷贝多个源文件到一个目标对象，请查看`ComposeObject` API。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`dst` | _minio.DestinationInfo_ |目标对象 | +|`src` | _minio.SourceInfo_ |源对象 | + + +__示例__ + + +```go +// Use-case 1: Simple copy object with no conditions. +// Source object +src := minio.NewSourceInfo("my-sourcebucketname", "my-sourceobjectname", nil) + +// Destination object +dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) +if err != nil { + fmt.Println(err) + return +} + +// Copy object call +err = minioClient.CopyObject(dst, src) +if err != nil { + fmt.Println(err) + return +} +``` + +```go +// Use-case 2: +// Copy object with copy-conditions, and copying only part of the source object. +// 1. that matches a given ETag +// 2. and modified after 1st April 2014 +// 3. but unmodified since 23rd April 2014 +// 4. copy only first 1MiB of object. + +// Source object +src := minio.NewSourceInfo("my-sourcebucketname", "my-sourceobjectname", nil) + +// Set matching ETag condition, copy object which matches the following ETag. +src.SetMatchETagCond("31624deb84149d2f8ef9c385918b653a") + +// Set modified condition, copy object modified since 2014 April 1. +src.SetModifiedSinceCond(time.Date(2014, time.April, 1, 0, 0, 0, 0, time.UTC)) + +// Set unmodified condition, copy object unmodified since 2014 April 23. +src.SetUnmodifiedSinceCond(time.Date(2014, time.April, 23, 0, 0, 0, 0, time.UTC)) + +// Set copy-range of only first 1MiB of file. +src.SetRange(0, 1024*1024-1) + +// Destination object +dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) +if err != nil { + fmt.Println(err) + return +} + +// Copy object call +err = minioClient.CopyObject(dst, src) +if err != nil { + fmt.Println(err) + return +} +``` + +<a name="ComposeObject"></a> +### ComposeObject(dst minio.DestinationInfo, srcs []minio.SourceInfo) error +通过使用服务端拷贝实现钭多个源对象合并创建成一个新的对象。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---|:---| +|`dst` | _minio.DestinationInfo_ |要被创建的目标对象 | +|`srcs` | _[]minio.SourceInfo_ |要合并的多个源对象 | + + +__示例__ + + +```go +// Prepare source decryption key (here we assume same key to +// decrypt all source objects.) +decKey := minio.NewSSEInfo([]byte{1, 2, 3}, "") + +// Source objects to concatenate. We also specify decryption +// key for each +src1 := minio.NewSourceInfo("bucket1", "object1", &decKey) +src1.SetMatchETagCond("31624deb84149d2f8ef9c385918b653a") + +src2 := minio.NewSourceInfo("bucket2", "object2", &decKey) +src2.SetMatchETagCond("f8ef9c385918b653a31624deb84149d2") + +src3 := minio.NewSourceInfo("bucket3", "object3", &decKey) +src3.SetMatchETagCond("5918b653a31624deb84149d2f8ef9c38") + +// Create slice of sources. +srcs := []minio.SourceInfo{src1, src2, src3} + +// Prepare destination encryption key +encKey := minio.NewSSEInfo([]byte{8, 9, 0}, "") + +// Create destination info +dst, err := minio.NewDestinationInfo("bucket", "object", &encKey, nil) +if err != nil { + fmt.Println(err) + return +} + +// Compose object call by concatenating multiple source files. +err = minioClient.ComposeObject(dst, srcs) +if err != nil { + fmt.Println(err) + return +} + +fmt.Println("Composed object successfully.") +``` + +<a name="NewSourceInfo"></a> +### NewSourceInfo(bucket, object string, decryptSSEC *SSEInfo) SourceInfo +构建一个可用于服务端拷贝操作（像`CopyObject`和`ComposeObject`）的`SourceInfo`对象。该对象可用于给源对象设置拷贝条件。 + +__参数__ + +| 参数 | 类型 | 描述 | +| :--- | :--- | :--- | +| `bucket` | _string_ | 源存储桶 | +| `object` | _string_ | 源对象 | +| `decryptSSEC` | _*minio.SSEInfo_ | 源对象的解密信息 (`nil`代表不用解密) | + +__示例__ + +```go +// No decryption parameter. +src := minio.NewSourceInfo("bucket", "object", nil) + +// Destination object +dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) +if err != nil { + fmt.Println(err) + return +} + +// Copy object call +err = minioClient.CopyObject(dst, src) +if err != nil { + fmt.Println(err) + return +} +``` + +```go +// With decryption parameter. +decKey := minio.NewSSEInfo([]byte{1,2,3}, "") +src := minio.NewSourceInfo("bucket", "object", &decKey) + +// Destination object +dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) +if err != nil { + fmt.Println(err) + return +} + +// Copy object call +err = minioClient.CopyObject(dst, src) +if err != nil { + fmt.Println(err) + return +} +``` + +<a name="NewDestinationInfo"></a> +### NewDestinationInfo(bucket, object string, encryptSSEC *SSEInfo, userMeta map[string]string) (DestinationInfo, error) +构建一个用于服务端拷贝操作（像`CopyObject`和`ComposeObject`）的用作目标对象的`DestinationInfo`。 + +__参数__ + +| 参数 | 类型 | 描述 | +| :--- | :--- | :--- | +| `bucket` | _string_ | 目标存储桶名称 | +| `object` | _string_ | 目标对象名称 | +| `encryptSSEC` | _*minio.SSEInfo_ | 源对象的加密信息 (`nil`代表不用加密) | +| `userMeta` | _map[string]string_ | 给目标对象的用户元数据，如果是nil,并只有一个源对象，则将源对象的用户元数据拷贝给目标对象。| + +__示例__ + +```go +// No encryption parameter. +src := minio.NewSourceInfo("bucket", "object", nil) +dst, err := minio.NewDestinationInfo("bucket", "object", nil, nil) +if err != nil { + fmt.Println(err) + return +} + +// Copy object call +err = minioClient.CopyObject(dst, src) +if err != nil { + fmt.Println(err) + return +} +``` + +```go +src := minio.NewSourceInfo("bucket", "object", nil) + +// With encryption parameter. +encKey := minio.NewSSEInfo([]byte{1,2,3}, "") +dst, err := minio.NewDestinationInfo("bucket", "object", &encKey, nil) +if err != nil { + fmt.Println(err) + return +} + +// Copy object call +err = minioClient.CopyObject(dst, src) +if err != nil { + fmt.Println(err) + return +} +``` + +<a name="FPutObject"></a> +### FPutObject(bucketName, objectName, filePath, opts PutObjectOptions) (length int64, err error) +将filePath对应的文件内容上传到一个对象中。 + +当对象小于64MiB时，FPutObject直接在一次PUT请求里进行上传。当大于64MiB时，根据文件的实际大小，FPutObject会自动地将对象进行拆分成64MiB一块或更大一些进行上传。对象的最大大小是5TB。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`objectName` | _string_ |对象的名称 | +|`filePath` | _string_ |要上传的文件的路径 | +|`opts` | _minio.PutObjectOptions_ |允许用户设置可选的自定义元数据，content-type，content-encoding，content-disposition以及cache-control headers，传递加密模块以加密对象，并可选地设置multipart put操作的线程数量。 | + + +__示例__ + + +```go +n, err := minioClient.FPutObject("my-bucketname", "my-objectname", "my-filename.csv", minio.PutObjectOptions{ + ContentType: "application/csv", +}); +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Successfully uploaded bytes: ", n) +``` + +<a name="FPutObjectWithContext"></a> +### FPutObjectWithContext(ctx context.Context, bucketName, objectName, filePath, opts PutObjectOptions) (length int64, err error) +和FPutObject操作是一样的，不过允许取消请求。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`ctx` | _context.Context_ |请求上下文 | +|`bucketName` | _string_ |存储桶名称 | +|`objectName` | _string_ |对象的名称 | +|`filePath` | _string_ |要上传的文件的路径 | +|`opts` | _minio.PutObjectOptions_ |允许用户设置可选的自定义元数据，content-type，content-encoding，content-disposition以及cache-control headers，传递加密模块以加密对象，并可选地设置multipart put操作的线程数量。 | + +__示例__ + + +```go +ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second) +defer cancel() + +n, err := minioClient.FPutObjectWithContext(ctx, "mybucket", "myobject.csv", "/tmp/otherobject.csv", minio.PutObjectOptions{ContentType:"application/csv"}) +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Successfully uploaded bytes: ", n) +``` + +<a name="StatObject"></a> +### StatObject(bucketName, objectName string, opts StatObjectOptions) (ObjectInfo, error) +获取对象的元数据。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`objectName` | _string_ |对象的名称 | +|`opts` | _minio.StatObjectOptions_ | GET info/stat请求的一些额外参数，像encryption，If-Match | + + +__返回值__ + +|参数 |类型 |描述 | +|:---|:---| :---| +|`objInfo` | _minio.ObjectInfo_ |对象stat信息 | + + +__minio.ObjectInfo__ + +|属性 |类型 |描述 | +|:---|:---| :---| +|`objInfo.LastModified` | _time.Time_ |对象的最后修改时间 | +|`objInfo.ETag` | _string_ |对象的MD5校验码| +|`objInfo.ContentType` | _string_ |对象的Content type| +|`objInfo.Size` | _int64_ |对象的大小| + + +__示例__ + + +```go +objInfo, err := minioClient.StatObject("mybucket", "myobject", minio.StatObjectOptions{}) +if err != nil { + fmt.Println(err) + return +} +fmt.Println(objInfo) +``` + +<a name="RemoveObject"></a> +### RemoveObject(bucketName, objectName string) error +删除一个对象。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`objectName` | _string_ |对象的名称 | + + +```go +err = minioClient.RemoveObject("mybucket", "myobject") +if err != nil { + fmt.Println(err) + return +} +``` + +<a name="RemoveObjects"></a> +### RemoveObjects(bucketName string, objectsCh chan string) (errorCh <-chan RemoveObjectError) + +从一个input channel里删除一个对象集合。一次发送到服务端的删除请求最多可删除1000个对象。通过error channel返回的错误信息。 + +__参数__ + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`objectsCh` | _chan string_ | 要删除的对象的channel | + + +__返回值__ + +|参数 |类型 |描述 | +|:---|:---| :---| +|`errorCh` | _<-chan minio.RemoveObjectError_ | 删除时观察到的错误的Receive-only channel。 | + + +```go +objectsCh := make(chan string) + +// Send object names that are needed to be removed to objectsCh +go func() { + defer close(objectsCh) + // List all objects from a bucket-name with a matching prefix. + for object := range minioClient.ListObjects("my-bucketname", "my-prefixname", true, nil) { + if object.Err != nil { + log.Fatalln(object.Err) + } + objectsCh <- object.Key + } +}() + +for rErr := range minioClient.RemoveObjects("mybucket", objectsCh) { + fmt.Println("Error detected during deletion: ", rErr) +} +``` + +<a name="RemoveIncompleteUpload"></a> +### RemoveIncompleteUpload(bucketName, objectName string) error +删除一个未完整上传的对象。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`objectName` | _string_ |对象的名称 | + +__示例__ + + +```go +err = minioClient.RemoveIncompleteUpload("mybucket", "myobject") +if err != nil { + fmt.Println(err) + return +} +``` + +## 4. 操作加密对象 + +<a name="NewSymmetricKey"></a> +### NewSymmetricKey(key []byte) *encrypt.SymmetricKey + +__参数__ + +|参数 |类型 |描述 | +|:---|:---| :---| +|`key` | _string_ |存储桶名称 | + + +__返回值__ + +|参数 |类型 |描述 | +|:---|:---| :---| +|`symmetricKey` | _*encrypt.SymmetricKey_ | 加密解密的对称秘钥 | + +```go +symKey := encrypt.NewSymmetricKey([]byte("my-secret-key-00")) + +// Build the CBC encryption material with symmetric key. +cbcMaterials, err := encrypt.NewCBCSecureMaterials(symKey) +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Successfully initialized Symmetric key CBC materials", cbcMaterials) + +object, err := minioClient.GetEncryptedObject("mybucket", "myobject", cbcMaterials) +if err != nil { + fmt.Println(err) + return +} +defer object.Close() +``` + +<a name="NewAsymmetricKey"></a> +### NewAsymmetricKey(privateKey []byte, publicKey[]byte) (*encrypt.AsymmetricKey, error) + +__参数__ + +|参数 |类型 |描述 | +|:---|:---| :---| +|`privateKey` | _[]byte_ | Private key数据 | +|`publicKey` | _[]byte_ | Public key数据 | + + +__返回值__ + +|参数 |类型 |描述 | +|:---|:---| :---| +|`asymmetricKey` | _*encrypt.AsymmetricKey_ | 加密解密的非对称秘钥 | +|`err` | _error_ | 标准Error | + + +```go +privateKey, err := ioutil.ReadFile("private.key") +if err != nil { + fmt.Println(err) + return +} + +publicKey, err := ioutil.ReadFile("public.key") +if err != nil { + fmt.Println(err) + return +} + +// Initialize the asymmetric key +asymmetricKey, err := encrypt.NewAsymmetricKey(privateKey, publicKey) +if err != nil { + fmt.Println(err) + return +} + +// Build the CBC encryption material for asymmetric key. +cbcMaterials, err := encrypt.NewCBCSecureMaterials(asymmetricKey) +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Successfully initialized Asymmetric key CBC materials", cbcMaterials) + +object, err := minioClient.GetEncryptedObject("mybucket", "myobject", cbcMaterials) +if err != nil { + fmt.Println(err) + return +} +defer object.Close() +``` + +<a name="GetEncryptedObject"></a> +### GetEncryptedObject(bucketName, objectName string, encryptMaterials encrypt.Materials) (io.ReadCloser, error) + +返回对象的解密流。读流时的常见错误。 + +__参数__ + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ | 存储桶名称 | +|`objectName` | _string_ | 对象的名称 | +|`encryptMaterials` | _encrypt.Materials_ | `encrypt`包提供的对流加密的接口，(更多信息，请看https://godoc.org/github.com/minio/minio-go) | + + +__返回值__ + +|参数 |类型 |描述 | +|:---|:---| :---| +|`stream` | _io.ReadCloser_ | 返回对象的reader,调用者需要在读取之后进行关闭。 | +|`err` | _error | 错误信息 | + + +__示例__ + + +```go +// Generate a master symmetric key +key := encrypt.NewSymmetricKey([]byte("my-secret-key-00")) + +// Build the CBC encryption material +cbcMaterials, err := encrypt.NewCBCSecureMaterials(key) +if err != nil { + fmt.Println(err) + return +} + +object, err := minioClient.GetEncryptedObject("mybucket", "myobject", cbcMaterials) +if err != nil { + fmt.Println(err) + return +} +defer object.Close() + +localFile, err := os.Create("/tmp/local-file.jpg") +if err != nil { + fmt.Println(err) + return +} +defer localFile.Close() + +if _, err = io.Copy(localFile, object); err != nil { + fmt.Println(err) + return +} +``` + +<a name="PutEncryptedObject"></a> + +### PutEncryptedObject(bucketName, objectName string, reader io.Reader, encryptMaterials encrypt.Materials) (n int, err error) +加密并上传对象。 + +__参数__ + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`objectName` | _string_ |对象的名称 | +|`reader` | _io.Reader_ |任何实现io.Reader的Go类型 | +|`encryptMaterials` | _encrypt.Materials_ | `encrypt`包提供的对流加密的接口，(更多信息，请看https://godoc.org/github.com/minio/minio-go) | + +__示例__ + +```go +// Load a private key +privateKey, err := ioutil.ReadFile("private.key") +if err != nil { + fmt.Println(err) + return +} + +// Load a public key +publicKey, err := ioutil.ReadFile("public.key") +if err != nil { + fmt.Println(err) + return +} + +// Build an asymmetric key +key, err := encrypt.NewAsymmetricKey(privateKey, publicKey) +if err != nil { + fmt.Println(err) + return +} + +// Build the CBC encryption module +cbcMaterials, err := encrypt.NewCBCSecureMaterials(key) +if err != nil { + fmt.Println(err) + return +} + +// Open a file to upload +file, err := os.Open("my-testfile") +if err != nil { + fmt.Println(err) + return +} +defer file.Close() + +// Upload the encrypted form of the file +n, err := minioClient.PutEncryptedObject("mybucket", "myobject", file, cbcMaterials) +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Successfully uploaded encrypted bytes: ", n) +``` + +<a name="FPutEncryptedObject"></a> +### FPutEncryptedObject(bucketName, objectName, filePath, encryptMaterials encrypt.Materials) (n int, err error) +通过一个文件进行加密并上传到对象。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`objectName` | _string_ |对象的名称 | +|`filePath` | _string_ |要上传的文件的路径 | +|`encryptMaterials` | _encrypt.Materials_ | `encrypt`包提供的对流加密的接口，(更多信息，请看https://godoc.org/github.com/minio/minio-go) | + +__示例__ + + +```go +// Load a private key +privateKey, err := ioutil.ReadFile("private.key") +if err != nil { + fmt.Println(err) + return +} + +// Load a public key +publicKey, err := ioutil.ReadFile("public.key") +if err != nil { + fmt.Println(err) + return +} + +// Build an asymmetric key +key, err := encrypt.NewAsymmetricKey(privateKey, publicKey) +if err != nil { + fmt.Println(err) + return +} + +// Build the CBC encryption module +cbcMaterials, err := encrypt.NewCBCSecureMaterials(key) +if err != nil { + fmt.Println(err) + return +} + +n, err := minioClient.FPutEncryptedObject("mybucket", "myobject.csv", "/tmp/otherobject.csv", cbcMaterials) +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Successfully uploaded encrypted bytes: ", n) +``` + +<a name="NewSSEInfo"></a> + +### NewSSEInfo(key []byte, algo string) SSEInfo +创建一个通过用户提供的key(SSE-C),进行服务端加解密操作的key对象。 + +__参数__ + +| 参数 | 类型 | 描述 | +| :--- | :--- | :--- | +| `key` | _[]byte_ | 未编码的二进制key数组 | +| `algo` | _string_ | 加密算法，可以为空（默认是`AES256`） | + + +## 5. Presigned操作 + +<a name="PresignedGetObject"></a> +### PresignedGetObject(bucketName, objectName string, expiry time.Duration, reqParams url.Values) (*url.URL, error) +生成一个用于HTTP GET操作的presigned URL。浏览器/移动客户端可以在即使存储桶为私有的情况下也可以通过这个URL进行下载。这个presigned URL可以有一个过期时间，默认是7天。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`objectName` | _string_ |对象的名称 | +|`expiry` | _time.Duration_ |presigned URL的过期时间，单位是秒 | +|`reqParams` | _url.Values_ |额外的响应头，支持_response-expires_， _response-content-type_， _response-cache-control_， _response-content-disposition_。 | + + +__示例__ + + +```go +// 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 +} +fmt.Println("Successfully generated presigned URL", presignedURL) +``` + +<a name="PresignedPutObject"></a> +### PresignedPutObject(bucketName, objectName string, expiry time.Duration) (*url.URL, error) +生成一个用于HTTP GET操作的presigned URL。浏览器/移动客户端可以在即使存储桶为私有的情况下也可以通过这个URL进行下载。这个presigned URL可以有一个过期时间，默认是7天。 + +注意：你可以通过只指定对象名称上传到S3。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`objectName` | _string_ |对象的名称 | +|`expiry` | _time.Duration_ |presigned URL的过期时间，单位是秒 | + + +__示例__ + + +```go +// 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("Successfully generated presigned URL", presignedURL) +``` + +<a name="PresignedHeadObject"></a> +### PresignedHeadObject(bucketName, objectName string, expiry time.Duration, reqParams url.Values) (*url.URL, error) +生成一个用于HTTP GET操作的presigned URL。浏览器/移动客户端可以在即使存储桶为私有的情况下也可以通过这个URL进行下载。这个presigned URL可以有一个过期时间，默认是7天。 + +__参数__ + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`objectName` | _string_ |对象的名称 | +|`expiry` | _time.Duration_ |presigned URL的过期时间，单位是秒 | +|`reqParams` | _url.Values_ |额外的响应头，支持_response-expires_， _response-content-type_， _response-cache-control_， _response-content-disposition_。 | + + +__示例__ + + +```go +// 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.PresignedHeadObject("mybucket", "myobject", time.Second * 24 * 60 * 60, reqParams) +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Successfully generated presigned URL", presignedURL) +``` + +<a name="PresignedPostPolicy"></a> +### PresignedPostPolicy(PostPolicy) (*url.URL, map[string]string, error) +允许给POST操作的presigned URL设置策略条件。这些策略包括比如，接收对象上传的存储桶名称，名称前缀，过期策略。 + +```go +// Initialize policy condition config. +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) + +// Add a user metadata using the key "custom" and value "user" +policy.SetUserMetadata("custom", "user") + +// 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) +``` + +## 6. 存储桶策略/通知 + +<a name="SetBucketPolicy"></a> +### SetBucketPolicy(bucketname, objectPrefix string, policy policy.BucketPolicy) error +给存储桶或者对象前缀设置访问权限。 + +必须引入`github.com/minio/minio-go/pkg/policy`包。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称| +|`objectPrefix` | _string_ |对象的名称前缀| +|`policy` | _policy.BucketPolicy_ |Policy的取值如下： | +| | | _policy.BucketPolicyNone_ | +| | | _policy.BucketPolicyReadOnly_ | +| | | _policy.BucketPolicyReadWrite_ | +| | | _policy.BucketPolicyWriteOnly_ | + + +__返回值__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`err` | _error_ |标准Error | + + +__示例__ + + +```go +// Sets 'mybucket' with a sub-directory 'myprefix' to be anonymously accessible for +// both read and write operations. +err = minioClient.SetBucketPolicy("mybucket", "myprefix", policy.BucketPolicyReadWrite) +if err != nil { + fmt.Println(err) + return +} +``` + +<a name="GetBucketPolicy"></a> +### GetBucketPolicy(bucketName, objectPrefix string) (policy.BucketPolicy, error) +获取存储桶或者对象前缀的访问权限。 + +必须引入`github.com/minio/minio-go/pkg/policy`包。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`objectPrefix` | _string_ |该存储桶下的对象前缀 | + +__返回值__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketPolicy` | _policy.BucketPolicy_ |取值如下： `none`, `readonly`, `readwrite`,或者`writeonly` | +|`err` | _error_ |标准Error | + +__示例__ + + +```go +bucketPolicy, err := minioClient.GetBucketPolicy("mybucket", "") +if err != nil { + fmt.Println(err) + return +} +fmt.Println("Access permissions for mybucket is", bucketPolicy) +``` + +<a name="ListBucketPolicies"></a> +### ListBucketPolicies(bucketName, objectPrefix string) (map[string]BucketPolicy, error) +获取指定的存储桶和前缀的访问策略。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`objectPrefix` | _string_ |该存储桶下的对象前缀 | + +__返回值__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketPolicies` | _map[string]minio.BucketPolicy_ |对象以及它们的权限的Map | +|`err` | _error_ |标准Error | + +__示例__ + + +```go +bucketPolicies, err := minioClient.ListBucketPolicies("mybucket", "") +if err != nil { + fmt.Println(err) + return +} +for resource, permission := range bucketPolicies { + fmt.Println(resource, " => ", permission) +} +``` + +<a name="GetBucketNotification"></a> +### GetBucketNotification(bucketName string) (BucketNotification, error) +获取存储桶的通知配置 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | + +__返回值__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketNotification` | _minio.BucketNotification_ |含有所有通知配置的数据结构| +|`err` | _error_ |标准Error | + +__示例__ + + +```go +bucketNotification, err := minioClient.GetBucketNotification("mybucket") +if err != nil { + fmt.Println("Failed to get bucket notification configurations for mybucket", err) + return +} + +for _, queueConfig := range bucketNotification.QueueConfigs { + for _, e := range queueConfig.Events { + fmt.Println(e + " event is enabled") + } +} +``` + +<a name="SetBucketNotification"></a> +### SetBucketNotification(bucketName string, bucketNotification BucketNotification) error +给存储桶设置新的通知 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | +|`bucketNotification` | _minio.BucketNotification_ |发送给配置的web service的XML | + +__返回值__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`err` | _error_ |标准Error | + +__示例__ + + +```go +queueArn := minio.NewArn("aws", "sqs", "us-east-1", "804605494417", "PhotoUpdate") + +queueConfig := minio.NewNotificationConfig(queueArn) +queueConfig.AddEvents(minio.ObjectCreatedAll, minio.ObjectRemovedAll) +queueConfig.AddFilterPrefix("photos/") +queueConfig.AddFilterSuffix(".jpg") + +bucketNotification := minio.BucketNotification{} +bucketNotification.AddQueue(queueConfig) + +err = minioClient.SetBucketNotification("mybucket", bucketNotification) +if err != nil { + fmt.Println("Unable to set the bucket notification: ", err) + return +} +``` + +<a name="RemoveAllBucketNotification"></a> +### RemoveAllBucketNotification(bucketName string) error +删除存储桶上所有配置的通知 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ |存储桶名称 | + +__返回值__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`err` | _error_ |标准Error | + +__示例__ + + +```go +err = minioClient.RemoveAllBucketNotification("mybucket") +if err != nil { + fmt.Println("Unable to remove bucket notifications.", err) + return +} +``` + +<a name="ListenBucketNotification"></a> +### ListenBucketNotification(bucketName, prefix, suffix string, events []string, doneCh <-chan struct{}) <-chan NotificationInfo +ListenBucketNotification API通过notification channel接收存储桶通知事件。返回的notification channel有两个属性，'Records'和'Err'。 + +- 'Records'持有从服务器返回的通知信息。 +- 'Err'表示的是处理接收到的通知时报的任何错误。 + +注意：一旦报错，notification channel就会关闭。 + +__参数__ + + +|参数 |类型 |描述 | +|:---|:---| :---| +|`bucketName` | _string_ | 被监听通知的存储桶 | +|`prefix` | _string_ | 过滤通知的对象前缀 | +|`suffix` | _string_ | 过滤通知的对象后缀 | +|`events` | _[]string_ | 开启指定事件类型的通知 | +|`doneCh` | _chan struct{}_ | 在该channel上结束ListenBucketNotification iterator的一个message。 | + +__返回值__ + +|参数 |类型 |描述 | +|:---|:---| :---| +|`notificationInfo` | _chan minio.NotificationInfo_ | 存储桶通知的channel | + +__minio.NotificationInfo__ + +|属性 |类型 |描述 | +|`notificationInfo.Records` | _[]minio.NotificationEvent_ | 通知事件的集合 | +|`notificationInfo.Err` | _error_ | 操作时报的任何错误(标准Error) | + + +__示例__ + + +```go +// 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) + +// Listen for bucket notifications on "mybucket" filtered by prefix, suffix and events. +for notificationInfo := range minioClient.ListenBucketNotification("mybucket", "myprefix/", ".mysuffix", []string{ + "s3:ObjectCreated:*", + "s3:ObjectAccessed:*", + "s3:ObjectRemoved:*", + }, doneCh) { + if notificationInfo.Err != nil { + fmt.Println(notificationInfo.Err) + } + fmt.Println(notificationInfo) +} +``` + +## 7. 客户端自定义设置 + +<a name="SetAppInfo"></a> +### SetAppInfo(appName, appVersion string) +给User-Agent添加的自定义应用信息。 + +__参数__ + +| 参数 | 类型 | 描述 | +|---|---|---| +|`appName` | _string_ | 发请求的应用名称 | +| `appVersion`| _string_ | 发请求的应用版本 | + + +__示例__ + + +```go +// Set Application name and version to be used in subsequent API requests. +minioClient.SetAppInfo("myCloudApp", "1.0.0") +``` + +<a name="SetCustomTransport"></a> +### SetCustomTransport(customHTTPTransport http.RoundTripper) +重写默认的HTTP transport，通常用于调试或者添加自定义的TLS证书。 + +__参数__ + +| 参数 | 类型 | 描述 | +|---|---|---| +|`customHTTPTransport` | _http.RoundTripper_ | 自定义的transport，例如：为了调试对API请求响应进行追踪。| + + +<a name="TraceOn"></a> +### TraceOn(outputStream io.Writer) +开启HTTP tracing。追踪信息输出到io.Writer，如果outputstream为nil，则trace写入到os.Stdout标准输出。 + +__参数__ + +| 参数 | 类型 | 描述 | +|---|---|---| +|`outputStream` | _io.Writer_ | HTTP trace写入到outputStream | + + +<a name="TraceOff"></a> +### TraceOff() +关闭HTTP tracing。 + +<a name="SetS3TransferAccelerate"></a> +### SetS3TransferAccelerate(acceleratedEndpoint string) +给后续所有API请求设置ASW S3传输加速endpoint。 +注意：此API仅对AWS S3有效，对其它S3兼容的对象存储服务不生效。 + +__参数__ + +| 参数 | 类型 | 描述 | +|---|---|---| +|`acceleratedEndpoint` | _string_ | 设置新的S3传输加速endpoint。| + + +## 8. 了解更多 + +- [用Go语言创建属于你的音乐播放器APP示例](https://docs.minio.io/docs/go-music-player-app) diff --git a/docs/zh_CN/CONTRIBUTING.md b/docs/zh_CN/CONTRIBUTING.md new file mode 100644 index 0000000..bc408c6 --- /dev/null +++ b/docs/zh_CN/CONTRIBUTING.md @@ -0,0 +1,22 @@ + +### 开发者指南 + +``minio-go``欢迎你的贡献。为了让大家配合更加默契，我们做出如下约定： + +* fork项目并修改，我们鼓励大家使用pull requests进行代码相关的讨论。 + - Fork项目 + - 创建你的特性分支 (git checkout -b my-new-feature) + - Commit你的修改(git commit -am 'Add some feature') + - Push到远程分支(git push origin my-new-feature) + - 创建一个Pull Request + +* 当你准备创建pull request时，请确保： + - 写单元测试，如果你有什么疑问，请在pull request中提出来。 + - 运行`go fmt` + - 将你的多个提交合并成一个提交： `git rebase -i`。你可以强制update你的pull request。 + - 确保`go test -race ./...`和`go build`完成。 + 注意：go test会进行功能测试，这需要你有一个AWS S3账号。将账户信息设为``ACCESS_KEY``和``SECRET_KEY``环境变量。如果想运行简版测试，请使用``go test -short -race ./...``。 + +* 请阅读 [Effective Go](https://github.com/golang/go/wiki/CodeReviewComments) + - `minio-go`项目严格符合Golang风格 + - 如果您看到代码有问题，请随时发一个pull request |