github.com/minio/minio-go/v6@v6.0.57/docs/API.md (about) 1 # MinIO Go Client API Reference [](https://slack.min.io) 2 3 ## Initialize MinIO Client object. 4 5 ## MinIO 6 7 ```go 8 package main 9 10 import ( 11 "fmt" 12 13 "github.com/minio/minio-go/v6" 14 ) 15 16 func main() { 17 // Use a secure connection. 18 ssl := true 19 20 // Initialize minio client object. 21 minioClient, err := minio.New("play.min.io", "Q3AM3UQ867SPQQA43P2F", "zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG", ssl) 22 if err != nil { 23 fmt.Println(err) 24 return 25 } 26 } 27 ``` 28 29 ## AWS S3 30 31 ```go 32 package main 33 34 import ( 35 "fmt" 36 37 "github.com/minio/minio-go/v6" 38 ) 39 40 func 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 | [`MakeBucketWithObjectLock`](#MakeBucketWithObjectLock) | [`PutObject`](#PutObject) | [`PutObject`](#PutObject) | [`PresignedPutObject`](#PresignedPutObject) | [`GetBucketPolicy`](#GetBucketPolicy) | [`SetCustomTransport`](#SetCustomTransport) | 57 | [`ListBuckets`](#ListBuckets) | [`CopyObject`](#CopyObject) | [`CopyObject`](#CopyObject) | [`PresignedPostPolicy`](#PresignedPostPolicy) | [`SetBucketNotification`](#SetBucketNotification) | [`TraceOn`](#TraceOn) | 58 | [`BucketExists`](#BucketExists) | [`StatObject`](#StatObject) | [`StatObject`](#StatObject) | | [`GetBucketNotification`](#GetBucketNotification) | [`TraceOff`](#TraceOff) | 59 | [`RemoveBucket`](#RemoveBucket) | [`RemoveObject`](#RemoveObject) | | | [`RemoveAllBucketNotification`](#RemoveAllBucketNotification) | [`SetS3TransferAccelerate`](#SetS3TransferAccelerate) | 60 | [`ListObjects`](#ListObjects) | [`RemoveObjects`](#RemoveObjects) | | | [`ListenBucketNotification`](#ListenBucketNotification) | | 61 | [`ListObjectsV2`](#ListObjectsV2) | [`RemoveIncompleteUpload`](#RemoveIncompleteUpload) | | | [`SetBucketLifecycle`](#SetBucketLifecycle) | | 62 | [`ListIncompleteUploads`](#ListIncompleteUploads) | [`FPutObject`](#FPutObject) | [`FPutObject`](#FPutObject) | | [`GetBucketLifecycle`](#GetBucketLifecycle) | | 63 | [`SetBucketTagging`](#SetBucketTagging) | [`FGetObject`](#FGetObject) | [`FGetObject`](#FGetObject) | | [`SetObjectLockConfig`](#SetObjectLockConfig) | | 64 | [`GetBucketTagging`](#GetBucketTagging) | [`ComposeObject`](#ComposeObject) | [`ComposeObject`](#ComposeObject) | | [`GetObjectLockConfig`](#GetObjectLockConfig) | | 65 | [`DeleteBucketTagging`](#DeleteBucketTagging) | [`NewSourceInfo`](#NewSourceInfo) | [`NewSourceInfo`](#NewSourceInfo) | | [`EnableVersioning`](#EnableVersioning) | | 66 | | [`NewDestinationInfo`](#NewDestinationInfo) | [`NewDestinationInfo`](#NewDestinationInfo) | | [`DisableVersioning`](#DisableVersioning) | | 67 | | [`PutObjectWithContext`](#PutObjectWithContext) | [`PutObjectWithContext`](#PutObjectWithContext) | | [`GetBucketVersioning`](#GetBucketVersioning) | | 68 | | [`GetObjectWithContext`](#GetObjectWithContext) | [`GetObjectWithContext`](#GetObjectWithContext) | | [`SetBucketEncryption`](#SetBucketEncryption) | | 69 | | [`FPutObjectWithContext`](#FPutObjectWithContext) | [`FPutObjectWithContext`](#FPutObjectWithContext) | | [`GetBucketEncryption`](#GetBucketEncryption) | | 70 | | [`FGetObjectWithContext`](#FGetObjectWithContext) | [`FGetObjectWithContext`](#FGetObjectWithContext) | | [`DeleteBucketEncryption`](#DeleteBucketEncryption) | | 71 | | [`RemoveObjectsWithContext`](#RemoveObjectsWithContext) | | | | | 72 | | [`RemoveObjectsWithOptions`](#RemoveObjectsWithOptions) | | | | | 73 | | [`RemoveObjectsWithOptionsContext`](#RemoveObjectsWithOptionsContext) | | | | | 74 | | [`RemoveObjectWithOptions`](#RemoveObjectWithOptions) | | | | | 75 | | [`PutObjectRetention`](#PutObjectRetention) | | | | | 76 | | [`GetObjectRetention`](#GetObjectRetention) | | | | | 77 | | [`PutObjectLegalHold`](#PutObjectLegalHold) | | | | | 78 | | [`GetObjectLegalHold`](#GetObjectLegalHold) | | | | | 79 | | [`SelectObjectContent`](#SelectObjectContent) | | | | | 80 | | [`PutObjectTagging`](#PutObjectTagging) | | | | | 81 | | [`PutObjectTaggingWithContext`](#PutObjectTaggingWithContext) | | | | | 82 | | [`GetObjectTagging`](#GetObjectTagging) | | | | | 83 | | [`GetObjectTaggingWithContext`](#GetObjectTaggingWithContext) | | | | | 84 | | [`RemoveObjectTagging`](#RemoveObjectTagging) | | | | | 85 | | [`RemoveObjectTaggingWithContext`](#RemoveObjectTaggingWithContext) | | | | | 86 87 ## 1. Constructor 88 <a name="MinIO"></a> 89 90 ### New(endpoint, accessKeyID, secretAccessKey string, ssl bool) (*Client, error) 91 Initializes a new client object. 92 93 __Parameters__ 94 95 |Param |Type |Description | 96 |:---|:---| :---| 97 |`endpoint` | _string_ |S3 compatible object storage endpoint | 98 |`accessKeyID` |_string_ |Access key for the object storage | 99 |`secretAccessKey` | _string_ |Secret key for the object storage | 100 |`ssl` | _bool_ | If 'true' API requests will be secure (HTTPS), and insecure (HTTP) otherwise | 101 102 ### NewWithRegion(endpoint, accessKeyID, secretAccessKey string, ssl bool, region string) (*Client, error) 103 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. 104 105 ### NewWithOptions(endpoint string, options *Options) (*Client, error) 106 Initializes minio client with options configured. 107 108 __Parameters__ 109 110 |Param |Type |Description | 111 |:---|:---| :---| 112 |`endpoint` | _string_ |S3 compatible object storage endpoint | 113 |`opts` |_minio.Options_ | Options for constructing a new client| 114 115 __minio.Options__ 116 117 |Field | Type | Description | 118 |:--- |:--- | :--- | 119 | `opts.Creds` | _*credentials.Credentials_ | Access Credentials| 120 | `opts.Secure` | _bool_ | If 'true' API requests will be secure (HTTPS), and insecure (HTTP) otherwise | 121 | `opts.Region` | _string_ | region | 122 | `opts.BucketLookup` | _BucketLookupType_ | Bucket lookup type can be one of the following values | 123 | | | _minio.BucketLookupDNS_ | 124 | | | _minio.BucketLookupPath_ | 125 | | | _minio.BucketLookupAuto_ | 126 ## 2. Bucket operations 127 128 <a name="MakeBucket"></a> 129 ### MakeBucket(bucketName, location string) error 130 Creates a new bucket. 131 132 __Parameters__ 133 134 | Param | Type | Description | 135 |---|---|---| 136 |`bucketName` | _string_ | Name of the bucket | 137 | `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).| 138 | | |us-east-1 | 139 | | |us-east-2 | 140 | | |us-west-1 | 141 | | |us-west-2 | 142 | | |ca-central-1 | 143 | | |eu-west-1 | 144 | | |eu-west-2 | 145 | | |eu-west-3 | 146 | | | eu-central-1| 147 | | | eu-north-1| 148 | | | ap-east-1| 149 | | | ap-south-1| 150 | | | ap-southeast-1| 151 | | | ap-southeast-2| 152 | | | ap-northeast-1| 153 | | | ap-northeast-2| 154 | | | ap-northeast-3| 155 | | | me-south-1| 156 | | | sa-east-1| 157 | | | us-gov-west-1| 158 | | | us-gov-east-1| 159 | | | cn-north-1| 160 | | | cn-northwest-1| 161 162 163 __Example__ 164 165 166 ```go 167 err = minioClient.MakeBucket("mybucket", "us-east-1") 168 if err != nil { 169 fmt.Println(err) 170 return 171 } 172 fmt.Println("Successfully created mybucket.") 173 ``` 174 175 <a name="MakeBucketWithObjectLock"></a> 176 ### MakeBucketWithObjectLock(bucketName, location string) error 177 Creates a new bucket with object lock enabled. 178 179 __Parameters__ 180 181 | Param | Type | Description | 182 |---|---|---| 183 |`bucketName` | _string_ | Name of the bucket | 184 | `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).| 185 | | |us-east-1 | 186 | | |us-west-1 | 187 | | |us-west-2 | 188 | | |eu-west-1 | 189 | | | eu-central-1| 190 | | | ap-southeast-1| 191 | | | ap-northeast-1| 192 | | | ap-southeast-2| 193 | | | sa-east-1| 194 195 196 __Example__ 197 198 199 ```go 200 err = minioClient.MakeBucketWithObjectLock("mybucket", "us-east-1") 201 if err != nil { 202 fmt.Println(err) 203 return 204 } 205 fmt.Println("Successfully created mybucket.") 206 ``` 207 208 <a name="ListBuckets"></a> 209 ### ListBuckets() ([]BucketInfo, error) 210 Lists all buckets. 211 212 | Param | Type | Description | 213 |---|---|---| 214 |`bucketList` | _[]minio.BucketInfo_ | Lists of all buckets | 215 216 217 __minio.BucketInfo__ 218 219 | Field | Type | Description | 220 |---|---|---| 221 |`bucket.Name` | _string_ | Name of the bucket | 222 |`bucket.CreationDate` | _time.Time_ | Date of bucket creation | 223 224 225 __Example__ 226 227 228 ```go 229 buckets, err := minioClient.ListBuckets() 230 if err != nil { 231 fmt.Println(err) 232 return 233 } 234 for _, bucket := range buckets { 235 fmt.Println(bucket) 236 } 237 ``` 238 239 <a name="BucketExists"></a> 240 ### BucketExists(bucketName string) (found bool, err error) 241 Checks if a bucket exists. 242 243 __Parameters__ 244 245 246 |Param |Type |Description | 247 |:---|:---| :---| 248 |`bucketName` | _string_ |Name of the bucket | 249 250 251 __Return Values__ 252 253 |Param |Type |Description | 254 |:---|:---| :---| 255 |`found` | _bool_ | Indicates whether bucket exists or not | 256 |`err` | _error_ | Standard Error | 257 258 259 __Example__ 260 261 262 ```go 263 found, err := minioClient.BucketExists("mybucket") 264 if err != nil { 265 fmt.Println(err) 266 return 267 } 268 if found { 269 fmt.Println("Bucket found") 270 } 271 ``` 272 273 <a name="RemoveBucket"></a> 274 ### RemoveBucket(bucketName string) error 275 Removes a bucket, bucket should be empty to be successfully removed. 276 277 __Parameters__ 278 279 280 |Param |Type |Description | 281 |:---|:---| :---| 282 |`bucketName` | _string_ |Name of the bucket | 283 284 __Example__ 285 286 287 ```go 288 err = minioClient.RemoveBucket("mybucket") 289 if err != nil { 290 fmt.Println(err) 291 return 292 } 293 ``` 294 295 <a name="ListObjects"></a> 296 ### ListObjects(bucketName, prefix string, recursive bool, doneCh chan struct{}) <-chan ObjectInfo 297 Lists objects in a bucket. 298 299 __Parameters__ 300 301 302 |Param |Type |Description | 303 |:---|:---| :---| 304 |`bucketName` | _string_ |Name of the bucket | 305 |`objectPrefix` |_string_ | Prefix of objects to be listed | 306 |`recursive` | _bool_ |`true` indicates recursive style listing and `false` indicates directory style listing delimited by '/'. | 307 |`doneCh` | _chan struct{}_ | A message on this channel ends the ListObjects iterator. | 308 309 310 __Return Value__ 311 312 |Param |Type |Description | 313 |:---|:---| :---| 314 |`objectInfo` | _chan minio.ObjectInfo_ |Read channel for all objects in the bucket, the object is of the format listed below: | 315 316 __minio.ObjectInfo__ 317 318 |Field |Type |Description | 319 |:---|:---| :---| 320 |`objectInfo.Key` | _string_ |Name of the object | 321 |`objectInfo.Size` | _int64_ |Size of the object | 322 |`objectInfo.ETag` | _string_ |MD5 checksum of the object | 323 |`objectInfo.LastModified` | _time.Time_ |Time when object was last modified | 324 325 326 ```go 327 // Create a done channel to control 'ListObjects' go routine. 328 doneCh := make(chan struct{}) 329 330 // Indicate to our routine to exit cleanly upon return. 331 defer close(doneCh) 332 333 isRecursive := true 334 objectCh := minioClient.ListObjects("mybucket", "myprefix", isRecursive, doneCh) 335 for object := range objectCh { 336 if object.Err != nil { 337 fmt.Println(object.Err) 338 return 339 } 340 fmt.Println(object) 341 } 342 ``` 343 344 345 <a name="ListObjectsV2"></a> 346 ### ListObjectsV2(bucketName, prefix string, recursive bool, doneCh chan struct{}) <-chan ObjectInfo 347 Lists objects in a bucket using the recommended listing API v2 348 349 __Parameters__ 350 351 352 |Param |Type |Description | 353 |:---|:---| :---| 354 |`bucketName` | _string_ |Name of the bucket | 355 | `objectPrefix` |_string_ | Prefix of objects to be listed | 356 | `recursive` | _bool_ |`true` indicates recursive style listing and `false` indicates directory style listing delimited by '/'. | 357 |`doneCh` | _chan struct{}_ | A message on this channel ends the ListObjectsV2 iterator. | 358 359 360 __Return Value__ 361 362 |Param |Type |Description | 363 |:---|:---| :---| 364 |`objectInfo` | _chan minio.ObjectInfo_ |Read channel for all the objects in the bucket, the object is of the format listed below: | 365 366 367 ```go 368 // Create a done channel to control 'ListObjectsV2' go routine. 369 doneCh := make(chan struct{}) 370 371 // Indicate to our routine to exit cleanly upon return. 372 defer close(doneCh) 373 374 isRecursive := true 375 objectCh := minioClient.ListObjectsV2("mybucket", "myprefix", isRecursive, doneCh) 376 for object := range objectCh { 377 if object.Err != nil { 378 fmt.Println(object.Err) 379 return 380 } 381 fmt.Println(object) 382 } 383 ``` 384 385 <a name="ListIncompleteUploads"></a> 386 ### ListIncompleteUploads(bucketName, prefix string, recursive bool, doneCh chan struct{}) <- chan ObjectMultipartInfo 387 Lists partially uploaded objects in a bucket. 388 389 390 __Parameters__ 391 392 393 |Param |Type |Description | 394 |:---|:---| :---| 395 |`bucketName` | _string_ |Name of the bucket | 396 | `prefix` |_string_ | Prefix of objects that are partially uploaded | 397 | `recursive` | _bool_ |`true` indicates recursive style listing and `false` indicates directory style listing delimited by '/'. | 398 |`doneCh` | _chan struct{}_ | A message on this channel ends the ListenIncompleteUploads iterator. | 399 400 401 __Return Value__ 402 403 |Param |Type |Description | 404 |:---|:---| :---| 405 |`multiPartInfo` | _chan minio.ObjectMultipartInfo_ |Emits multipart objects of the format listed below: | 406 407 __minio.ObjectMultipartInfo__ 408 409 |Field |Type |Description | 410 |:---|:---| :---| 411 |`multiPartObjInfo.Key` | _string_ |Name of incompletely uploaded object | 412 |`multiPartObjInfo.UploadID` | _string_ |Upload ID of incompletely uploaded object | 413 |`multiPartObjInfo.Size` | _int64_ |Size of incompletely uploaded object | 414 415 __Example__ 416 417 418 ```go 419 // Create a done channel to control 'ListObjects' go routine. 420 doneCh := make(chan struct{}) 421 422 // Indicate to our routine to exit cleanly upon return. 423 defer close(doneCh) 424 425 isRecursive := true // Recursively list everything at 'myprefix' 426 multiPartObjectCh := minioClient.ListIncompleteUploads("mybucket", "myprefix", isRecursive, doneCh) 427 for multiPartObject := range multiPartObjectCh { 428 if multiPartObject.Err != nil { 429 fmt.Println(multiPartObject.Err) 430 return 431 } 432 fmt.Println(multiPartObject) 433 } 434 ``` 435 436 <a name="SetBucketTagging"></a> 437 ### SetBucketTagging(bucketName string, tags *tags.Tags) error 438 Sets tags to a bucket. 439 440 441 __Parameters__ 442 | Param | Type | Description | 443 |:-------------|:-------------|:-------------------| 444 | `bucketName` | _string_ | Name of the bucket | 445 | `tags` | _*tags.Tags_ | Bucket tags | 446 447 __Example__ 448 ```go 449 // Create tags from a map. 450 tags, err := tags.NewTags(map[string]string{ 451 "Tag1": "Value1", 452 "Tag2": "Value2", 453 }, false) 454 if err != nil { 455 log.Fatalln(err) 456 } 457 458 err = minioClient.SetBucketTagging("my-bucketname", tags) 459 if err != nil { 460 log.Fatalln(err) 461 } 462 ``` 463 464 <a name="GetBucketTagging"></a> 465 ### GetBucketTagging(bucketName string) (*tags.Tags, error) 466 Gets tags of a bucket. 467 468 469 __Parameters__ 470 | Param | Type | Description | 471 |:-------------|:-------------|:-------------------| 472 | `bucketName` | _string_ | Name of the bucket | 473 474 __Return Value__ 475 476 | Param | Type | Description | 477 |:-------|:-------------|:------------| 478 | `tags` | _*tags.Tags_ | Bucket tags | 479 480 __Example__ 481 ```go 482 tags, err := minioClient.GetBucketTagging("my-bucketname") 483 if err != nil { 484 log.Fatalln(err) 485 } 486 487 fmt.Printf("Fetched Object Tags: %v\n", tags) 488 ``` 489 490 <a name="DeleteBucketTagging"></a> 491 ### DeleteBucketTagging(bucketName string) error 492 Deletes all tags of a bucket. 493 494 495 __Parameters__ 496 | Param | Type | Description | 497 |:-------------|:-------------|:-------------------| 498 | `bucketName` | _string_ | Name of the bucket | 499 500 __Example__ 501 ```go 502 err := minioClient.DeleteBucketTagging("my-bucketname") 503 if err != nil { 504 log.Fatalln(err) 505 } 506 ``` 507 508 ## 3. Object operations 509 510 <a name="GetObject"></a> 511 ### GetObject(bucketName, objectName string, opts GetObjectOptions) (*Object, error) 512 Returns a stream of the object data. Most of the common errors occur when reading the stream. 513 514 515 __Parameters__ 516 517 518 |Param |Type |Description | 519 |:---|:---| :---| 520 |`bucketName` | _string_ |Name of the bucket | 521 |`objectName` | _string_ |Name of the object | 522 |`opts` | _minio.GetObjectOptions_ | Options for GET requests specifying additional options like encryption, If-Match | 523 524 525 __minio.GetObjectOptions__ 526 527 |Field | Type | Description | 528 |:---|:---|:---| 529 | `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/v6) | 530 531 __Return Value__ 532 533 534 |Param |Type |Description | 535 |:---|:---| :---| 536 |`object` | _*minio.Object_ |_minio.Object_ represents object reader. It implements io.Reader, io.Seeker, io.ReaderAt and io.Closer interfaces. | 537 538 539 __Example__ 540 541 542 ```go 543 object, err := minioClient.GetObject("mybucket", "myobject", minio.GetObjectOptions{}) 544 if err != nil { 545 fmt.Println(err) 546 return 547 } 548 localFile, err := os.Create("/tmp/local-file.jpg") 549 if err != nil { 550 fmt.Println(err) 551 return 552 } 553 if _, err = io.Copy(localFile, object); err != nil { 554 fmt.Println(err) 555 return 556 } 557 ``` 558 559 <a name="FGetObject"></a> 560 ### FGetObject(bucketName, objectName, filePath string, opts GetObjectOptions) error 561 Downloads and saves the object as a file in the local filesystem. 562 563 __Parameters__ 564 565 566 |Param |Type |Description | 567 |:---|:---| :---| 568 |`bucketName` | _string_ |Name of the bucket | 569 |`objectName` | _string_ |Name of the object | 570 |`filePath` | _string_ |Path to download object to | 571 |`opts` | _minio.GetObjectOptions_ | Options for GET requests specifying additional options like encryption, If-Match | 572 573 574 __Example__ 575 576 577 ```go 578 err = minioClient.FGetObject("mybucket", "myobject", "/tmp/myobject", minio.GetObjectOptions{}) 579 if err != nil { 580 fmt.Println(err) 581 return 582 } 583 ``` 584 <a name="GetObjectWithContext"></a> 585 ### GetObjectWithContext(ctx context.Context, bucketName, objectName string, opts GetObjectOptions) (*Object, error) 586 Identical to GetObject operation, but accepts a context for request cancellation. 587 588 __Parameters__ 589 590 591 |Param |Type |Description | 592 |:---|:---| :---| 593 |`ctx` | _context.Context_ |Request context | 594 |`bucketName` | _string_ |Name of the bucket | 595 |`objectName` | _string_ |Name of the object | 596 |`opts` | _minio.GetObjectOptions_ | Options for GET requests specifying additional options like encryption, If-Match | 597 598 599 __Return Value__ 600 601 602 |Param |Type |Description | 603 |:---|:---| :---| 604 |`object` | _*minio.Object_ |_minio.Object_ represents object reader. It implements io.Reader, io.Seeker, io.ReaderAt and io.Closer interfaces. | 605 606 607 __Example__ 608 609 610 ```go 611 ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second) 612 defer cancel() 613 614 object, err := minioClient.GetObjectWithContext(ctx, "mybucket", "myobject", minio.GetObjectOptions{}) 615 if err != nil { 616 fmt.Println(err) 617 return 618 } 619 620 localFile, err := os.Create("/tmp/local-file.jpg") 621 if err != nil { 622 fmt.Println(err) 623 return 624 } 625 626 if _, err = io.Copy(localFile, object); err != nil { 627 fmt.Println(err) 628 return 629 } 630 ``` 631 632 <a name="FGetObjectWithContext"></a> 633 ### FGetObjectWithContext(ctx context.Context, bucketName, objectName, filePath string, opts GetObjectOptions) error 634 Identical to FGetObject operation, but allows request cancellation. 635 636 __Parameters__ 637 638 639 |Param |Type |Description | 640 |:---|:---| :---| 641 |`ctx` | _context.Context_ |Request context | 642 |`bucketName` | _string_ |Name of the bucket | 643 |`objectName` | _string_ |Name of the object | 644 |`filePath` | _string_ |Path to download object to | 645 |`opts` | _minio.GetObjectOptions_ | Options for GET requests specifying additional options like encryption, If-Match | 646 647 648 __Example__ 649 650 651 ```go 652 ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second) 653 defer cancel() 654 655 err = minioClient.FGetObjectWithContext(ctx, "mybucket", "myobject", "/tmp/myobject", minio.GetObjectOptions{}) 656 if err != nil { 657 fmt.Println(err) 658 return 659 } 660 ``` 661 662 <a name="PutObject"></a> 663 ### PutObject(bucketName, objectName string, reader io.Reader, objectSize int64,opts PutObjectOptions) (n int, err error) 664 Uploads objects that are less than 128MiB in a single PUT operation. For objects that are greater than 128MiB in size, PutObject seamlessly uploads the object as parts of 128MiB or more depending on the actual file size. The max upload size for an object is 5TB. 665 666 __Parameters__ 667 668 669 |Param |Type |Description | 670 |:---|:---| :---| 671 |`bucketName` | _string_ |Name of the bucket | 672 |`objectName` | _string_ |Name of the object | 673 |`reader` | _io.Reader_ |Any Go type that implements io.Reader | 674 |`objectSize`| _int64_ |Size of the object being uploaded. Pass -1 if stream size is unknown | 675 |`opts` | _minio.PutObjectOptions_ | Allows user to set optional custom metadata, content headers, encryption keys and number of threads for multipart upload operation. | 676 677 __minio.PutObjectOptions__ 678 679 | Field | Type | Description | 680 |:-------------------------------|:-----------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 681 | `opts.UserMetadata` | _map[string]string_ | Map of user metadata | 682 | `opts.UserTags` | _map[string]string_ | Map of user object tags | 683 | `opts.Progress` | _io.Reader_ | Reader to fetch progress of an upload | 684 | `opts.ContentType` | _string_ | Content type of object, e.g "application/text" | 685 | `opts.ContentEncoding` | _string_ | Content encoding of object, e.g "gzip" | 686 | `opts.ContentDisposition` | _string_ | Content disposition of object, "inline" | 687 | `opts.ContentLanguage` | _string_ | Content language of object, e.g "French" | 688 | `opts.CacheControl` | _string_ | Used to specify directives for caching mechanisms in both requests and responses e.g "max-age=600" | 689 | `opts.Mode` | _*minio.RetentionMode_ | Retention mode to be set, e.g "COMPLIANCE" | 690 | `opts.RetainUntilDate` | _*time.Time_ | Time until which the retention applied is valid | 691 | `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/v6) | 692 | `opts.StorageClass` | _string_ | Specify storage class for the object. Supported values for MinIO server are `REDUCED_REDUNDANCY` and `STANDARD` | 693 | `opts.WebsiteRedirectLocation` | _string_ | Specify a redirect for the object, to another object in the same bucket or to a external URL. | 694 | `opts.SendContentMd5` | _bool_ | Specify if you'd like to send `content-md5` header with PutObject operation. Note that setting this flag will cause higher memory usage because of in-memory `md5sum` calculation. | 695 | `opts.PartSize` | _uint64_ | Specify a custom part size used for uploading the object | 696 697 698 __Example__ 699 700 701 ```go 702 file, err := os.Open("my-testfile") 703 if err != nil { 704 fmt.Println(err) 705 return 706 } 707 defer file.Close() 708 709 fileStat, err := file.Stat() 710 if err != nil { 711 fmt.Println(err) 712 return 713 } 714 715 n, err := minioClient.PutObject("mybucket", "myobject", file, fileStat.Size(), minio.PutObjectOptions{ContentType:"application/octet-stream"}) 716 if err != nil { 717 fmt.Println(err) 718 return 719 } 720 fmt.Println("Successfully uploaded bytes: ", n) 721 ``` 722 723 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. 724 725 <a name="PutObjectWithContext"></a> 726 ### PutObjectWithContext(ctx context.Context, bucketName, objectName string, reader io.Reader, objectSize int64, opts PutObjectOptions) (n int, err error) 727 Identical to PutObject operation, but allows request cancellation. 728 729 __Parameters__ 730 731 732 |Param |Type |Description | 733 |:---|:---| :---| 734 |`ctx` | _context.Context_ |Request context | 735 |`bucketName` | _string_ |Name of the bucket | 736 |`objectName` | _string_ |Name of the object | 737 |`reader` | _io.Reader_ |Any Go type that implements io.Reader | 738 |`objectSize`| _int64_ | size of the object being uploaded. Pass -1 if stream size is unknown | 739 |`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. | 740 741 742 __Example__ 743 744 745 ```go 746 ctx, cancel := context.WithTimeout(context.Background(), 10 * time.Second) 747 defer cancel() 748 749 file, err := os.Open("my-testfile") 750 if err != nil { 751 fmt.Println(err) 752 return 753 } 754 defer file.Close() 755 756 fileStat, err := file.Stat() 757 if err != nil { 758 fmt.Println(err) 759 return 760 } 761 762 n, err := minioClient.PutObjectWithContext(ctx, "my-bucketname", "my-objectname", file, fileStat.Size(), minio.PutObjectOptions{ 763 ContentType: "application/octet-stream", 764 }) 765 if err != nil { 766 fmt.Println(err) 767 return 768 } 769 fmt.Println("Successfully uploaded bytes: ", n) 770 ``` 771 772 <a name="CopyObject"></a> 773 ### CopyObject(dst DestinationInfo, src SourceInfo) error 774 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. 775 776 To copy multiple source objects into a single destination object see the `ComposeObject` API. 777 778 __Parameters__ 779 780 781 |Param |Type |Description | 782 |:---|:---| :---| 783 |`dst` | _minio.DestinationInfo_ |Argument describing the destination object | 784 |`src` | _minio.SourceInfo_ |Argument describing the source object | 785 786 787 __Example__ 788 789 790 ```go 791 // Use-case 1: Simple copy object with no conditions. 792 // Source object 793 src := minio.NewSourceInfo("my-sourcebucketname", "my-sourceobjectname", nil) 794 795 // Destination object 796 dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) 797 if err != nil { 798 fmt.Println(err) 799 return 800 } 801 802 // Copy object call 803 err = minioClient.CopyObject(dst, src) 804 if err != nil { 805 fmt.Println(err) 806 return 807 } 808 ``` 809 810 ```go 811 // Use-case 2: 812 // Copy object with copy-conditions, and copying only part of the source object. 813 // 1. that matches a given ETag 814 // 2. and modified after 1st April 2014 815 // 3. but unmodified since 23rd April 2014 816 // 4. copy only first 1MiB of object. 817 818 // Source object 819 src := minio.NewSourceInfo("my-sourcebucketname", "my-sourceobjectname", nil) 820 821 // Set matching ETag condition, copy object which matches the following ETag. 822 src.SetMatchETagCond("31624deb84149d2f8ef9c385918b653a") 823 824 // Set modified condition, copy object modified since 2014 April 1. 825 src.SetModifiedSinceCond(time.Date(2014, time.April, 1, 0, 0, 0, 0, time.UTC)) 826 827 // Set unmodified condition, copy object unmodified since 2014 April 23. 828 src.SetUnmodifiedSinceCond(time.Date(2014, time.April, 23, 0, 0, 0, 0, time.UTC)) 829 830 // Set copy-range of only first 1MiB of file. 831 src.SetRange(0, 1024*1024-1) 832 833 // Destination object 834 dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) 835 if err != nil { 836 fmt.Println(err) 837 return 838 } 839 840 // Copy object call 841 err = minioClient.CopyObject(dst, src) 842 if err != nil { 843 fmt.Println(err) 844 return 845 } 846 ``` 847 848 <a name="ComposeObject"></a> 849 ### ComposeObject(dst minio.DestinationInfo, srcs []minio.SourceInfo) error 850 Create an object by concatenating a list of source objects using server-side copying. 851 852 __Parameters__ 853 854 855 |Param |Type |Description | 856 |:---|:---|:---| 857 |`dst` | _minio.DestinationInfo_ |Struct with info about the object to be created. | 858 |`srcs` | _[]minio.SourceInfo_ |Slice of struct with info about source objects to be concatenated in order. | 859 860 861 __Example__ 862 863 864 ```go 865 // Prepare source decryption key (here we assume same key to 866 // decrypt all source objects.) 867 sseSrc := encrypt.DefaultPBKDF([]byte("password"), []byte("salt")) 868 869 // Source objects to concatenate. We also specify decryption 870 // key for each 871 src1 := minio.NewSourceInfo("bucket1", "object1", sseSrc) 872 src1.SetMatchETagCond("31624deb84149d2f8ef9c385918b653a") 873 874 src2 := minio.NewSourceInfo("bucket2", "object2", sseSrc) 875 src2.SetMatchETagCond("f8ef9c385918b653a31624deb84149d2") 876 877 src3 := minio.NewSourceInfo("bucket3", "object3", sseSrc) 878 src3.SetMatchETagCond("5918b653a31624deb84149d2f8ef9c38") 879 880 // Create slice of sources. 881 srcs := []minio.SourceInfo{src1, src2, src3} 882 883 // Prepare destination encryption key 884 sseDst := encrypt.DefaultPBKDF([]byte("new-password"), []byte("new-salt")) 885 886 // Create destination info 887 dst, err := minio.NewDestinationInfo("bucket", "object", sseDst, nil) 888 if err != nil { 889 fmt.Println(err) 890 return 891 } 892 893 // Compose object call by concatenating multiple source files. 894 err = minioClient.ComposeObject(dst, srcs) 895 if err != nil { 896 fmt.Println(err) 897 return 898 } 899 900 fmt.Println("Composed object successfully.") 901 ``` 902 903 <a name="NewSourceInfo"></a> 904 ### NewSourceInfo(bucket, object string, decryptSSEC *SSEInfo) SourceInfo 905 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. 906 907 __Parameters__ 908 909 | Param | Type | Description | 910 | :--- | :--- | :--- | 911 | `bucket` | _string_ | Name of the source bucket | 912 | `object` | _string_ | Name of the source object | 913 | `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/v6) | 914 915 __Example__ 916 917 ```go 918 // No decryption parameter. 919 src := minio.NewSourceInfo("bucket", "object", nil) 920 921 // Destination object 922 dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) 923 if err != nil { 924 fmt.Println(err) 925 return 926 } 927 928 // Copy object call 929 err = minioClient.CopyObject(dst, src) 930 if err != nil { 931 fmt.Println(err) 932 return 933 } 934 ``` 935 936 ```go 937 // With decryption parameter. 938 sseSrc := encrypt.DefaultPBKDF([]byte("password"), []byte("salt")) 939 src := minio.NewSourceInfo("bucket", "object", sseSrc) 940 941 // Destination object 942 dst, err := minio.NewDestinationInfo("my-bucketname", "my-objectname", nil, nil) 943 if err != nil { 944 fmt.Println(err) 945 return 946 } 947 948 // Copy object call 949 err = minioClient.CopyObject(dst, src) 950 if err != nil { 951 fmt.Println(err) 952 return 953 } 954 ``` 955 956 <a name="NewDestinationInfo"></a> 957 ### NewDestinationInfo(bucket, object string, encryptSSEC *SSEInfo, userMeta map[string]string) (DestinationInfo, error) 958 Construct a `DestinationInfo` object that can be used as the destination object for server-side copying operations like `CopyObject` and `ComposeObject`. 959 960 __Parameters__ 961 962 | Param | Type | Description | 963 | :--- | :--- | :--- | 964 | `bucket` | _string_ | Name of the destination bucket | 965 | `object` | _string_ | Name of the destination object | 966 | `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/v6) | | 967 | `userMeta` | _map[string]string_ | User metadata to be set on the destination. If nil, with only one source, user-metadata is copied from source. | 968 969 __Example__ 970 971 ```go 972 // No encryption parameter. 973 src := minio.NewSourceInfo("bucket", "object", nil) 974 dst, err := minio.NewDestinationInfo("bucket", "object", nil, nil) 975 if err != nil { 976 fmt.Println(err) 977 return 978 } 979 980 // Copy object call 981 err = minioClient.CopyObject(dst, src) 982 if err != nil { 983 fmt.Println(err) 984 return 985 } 986 ``` 987 988 ```go 989 src := minio.NewSourceInfo("bucket", "object", nil) 990 991 // With encryption parameter. 992 sseDst := encrypt.DefaultPBKDF([]byte("password"), []byte("salt")) 993 dst, err := minio.NewDestinationInfo("bucket", "object", sseDst, nil) 994 if err != nil { 995 fmt.Println(err) 996 return 997 } 998 999 // Copy object call 1000 err = minioClient.CopyObject(dst, src) 1001 if err != nil { 1002 fmt.Println(err) 1003 return 1004 } 1005 ``` 1006 1007 <a name="NewDestinationInfoWithOptions"></a> 1008 ### NewDestinationInfoWithOptions(bucket, object string, destOpts DestInfoOptions) (DestinationInfo, error) 1009 Construct a `DestinationInfo` object that can be used as the destination object for server-side copying operations like `CopyObject` and `ComposeObject`. 1010 1011 __Parameters__ 1012 1013 | Param | Type | Description | 1014 | :--- | :--- | :--- | 1015 | `bucket` | _string_ | Name of the destination bucket | 1016 | `object` | _string_ | Name of the destination object | 1017 | `destOpts` | _minio.DestInfoOptions_ | Pointer to struct that allows user to set optional custom metadata, user tags, and server side encryption parameters. | 1018 1019 __minio.DestInfoOptions__ 1020 1021 |Field | Type | Description | 1022 |:--- |:--- | :--- | 1023 | `destOpts.Encryption` | _encrypt.ServerSide_ | Interface provided by encrypt package to specify server-side-encryption. (For more information see https://godoc.org/github.com/minio/minio-go/v6). | 1024 | `destOpts.UserMetadata` | _map[string]string_ | Map of user meta data to be set on destination object. | 1025 | `destOpts.UserTags` | _map[string]string_ | Map of user object tags to be set on destination object. | 1026 | `destOpts.ReplaceTags` | _bool_ | Replace object tags of the destination object. | 1027 | `destOpts.LegalHold` | _minio.LegalHoldStatus_ | LegalHold(En|Dis)abled. | 1028 | `destOpts.Mode` | _minio.RetentionMode_ | Retention mode to be set on copied object. | 1029 | `destOpts.RetainUntilDate` | _time.Time_ | Time until object retention should be applied on copied object. | 1030 1031 __Example__ 1032 1033 ```go 1034 // No encryption parameter. 1035 src := minio.NewSourceInfo("bucket", "object", nil) 1036 tags := map[string]string{ 1037 "Tag1": "Value1", 1038 "Tag2": "Value2", 1039 } 1040 dst, err := minio.NewDestinationInfoWithOptions("bucket", "object", minio.DestInfoOptions{ 1041 UserTags: tags, ReplaceTags: true, 1042 }) 1043 if err != nil { 1044 fmt.Println(err) 1045 return 1046 } 1047 1048 // Copy object call 1049 err = minioClient.CopyObject(dst, src) 1050 if err != nil { 1051 fmt.Println(err) 1052 return 1053 } 1054 ``` 1055 1056 ```go 1057 src := minio.NewSourceInfo("bucket", "object", nil) 1058 1059 // With encryption parameter. 1060 sseDst := encrypt.DefaultPBKDF([]byte("password"), []byte("salt")) 1061 tags := map[string]string{ 1062 "Tag1": "Value1", 1063 "Tag2": "Value2", 1064 } 1065 dst, err := minio.NewDestinationInfoWithOptions("bucket", "object", minio.DestInfoOptions{ 1066 Encryption: sseDst, UserTags: tags, ReplaceTags: true, 1067 }) 1068 if err != nil { 1069 fmt.Println(err) 1070 return 1071 } 1072 1073 // Copy object call 1074 err = minioClient.CopyObject(dst, src) 1075 if err != nil { 1076 fmt.Println(err) 1077 return 1078 } 1079 ``` 1080 1081 <a name="FPutObject"></a> 1082 ### FPutObject(bucketName, objectName, filePath, opts PutObjectOptions) (length int64, err error) 1083 Uploads contents from a file to objectName. 1084 1085 FPutObject uploads objects that are less than 128MiB in a single PUT operation. For objects that are greater than the 128MiB in size, FPutObject seamlessly uploads the object in chunks of 128MiB or more depending on the actual file size. The max upload size for an object is 5TB. 1086 1087 __Parameters__ 1088 1089 1090 |Param |Type |Description | 1091 |:---|:---| :---| 1092 |`bucketName` | _string_ |Name of the bucket | 1093 |`objectName` | _string_ |Name of the object | 1094 |`filePath` | _string_ |Path to file to be uploaded | 1095 |`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. | 1096 1097 1098 __Example__ 1099 1100 1101 ```go 1102 n, err := minioClient.FPutObject("my-bucketname", "my-objectname", "my-filename.csv", minio.PutObjectOptions{ 1103 ContentType: "application/csv", 1104 }); 1105 if err != nil { 1106 fmt.Println(err) 1107 return 1108 } 1109 fmt.Println("Successfully uploaded bytes: ", n) 1110 ``` 1111 1112 <a name="FPutObjectWithContext"></a> 1113 ### FPutObjectWithContext(ctx context.Context, bucketName, objectName, filePath, opts PutObjectOptions) (length int64, err error) 1114 Identical to FPutObject operation, but allows request cancellation. 1115 1116 __Parameters__ 1117 1118 1119 |Param |Type |Description | 1120 |:---|:---| :---| 1121 |`ctx` | _context.Context_ |Request context | 1122 |`bucketName` | _string_ |Name of the bucket | 1123 |`objectName` | _string_ |Name of the object | 1124 |`filePath` | _string_ |Path to file to be uploaded | 1125 |`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. | 1126 1127 __Example__ 1128 1129 1130 ```go 1131 ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second) 1132 defer cancel() 1133 1134 n, err := minioClient.FPutObjectWithContext(ctx, "mybucket", "myobject.csv", "/tmp/otherobject.csv", minio.PutObjectOptions{ContentType:"application/csv"}) 1135 if err != nil { 1136 fmt.Println(err) 1137 return 1138 } 1139 fmt.Println("Successfully uploaded bytes: ", n) 1140 ``` 1141 1142 <a name="StatObject"></a> 1143 ### StatObject(bucketName, objectName string, opts StatObjectOptions) (ObjectInfo, error) 1144 Fetch metadata of an object. 1145 1146 __Parameters__ 1147 1148 1149 |Param |Type |Description | 1150 |:---|:---| :---| 1151 |`bucketName` | _string_ |Name of the bucket | 1152 |`objectName` | _string_ |Name of the object | 1153 |`opts` | _minio.StatObjectOptions_ | Options for GET info/stat requests specifying additional options like encryption, If-Match | 1154 1155 1156 __Return Value__ 1157 1158 |Param |Type |Description | 1159 |:---|:---| :---| 1160 |`objInfo` | _minio.ObjectInfo_ |Object stat information | 1161 1162 1163 __minio.ObjectInfo__ 1164 1165 |Field |Type |Description | 1166 |:---|:---| :---| 1167 |`objInfo.LastModified` | _time.Time_ |Time when object was last modified | 1168 |`objInfo.ETag` | _string_ |MD5 checksum of the object| 1169 |`objInfo.ContentType` | _string_ |Content type of the object| 1170 |`objInfo.Size` | _int64_ |Size of the object| 1171 1172 1173 __Example__ 1174 1175 1176 ```go 1177 objInfo, err := minioClient.StatObject("mybucket", "myobject", minio.StatObjectOptions{}) 1178 if err != nil { 1179 fmt.Println(err) 1180 return 1181 } 1182 fmt.Println(objInfo) 1183 ``` 1184 1185 <a name="RemoveObject"></a> 1186 ### RemoveObject(bucketName, objectName string) error 1187 Removes an object. 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 1197 1198 ```go 1199 err = minioClient.RemoveObject("mybucket", "myobject") 1200 if err != nil { 1201 fmt.Println(err) 1202 return 1203 } 1204 ``` 1205 1206 <a name="RemoveObjects"></a> 1207 ### RemoveObjects(bucketName string, objectsCh chan string) (errorCh <-chan RemoveObjectError) 1208 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. 1209 1210 __Parameters__ 1211 1212 |Param |Type |Description | 1213 |:---|:---| :---| 1214 |`bucketName` | _string_ |Name of the bucket | 1215 |`objectsCh` | _chan string_ | Channel of objects to be removed | 1216 1217 1218 __Return Values__ 1219 1220 |Param |Type |Description | 1221 |:---|:---| :---| 1222 |`errorCh` | _<-chan minio.RemoveObjectError_ | Receive-only channel of errors observed during deletion. | 1223 1224 1225 ```go 1226 objectsCh := make(chan string) 1227 1228 // Send object names that are needed to be removed to objectsCh 1229 go func() { 1230 defer close(objectsCh) 1231 // List all objects from a bucket-name with a matching prefix. 1232 for object := range minioClient.ListObjects("my-bucketname", "my-prefixname", true, nil) { 1233 if object.Err != nil { 1234 log.Fatalln(object.Err) 1235 } 1236 objectsCh <- object.Key 1237 } 1238 }() 1239 1240 for rErr := range minioClient.RemoveObjects("mybucket", objectsCh) { 1241 fmt.Println("Error detected during deletion: ", rErr) 1242 } 1243 ``` 1244 1245 <a name="RemoveObjectsWithContext"></a> 1246 ### RemoveObjectsWithContext(ctx context.Context, bucketName string, objectsCh chan string) (errorCh <-chan RemoveObjectError) 1247 *Identical to RemoveObjects operation, but accepts a context for request cancellation.* 1248 1249 Parameters 1250 1251 |Param |Type |Description | 1252 |:---|:---| :---| 1253 |`ctx` | _context.Context_ |Request context | 1254 |`bucketName` | _string_ |Name of the bucket | 1255 |`objectsCh` | _chan string_ | Channel of objects to be removed | 1256 1257 1258 __Return Values__ 1259 1260 |Param |Type |Description | 1261 |:---|:---| :---| 1262 |`errorCh` | _<-chan minio.RemoveObjectError_ | Receive-only channel of errors observed during deletion. | 1263 1264 ```go 1265 objectsCh := make(chan string) 1266 ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second) 1267 defer cancel() 1268 1269 // Send object names that are needed to be removed to objectsCh 1270 go func() { 1271 defer close(objectsCh) 1272 // List all objects from a bucket-name with a matching prefix. 1273 for object := range minioClient.ListObjects("my-bucketname", "my-prefixname", true, nil) { 1274 if object.Err != nil { 1275 log.Fatalln(object.Err) 1276 } 1277 objectsCh <- object.Key 1278 } 1279 }() 1280 1281 for rErr := range minioClient.RemoveObjects(ctx, "my-bucketname", objectsCh) { 1282 fmt.Println("Error detected during deletion: ", rErr) 1283 } 1284 ``` 1285 <a name="RemoveObjectWithOptions"></a> 1286 ### RemoveObjectWithOptions(bucketName, objectName string, opts minio.RemoveObjectOptions) error 1287 Removes an object. 1288 1289 __Parameters__ 1290 1291 1292 |Param |Type |Description | 1293 |:---|:---| :---| 1294 |`bucketName` | _string_ |Name of the bucket | 1295 |`objectName` | _string_ |Name of the object | 1296 |`opts` |_minio.RemoveObjectOptions_ |Allows user to set options | 1297 1298 __minio.RemoveObjectOptions__ 1299 1300 |Field | Type | Description | 1301 |:--- |:--- | :--- | 1302 | `opts.GovernanceBypass` | _bool_ |Set the bypass governance header to delete an object locked with GOVERNANCE mode| 1303 | `opts.VersionID` | _string_ |Version ID of the object to delete| 1304 1305 1306 ```go 1307 opts := minio.RemoveObjectOptions { 1308 GovernanceBypass: true, 1309 VersionID: "myversionid", 1310 } 1311 err = minioClient.RemoveObjectWithOptions("mybucket", "myobject", opts) 1312 if err != nil { 1313 fmt.Println(err) 1314 return 1315 } 1316 ``` 1317 <a name="PutObjectRetention"></a> 1318 ### PutObjectRetention(bucketName, objectName string, opts minio.PutObjectRetentionOptions) error 1319 Applies object retention lock onto an object. 1320 1321 __Parameters__ 1322 1323 1324 |Param |Type |Description | 1325 |:---|:---| :---| 1326 |`bucketName` | _string_ |Name of the bucket | 1327 |`objectName` | _string_ |Name of the object | 1328 |`opts` |_minio.PutObjectRetentionOptions_ |Allows user to set options like retention mode, expiry date and version id | 1329 1330 <a name="RemoveObjectsWithOptions"></a> 1331 ### RemoveObjectsWithOptions(bucketName string, objectsCh <-chan string, opts RemoveObjectsOptions) <-chan RemoveObjectError 1332 *Identical to RemoveObjects operation, but accepts opts for bypassing Governance mode.* 1333 1334 Parameters 1335 1336 |Param |Type |Description | 1337 |:---|:---| :---| 1338 |`bucketName` | _string_ |Name of the bucket | 1339 |`objectsCh` | _chan string_ | Channel of objects to be removed | 1340 |`opts` |_minio.RemoveObjectsOptions_ | Allows user to set options | 1341 1342 __minio.RemoveObjectsOptions__ 1343 1344 |Field | Type | Description | 1345 |:--- |:--- | :--- | 1346 | `opts.GovernanceBypass` | _bool_ |Set the bypass governance header to delete an object locked with GOVERNANCE mode| 1347 1348 __Return Values__ 1349 1350 |Param |Type |Description | 1351 |:---|:---| :---| 1352 |`errorCh` | _<-chan minio.RemoveObjectError_ | Receive-only channel of errors observed during deletion. | 1353 1354 ```go 1355 objectsCh := make(chan string) 1356 1357 // Send object names that are needed to be removed to objectsCh 1358 go func() { 1359 defer close(objectsCh) 1360 // List all objects from a bucket-name with a matching prefix. 1361 for object := range minioClient.ListObjects("my-bucketname", "my-prefixname", true, nil) { 1362 if object.Err != nil { 1363 log.Fatalln(object.Err) 1364 } 1365 objectsCh <- object.Key 1366 } 1367 }() 1368 1369 opts := minio.RemoveObjectsOptions{ 1370 GovernanceBypass: true, 1371 } 1372 1373 for rErr := range minioClient.RemoveObjectsWithOptions("my-bucketname", objectsCh, opts) { 1374 fmt.Println("Error detected during deletion: ", rErr) 1375 } 1376 ``` 1377 1378 <a name="RemoveObjectsWithOptionsContext"></a> 1379 ### RemoveObjectsWithOptionsContext(ctx context.Context, bucketName string, objectsCh <-chan string, opts RemoveObjectsOptions) <-chan RemoveObjectError 1380 *Identical to RemoveObjectsWithContext operation, but accepts opts for bypassing Governance mode.* 1381 1382 Parameters 1383 1384 |Param |Type |Description | 1385 |:---|:---| :---| 1386 |`ctx` | _context.Context_ |Request context | 1387 |`bucketName` | _string_ |Name of the bucket | 1388 |`objectsCh` | _chan string_ | Channel of objects to be removed | 1389 |`opts` |_minio.RemoveObjectsOptions_ | Allows user to set options | 1390 1391 __Return Values__ 1392 1393 |Param |Type |Description | 1394 |:---|:---| :---| 1395 |`errorCh` | _<-chan minio.RemoveObjectError_ | Receive-only channel of errors observed during deletion. | 1396 1397 ```go 1398 objectsCh := make(chan string) 1399 ctx, cancel := context.WithTimeout(context.Background(), 100 * time.Second) 1400 defer cancel() 1401 1402 // Send object names that are needed to be removed to objectsCh 1403 go func() { 1404 defer close(objectsCh) 1405 // List all objects from a bucket-name with a matching prefix. 1406 for object := range minioClient.ListObjects("my-bucketname", "my-prefixname", true, nil) { 1407 if object.Err != nil { 1408 log.Fatalln(object.Err) 1409 } 1410 objectsCh <- object.Key 1411 } 1412 }() 1413 1414 opts := minio.RemoveObjectsOptions{ 1415 GovernanceBypass: true, 1416 } 1417 1418 for rErr := range minioClient.RemoveObjectsWithOptionsContext(ctx, "my-bucketname", objectsCh, opts) { 1419 fmt.Println("Error detected during deletion: ", rErr) 1420 } 1421 ``` 1422 1423 __minio.PutObjectRetentionOptions__ 1424 1425 |Field | Type | Description | 1426 |:--- |:--- | :--- | 1427 | `opts.GovernanceBypass` | _bool_ |Set the bypass governance header to overwrite object retention if the existing retention mode is set to GOVERNANCE| 1428 | `opts.Mode` | _*minio.RetentionMode_ |Retention mode to be set| 1429 | `opts.RetainUntilDate` | _*time.Time_ |Time until which the retention applied is valid| 1430 | `opts.VersionID` | _string_ |Version ID of the object to apply retention on| 1431 1432 ```go 1433 t := time.Date(2020, time.November, 18, 14, 0, 0, 0, time.UTC) 1434 m := minio.RetentionMode(minio.Compliance) 1435 opts := minio.PutObjectRetentionOptions { 1436 GovernanceBypass: true, 1437 RetainUntilDate: &t, 1438 Mode: &m, 1439 } 1440 err = minioClient.PutObjectRetention("mybucket", "myobject", opts) 1441 if err != nil { 1442 fmt.Println(err) 1443 return 1444 } 1445 ``` 1446 <a name="GetObjectRetention"></a> 1447 ### GetObjectRetention(bucketName, objectName, versionID string) (mode *RetentionMode, retainUntilDate *time.Time, err error) 1448 Returns retention set on a given object. 1449 1450 __Parameters__ 1451 1452 1453 |Param |Type |Description | 1454 |:---|:---| :---| 1455 |`bucketName` | _string_ |Name of the bucket | 1456 |`objectName` | _string_ |Name of the object | 1457 |`versionID` |_string_ |Version ID of the object | 1458 1459 ```go 1460 err = minioClient.PutObjectRetention("mybucket", "myobject", "") 1461 if err != nil { 1462 fmt.Println(err) 1463 return 1464 } 1465 ``` 1466 <a name="PutObjectLegalHold"></a> 1467 ### PutObjectLegalHold(bucketName, objectName string, opts minio.PutObjectLegalHoldOptions) error 1468 Applies legal-hold onto an object. 1469 1470 __Parameters__ 1471 1472 1473 |Param |Type |Description | 1474 |:---|:---| :---| 1475 |`bucketName` | _string_ |Name of the bucket | 1476 |`objectName` | _string_ |Name of the object | 1477 |`opts` |_minio.PutObjectLegalHoldOptions_ |Allows user to set options like status and version id | 1478 1479 _minio.PutObjectLegalHoldOptions_ 1480 1481 |Field | Type | Description | 1482 |:--- |:--- | :--- | 1483 | `opts.Status` | _*minio.LegalHoldStatus_ |Legal-Hold status to be set| 1484 | `opts.VersionID` | _string_ |Version ID of the object to apply retention on| 1485 1486 ```go 1487 s := minio.LegalHoldEnabled 1488 opts := minio.PutObjectLegalHoldOptions { 1489 Status: &s, 1490 } 1491 err = minioClient.PutObjectLegalHold("mybucket", "myobject", opts) 1492 if err != nil { 1493 fmt.Println(err) 1494 return 1495 } 1496 ``` 1497 <a name="GetObjectLegalHold"></a> 1498 ### GetObjectLegalHold(bucketName, objectName, versionID string) (status *LegalHoldStatus, err error) 1499 Returns legal-hold status on a given object. 1500 1501 __Parameters__ 1502 1503 |Param |Type |Description | 1504 |:---|:---| :---| 1505 |`bucketName` | _string_ |Name of the bucket | 1506 |`objectName` | _string_ |Name of the object | 1507 |`opts` |_minio.GetObjectLegalHoldOptions_ |Allows user to set options like version id | 1508 1509 ```go 1510 opts := minio.GetObjectLegalHoldOptions{} 1511 err = minioClient.GetObjectLegalHold("mybucket", "myobject", opts) 1512 if err != nil { 1513 fmt.Println(err) 1514 return 1515 } 1516 ``` 1517 <a name="SelectObjectContent"></a> 1518 ### SelectObjectContent(ctx context.Context, bucketName string, objectsName string, expression string, options SelectObjectOptions) *SelectResults 1519 Parameters 1520 1521 |Param |Type |Description | 1522 |:---|:---| :---| 1523 |`ctx` | _context.Context_ |Request context | 1524 |`bucketName` | _string_ |Name of the bucket | 1525 |`objectName` | _string_ |Name of the object | 1526 |`options` | _SelectObjectOptions_ | Query Options | 1527 1528 __Return Values__ 1529 1530 |Param |Type |Description | 1531 |:---|:---| :---| 1532 |`SelectResults` | _SelectResults_ | Is an io.ReadCloser object which can be directly passed to csv.NewReader for processing output. | 1533 1534 ```go 1535 // Initialize minio client object. 1536 minioClient, err := minio.New(endpoint, accessKeyID, secretAccessKey, useSSL) 1537 if err != nil { 1538 log.Fatalln(err) 1539 } 1540 1541 opts := minio.SelectObjectOptions{ 1542 Expression: "select count(*) from s3object", 1543 ExpressionType: minio.QueryExpressionTypeSQL, 1544 InputSerialization: minio.SelectObjectInputSerialization{ 1545 CompressionType: minio.SelectCompressionNONE, 1546 CSV: &minio.CSVInputOptions{ 1547 FileHeaderInfo: minio.CSVFileHeaderInfoNone, 1548 RecordDelimiter: "\n", 1549 FieldDelimiter: ",", 1550 }, 1551 }, 1552 OutputSerialization: minio.SelectObjectOutputSerialization{ 1553 CSV: &minio.CSVOutputOptions{ 1554 RecordDelimiter: "\n", 1555 FieldDelimiter: ",", 1556 }, 1557 }, 1558 } 1559 1560 reader, err := s3Client.SelectObjectContent(context.Background(), "mycsvbucket", "mycsv.csv", opts) 1561 if err != nil { 1562 log.Fatalln(err) 1563 } 1564 defer reader.Close() 1565 1566 if _, err := io.Copy(os.Stdout, reader); err != nil { 1567 log.Fatalln(err) 1568 } 1569 ``` 1570 1571 <a name="PutObjectTagging"></a> 1572 ### PutObjectTagging(bucketName, objectName string, objectTags map[string]string) error 1573 Adds or replace Object Tags to the given object 1574 1575 __Parameters__ 1576 1577 1578 |Param |Type |Description | 1579 |:---|:---| :---| 1580 |`bucketName` | _string_ |Name of the bucket | 1581 |`objectName` | _string_ |Name of the object | 1582 |`objectTags` | _map[string]string_ | Map with Object Tag's Key and Value | 1583 1584 __Example__ 1585 1586 1587 ```go 1588 err = minioClient.PutObjectTagging(bucketName, objectName, objectTags) 1589 if err != nil { 1590 fmt.Println(err) 1591 return 1592 } 1593 ``` 1594 1595 <a name="PutObjectTaggingWithContext"></a> 1596 ### PutObjectTaggingWithContext(ctx context.Context, sssbucketName, objectName string, objectTags map[string]string) error 1597 Identical to PutObjectTagging, but allows setting context to allow controlling context cancellations and timeouts. 1598 1599 __Parameters__ 1600 1601 1602 |Param |Type |Description | 1603 |:---|:---| :---| 1604 |`ctx` | _context.Context_ |Request context | 1605 |`bucketName` | _string_ |Name of the bucket | 1606 |`objectName` | _string_ |Name of the object | 1607 |`objectTags` | _map[string]string_ | Map with Object Tag's Key and Value | 1608 1609 __Example__ 1610 1611 1612 ```go 1613 err = minioClient.PutObjectTaggingWithContext(ctx, bucketName, objectName, objectTags) 1614 if err != nil { 1615 fmt.Println(err) 1616 return 1617 } 1618 ``` 1619 1620 <a name="GetObjectTagging"></a> 1621 ### GetObjectTagging(bucketName, objectName string) (string, error) 1622 Fetch Object Tags from the given object 1623 1624 __Parameters__ 1625 1626 1627 |Param |Type |Description | 1628 |:---|:---| :---| 1629 |`bucketName` | _string_ |Name of the bucket | 1630 |`objectName` | _string_ |Name of the object | 1631 1632 __Example__ 1633 1634 1635 ```go 1636 tags, err = minioClient.GetObjectTagging(bucketName, objectName) 1637 if err != nil { 1638 fmt.Println(err) 1639 return 1640 } 1641 fmt.Printf("Fetched Tags: %s", tags) 1642 ``` 1643 1644 <a name="GetObjectTaggingWithContext"></a> 1645 ### GetObjectTaggingWithContext(ctx context.Context, bucketName, objectName string) (string, error) 1646 Identical to GetObjectTagging, but allows setting context to allow controlling context cancellations and timeouts. 1647 1648 __Parameters__ 1649 1650 1651 |Param |Type |Description | 1652 |:---|:---| :---| 1653 |`ctx` | _context.Context_ |Request context | 1654 |`bucketName` | _string_ |Name of the bucket | 1655 |`objectName` | _string_ |Name of the object | 1656 1657 __Example__ 1658 1659 1660 ```go 1661 tags, err = minioClient.GetObjectTaggingWithContext(ctx, bucketName, objectName) 1662 if err != nil { 1663 fmt.Println(err) 1664 return 1665 } 1666 fmt.Printf("Fetched Tags: %s", tags) 1667 ``` 1668 1669 <a name="RemoveObjectTagging"></a> 1670 ### RemoveObjectTagging(bucketName, objectName string) error 1671 Remove Object Tags from the given object 1672 1673 __Parameters__ 1674 1675 1676 |Param |Type |Description | 1677 |:---|:---| :---| 1678 |`bucketName` | _string_ |Name of the bucket | 1679 |`objectName` | _string_ |Name of the object | 1680 1681 __Example__ 1682 1683 1684 ```go 1685 err = minioClient.RemoveObjectTagging(bucketName, objectName) 1686 if err != nil { 1687 fmt.Println(err) 1688 return 1689 } 1690 ``` 1691 1692 <a name="RemoveObjectTaggingWithContext"></a> 1693 ### RemoveObjectTaggingWithContext(ctx context.Context, bucketName, objectName string) error 1694 Identical to RemoveObjectTagging, but allows setting context to allow controlling context cancellations and timeouts. 1695 1696 __Parameters__ 1697 1698 1699 |Param |Type |Description | 1700 |:---|:---| :---| 1701 |`ctx` | _context.Context_ |Request context | 1702 |`bucketName` | _string_ |Name of the bucket | 1703 |`objectName` | _string_ |Name of the object | 1704 1705 __Example__ 1706 1707 1708 ```go 1709 err = minioClient.RemoveObjectTaggingWithContext(ctx, bucketName, objectName) 1710 if err != nil { 1711 fmt.Println(err) 1712 return 1713 } 1714 ``` 1715 1716 <a name="RemoveIncompleteUpload"></a> 1717 ### RemoveIncompleteUpload(bucketName, objectName string) error 1718 Removes a partially uploaded object. 1719 1720 __Parameters__ 1721 1722 1723 |Param |Type |Description | 1724 |:---|:---| :---| 1725 |`bucketName` | _string_ |Name of the bucket | 1726 |`objectName` | _string_ |Name of the object | 1727 1728 __Example__ 1729 1730 1731 ```go 1732 err = minioClient.RemoveIncompleteUpload("mybucket", "myobject") 1733 if err != nil { 1734 fmt.Println(err) 1735 return 1736 } 1737 ``` 1738 1739 ## 5. Presigned operations 1740 1741 <a name="PresignedGetObject"></a> 1742 ### PresignedGetObject(bucketName, objectName string, expiry time.Duration, reqParams url.Values) (*url.URL, error) 1743 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. 1744 1745 __Parameters__ 1746 1747 1748 |Param |Type |Description | 1749 |:---|:---| :---| 1750 |`bucketName` | _string_ |Name of the bucket | 1751 |`objectName` | _string_ |Name of the object | 1752 |`expiry` | _time.Duration_ |Expiry of presigned URL in seconds | 1753 |`reqParams` | _url.Values_ |Additional response header overrides supports _response-expires_, _response-content-type_, _response-cache-control_, _response-content-disposition_. | 1754 1755 1756 __Example__ 1757 1758 1759 ```go 1760 // Set request parameters for content-disposition. 1761 reqParams := make(url.Values) 1762 reqParams.Set("response-content-disposition", "attachment; filename=\"your-filename.txt\"") 1763 1764 // Generates a presigned url which expires in a day. 1765 presignedURL, err := minioClient.PresignedGetObject("mybucket", "myobject", time.Second * 24 * 60 * 60, reqParams) 1766 if err != nil { 1767 fmt.Println(err) 1768 return 1769 } 1770 fmt.Println("Successfully generated presigned URL", presignedURL) 1771 ``` 1772 1773 <a name="PresignedPutObject"></a> 1774 ### PresignedPutObject(bucketName, objectName string, expiry time.Duration) (*url.URL, error) 1775 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. 1776 1777 NOTE: you can upload to S3 only with specified object name. 1778 1779 __Parameters__ 1780 1781 1782 |Param |Type |Description | 1783 |:---|:---| :---| 1784 |`bucketName` | _string_ |Name of the bucket | 1785 |`objectName` | _string_ |Name of the object | 1786 |`expiry` | _time.Duration_ |Expiry of presigned URL in seconds | 1787 1788 1789 __Example__ 1790 1791 1792 ```go 1793 // Generates a url which expires in a day. 1794 expiry := time.Second * 24 * 60 * 60 // 1 day. 1795 presignedURL, err := minioClient.PresignedPutObject("mybucket", "myobject", expiry) 1796 if err != nil { 1797 fmt.Println(err) 1798 return 1799 } 1800 fmt.Println("Successfully generated presigned URL", presignedURL) 1801 ``` 1802 1803 <a name="PresignedHeadObject"></a> 1804 ### PresignedHeadObject(bucketName, objectName string, expiry time.Duration, reqParams url.Values) (*url.URL, error) 1805 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. 1806 1807 __Parameters__ 1808 1809 |Param |Type |Description | 1810 |:---|:---| :---| 1811 |`bucketName` | _string_ |Name of the bucket | 1812 |`objectName` | _string_ |Name of the object | 1813 |`expiry` | _time.Duration_ |Expiry of presigned URL in seconds | 1814 |`reqParams` | _url.Values_ |Additional response header overrides supports _response-expires_, _response-content-type_, _response-cache-control_, _response-content-disposition_. | 1815 1816 1817 __Example__ 1818 1819 1820 ```go 1821 // Set request parameters for content-disposition. 1822 reqParams := make(url.Values) 1823 reqParams.Set("response-content-disposition", "attachment; filename=\"your-filename.txt\"") 1824 1825 // Generates a presigned url which expires in a day. 1826 presignedURL, err := minioClient.PresignedHeadObject("mybucket", "myobject", time.Second * 24 * 60 * 60, reqParams) 1827 if err != nil { 1828 fmt.Println(err) 1829 return 1830 } 1831 fmt.Println("Successfully generated presigned URL", presignedURL) 1832 ``` 1833 1834 <a name="PresignedPostPolicy"></a> 1835 ### PresignedPostPolicy(PostPolicy) (*url.URL, map[string]string, error) 1836 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. 1837 1838 ```go 1839 // Initialize policy condition config. 1840 policy := minio.NewPostPolicy() 1841 1842 // Apply upload policy restrictions: 1843 policy.SetBucket("mybucket") 1844 policy.SetKey("myobject") 1845 policy.SetExpires(time.Now().UTC().AddDate(0, 0, 10)) // expires in 10 days 1846 1847 // Only allow 'png' images. 1848 policy.SetContentType("image/png") 1849 1850 // Only allow content size in range 1KB to 1MB. 1851 policy.SetContentLengthRange(1024, 1024*1024) 1852 1853 // Add a user metadata using the key "custom" and value "user" 1854 policy.SetUserMetadata("custom", "user") 1855 1856 // Get the POST form key/value object: 1857 url, formData, err := minioClient.PresignedPostPolicy(policy) 1858 if err != nil { 1859 fmt.Println(err) 1860 return 1861 } 1862 1863 // POST your content from the command line using `curl` 1864 fmt.Printf("curl ") 1865 for k, v := range formData { 1866 fmt.Printf("-F %s=%s ", k, v) 1867 } 1868 fmt.Printf("-F file=@/etc/bash.bashrc ") 1869 fmt.Printf("%s\n", url) 1870 ``` 1871 1872 ## 6. Bucket policy/notification operations 1873 1874 <a name="SetBucketPolicy"></a> 1875 ### SetBucketPolicy(bucketname, policy string) error 1876 Set access permissions on bucket or an object prefix. 1877 1878 __Parameters__ 1879 1880 |Param |Type |Description | 1881 |:---|:---| :---| 1882 |`bucketName` | _string_ |Name of the bucket| 1883 |`policy` | _string_ |Policy to be set | 1884 1885 __Return Values__ 1886 1887 |Param |Type |Description | 1888 |:---|:---| :---| 1889 |`err` | _error_ |Standard Error | 1890 1891 __Example__ 1892 1893 ```go 1894 policy := `{"Version": "2012-10-17","Statement": [{"Action": ["s3:GetObject"],"Effect": "Allow","Principal": {"AWS": ["*"]},"Resource": ["arn:aws:s3:::my-bucketname/*"],"Sid": ""}]}` 1895 1896 err = minioClient.SetBucketPolicy("my-bucketname", policy) 1897 if err != nil { 1898 fmt.Println(err) 1899 return 1900 } 1901 ``` 1902 1903 <a name="GetBucketPolicy"></a> 1904 ### GetBucketPolicy(bucketName) (policy string, error) 1905 Get access permissions on a bucket or a prefix. 1906 1907 __Parameters__ 1908 1909 1910 |Param |Type |Description | 1911 |:---|:---| :---| 1912 |`bucketName` | _string_ |Name of the bucket | 1913 1914 __Return Values__ 1915 1916 1917 |Param |Type |Description | 1918 |:---|:---| :---| 1919 |`policy` | _string_ |Policy returned from the server | 1920 |`err` | _error_ |Standard Error | 1921 1922 __Example__ 1923 1924 ```go 1925 policy, err := minioClient.GetBucketPolicy("my-bucketname") 1926 if err != nil { 1927 log.Fatalln(err) 1928 } 1929 ``` 1930 1931 <a name="GetBucketNotification"></a> 1932 ### GetBucketNotification(bucketName string) (BucketNotification, error) 1933 Get notification configuration on a bucket. 1934 1935 __Parameters__ 1936 1937 1938 |Param |Type |Description | 1939 |:---|:---| :---| 1940 |`bucketName` | _string_ |Name of the bucket | 1941 1942 __Return Values__ 1943 1944 1945 |Param |Type |Description | 1946 |:---|:---| :---| 1947 |`bucketNotification` | _minio.BucketNotification_ |structure which holds all notification configurations| 1948 |`err` | _error_ |Standard Error | 1949 1950 __Example__ 1951 1952 1953 ```go 1954 bucketNotification, err := minioClient.GetBucketNotification("mybucket") 1955 if err != nil { 1956 fmt.Println("Failed to get bucket notification configurations for mybucket", err) 1957 return 1958 } 1959 1960 for _, queueConfig := range bucketNotification.QueueConfigs { 1961 for _, e := range queueConfig.Events { 1962 fmt.Println(e + " event is enabled") 1963 } 1964 } 1965 ``` 1966 1967 <a name="SetBucketNotification"></a> 1968 ### SetBucketNotification(bucketName string, bucketNotification BucketNotification) error 1969 Set a new bucket notification on a bucket. 1970 1971 __Parameters__ 1972 1973 1974 |Param |Type |Description | 1975 |:---|:---| :---| 1976 |`bucketName` | _string_ |Name of the bucket | 1977 |`bucketNotification` | _minio.BucketNotification_ |Represents the XML to be sent to the configured web service | 1978 1979 __Return Values__ 1980 1981 1982 |Param |Type |Description | 1983 |:---|:---| :---| 1984 |`err` | _error_ |Standard Error | 1985 1986 __Example__ 1987 1988 1989 ```go 1990 queueArn := minio.NewArn("aws", "sqs", "us-east-1", "804605494417", "PhotoUpdate") 1991 1992 queueConfig := minio.NewNotificationConfig(queueArn) 1993 queueConfig.AddEvents(minio.ObjectCreatedAll, minio.ObjectRemovedAll) 1994 queueConfig.AddFilterPrefix("photos/") 1995 queueConfig.AddFilterSuffix(".jpg") 1996 1997 bucketNotification := minio.BucketNotification{} 1998 bucketNotification.AddQueue(queueConfig) 1999 2000 err = minioClient.SetBucketNotification("mybucket", bucketNotification) 2001 if err != nil { 2002 fmt.Println("Unable to set the bucket notification: ", err) 2003 return 2004 } 2005 ``` 2006 2007 <a name="RemoveAllBucketNotification"></a> 2008 ### RemoveAllBucketNotification(bucketName string) error 2009 Remove all configured bucket notifications on a bucket. 2010 2011 __Parameters__ 2012 2013 2014 |Param |Type |Description | 2015 |:---|:---| :---| 2016 |`bucketName` | _string_ |Name of the bucket | 2017 2018 __Return Values__ 2019 2020 2021 |Param |Type |Description | 2022 |:---|:---| :---| 2023 |`err` | _error_ |Standard Error | 2024 2025 __Example__ 2026 2027 2028 ```go 2029 err = minioClient.RemoveAllBucketNotification("mybucket") 2030 if err != nil { 2031 fmt.Println("Unable to remove bucket notifications.", err) 2032 return 2033 } 2034 ``` 2035 2036 <a name="ListenBucketNotification"></a> 2037 ### ListenBucketNotification(bucketName, prefix, suffix string, events []string, doneCh <-chan struct{}) <-chan NotificationInfo 2038 ListenBucketNotification API receives bucket notification events through the notification channel. The returned notification channel has two fields 'Records' and 'Err'. 2039 2040 - 'Records' holds the notifications received from the server. 2041 - 'Err' indicates any error while processing the received notifications. 2042 2043 NOTE: Notification channel is closed at the first occurrence of an error. 2044 2045 __Parameters__ 2046 2047 2048 |Param |Type |Description | 2049 |:---|:---| :---| 2050 |`bucketName` | _string_ | Bucket to listen notifications on | 2051 |`prefix` | _string_ | Object key prefix to filter notifications for | 2052 |`suffix` | _string_ | Object key suffix to filter notifications for | 2053 |`events` | _[]string_ | Enables notifications for specific event types | 2054 |`doneCh` | _chan struct{}_ | A message on this channel ends the ListenBucketNotification iterator | 2055 2056 __Return Values__ 2057 2058 |Param |Type |Description | 2059 |:---|:---| :---| 2060 |`notificationInfo` | _chan minio.NotificationInfo_ | Channel of bucket notifications | 2061 2062 __minio.NotificationInfo__ 2063 2064 |Field |Type |Description | 2065 |`notificationInfo.Records` | _[]minio.NotificationEvent_ | Collection of notification events | 2066 |`notificationInfo.Err` | _error_ | Carries any error occurred during the operation (Standard Error) | 2067 2068 2069 __Example__ 2070 2071 2072 ```go 2073 // Create a done channel to control 'ListenBucketNotification' go routine. 2074 doneCh := make(chan struct{}) 2075 2076 // Indicate a background go-routine to exit cleanly upon return. 2077 defer close(doneCh) 2078 2079 // Listen for bucket notifications on "mybucket" filtered by prefix, suffix and events. 2080 for notificationInfo := range minioClient.ListenBucketNotification("mybucket", "myprefix/", ".mysuffix", []string{ 2081 "s3:ObjectCreated:*", 2082 "s3:ObjectAccessed:*", 2083 "s3:ObjectRemoved:*", 2084 }, doneCh) { 2085 if notificationInfo.Err != nil { 2086 fmt.Println(notificationInfo.Err) 2087 } 2088 fmt.Println(notificationInfo) 2089 } 2090 ``` 2091 2092 <a name="SetBucketLifecycle"></a> 2093 ### SetBucketLifecycle(bucketname, lifecycle string) error 2094 Set lifecycle on bucket or an object prefix. 2095 2096 __Parameters__ 2097 2098 |Param |Type |Description | 2099 |:---|:---| :---| 2100 |`bucketName` | _string_ |Name of the bucket| 2101 |`lifecycle` | _string_ |Lifecycle to be set | 2102 2103 __Return Values__ 2104 2105 |Param |Type |Description | 2106 |:---|:---| :---| 2107 |`err` | _error_ |Standard Error | 2108 2109 __Example__ 2110 2111 ```go 2112 lifecycle := `<LifecycleConfiguration> 2113 <Rule> 2114 <ID>expire-bucket</ID> 2115 <Prefix></Prefix> 2116 <Status>Enabled</Status> 2117 <Expiration> 2118 <Days>365</Days> 2119 </Expiration> 2120 </Rule> 2121 </LifecycleConfiguration>` 2122 2123 err = minioClient.SetBucketLifecycle("my-bucketname", lifecycle) 2124 if err != nil { 2125 fmt.Println(err) 2126 return 2127 } 2128 ``` 2129 2130 <a name="GetBucketLifecycle"></a> 2131 ### GetBucketLifecycle(bucketName) (lifecycle string, error) 2132 Get lifecycle on a bucket or a prefix. 2133 2134 __Parameters__ 2135 2136 2137 |Param |Type |Description | 2138 |:---|:---| :---| 2139 |`bucketName` | _string_ |Name of the bucket | 2140 2141 __Return Values__ 2142 2143 2144 |Param |Type |Description | 2145 |:---|:---| :---| 2146 |`lifecycle` | _string_ |Lifecycle returned from the server | 2147 |`err` | _error_ |Standard Error | 2148 2149 __Example__ 2150 2151 ```go 2152 lifecycle, err := minioClient.GetBucketLifecycle("my-bucketname") 2153 if err != nil { 2154 log.Fatalln(err) 2155 } 2156 ``` 2157 2158 <a name="SetBucketEncryption"></a> 2159 ### SetBucketEncryption(bucketname string, configuration ServerSideEncryptionConfiguration) error 2160 Set default encryption configuration on a bucket. 2161 2162 __Parameters__ 2163 2164 |Param |Type |Description | 2165 |:---|:---| :---| 2166 |`bucketName` | _string_ |Name of the bucket| 2167 |`configuration` | _minio.ServerSideEncyrptionConfiguration_ | Structure that holds default encryption configuration to be set | 2168 2169 __Return Values__ 2170 2171 |Param |Type |Description | 2172 |:---|:---| :---| 2173 |`err` | _error_ |Standard Error | 2174 2175 __Example__ 2176 2177 ```go 2178 s3Client, err := minio.New("s3.amazonaws.com", "YOUR-ACCESSKEYID", "YOUR-SECRETACCESSKEY", true) 2179 if err != nil { 2180 log.Fatalln(err) 2181 } 2182 2183 // Initialize default encryption configuration structure 2184 config := minio.ServerSideEncryptionConfiguration{Rules: []minio.Rule{ 2185 minio.Rule{ 2186 Apply: minio.ApplyServerSideEncryptionByDefault{ 2187 SSEAlgorithm: "AES256", 2188 }, 2189 }, 2190 }} 2191 // Set default encryption configuration on an S3 bucket 2192 err = s3Client.SetBucketEncryption("my-bucketname", config) 2193 if err != nil { 2194 log.Fatalln(err) 2195 } 2196 ``` 2197 2198 <a name="GetBucketEncryption"></a> 2199 ### GetBucketEncryption(bucketName string) (ServerSideEncryptionConfiguration, error) 2200 Get default encryption configuration set on a bucket. 2201 2202 __Parameters__ 2203 2204 2205 |Param |Type |Description | 2206 |:---|:---| :---| 2207 |`bucketName` | _string_ |Name of the bucket | 2208 2209 __Return Values__ 2210 2211 2212 |Param |Type |Description | 2213 |:---|:---| :---| 2214 |`configuration` | _minio.ServerSideEncyrptionConfiguration_ | Structure that holds default encryption configuration | 2215 |`err` | _error_ |Standard Error | 2216 2217 __Example__ 2218 2219 ```go 2220 s3Client, err := minio.New("s3.amazonaws.com", "YOUR-ACCESSKEYID", "YOUR-SECRETACCESSKEY", true) 2221 if err != nil { 2222 log.Fatalln(err) 2223 } 2224 2225 // Get default encryption configuration set on an S3 bucket and print it out 2226 encryptionConfig, err := s3Client.GetBucketEncryption("my-bucketname") 2227 if err != nil { 2228 log.Fatalln(err) 2229 } 2230 fmt.Printf("%+v\n", encryptionConfig) 2231 ``` 2232 2233 <a name="DeleteBucketEncryption"></a> 2234 ### DeleteBucketEncryption(bucketName string) (error) 2235 Delete/Remove default encryption configuration set on a bucket. 2236 2237 __Parameters__ 2238 2239 2240 |Param |Type |Description | 2241 |:---|:---|:---| 2242 |`bucketName` | _string_ |Name of the bucket | 2243 2244 __Return Values__ 2245 2246 2247 |Param |Type |Description | 2248 |:---|:---| :---| 2249 |`err` | _error_ |Standard Error | 2250 2251 __Example__ 2252 2253 ```go 2254 err := s3Client.DeleteBucketEncryption("my-bucketname") 2255 if err != nil { 2256 log.Fatalln(err) 2257 } 2258 // "my-bucket" is successfully deleted/removed. 2259 ``` 2260 2261 <a name="SetObjectLockConfig"></a> 2262 ### SetObjectLockConfig(bucketname, mode *RetentionMode, validity *uint, unit *ValidityUnit) error 2263 Set object lock configuration in given bucket. mode, validity and unit are either all set or all nil. 2264 2265 __Parameters__ 2266 2267 |Param |Type |Description | 2268 |:---|:---| :---| 2269 |`bucketName` | _string_ |Name of the bucket| 2270 |`mode` | _RetentionMode_ |Retention mode to be set | 2271 |`validity` | _uint_ |Validity period to be set | 2272 |`unit` | _ValidityUnit_ |Unit of validity period | 2273 2274 __Return Values__ 2275 2276 |Param |Type |Description | 2277 |:---|:---| :---| 2278 |`err` | _error_ |Standard Error | 2279 2280 __Example__ 2281 2282 ```go 2283 mode := Governance 2284 validity := uint(30) 2285 unit := Days 2286 2287 err = minioClient.SetObjectLockConfig("my-bucketname", &mode, &validity, &unit) 2288 if err != nil { 2289 fmt.Println(err) 2290 return 2291 } 2292 ``` 2293 2294 <a name="GetObjectLockConfig"></a> 2295 ### GetObjectLockConfig(bucketName) (objectLock,*RetentionMode, *uint, *ValidityUnit, error) 2296 Get object lock configuration of given bucket. 2297 2298 __Parameters__ 2299 2300 2301 |Param |Type |Description | 2302 |:---|:---| :---| 2303 |`bucketName` | _string_ |Name of the bucket | 2304 2305 __Return Values__ 2306 2307 2308 |Param |Type |Description | 2309 |:---|:---| :---| 2310 |`objectLock` | _objectLock_ |lock enabled status | 2311 |`mode` | _RetentionMode_ |Current retention mode | 2312 |`validity` | _uint_ |Current validity period | 2313 |`unit` | _ValidityUnit_ |Unit of validity period | 2314 |`err` | _error_ |Standard Error | 2315 2316 __Example__ 2317 2318 ```go 2319 enabled, mode, validity, unit, err := minioClient.GetObjectLockConfig("my-bucketname") 2320 if err != nil { 2321 log.Fatalln(err) 2322 } 2323 fmt.Println("object lock is %s for this bucket",enabled) 2324 if mode != nil { 2325 fmt.Printf("%v mode is enabled for %v %v for bucket 'my-bucketname'\n", *mode, *validity, *unit) 2326 } else { 2327 fmt.Println("No mode is enabled for bucket 'my-bucketname'") 2328 } 2329 ``` 2330 2331 <a name="EnableVersioning"></a> 2332 ### EnableVersioning(bucketName) error 2333 Enable bucket versioning support. 2334 2335 __Parameters__ 2336 2337 2338 |Param |Type |Description | 2339 |:---|:---| :---| 2340 |`bucketName` | _string_ |Name of the bucket | 2341 2342 __Return Values__ 2343 2344 2345 |Param |Type |Description | 2346 |:---|:---| :---| 2347 |`err` | _error_ |Standard Error | 2348 2349 __Example__ 2350 2351 ```go 2352 err := minioClient.EnableVersioning("my-bucketname") 2353 if err != nil { 2354 log.Fatalln(err) 2355 } 2356 2357 fmt.Println("versioning enabled for bucket 'my-bucketname'") 2358 ``` 2359 2360 <a name="DisableVersioning"></a> 2361 ### DisableVersioning(bucketName) error 2362 Disable bucket versioning support. 2363 2364 __Parameters__ 2365 2366 2367 |Param |Type |Description | 2368 |:---|:---| :---| 2369 |`bucketName` | _string_ |Name of the bucket | 2370 2371 __Return Values__ 2372 2373 2374 |Param |Type |Description | 2375 |:---|:---| :---| 2376 |`err` | _error_ |Standard Error | 2377 2378 __Example__ 2379 2380 ```go 2381 err := minioClient.DisableVersioning("my-bucketname") 2382 if err != nil { 2383 log.Fatalln(err) 2384 } 2385 2386 fmt.Println("versioning disabled for bucket 'my-bucketname'") 2387 ``` 2388 2389 <a name="GetBucketVersioning"></a> 2390 ### GetBucketVersioning(bucketName string) (BucketVersioningConfiguration, error) 2391 Get versioning configuration set on a bucket. 2392 2393 __Parameters__ 2394 2395 2396 |Param |Type |Description | 2397 |:---|:---| :---| 2398 |`bucketName` | _string_ |Name of the bucket | 2399 2400 __Return Values__ 2401 2402 2403 |Param |Type |Description | 2404 |:---|:---| :---| 2405 |`configuration` | _minio.BucketVersioningConfiguration_ | Structure that holds versioning configuration | 2406 |`err` | _error_ |Standard Error | 2407 2408 __Example__ 2409 2410 ```go 2411 s3Client, err := minio.New("s3.amazonaws.com", "YOUR-ACCESSKEYID", "YOUR-SECRETACCESSKEY", true) 2412 if err != nil { 2413 log.Fatalln(err) 2414 } 2415 2416 // Get versioning configuration set on an S3 bucket and print it out 2417 versioningConfig, err := s3Client.GetBucketVersioning("my-bucketname") 2418 if err != nil { 2419 log.Fatalln(err) 2420 } 2421 fmt.Printf("%+v\n", versioningConfig) 2422 ``` 2423 2424 ## 7. Client custom settings 2425 2426 <a name="SetAppInfo"></a> 2427 ### SetAppInfo(appName, appVersion string) 2428 Add custom application details to User-Agent. 2429 2430 __Parameters__ 2431 2432 | Param | Type | Description | 2433 |---|---|---| 2434 |`appName` | _string_ | Name of the application performing the API requests. | 2435 | `appVersion`| _string_ | Version of the application performing the API requests. | 2436 2437 2438 __Example__ 2439 2440 2441 ```go 2442 // Set Application name and version to be used in subsequent API requests. 2443 minioClient.SetAppInfo("myCloudApp", "1.0.0") 2444 ``` 2445 2446 <a name="SetCustomTransport"></a> 2447 ### SetCustomTransport(customHTTPTransport http.RoundTripper) 2448 Overrides default HTTP transport. This is usually needed for debugging or for adding custom TLS certificates. 2449 2450 __Parameters__ 2451 2452 | Param | Type | Description | 2453 |---|---|---| 2454 |`customHTTPTransport` | _http.RoundTripper_ | Custom transport e.g, to trace API requests and responses for debugging purposes.| 2455 2456 2457 <a name="TraceOn"></a> 2458 ### TraceOn(outputStream io.Writer) 2459 Enables HTTP tracing. The trace is written to the io.Writer provided. If outputStream is nil, trace is written to os.Stdout. 2460 2461 __Parameters__ 2462 2463 | Param | Type | Description | 2464 |---|---|---| 2465 |`outputStream` | _io.Writer_ | HTTP trace is written into outputStream.| 2466 2467 2468 <a name="TraceOff"></a> 2469 ### TraceOff() 2470 Disables HTTP tracing. 2471 2472 <a name="SetS3TransferAccelerate"></a> 2473 ### SetS3TransferAccelerate(acceleratedEndpoint string) 2474 Set AWS S3 transfer acceleration endpoint for all API requests hereafter. 2475 NOTE: This API applies only to AWS S3 and is a no operation for S3 compatible object storage services. 2476 2477 __Parameters__ 2478 2479 | Param | Type | Description | 2480 |---|---|---| 2481 |`acceleratedEndpoint` | _string_ | Set to new S3 transfer acceleration endpoint.|