1# Minio Go Client API Reference [![Slack](https://slack.minio.io/slack?type=svg)](https://slack.minio.io) 2 3## Initialize Minio Client object. 4 5## Minio 6 7```go 8package main 9 10import ( 11 "fmt" 12 13 "github.com/minio/minio-go" 14) 15 16func main() { 17 // Use a secure connection. 18 ssl := true 19 20 // Initialize minio client object. 21 minioClient, err := minio.New("play.minio.io:9000", "Q3AM3UQ867SPQQA43P2F", "zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ssl) 22 if err != nil { 23 fmt.Println(err) 24 return 25 } 26} 27``` 28 29## AWS S3 30 31```go 32package main 33 34import ( 35 "fmt" 36 37 "github.com/minio/minio-go" 38) 39 40func main() { 41 // Use a secure connection. 42 ssl := true 43 44 // Initialize minio client object. 45 s3Client, err := minio.New("s3.amazonaws.com", "YOUR-ACCESSKEYID", "YOUR-SECRETACCESSKEY", ssl) 46 if err != nil { 47 fmt.Println(err) 48 return 49 } 50} 51``` 52 53| Bucket operations | Object operations | Encrypted Object operations | Presigned operations | Bucket Policy/Notification Operations | Client custom settings | 54| :--- | :--- | :--- | :--- | :--- | :--- | 55| [`MakeBucket`](#MakeBucket) | [`GetObject`](#GetObject) | [`GetObject`](#GetObject) | [`PresignedGetObject`](#PresignedGetObject) | [`SetBucketPolicy`](#SetBucketPolicy) | [`SetAppInfo`](#SetAppInfo) | 56| [`ListBuckets`](#ListBuckets) | [`PutObject`](#PutObject) | [`PutObject`](#PutObject) | [`PresignedPutObject`](#PresignedPutObject) | [`GetBucketPolicy`](#GetBucketPolicy) | [`SetCustomTransport`](#SetCustomTransport) | 57| [`BucketExists`](#BucketExists) | [`CopyObject`](#CopyObject) | [`CopyObject`](#CopyObject) | [`PresignedPostPolicy`](#PresignedPostPolicy) | [`SetBucketNotification`](#SetBucketNotification) | [`TraceOn`](#TraceOn) | 58| [`RemoveBucket`](#RemoveBucket) | [`StatObject`](#StatObject) | [`StatObject`](#StatObject) | | [`GetBucketNotification`](#GetBucketNotification) | [`TraceOff`](#TraceOff) | 59| [`ListObjects`](#ListObjects) | [`RemoveObject`](#RemoveObject) | | | [`RemoveAllBucketNotification`](#RemoveAllBucketNotification) | [`SetS3TransferAccelerate`](#SetS3TransferAccelerate) | 60| [`ListObjectsV2`](#ListObjectsV2) | [`RemoveObjects`](#RemoveObjects) | | | [`ListenBucketNotification`](#ListenBucketNotification) | | 61| [`ListIncompleteUploads`](#ListIncompleteUploads) | [`RemoveIncompleteUpload`](#RemoveIncompleteUpload) | | | [`SetBucketLifecycle`](#SetBucketLifecycle) | | 62| | [`FPutObject`](#FPutObject) | [`FPutObject`](#FPutObject) | | [`GetBucketLifecycle`](#GetBucketLifecycle) | | 63| | [`FGetObject`](#FGetObject) | [`FGetObject`](#FGetObject) | | | | 64| | [`ComposeObject`](#ComposeObject) | [`ComposeObject`](#ComposeObject) | | | | 65| | [`NewSourceInfo`](#NewSourceInfo) | [`NewSourceInfo`](#NewSourceInfo) | | | | 66| | [`NewDestinationInfo`](#NewDestinationInfo) | [`NewDestinationInfo`](#NewDestinationInfo) | | | | 67| | [`PutObjectWithContext`](#PutObjectWithContext) | [`PutObjectWithContext`](#PutObjectWithContext) | | | 68| | [`GetObjectWithContext`](#GetObjectWithContext) | [`GetObjectWithContext`](#GetObjectWithContext) | | | 69| | [`FPutObjectWithContext`](#FPutObjectWithContext) | [`FPutObjectWithContext`](#FPutObjectWithContext) | | | 70| | [`FGetObjectWithContext`](#FGetObjectWithContext) | [`FGetObjectWithContext`](#FGetObjectWithContext) | | | 71| | [`RemoveObjectsWithContext`](#RemoveObjectsWithContext) | | | | 72| | [`SelectObjectContent`](#SelectObjectContent) | | 73## 1. Constructor 74<a name="Minio"></a> 75 76### New(endpoint, accessKeyID, secretAccessKey string, ssl bool) (*Client, error) 77Initializes a new client object. 78 79__Parameters__ 80 81|Param |Type |Description | 82|:---|:---| :---| 83|`endpoint` | _string_ |S3 compatible object storage endpoint | 84|`accessKeyID` |_string_ |Access key for the object storage | 85|`secretAccessKey` | _string_ |Secret key for the object storage | 86|`ssl` | _bool_ | If 'true' API requests will be secure (HTTPS), and insecure (HTTP) otherwise | 87 88### NewWithRegion(endpoint, accessKeyID, secretAccessKey string, ssl bool, region string) (*Client, error) 89Initializes 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. 90 91### NewWithOptions(endpoint string, options *Options) (*Client, error) 92Initializes minio client with options configured. 93 94__Parameters__ 95 96|Param |Type |Description | 97|:---|:---| :---| 98|`endpoint` | _string_ |S3 compatible object storage endpoint | 99|`opts` |_minio.Options_ | Options for constructing a new client| 100 101__minio.Options__ 102 103|Field | Type | Description | 104|:--- |:--- | :--- | 105| `opts.Creds` | _*credentials.Credentials_ | Access Credentials| 106| `opts.Secure` | _bool_ | If 'true' API requests will be secure (HTTPS), and insecure (HTTP) otherwise | 107| `opts.Region` | _string_ | region | 108| `opts.BucketLookup` | _BucketLookupType_ | Bucket lookup type can be one of the following values | 109| | | _minio.BucketLookupDNS_ | 110| | | _minio.BucketLookupPath_ | 111| | | _minio.BucketLookupAuto_ | 112## 2. Bucket operations 113 114<a name="MakeBucket"></a> 115### MakeBucket(bucketName, location string) error 116Creates a new bucket. 117 118__Parameters__ 119 120| Param | Type | Description | 121|---|---|---| 122|`bucketName` | _string_ | Name of the bucket | 123| `location` | _string_ | Region where the bucket is to be created. Default value is us-east-1. Other valid values are listed below. Note: When used with minio server, use the region specified in its config file (defaults to us-east-1).| 124| | |us-east-1 | 125| | |us-west-1 | 126| | |us-west-2 | 127| | |eu-west-1 | 128| | | eu-central-1| 129| | | ap-southeast-1| 130| | | ap-northeast-1| 131| | | ap-southeast-2| 132| | | sa-east-1| 133 134 135__Example__ 136 137 138```go 139err = minioClient.MakeBucket("mybucket", "us-east-1") 140if err != nil { 141 fmt.Println(err) 142 return 143} 144fmt.Println("Successfully created mybucket.") 145``` 146 147<a name="ListBuckets"></a> 148### ListBuckets() ([]BucketInfo, error) 149Lists all buckets. 150 151| Param | Type | Description | 152|---|---|---| 153|`bucketList` | _[]minio.BucketInfo_ | Lists of all buckets | 154 155 156__minio.BucketInfo__ 157 158| Field | Type | Description | 159|---|---|---| 160|`bucket.Name` | _string_ | Name of the bucket | 161|`bucket.CreationDate` | _time.Time_ | Date of bucket creation | 162 163 164__Example__ 165 166 167```go 168buckets, err := minioClient.ListBuckets() 169if err != nil { 170 fmt.Println(err) 171 return 172} 173for _, bucket := range buckets { 174 fmt.Println(bucket) 175} 176``` 177 178<a name="BucketExists"></a> 179### BucketExists(bucketName string) (found bool, err error) 180Checks if a bucket exists. 181 182__Parameters__ 183 184 185|Param |Type |Description | 186|:---|:---| :---| 187|`bucketName` | _string_ |Name of the bucket | 188 189 190__Return Values__ 191 192|Param |Type |Description | 193|:---|:---| :---| 194|`found` | _bool_ | Indicates whether bucket exists or not | 195|`err` | _error_ | Standard Error | 196 197 198__Example__ 199 200 201```go 202found, err := minioClient.BucketExists("mybucket") 203if err != nil { 204 fmt.Println(err) 205 return 206} 207if found { 208 fmt.Println("Bucket found") 209} 210``` 211 212<a name="RemoveBucket"></a> 213### RemoveBucket(bucketName string) error 214Removes a bucket, bucket should be empty to be successfully removed. 215 216__Parameters__ 217 218 219|Param |Type |Description | 220|:---|:---| :---| 221|`bucketName` | _string_ |Name of the bucket | 222 223__Example__ 224 225 226```go 227err = minioClient.RemoveBucket("mybucket") 228if err != nil { 229 fmt.Println(err) 230 return 231} 232``` 233 234<a name="ListObjects"></a> 235### ListObjects(bucketName, prefix string, recursive bool, doneCh chan struct{}) <-chan ObjectInfo 236Lists objects in a bucket. 237 238__Parameters__ 239 240 241|Param |Type |Description | 242|:---|:---| :---| 243|`bucketName` | _string_ |Name of the bucket | 244|`objectPrefix` |_string_ | Prefix of objects to be listed | 245|`recursive` | _bool_ |`true` indicates recursive style listing and `false` indicates directory style listing delimited by '/'. | 246|`doneCh` | _chan struct{}_ | A message on this channel ends the ListObjects iterator. | 247 248 249__Return Value__ 250 251|Param |Type |Description | 252|:---|:---| :---| 253|`objectInfo` | _chan minio.ObjectInfo_ |Read channel for all objects in the bucket, the object is of the format listed below: | 254 255__minio.ObjectInfo__ 256 257|Field |Type |Description | 258|:---|:---| :---| 259|`objectInfo.Key` | _string_ |Name of the object | 260|`objectInfo.Size` | _int64_ |Size of the object | 261|`objectInfo.ETag` | _string_ |MD5 checksum of the object | 262|`objectInfo.LastModified` | _time.Time_ |Time when object was last modified | 263 264 265```go 266// Create a done channel to control 'ListObjects' go routine. 267doneCh := make(chan struct{}) 268 269// Indicate to our routine to exit cleanly upon return. 270defer close(doneCh) 271 272isRecursive := true 273objectCh := minioClient.ListObjects("mybucket", "myprefix", isRecursive, doneCh) 274for object := range objectCh { 275 if object.Err != nil { 276 fmt.Println(object.Err) 277 return 278 } 279 fmt.Println(object) 280} 281``` 282 283 284<a name="ListObjectsV2"></a> 285### ListObjectsV2(bucketName, prefix string, recursive bool, doneCh chan struct{}) <-chan ObjectInfo 286Lists objects in a bucket using the recommended listing API v2 287 288__Parameters__ 289 290 291|Param |Type |Description | 292|:---|:---| :---| 293|`bucketName` | _string_ |Name of the bucket | 294| `objectPrefix` |_string_ | Prefix of objects to be listed | 295| `recursive` | _bool_ |`true` indicates recursive style listing and `false` indicates directory style listing delimited by '/'. | 296|`doneCh` | _chan struct{}_ | A message on this channel ends the ListObjectsV2 iterator. | 297 298 299__Return Value__ 300 301|Param |Type |Description | 302|:---|:---| :---| 303|`objectInfo` | _chan minio.ObjectInfo_ |Read channel for all the objects in the bucket, the object is of the format listed below: | 304 305 306```go 307// Create a done channel to control 'ListObjectsV2' go routine. 308doneCh := make(chan struct{}) 309 310// Indicate to our routine to exit cleanly upon return. 311defer close(doneCh) 312 313isRecursive := true 314objectCh := minioClient.ListObjectsV2("mybucket", "myprefix", isRecursive, doneCh) 315for object := range objectCh { 316 if object.Err != nil { 317 fmt.Println(object.Err) 318 return 319 } 320 fmt.Println(object) 321} 322``` 323 324<a name="ListIncompleteUploads"></a> 325### ListIncompleteUploads(bucketName, prefix string, recursive bool, doneCh chan struct{}) <- chan ObjectMultipartInfo 326Lists partially uploaded objects in a bucket. 327 328 329__Parameters__ 330 331 332|Param |Type |Description | 333|:---|:---| :---| 334|`bucketName` | _string_ |Name of the bucket | 335| `prefix` |_string_ | Prefix of objects that are partially uploaded | 336| `recursive` | _bool_ |`true` indicates recursive style listing and `false` indicates directory style listing delimited by '/'. | 337|`doneCh` | _chan struct{}_ | A message on this channel ends the ListenIncompleteUploads iterator. | 338 339 340__Return Value__ 341 342|Param |Type |Description | 343|:---|:---| :---| 344|`multiPartInfo` | _chan minio.ObjectMultipartInfo_ |Emits multipart objects of the format listed below: | 345 346__minio.ObjectMultipartInfo__ 347 348|Field |Type |Description | 349|:---|:---| :---| 350|`multiPartObjInfo.Key` | _string_ |Name of incompletely uploaded object | 351|`multiPartObjInfo.UploadID` | _string_ |Upload ID of incompletely uploaded object | 352|`multiPartObjInfo.Size` | _int64_ |Size of incompletely uploaded object | 353 354__Example__ 355 356 357```go 358// Create a done channel to control 'ListObjects' go routine. 359doneCh := make(chan struct{}) 360 361// Indicate to our routine to exit cleanly upon return. 362defer close(doneCh) 363 364isRecursive := true // Recursively list everything at 'myprefix' 365multiPartObjectCh := minioClient.ListIncompleteUploads("mybucket", "myprefix", isRecursive, doneCh) 366for multiPartObject := range multiPartObjectCh { 367 if multiPartObject.Err != nil { 368 fmt.Println(multiPartObject.Err) 369 return 370 } 371 fmt.Println(multiPartObject) 372} 373``` 374 375## 3. Object operations 376 377<a name="GetObject"></a> 378### GetObject(bucketName, objectName string, opts GetObjectOptions) (*Object, error) 379Returns a stream of the object data. Most of the common errors occur when reading the stream. 380 381 382__Parameters__ 383 384 385|Param |Type |Description | 386|:---|:---| :---| 387|`bucketName` | _string_ |Name of the bucket | 388|`objectName` | _string_ |Name of the object | 389|`opts` | _minio.GetObjectOptions_ | Options for GET requests specifying additional options like encryption, If-Match | 390 391 392__minio.GetObjectOptions__ 393 394|Field | Type | Description | 395|:---|:---|:---| 396| `opts.ServerSideEncryption` | _encrypt.ServerSide_ | Interface provided by `encrypt` package to specify server-side-encryption. (For more information see https://godoc.org/github.com/minio/minio-go) | 397 398__Return Value__ 399 400 401|Param |Type |Description | 402|:---|:---| :---| 403|`object` | _*minio.Object_ |_minio.Object_ represents object reader. It implements io.Reader, io.Seeker, io.ReaderAt and io.Closer interfaces. | 404 405 406__Example__ 407 408 409```go 410object, err := minioClient.GetObject("mybucket", "myobject", minio.GetObjectOptions{}) 411if err != nil { 412 fmt.Println(err) 413 return 414} 415localFile, err := os.Create("/tmp/local-file.jpg") 416if err != nil { 417 fmt.Println(err) 418 return 419} 420if _, err = io.Copy(localFile, object); err != nil { 421 fmt.Println(err) 422 return 423} 424``` 425 426<a name="FGetObject"></a> 427### FGetObject(bucketName, objectName, filePath string, opts GetObjectOptions) error 428Downloads and saves the object as a file in the local filesystem. 429 430__Parameters__ 431 432 433|Param |Type |Description | 434|:---|:---| :---| 435|`bucketName` | _string_ |Name of the bucket | 436|`objectName` | _string_ |Name of the object | 437|`filePath` | _string_ |Path to download object to | 438|`opts` | _minio.GetObjectOptions_ | Options for GET requests specifying additional options like encryption, If-Match | 439 440 441__Example__ 442 443 444```go 445err = minioClient.FGetObject("mybucket", "myobject", "/tmp/myobject", minio.GetObjectOptions{}) 446if err != nil { 447 fmt.Println(err) 448 return 449} 450``` 451<a name="GetObjectWithContext"></a> 452### GetObjectWithContext(ctx context.Context, bucketName, objectName string, opts GetObjectOptions) (*Object, error) 453Identical to GetObject operation, but accepts a context for request cancellation. 454 455__Parameters__ 456 457 458|Param |Type |Description | 459|:---|:---| :---| 460|`ctx` | _context.Context_ |Request context | 461|`bucketName` | _string_ |Name of the bucket | 462|`objectName` | _string_ |Name of the object | 463|`opts` | _minio.GetObjectOptions_ | Options for GET requests specifying additional options like encryption, If-Match | 464 465 466__Return Value__ 467 468 469|Param |Type |Description | 470|:---|:---| :---| 471|`object` | _*minio.Object_ |_minio.Object_ represents object reader. It implements io.Reader, io.Seeker, io.ReaderAt and io.Closer interfaces. | 472 473 474__Example__ 475 476 477```go 478ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second) 479defer cancel() 480 481object, err := minioClient.GetObjectWithContext(ctx, "mybucket", "myobject", minio.GetObjectOptions{}) 482if err != nil { 483 fmt.Println(err) 484 return 485} 486 487localFile, err := os.Create("/tmp/local-file.jpg") 488if err != nil { 489 fmt.Println(err) 490 return 491} 492 493if _, err = io.Copy(localFile, object); err != nil { 494 fmt.Println(err) 495 return 496} 497``` 498 499<a name="FGetObjectWithContext"></a> 500### FGetObjectWithContext(ctx context.Context, bucketName, objectName, filePath string, opts GetObjectOptions) error 501Identical to FGetObject operation, but allows request cancellation. 502 503__Parameters__ 504 505 506|Param |Type |Description | 507|:---|:---| :---| 508|`ctx` | _context.Context_ |Request context | 509|`bucketName` | _string_ |Name of the bucket | 510|`objectName` | _string_ |Name of the object | 511|`filePath` | _string_ |Path to download object to | 512|`opts` | _minio.GetObjectOptions_ | Options for GET requests specifying additional options like encryption, If-Match | 513 514 515__Example__ 516 517 518```go 519ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second) 520defer cancel() 521 522err = minioClient.FGetObjectWithContext(ctx, "mybucket", "myobject", "/tmp/myobject", minio.GetObjectOptions{}) 523if err != nil { 524 fmt.Println(err) 525 return 526} 527``` 528 529<a name="PutObject"></a> 530### PutObject(bucketName, objectName string, reader io.Reader, objectSize int64,opts PutObjectOptions) (n int, err error) 531Uploads 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. 532 533__Parameters__ 534 535 536|Param |Type |Description | 537|:---|:---| :---| 538|`bucketName` | _string_ |Name of the bucket | 539|`objectName` | _string_ |Name of the object | 540|`reader` | _io.Reader_ |Any Go type that implements io.Reader | 541|`objectSize`| _int64_ |Size of the object being uploaded. Pass -1 if stream size is unknown | 542|`opts` | _minio.PutObjectOptions_ | Allows user to set optional custom metadata, content headers, encryption keys and number of threads for multipart upload operation. | 543 544__minio.PutObjectOptions__ 545 546|Field | Type | Description | 547|:--- |:--- | :--- | 548| `opts.UserMetadata` | _map[string]string_ | Map of user metadata| 549| `opts.Progress` | _io.Reader_ | Reader to fetch progress of an upload | 550| `opts.ContentType` | _string_ | Content type of object, e.g "application/text" | 551| `opts.ContentEncoding` | _string_ | Content encoding of object, e.g "gzip" | 552| `opts.ContentDisposition` | _string_ | Content disposition of object, "inline" | 553| `opts.ContentLanguage` | _string_ | Content language of object, e.g "French" | 554| `opts.CacheControl` | _string_ | Used to specify directives for caching mechanisms in both requests and responses e.g "max-age=600"| 555| `opts.ServerSideEncryption` | _encrypt.ServerSide_ | Interface provided by `encrypt` package to specify server-side-encryption. (For more information see https://godoc.org/github.com/minio/minio-go) | 556| `opts.StorageClass` | _string_ | Specify storage class for the object. Supported values for Minio server are `REDUCED_REDUNDANCY` and `STANDARD` | 557| `opts.WebsiteRedirectLocation` | _string_ | Specify a redirect for the object, to another object in the same bucket or to a external URL. | 558 559__Example__ 560 561 562```go 563file, err := os.Open("my-testfile") 564if err != nil { 565 fmt.Println(err) 566 return 567} 568defer file.Close() 569 570fileStat, err := file.Stat() 571if err != nil { 572 fmt.Println(err) 573 return 574} 575 576n, err := minioClient.PutObject("mybucket", "myobject", file, fileStat.Size(), minio.PutObjectOptions{ContentType:"application/octet-stream"}) 577if err != nil { 578 fmt.Println(err) 579 return 580} 581fmt.Println("Successfully uploaded bytes: ", n) 582``` 583 584API 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. 585 586<a name="PutObjectWithContext"></a> 587### PutObjectWithContext(ctx context.Context, bucketName, objectName string, reader io.Reader, objectSize int64, opts PutObjectOptions) (n int, err error) 588Identical to PutObject operation, but allows request cancellation. 589 590__Parameters__ 591 592 593|Param |Type |Description | 594|:---|:---| :---| 595|`ctx` | _context.Context_ |Request context | 596|`bucketName` | _string_ |Name of the bucket | 597|`objectName` | _string_ |Name of the object | 598|`reader` | _io.Reader_ |Any Go type that implements io.Reader | 599|`objectSize`| _int64_ | size of the object being uploaded. Pass -1 if stream size is unknown | 600|`opts` | _minio.PutObjectOptions_ |Pointer to struct that allows user to set optional custom metadata, content-type, content-encoding, content-disposition, content-language and cache-control headers, pass encryption module for encrypting objects, and optionally configure number of threads for multipart put operation. | 601 602 603__Example__ 604 605 606```go 607ctx, cancel := context.WithTimeout(context.Background(), 10 * time.Second) 608defer cancel() 609 610file, err := os.Open("my-testfile") 611if err != nil { 612 fmt.Println(err) 613 return 614} 615defer file.Close() 616 617fileStat, err := file.Stat() 618if err != nil { 619 fmt.Println(err) 620 return 621} 622 623n, err := minioClient.PutObjectWithContext(ctx, "my-bucketname", "my-objectname", file, fileStat.Size(), minio.PutObjectOptions{ 624 ContentType: "application/octet-stream", 625}) 626if err != nil { 627 fmt.Println(err) 628 return 629} 630fmt.Println("Successfully uploaded bytes: ", n) 631``` 632 633<a name="CopyObject"></a> 634### CopyObject(dst DestinationInfo, src SourceInfo) error 635Create 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. 636 637To copy multiple source objects into a single destination object see the `ComposeObject` API. 638 639__Parameters__ 640 641 642|Param |Type |Description | 643|:---|:---| :---| 644|`dst` | _minio.DestinationInfo_ |Argument describing the destination object | 645|`src` | _minio.SourceInfo_ |Argument describing the source object | 646 647 648__Example__ 649 650 651```go 652// Use-case 1: Simple copy object with no conditions. 653// Source object 654src := minio.NewSourceInfo("my-sourcebucketname", "my-sourceobjectname", nil) 655 656// Destination object 657dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) 658if err != nil { 659 fmt.Println(err) 660 return 661} 662 663// Copy object call 664err = minioClient.CopyObject(dst, src) 665if err != nil { 666 fmt.Println(err) 667 return 668} 669``` 670 671```go 672// Use-case 2: 673// Copy object with copy-conditions, and copying only part of the source object. 674// 1. that matches a given ETag 675// 2. and modified after 1st April 2014 676// 3. but unmodified since 23rd April 2014 677// 4. copy only first 1MiB of object. 678 679// Source object 680src := minio.NewSourceInfo("my-sourcebucketname", "my-sourceobjectname", nil) 681 682// Set matching ETag condition, copy object which matches the following ETag. 683src.SetMatchETagCond("31624deb84149d2f8ef9c385918b653a") 684 685// Set modified condition, copy object modified since 2014 April 1. 686src.SetModifiedSinceCond(time.Date(2014, time.April, 1, 0, 0, 0, 0, time.UTC)) 687 688// Set unmodified condition, copy object unmodified since 2014 April 23. 689src.SetUnmodifiedSinceCond(time.Date(2014, time.April, 23, 0, 0, 0, 0, time.UTC)) 690 691// Set copy-range of only first 1MiB of file. 692src.SetRange(0, 1024*1024-1) 693 694// Destination object 695dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) 696if err != nil { 697 fmt.Println(err) 698 return 699} 700 701// Copy object call 702err = minioClient.CopyObject(dst, src) 703if err != nil { 704 fmt.Println(err) 705 return 706} 707``` 708 709<a name="ComposeObject"></a> 710### ComposeObject(dst minio.DestinationInfo, srcs []minio.SourceInfo) error 711Create an object by concatenating a list of source objects using server-side copying. 712 713__Parameters__ 714 715 716|Param |Type |Description | 717|:---|:---|:---| 718|`dst` | _minio.DestinationInfo_ |Struct with info about the object to be created. | 719|`srcs` | _[]minio.SourceInfo_ |Slice of struct with info about source objects to be concatenated in order. | 720 721 722__Example__ 723 724 725```go 726// Prepare source decryption key (here we assume same key to 727// decrypt all source objects.) 728sseSrc := encrypt.DefaultPBKDF([]byte("password"), []byte("salt")) 729 730// Source objects to concatenate. We also specify decryption 731// key for each 732src1 := minio.NewSourceInfo("bucket1", "object1", sseSrc) 733src1.SetMatchETagCond("31624deb84149d2f8ef9c385918b653a") 734 735src2 := minio.NewSourceInfo("bucket2", "object2", sseSrc) 736src2.SetMatchETagCond("f8ef9c385918b653a31624deb84149d2") 737 738src3 := minio.NewSourceInfo("bucket3", "object3", sseSrc) 739src3.SetMatchETagCond("5918b653a31624deb84149d2f8ef9c38") 740 741// Create slice of sources. 742srcs := []minio.SourceInfo{src1, src2, src3} 743 744// Prepare destination encryption key 745sseDst := encrypt.DefaultPBKDF([]byte("new-password"), []byte("new-salt")) 746 747// Create destination info 748dst, err := minio.NewDestinationInfo("bucket", "object", sseDst, nil) 749if err != nil { 750 fmt.Println(err) 751 return 752} 753 754// Compose object call by concatenating multiple source files. 755err = minioClient.ComposeObject(dst, srcs) 756if err != nil { 757 fmt.Println(err) 758 return 759} 760 761fmt.Println("Composed object successfully.") 762``` 763 764<a name="NewSourceInfo"></a> 765### NewSourceInfo(bucket, object string, decryptSSEC *SSEInfo) SourceInfo 766Construct 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. 767 768__Parameters__ 769 770| Param | Type | Description | 771| :--- | :--- | :--- | 772| `bucket` | _string_ | Name of the source bucket | 773| `object` | _string_ | Name of the source object | 774| `sse` | _*encrypt.ServerSide_ | Interface provided by `encrypt` package to specify server-side-encryption. (For more information see https://godoc.org/github.com/minio/minio-go) | 775 776__Example__ 777 778```go 779// No decryption parameter. 780src := minio.NewSourceInfo("bucket", "object", nil) 781 782// Destination object 783dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) 784if err != nil { 785 fmt.Println(err) 786 return 787} 788 789// Copy object call 790err = minioClient.CopyObject(dst, src) 791if err != nil { 792 fmt.Println(err) 793 return 794} 795``` 796 797```go 798// With decryption parameter. 799sseSrc := encrypt.DefaultPBKDF([]byte("password"), []byte("salt")) 800src := minio.NewSourceInfo("bucket", "object", sseSrc) 801 802// Destination object 803dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) 804if err != nil { 805 fmt.Println(err) 806 return 807} 808 809// Copy object call 810err = minioClient.CopyObject(dst, src) 811if err != nil { 812 fmt.Println(err) 813 return 814} 815``` 816 817<a name="NewDestinationInfo"></a> 818### NewDestinationInfo(bucket, object string, encryptSSEC *SSEInfo, userMeta map[string]string) (DestinationInfo, error) 819Construct a `DestinationInfo` object that can be used as the destination object for server-side copying operations like `CopyObject` and `ComposeObject`. 820 821__Parameters__ 822 823| Param | Type | Description | 824| :--- | :--- | :--- | 825| `bucket` | _string_ | Name of the destination bucket | 826| `object` | _string_ | Name of the destination object | 827| `sse` | _*encrypt.ServerSide_ | Interface provided by `encrypt` package to specify server-side-encryption. (For more information see https://godoc.org/github.com/minio/minio-go) | | 828| `userMeta` | _map[string]string_ | User metadata to be set on the destination. If nil, with only one source, user-metadata is copied from source. | 829 830__Example__ 831 832```go 833// No encryption parameter. 834src := minio.NewSourceInfo("bucket", "object", nil) 835dst, err := minio.NewDestinationInfo("bucket", "object", nil, nil) 836if err != nil { 837 fmt.Println(err) 838 return 839} 840 841// Copy object call 842err = minioClient.CopyObject(dst, src) 843if err != nil { 844 fmt.Println(err) 845 return 846} 847``` 848 849```go 850src := minio.NewSourceInfo("bucket", "object", nil) 851 852// With encryption parameter. 853sseDst := encrypt.DefaultPBKDF([]byte("password"), []byte("salt")) 854dst, err := minio.NewDestinationInfo("bucket", "object", sseDst, nil) 855if err != nil { 856 fmt.Println(err) 857 return 858} 859 860// Copy object call 861err = minioClient.CopyObject(dst, src) 862if err != nil { 863 fmt.Println(err) 864 return 865} 866``` 867 868<a name="FPutObject"></a> 869### FPutObject(bucketName, objectName, filePath, opts PutObjectOptions) (length int64, err error) 870Uploads contents from a file to objectName. 871 872FPutObject 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. 873 874__Parameters__ 875 876 877|Param |Type |Description | 878|:---|:---| :---| 879|`bucketName` | _string_ |Name of the bucket | 880|`objectName` | _string_ |Name of the object | 881|`filePath` | _string_ |Path to file to be uploaded | 882|`opts` | _minio.PutObjectOptions_ |Pointer to struct that allows user to set optional custom metadata, content-type, content-encoding, content-disposition, content-language and cache-control headers, pass encryption module for encrypting objects, and optionally configure number of threads for multipart put operation. | 883 884 885__Example__ 886 887 888```go 889n, err := minioClient.FPutObject("my-bucketname", "my-objectname", "my-filename.csv", minio.PutObjectOptions{ 890 ContentType: "application/csv", 891}); 892if err != nil { 893 fmt.Println(err) 894 return 895} 896fmt.Println("Successfully uploaded bytes: ", n) 897``` 898 899<a name="FPutObjectWithContext"></a> 900### FPutObjectWithContext(ctx context.Context, bucketName, objectName, filePath, opts PutObjectOptions) (length int64, err error) 901Identical to FPutObject operation, but allows request cancellation. 902 903__Parameters__ 904 905 906|Param |Type |Description | 907|:---|:---| :---| 908|`ctx` | _context.Context_ |Request context | 909|`bucketName` | _string_ |Name of the bucket | 910|`objectName` | _string_ |Name of the object | 911|`filePath` | _string_ |Path to file to be uploaded | 912|`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. | 913 914__Example__ 915 916 917```go 918ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second) 919defer cancel() 920 921n, err := minioClient.FPutObjectWithContext(ctx, "mybucket", "myobject.csv", "/tmp/otherobject.csv", minio.PutObjectOptions{ContentType:"application/csv"}) 922if err != nil { 923 fmt.Println(err) 924 return 925} 926fmt.Println("Successfully uploaded bytes: ", n) 927``` 928 929<a name="StatObject"></a> 930### StatObject(bucketName, objectName string, opts StatObjectOptions) (ObjectInfo, error) 931Fetch metadata of an object. 932 933__Parameters__ 934 935 936|Param |Type |Description | 937|:---|:---| :---| 938|`bucketName` | _string_ |Name of the bucket | 939|`objectName` | _string_ |Name of the object | 940|`opts` | _minio.StatObjectOptions_ | Options for GET info/stat requests specifying additional options like encryption, If-Match | 941 942 943__Return Value__ 944 945|Param |Type |Description | 946|:---|:---| :---| 947|`objInfo` | _minio.ObjectInfo_ |Object stat information | 948 949 950__minio.ObjectInfo__ 951 952|Field |Type |Description | 953|:---|:---| :---| 954|`objInfo.LastModified` | _time.Time_ |Time when object was last modified | 955|`objInfo.ETag` | _string_ |MD5 checksum of the object| 956|`objInfo.ContentType` | _string_ |Content type of the object| 957|`objInfo.Size` | _int64_ |Size of the object| 958 959 960__Example__ 961 962 963```go 964objInfo, err := minioClient.StatObject("mybucket", "myobject", minio.StatObjectOptions{}) 965if err != nil { 966 fmt.Println(err) 967 return 968} 969fmt.Println(objInfo) 970``` 971 972<a name="RemoveObject"></a> 973### RemoveObject(bucketName, objectName string) error 974Removes an object. 975 976__Parameters__ 977 978 979|Param |Type |Description | 980|:---|:---| :---| 981|`bucketName` | _string_ |Name of the bucket | 982|`objectName` | _string_ |Name of the object | 983 984 985```go 986err = minioClient.RemoveObject("mybucket", "myobject") 987if err != nil { 988 fmt.Println(err) 989 return 990} 991``` 992 993<a name="RemoveObjects"></a> 994### RemoveObjects(bucketName string, objectsCh chan string) (errorCh <-chan RemoveObjectError) 995Removes 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. 996 997__Parameters__ 998 999|Param |Type |Description | 1000|:---|:---| :---| 1001|`bucketName` | _string_ |Name of the bucket | 1002|`objectsCh` | _chan string_ | Channel of objects to be removed | 1003 1004 1005__Return Values__ 1006 1007|Param |Type |Description | 1008|:---|:---| :---| 1009|`errorCh` | _<-chan minio.RemoveObjectError_ | Receive-only channel of errors observed during deletion. | 1010 1011 1012```go 1013objectsCh := make(chan string) 1014 1015// Send object names that are needed to be removed to objectsCh 1016go func() { 1017 defer close(objectsCh) 1018 // List all objects from a bucket-name with a matching prefix. 1019 for object := range minioClient.ListObjects("my-bucketname", "my-prefixname", true, nil) { 1020 if object.Err != nil { 1021 log.Fatalln(object.Err) 1022 } 1023 objectsCh <- object.Key 1024 } 1025}() 1026 1027for rErr := range minioClient.RemoveObjects("mybucket", objectsCh) { 1028 fmt.Println("Error detected during deletion: ", rErr) 1029} 1030``` 1031 1032<a name="RemoveObjectsWithContext"></a> 1033### RemoveObjectsWithContext(ctx context.Context, bucketName string, objectsCh chan string) (errorCh <-chan RemoveObjectError) 1034*Identical to RemoveObjects operation, but accepts a context for request cancellation.* 1035 1036Parameters 1037 1038|Param |Type |Description | 1039|:---|:---| :---| 1040|`ctx` | _context.Context_ |Request context | 1041|`bucketName` | _string_ |Name of the bucket | 1042|`objectsCh` | _chan string_ | Channel of objects to be removed | 1043 1044 1045__Return Values__ 1046 1047|Param |Type |Description | 1048|:---|:---| :---| 1049|`errorCh` | _<-chan minio.RemoveObjectError_ | Receive-only channel of errors observed during deletion. | 1050 1051```go 1052objectsCh := make(chan string) 1053ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second) 1054defer cancel() 1055 1056// Send object names that are needed to be removed to objectsCh 1057go func() { 1058 defer close(objectsCh) 1059 // List all objects from a bucket-name with a matching prefix. 1060 for object := range minioClient.ListObjects("my-bucketname", "my-prefixname", true, nil) { 1061 if object.Err != nil { 1062 log.Fatalln(object.Err) 1063 } 1064 objectsCh <- object.Key 1065 } 1066}() 1067 1068for rErr := range minioClient.RemoveObjects(ctx, "my-bucketname", objectsCh) { 1069 fmt.Println("Error detected during deletion: ", rErr) 1070} 1071``` 1072<a name="SelectObjectContent"></a> 1073### SelectObjectContent(ctx context.Context, bucketName string, objectsName string, expression string, options SelectObjectOptions) *SelectResults 1074Parameters 1075 1076|Param |Type |Description | 1077|:---|:---| :---| 1078|`ctx` | _context.Context_ |Request context | 1079|`bucketName` | _string_ |Name of the bucket | 1080|`objectName` | _string_ |Name of the object | 1081|`options` | _SelectObjectOptions_ | Query Options | 1082 1083__Return Values__ 1084 1085|Param |Type |Description | 1086|:---|:---| :---| 1087|`SelectResults` | _SelectResults_ | Is an io.ReadCloser object which can be directly passed to csv.NewReader for processing output. | 1088 1089```go 1090 // Initialize minio client object. 1091 minioClient, err := minio.New(endpoint, accessKeyID, secretAccessKey, useSSL) 1092 if err != nil { 1093 log.Fatalln(err) 1094 } 1095 1096 opts := minio.SelectObjectOptions{ 1097 Expression: "select count(*) from s3object", 1098 ExpressionType: minio.QueryExpressionTypeSQL, 1099 InputSerialization: minio.SelectObjectInputSerialization{ 1100 CompressionType: minio.SelectCompressionNONE, 1101 CSV: &minio.CSVInputOptions{ 1102 FileHeaderInfo: minio.CSVFileHeaderInfoNone, 1103 RecordDelimiter: "\n", 1104 FieldDelimiter: ",", 1105 }, 1106 }, 1107 OutputSerialization: minio.SelectObjectOutputSerialization{ 1108 CSV: &minio.CSVOutputOptions{ 1109 RecordDelimiter: "\n", 1110 FieldDelimiter: ",", 1111 }, 1112 }, 1113 } 1114 1115 reader, err := s3Client.SelectObjectContent(context.Background(), "mycsvbucket", "mycsv.csv", opts) 1116 if err != nil { 1117 log.Fatalln(err) 1118 } 1119 defer reader.Close() 1120 1121 if _, err := io.Copy(os.Stdout, reader); err != nil { 1122 log.Fatalln(err) 1123 } 1124``` 1125 1126<a name="RemoveIncompleteUpload"></a> 1127### RemoveIncompleteUpload(bucketName, objectName string) error 1128Removes a partially uploaded object. 1129 1130__Parameters__ 1131 1132 1133|Param |Type |Description | 1134|:---|:---| :---| 1135|`bucketName` | _string_ |Name of the bucket | 1136|`objectName` | _string_ |Name of the object | 1137 1138__Example__ 1139 1140 1141```go 1142err = minioClient.RemoveIncompleteUpload("mybucket", "myobject") 1143if err != nil { 1144 fmt.Println(err) 1145 return 1146} 1147``` 1148 1149## 5. Presigned operations 1150 1151<a name="PresignedGetObject"></a> 1152### PresignedGetObject(bucketName, objectName string, expiry time.Duration, reqParams url.Values) (*url.URL, error) 1153Generates 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. 1154 1155__Parameters__ 1156 1157 1158|Param |Type |Description | 1159|:---|:---| :---| 1160|`bucketName` | _string_ |Name of the bucket | 1161|`objectName` | _string_ |Name of the object | 1162|`expiry` | _time.Duration_ |Expiry of presigned URL in seconds | 1163|`reqParams` | _url.Values_ |Additional response header overrides supports _response-expires_, _response-content-type_, _response-cache-control_, _response-content-disposition_. | 1164 1165 1166__Example__ 1167 1168 1169```go 1170// Set request parameters for content-disposition. 1171reqParams := make(url.Values) 1172reqParams.Set("response-content-disposition", "attachment; filename=\"your-filename.txt\"") 1173 1174// Generates a presigned url which expires in a day. 1175presignedURL, err := minioClient.PresignedGetObject("mybucket", "myobject", time.Second * 24 * 60 * 60, reqParams) 1176if err != nil { 1177 fmt.Println(err) 1178 return 1179} 1180fmt.Println("Successfully generated presigned URL", presignedURL) 1181``` 1182 1183<a name="PresignedPutObject"></a> 1184### PresignedPutObject(bucketName, objectName string, expiry time.Duration) (*url.URL, error) 1185Generates 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. 1186 1187NOTE: you can upload to S3 only with specified object name. 1188 1189__Parameters__ 1190 1191 1192|Param |Type |Description | 1193|:---|:---| :---| 1194|`bucketName` | _string_ |Name of the bucket | 1195|`objectName` | _string_ |Name of the object | 1196|`expiry` | _time.Duration_ |Expiry of presigned URL in seconds | 1197 1198 1199__Example__ 1200 1201 1202```go 1203// Generates a url which expires in a day. 1204expiry := time.Second * 24 * 60 * 60 // 1 day. 1205presignedURL, err := minioClient.PresignedPutObject("mybucket", "myobject", expiry) 1206if err != nil { 1207 fmt.Println(err) 1208 return 1209} 1210fmt.Println("Successfully generated presigned URL", presignedURL) 1211``` 1212 1213<a name="PresignedHeadObject"></a> 1214### PresignedHeadObject(bucketName, objectName string, expiry time.Duration, reqParams url.Values) (*url.URL, error) 1215Generates 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. 1216 1217__Parameters__ 1218 1219|Param |Type |Description | 1220|:---|:---| :---| 1221|`bucketName` | _string_ |Name of the bucket | 1222|`objectName` | _string_ |Name of the object | 1223|`expiry` | _time.Duration_ |Expiry of presigned URL in seconds | 1224|`reqParams` | _url.Values_ |Additional response header overrides supports _response-expires_, _response-content-type_, _response-cache-control_, _response-content-disposition_. | 1225 1226 1227__Example__ 1228 1229 1230```go 1231// Set request parameters for content-disposition. 1232reqParams := make(url.Values) 1233reqParams.Set("response-content-disposition", "attachment; filename=\"your-filename.txt\"") 1234 1235// Generates a presigned url which expires in a day. 1236presignedURL, err := minioClient.PresignedHeadObject("mybucket", "myobject", time.Second * 24 * 60 * 60, reqParams) 1237if err != nil { 1238 fmt.Println(err) 1239 return 1240} 1241fmt.Println("Successfully generated presigned URL", presignedURL) 1242``` 1243 1244<a name="PresignedPostPolicy"></a> 1245### PresignedPostPolicy(PostPolicy) (*url.URL, map[string]string, error) 1246Allows 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. 1247 1248```go 1249// Initialize policy condition config. 1250policy := minio.NewPostPolicy() 1251 1252// Apply upload policy restrictions: 1253policy.SetBucket("mybucket") 1254policy.SetKey("myobject") 1255policy.SetExpires(time.Now().UTC().AddDate(0, 0, 10)) // expires in 10 days 1256 1257// Only allow 'png' images. 1258policy.SetContentType("image/png") 1259 1260// Only allow content size in range 1KB to 1MB. 1261policy.SetContentLengthRange(1024, 1024*1024) 1262 1263// Add a user metadata using the key "custom" and value "user" 1264policy.SetUserMetadata("custom", "user") 1265 1266// Get the POST form key/value object: 1267url, formData, err := minioClient.PresignedPostPolicy(policy) 1268if err != nil { 1269 fmt.Println(err) 1270 return 1271} 1272 1273// POST your content from the command line using `curl` 1274fmt.Printf("curl ") 1275for k, v := range formData { 1276 fmt.Printf("-F %s=%s ", k, v) 1277} 1278fmt.Printf("-F file=@/etc/bash.bashrc ") 1279fmt.Printf("%s\n", url) 1280``` 1281 1282## 6. Bucket policy/notification operations 1283 1284<a name="SetBucketPolicy"></a> 1285### SetBucketPolicy(bucketname, policy string) error 1286Set access permissions on bucket or an object prefix. 1287 1288__Parameters__ 1289 1290|Param |Type |Description | 1291|:---|:---| :---| 1292|`bucketName` | _string_ |Name of the bucket| 1293|`policy` | _string_ |Policy to be set | 1294 1295__Return Values__ 1296 1297|Param |Type |Description | 1298|:---|:---| :---| 1299|`err` | _error_ |Standard Error | 1300 1301__Example__ 1302 1303```go 1304policy := `{"Version": "2012-10-17","Statement": [{"Action": ["s3:GetObject"],"Effect": "Allow","Principal": {"AWS": ["*"]},"Resource": ["arn:aws:s3:::my-bucketname/*"],"Sid": ""}]}` 1305 1306err = minioClient.SetBucketPolicy("my-bucketname", policy) 1307if err != nil { 1308 fmt.Println(err) 1309 return 1310} 1311``` 1312 1313<a name="GetBucketPolicy"></a> 1314### GetBucketPolicy(bucketName) (policy string, error) 1315Get access permissions on a bucket or a prefix. 1316 1317__Parameters__ 1318 1319 1320|Param |Type |Description | 1321|:---|:---| :---| 1322|`bucketName` | _string_ |Name of the bucket | 1323 1324__Return Values__ 1325 1326 1327|Param |Type |Description | 1328|:---|:---| :---| 1329|`policy` | _string_ |Policy returned from the server | 1330|`err` | _error_ |Standard Error | 1331 1332__Example__ 1333 1334```go 1335policy, err := minioClient.GetBucketPolicy("my-bucketname") 1336if err != nil { 1337 log.Fatalln(err) 1338} 1339``` 1340 1341<a name="GetBucketNotification"></a> 1342### GetBucketNotification(bucketName string) (BucketNotification, error) 1343Get notification configuration on a bucket. 1344 1345__Parameters__ 1346 1347 1348|Param |Type |Description | 1349|:---|:---| :---| 1350|`bucketName` | _string_ |Name of the bucket | 1351 1352__Return Values__ 1353 1354 1355|Param |Type |Description | 1356|:---|:---| :---| 1357|`bucketNotification` | _minio.BucketNotification_ |structure which holds all notification configurations| 1358|`err` | _error_ |Standard Error | 1359 1360__Example__ 1361 1362 1363```go 1364bucketNotification, err := minioClient.GetBucketNotification("mybucket") 1365if err != nil { 1366 fmt.Println("Failed to get bucket notification configurations for mybucket", err) 1367 return 1368} 1369 1370for _, queueConfig := range bucketNotification.QueueConfigs { 1371 for _, e := range queueConfig.Events { 1372 fmt.Println(e + " event is enabled") 1373 } 1374} 1375``` 1376 1377<a name="SetBucketNotification"></a> 1378### SetBucketNotification(bucketName string, bucketNotification BucketNotification) error 1379Set a new bucket notification on a bucket. 1380 1381__Parameters__ 1382 1383 1384|Param |Type |Description | 1385|:---|:---| :---| 1386|`bucketName` | _string_ |Name of the bucket | 1387|`bucketNotification` | _minio.BucketNotification_ |Represents the XML to be sent to the configured web service | 1388 1389__Return Values__ 1390 1391 1392|Param |Type |Description | 1393|:---|:---| :---| 1394|`err` | _error_ |Standard Error | 1395 1396__Example__ 1397 1398 1399```go 1400queueArn := minio.NewArn("aws", "sqs", "us-east-1", "804605494417", "PhotoUpdate") 1401 1402queueConfig := minio.NewNotificationConfig(queueArn) 1403queueConfig.AddEvents(minio.ObjectCreatedAll, minio.ObjectRemovedAll) 1404queueConfig.AddFilterPrefix("photos/") 1405queueConfig.AddFilterSuffix(".jpg") 1406 1407bucketNotification := minio.BucketNotification{} 1408bucketNotification.AddQueue(queueConfig) 1409 1410err = minioClient.SetBucketNotification("mybucket", bucketNotification) 1411if err != nil { 1412 fmt.Println("Unable to set the bucket notification: ", err) 1413 return 1414} 1415``` 1416 1417<a name="RemoveAllBucketNotification"></a> 1418### RemoveAllBucketNotification(bucketName string) error 1419Remove all configured bucket notifications on a bucket. 1420 1421__Parameters__ 1422 1423 1424|Param |Type |Description | 1425|:---|:---| :---| 1426|`bucketName` | _string_ |Name of the bucket | 1427 1428__Return Values__ 1429 1430 1431|Param |Type |Description | 1432|:---|:---| :---| 1433|`err` | _error_ |Standard Error | 1434 1435__Example__ 1436 1437 1438```go 1439err = minioClient.RemoveAllBucketNotification("mybucket") 1440if err != nil { 1441 fmt.Println("Unable to remove bucket notifications.", err) 1442 return 1443} 1444``` 1445 1446<a name="ListenBucketNotification"></a> 1447### ListenBucketNotification(bucketName, prefix, suffix string, events []string, doneCh <-chan struct{}) <-chan NotificationInfo 1448ListenBucketNotification API receives bucket notification events through the notification channel. The returned notification channel has two fields 'Records' and 'Err'. 1449 1450- 'Records' holds the notifications received from the server. 1451- 'Err' indicates any error while processing the received notifications. 1452 1453NOTE: Notification channel is closed at the first occurrence of an error. 1454 1455__Parameters__ 1456 1457 1458|Param |Type |Description | 1459|:---|:---| :---| 1460|`bucketName` | _string_ | Bucket to listen notifications on | 1461|`prefix` | _string_ | Object key prefix to filter notifications for | 1462|`suffix` | _string_ | Object key suffix to filter notifications for | 1463|`events` | _[]string_ | Enables notifications for specific event types | 1464|`doneCh` | _chan struct{}_ | A message on this channel ends the ListenBucketNotification iterator | 1465 1466__Return Values__ 1467 1468|Param |Type |Description | 1469|:---|:---| :---| 1470|`notificationInfo` | _chan minio.NotificationInfo_ | Channel of bucket notifications | 1471 1472__minio.NotificationInfo__ 1473 1474|Field |Type |Description | 1475|`notificationInfo.Records` | _[]minio.NotificationEvent_ | Collection of notification events | 1476|`notificationInfo.Err` | _error_ | Carries any error occurred during the operation (Standard Error) | 1477 1478 1479__Example__ 1480 1481 1482```go 1483// Create a done channel to control 'ListenBucketNotification' go routine. 1484doneCh := make(chan struct{}) 1485 1486// Indicate a background go-routine to exit cleanly upon return. 1487defer close(doneCh) 1488 1489// Listen for bucket notifications on "mybucket" filtered by prefix, suffix and events. 1490for notificationInfo := range minioClient.ListenBucketNotification("mybucket", "myprefix/", ".mysuffix", []string{ 1491 "s3:ObjectCreated:*", 1492 "s3:ObjectAccessed:*", 1493 "s3:ObjectRemoved:*", 1494 }, doneCh) { 1495 if notificationInfo.Err != nil { 1496 fmt.Println(notificationInfo.Err) 1497 } 1498 fmt.Println(notificationInfo) 1499} 1500``` 1501 1502<a name="SetBucketLifecycle"></a> 1503### SetBucketLifecycle(bucketname, lifecycle string) error 1504Set lifecycle on bucket or an object prefix. 1505 1506__Parameters__ 1507 1508|Param |Type |Description | 1509|:---|:---| :---| 1510|`bucketName` | _string_ |Name of the bucket| 1511|`lifecycle` | _string_ |Lifecycle to be set | 1512 1513__Return Values__ 1514 1515|Param |Type |Description | 1516|:---|:---| :---| 1517|`err` | _error_ |Standard Error | 1518 1519__Example__ 1520 1521```go 1522lifecycle := `<LifecycleConfiguration> 1523 <Rule> 1524 <ID>expire-bucket</ID> 1525 <Prefix></Prefix> 1526 <Status>Enabled</Status> 1527 <Expiration> 1528 <Days>365</Days> 1529 </Expiration> 1530 </Rule> 1531</LifecycleConfiguration>` 1532 1533err = minioClient.SetBucketLifecycle("my-bucketname", lifecycle) 1534if err != nil { 1535 fmt.Println(err) 1536 return 1537} 1538``` 1539 1540<a name="GetBucketLifecycle"></a> 1541### GetBucketLifecycle(bucketName) (lifecycle string, error) 1542Get lifecycle on a bucket or a prefix. 1543 1544__Parameters__ 1545 1546 1547|Param |Type |Description | 1548|:---|:---| :---| 1549|`bucketName` | _string_ |Name of the bucket | 1550 1551__Return Values__ 1552 1553 1554|Param |Type |Description | 1555|:---|:---| :---| 1556|`lifecycle` | _string_ |Lifecycle returned from the server | 1557|`err` | _error_ |Standard Error | 1558 1559__Example__ 1560 1561```go 1562lifecycle, err := minioClient.GetBucketLifecycle("my-bucketname") 1563if err != nil { 1564 log.Fatalln(err) 1565} 1566``` 1567 1568## 7. Client custom settings 1569 1570<a name="SetAppInfo"></a> 1571### SetAppInfo(appName, appVersion string) 1572Add custom application details to User-Agent. 1573 1574__Parameters__ 1575 1576| Param | Type | Description | 1577|---|---|---| 1578|`appName` | _string_ | Name of the application performing the API requests. | 1579| `appVersion`| _string_ | Version of the application performing the API requests. | 1580 1581 1582__Example__ 1583 1584 1585```go 1586// Set Application name and version to be used in subsequent API requests. 1587minioClient.SetAppInfo("myCloudApp", "1.0.0") 1588``` 1589 1590<a name="SetCustomTransport"></a> 1591### SetCustomTransport(customHTTPTransport http.RoundTripper) 1592Overrides default HTTP transport. This is usually needed for debugging or for adding custom TLS certificates. 1593 1594__Parameters__ 1595 1596| Param | Type | Description | 1597|---|---|---| 1598|`customHTTPTransport` | _http.RoundTripper_ | Custom transport e.g, to trace API requests and responses for debugging purposes.| 1599 1600 1601<a name="TraceOn"></a> 1602### TraceOn(outputStream io.Writer) 1603Enables HTTP tracing. The trace is written to the io.Writer provided. If outputStream is nil, trace is written to os.Stdout. 1604 1605__Parameters__ 1606 1607| Param | Type | Description | 1608|---|---|---| 1609|`outputStream` | _io.Writer_ | HTTP trace is written into outputStream.| 1610 1611 1612<a name="TraceOff"></a> 1613### TraceOff() 1614Disables HTTP tracing. 1615 1616<a name="SetS3TransferAccelerate"></a> 1617### SetS3TransferAccelerate(acceleratedEndpoint string) 1618Set AWS S3 transfer acceleration endpoint for all API requests hereafter. 1619NOTE: This API applies only to AWS S3 and is a no operation for S3 compatible object storage services. 1620 1621__Parameters__ 1622 1623| Param | Type | Description | 1624|---|---|---| 1625|`acceleratedEndpoint` | _string_ | Set to new S3 transfer acceleration endpoint.| 1626 1627 1628## 8. Explore Further 1629 1630- [Build your own Go Music Player App example](https://docs.minio.io/docs/go-music-player-app) 1631