diff options
Diffstat (limited to 'vendor/github.com/minio/minio-go/docs/API.md')
| -rw-r--r-- | vendor/github.com/minio/minio-go/docs/API.md | 215 |
1 files changed, 175 insertions, 40 deletions
diff --git a/vendor/github.com/minio/minio-go/docs/API.md b/vendor/github.com/minio/minio-go/docs/API.md index 06735427e..e0d0a11e6 100644 --- a/vendor/github.com/minio/minio-go/docs/API.md +++ b/vendor/github.com/minio/minio-go/docs/API.md @@ -50,17 +50,21 @@ func main() { } ``` -| Bucket operations |Object operations | Encrypted Object operations | Presigned operations | Bucket Policy/Notification Operations | Client custom settings | -|:---|:---|:---|:---|:---|:---| -|[`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) | | | [`RemoveAllBucketNotification`](#RemoveAllBucketNotification) | -|[`ListIncompleteUploads`](#ListIncompleteUploads) | [`RemoveIncompleteUpload`](#RemoveIncompleteUpload) | | | [`ListenBucketNotification`](#ListenBucketNotification) | -| | [`FPutObject`](#FPutObject) | | | | -| | [`FGetObject`](#FGetObject) | | | | +| Bucket operations | Object operations | Encrypted Object operations | Presigned operations | Bucket Policy/Notification Operations | Client custom settings | +| :--- | :--- | :--- | :--- | :--- | :--- | +| [`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) | | +| [`ListIncompleteUploads`](#ListIncompleteUploads) | [`RemoveIncompleteUpload`](#RemoveIncompleteUpload) | | | [`ListenBucketNotification`](#ListenBucketNotification) | | +| | [`FPutObject`](#FPutObject) | | | | | +| | [`FGetObject`](#FGetObject) | | | | | +| | [`ComposeObject`](#ComposeObject) | | | | | +| | [`NewSourceInfo`](#NewSourceInfo) | | | | | +| | [`NewDestinationInfo`](#NewDestinationInfo) | | | | | + ## 1. Constructor <a name="Minio"></a> @@ -438,9 +442,6 @@ if err != nil { 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. -In the event that PutObject fails to upload an object, the user may attempt to re-upload the same object. If the same object is being uploaded, PutObject API examines the previous partial attempt to upload this object and resumes automatically from where it left off. - - __Parameters__ @@ -505,9 +506,11 @@ if err != nil { <a name="CopyObject"></a> -### CopyObject(bucketName, objectName, objectSource string, conditions CopyConditions) error +### CopyObject(dst DestinationInfo, src SourceInfo) error -Copy a source object into a new object with the provided name in the provided bucket. +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__ @@ -515,50 +518,161 @@ __Parameters__ |Param |Type |Description | |:---|:---| :---| -|`bucketName` | _string_ |Name of the bucket | -|`objectName` | _string_ |Name of the object | -|`objectSource` | _string_ |Name of the source object | -|`conditions` | _CopyConditions_ |Collection of supported CopyObject conditions. [`x-amz-copy-source`, `x-amz-copy-source-if-match`, `x-amz-copy-source-if-none-match`, `x-amz-copy-source-if-unmodified-since`, `x-amz-copy-source-if-modified-since`]| +|`dst` | _DestinationInfo_ |Argument describing the destination object | +|`src` | _SourceInfo_ |Argument describing the source object | __Example__ ```go -// Use-case-1 -// To copy an existing object to a new object with _no_ copy conditions. -copyConds := minio.CopyConditions{} -err := minioClient.CopyObject("mybucket", "myobject", "my-sourcebucketname/my-sourceobjectname", copyConds) +// Use-case 1: Simple copy object with no conditions, etc +// Source object +src := minio.NewSourceInfo("my-sourcebucketname", "my-sourceobjectname", nil) + +// Destination object +dst := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) + +/ Copy object call +err = s3Client.CopyObject(dst, src) if err != nil { fmt.Println(err) return } -// Use-case-2 -// To copy an existing object to a new object with the following copy conditions +// 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) -// Initialize empty copy conditions. -var copyConds = minio.CopyConditions{} +// Set matching ETag condition, copy object which matches the following ETag. +src.SetMatchETagCond("31624deb84149d2f8ef9c385918b653a") -// copy object that matches the given ETag. -copyConds.SetMatchETag("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)) -// and modified after 1st April 2014 -copyConds.SetModified(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)) -// but unmodified since 23rd April 2014 -copyConds.SetUnmodified(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) -err := minioClient.CopyObject("mybucket", "myobject", "my-sourcebucketname/my-sourceobjectname", copyConds) +// Destination object +dst := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) + +/ Copy object call +err = s3Client.CopyObject(dst, src) if err != nil { fmt.Println(err) return } ``` +<a name="ComposeObject"></a> +### ComposeObject(dst DestinationInfo, srcs []SourceInfo) error + +Create an object by concatenating a list of source objects using +server-side copying. + +__Parameters__ + + +|Param |Type |Description | +|:---|:---|:---| +|`dst` | _minio.DestinationInfo_ |Struct with info about the object to be created. | +|`srcs` | _[]minio.SourceInfo_ |Slice of struct with info about source objects to be concatenated in order. | + + +__Example__ + + +```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.SetMatchETag("31624deb84149d2f8ef9c385918b653a") + +src2 := minio.NewSourceInfo("bucket2", "object2", decKey) +src2.SetMatchETag("f8ef9c385918b653a31624deb84149d2") + +src3 := minio.NewSourceInfo("bucket3", "object3", decKey) +src3.SetMatchETag("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 := minio.NewDestinationInfo("bucket", "object", encKey, nil) +err = s3Client.ComposeObject(dst, srcs) +if err != nil { + log.Println(err) + return +} + +log.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__ + +| Param | Type | Description | +| :--- | :--- | :--- | +| `bucket` | _string_ | Name of the source bucket | +| `object` | _string_ | Name of the source object | +| `decryptSSEC` | _*minio.SSEInfo_ | Decryption info for the source object (`nil` without encryption) | + +__Example__ + +``` go +// No decryption parameter. +src := NewSourceInfo("bucket", "object", nil) + +// With decryption parameter. +decKey := NewSSEKey([]byte{1,2,3}, "") +src := NewSourceInfo("bucket", "object", decKey) +``` + +<a name="NewDestinationInfo"></a> +### NewDestinationInfo(bucket, object string, encryptSSEC *SSEInfo, userMeta map[string]string) DestinationInfo + +Construct a `DestinationInfo` object that can be used as the destination object for server-side copying operations like `CopyObject` and `ComposeObject`. + +__Parameters__ + +| Param | Type | Description | +| :--- | :--- | :--- | +| `bucket` | _string_ | Name of the destination bucket | +| `object` | _string_ | Name of the destination object | +| `encryptSSEC` | _*minio.SSEInfo_ | Encryption info for the source object (`nil` without encryption) | +| `userMeta` | _map[string]string_ | User metadata to be set on the destination. If nil, with only one source, user-metadata is copied from source. | + +__Example__ + +``` go +// No encryption parameter. +src := NewDestinationInfo("bucket", "object", nil, nil) + +// With encryption parameter. +encKey := NewSSEKey([]byte{1,2,3}, "") +src := NewDecryptionInfo("bucket", "object", encKey, nil) +``` + + <a name="FPutObject"></a> ### FPutObject(bucketName, objectName, filePath, contentType string) (length int64, err error) @@ -566,8 +680,6 @@ 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. -In the event that FPutObject fails to upload an object, the user may attempt to re-upload the same object. If the same object is being uploaded, FPutObject API examines the previous partial attempt to upload this object and resumes automatically from where it left off. - __Parameters__ @@ -771,7 +883,7 @@ if err != nil { ``` <a name="GetEncryptedObject"></a> -### GetEncryptedObject(bucketName, objectName string, encryptMaterials minio.EncryptionMaterials) (io.Reader, error) +### GetEncryptedObject(bucketName, objectName string, encryptMaterials minio.EncryptionMaterials) (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. @@ -788,7 +900,7 @@ __Return Value__ |Param |Type |Description | |:---|:---| :---| -|`stream` | _io.Reader_ | Returns the deciphered object reader. | +|`stream` | _io.ReadCloser_ | Returns the deciphered object reader, caller should close after reading. | |`err` | _error | Returns errors. | @@ -810,11 +922,14 @@ 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 } + if _, err = io.Copy(localFile, object); err != nil { fmt.Println(err) return @@ -883,6 +998,26 @@ if err != nil { } ``` +<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__ + +| Param | Type | Description | +| :--- | :--- | :--- | +| `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> @@ -1240,7 +1375,7 @@ __Return Values__ |Param |Type |Description | |:---|:---| :---| -|`chan NotificationInfo` | _chan_ | Read channel for all notificatons on bucket | +|`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 | |