From e0b68385002c0f63d5ea17f94eacc9043acdef24 Mon Sep 17 00:00:00 2001 From: Andrea Longo Date: Thu, 2 Nov 2023 09:30:58 -0600 Subject: [PATCH] Update the Go Quickstart README (#1896) * Update the Go Quickstart README to clarify a few steps and make the example easier to follow. --- README.md | 118 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 91 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 1aa85a188..82f70a131 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,28 @@ # MinIO Go Client SDK for Amazon S3 Compatible Cloud Storage [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) [![Sourcegraph](https://sourcegraph.com/github.com/minio/minio-go/-/badge.svg)](https://sourcegraph.com/github.com/minio/minio-go?badge) [![Apache V2 License](https://img.shields.io/badge/license-Apache%20V2-blue.svg)](https://github.com/minio/minio-go/blob/master/LICENSE) -The MinIO Go Client SDK provides simple APIs to access any Amazon S3 compatible object storage. +The MinIO Go Client SDK provides straightforward APIs to access any Amazon S3 compatible object storage. -This quickstart guide will show you how to install the MinIO client SDK, connect to MinIO, and provide a walkthrough for a simple file uploader. -For a complete list of APIs and examples, please take a look at the [godoc documentation](https://pkg.go.dev/github.com/minio/minio-go/v7) or [Go Client API Reference](https://min.io/docs/minio/linux/developers/go/API.html). +This Quickstart Guide covers how to install the MinIO client SDK, connect to MinIO, and create a sample file uploader. +For a complete list of APIs and examples, see the [godoc documentation](https://pkg.go.dev/github.com/minio/minio-go/v7) or [Go Client API Reference](https://min.io/docs/minio/linux/developers/go/API.html). -This document assumes that you have a working [Go development environment](https://golang.org/doc/install). +These examples presume a working [Go development environment](https://golang.org/doc/install) and the [MinIO `mc` command line tool](https://min.io/docs/minio/linux/reference/minio-mc.html). ## Download from Github + +From your project directory: + ```sh go get github.com/minio/minio-go/v7 ``` -## Initialize MinIO Client -MinIO client requires the following four parameters specified to connect to an Amazon S3 compatible object storage. +## Initialize a MinIO Client Object + +The MinIO client requires the following parameters to connect to an Amazon S3 compatible object storage: -| Parameter | Description| -| :--- | :--- | -| endpoint | URL to object storage service. | -| _minio.Options_ | All the options such as credentials, custom transport etc. | +| Parameter | Description | +| ----------------- | ---------------------------------------------------------- | +| `endpoint` | URL to object storage service. | +| `_minio.Options_` | All the options such as credentials, custom transport etc. | ```go package main @@ -49,13 +53,25 @@ func main() { } ``` -## Quick Start Example - File Uploader -This example program connects to an object storage server, creates a bucket and uploads a file to the bucket. +## Example - File Uploader -We will use the MinIO server running at [https://play.min.io](https://play.min.io) in this example. Feel free to use this service for testing and development. Access credentials shown in this example are open to the public. +This sample code connects to an object storage server, creates a bucket, and uploads a file to the bucket. +It uses the MinIO `play` server, a public MinIO cluster located at [https://play.min.io](https://play.min.io). + +The `play` server runs the latest stable version of MinIO and may be used for testing and development. +The access credentials shown in this example are open to the public and all data uploaded to `play` should be considered public and non-protected. ### FileUploader.go + +This example does the following: + +- Connects to the MinIO `play` server using the provided credentials. +- Creates a bucket named `testbucket`. +- Uploads a file named `testdata` from `/tmp`. +- Verifies the file was created using `mc ls`. + ```go +// FileUploader.go MinIO example package main import ( @@ -82,8 +98,8 @@ func main() { log.Fatalln(err) } - // Make a new bucket called mymusic. - bucketName := "mymusic" + // Make a new bucket called testbucket. + bucketName := "testbucket" location := "us-east-1" err = minioClient.MakeBucket(ctx, bucketName, minio.MakeBucketOptions{Region: location}) @@ -99,12 +115,13 @@ func main() { log.Printf("Successfully created %s\n", bucketName) } - // Upload the zip file - objectName := "golden-oldies.zip" - filePath := "/tmp/golden-oldies.zip" - contentType := "application/zip" + // Upload the test file + // Change the value of filePath if the file is in another location + objectName := "testdata" + filePath := "/tmp/testdata" + contentType := "application/octet-stream" - // Upload the zip file with FPutObject + // Upload the test file with FPutObject info, err := minioClient.FPutObject(ctx, bucketName, objectName, filePath, minio.PutObjectOptions{ContentType: contentType}) if err != nil { log.Fatalln(err) @@ -114,22 +131,51 @@ func main() { } ``` -### Run FileUploader +**1. Create a test file containing data:** + +You can do this with `dd` on Linux or macOS systems: + +```sh +dd if=/dev/urandom of=/tmp/testdata bs=2048 count=10 +``` + +or `fsutil` on Windows: + +```sh +fsutil file createnew "C:\Users\\Desktop\sample.txt" 20480 +``` + +**2. Run FileUploader with the following commands:** + ```sh -go run file-uploader.go -2016/08/13 17:03:28 Successfully created mymusic -2016/08/13 17:03:40 Successfully uploaded golden-oldies.zip of size 16253413 +go mod init example/FileUploader +go get github.com/minio/minio-go/v7 +go get github.com/minio/minio-go/v7/pkg/credentials +go run FileUploader.go +``` + +The output resembles the following: -mc ls play/mymusic/ -[2016-05-27 16:02:16 PDT] 17MiB golden-oldies.zip +```sh +2023/11/01 14:27:55 Successfully created testbucket +2023/11/01 14:27:55 Successfully uploaded testdata of size 20480 +``` + +**3. Verify the Uploaded File With `mc ls`:** + +```sh +mc ls play/testbucket +[2023-11-01 14:27:55 UTC] 20KiB STANDARD TestDataFile ``` ## API Reference + The full API Reference is available here. * [Complete API Reference](https://min.io/docs/minio/linux/developers/go/API.html) ### API Reference : Bucket Operations + * [`MakeBucket`](https://min.io/docs/minio/linux/developers/go/API.html#MakeBucket) * [`ListBuckets`](https://min.io/docs/minio/linux/developers/go/API.html#ListBuckets) * [`BucketExists`](https://min.io/docs/minio/linux/developers/go/API.html#BucketExists) @@ -138,10 +184,12 @@ The full API Reference is available here. * [`ListIncompleteUploads`](https://min.io/docs/minio/linux/developers/go/API.html#ListIncompleteUploads) ### API Reference : Bucket policy Operations + * [`SetBucketPolicy`](https://min.io/docs/minio/linux/developers/go/API.html#SetBucketPolicy) * [`GetBucketPolicy`](https://min.io/docs/minio/linux/developers/go/API.html#GetBucketPolicy) ### API Reference : Bucket notification Operations + * [`SetBucketNotification`](https://min.io/docs/minio/linux/developers/go/API.html#SetBucketNotification) * [`GetBucketNotification`](https://min.io/docs/minio/linux/developers/go/API.html#GetBucketNotification) * [`RemoveAllBucketNotification`](https://min.io/docs/minio/linux/developers/go/API.html#RemoveAllBucketNotification) @@ -149,10 +197,12 @@ The full API Reference is available here. * [`ListenNotification`](https://min.io/docs/minio/linux/developers/go/API.html#ListenNotification) (MinIO Extension) ### API Reference : File Object Operations + * [`FPutObject`](https://min.io/docs/minio/linux/developers/go/API.html#FPutObject) * [`FGetObject`](https://min.io/docs/minio/linux/developers/go/API.html#FGetObject) ### API Reference : Object Operations + * [`GetObject`](https://min.io/docs/minio/linux/developers/go/API.html#GetObject) * [`PutObject`](https://min.io/docs/minio/linux/developers/go/API.html#PutObject) * [`PutObjectStreaming`](https://min.io/docs/minio/linux/developers/go/API.html#PutObjectStreaming) @@ -163,14 +213,15 @@ The full API Reference is available here. * [`RemoveIncompleteUpload`](https://min.io/docs/minio/linux/developers/go/API.html#RemoveIncompleteUpload) * [`SelectObjectContent`](https://min.io/docs/minio/linux/developers/go/API.html#SelectObjectContent) - ### API Reference : Presigned Operations + * [`PresignedGetObject`](https://min.io/docs/minio/linux/developers/go/API.html#PresignedGetObject) * [`PresignedPutObject`](https://min.io/docs/minio/linux/developers/go/API.html#PresignedPutObject) * [`PresignedHeadObject`](https://min.io/docs/minio/linux/developers/go/API.html#PresignedHeadObject) * [`PresignedPostPolicy`](https://min.io/docs/minio/linux/developers/go/API.html#PresignedPostPolicy) ### API Reference : Client custom settings + * [`SetAppInfo`](https://min.io/docs/minio/linux/developers/go/API.html#SetAppInfo) * [`TraceOn`](https://min.io/docs/minio/linux/developers/go/API.html#TraceOn) * [`TraceOff`](https://min.io/docs/minio/linux/developers/go/API.html#TraceOff) @@ -178,6 +229,7 @@ The full API Reference is available here. ## Full Examples ### Full Examples : Bucket Operations + * [makebucket.go](https://github.com/minio/minio-go/blob/master/examples/s3/makebucket.go) * [listbuckets.go](https://github.com/minio/minio-go/blob/master/examples/s3/listbuckets.go) * [bucketexists.go](https://github.com/minio/minio-go/blob/master/examples/s3/bucketexists.go) @@ -187,25 +239,30 @@ The full API Reference is available here. * [listincompleteuploads.go](https://github.com/minio/minio-go/blob/master/examples/s3/listincompleteuploads.go) ### Full Examples : Bucket policy Operations + * [setbucketpolicy.go](https://github.com/minio/minio-go/blob/master/examples/s3/setbucketpolicy.go) * [getbucketpolicy.go](https://github.com/minio/minio-go/blob/master/examples/s3/getbucketpolicy.go) * [listbucketpolicies.go](https://github.com/minio/minio-go/blob/master/examples/s3/listbucketpolicies.go) ### Full Examples : Bucket lifecycle Operations + * [setbucketlifecycle.go](https://github.com/minio/minio-go/blob/master/examples/s3/setbucketlifecycle.go) * [getbucketlifecycle.go](https://github.com/minio/minio-go/blob/master/examples/s3/getbucketlifecycle.go) ### Full Examples : Bucket encryption Operations + * [setbucketencryption.go](https://github.com/minio/minio-go/blob/master/examples/s3/setbucketencryption.go) * [getbucketencryption.go](https://github.com/minio/minio-go/blob/master/examples/s3/getbucketencryption.go) * [deletebucketencryption.go](https://github.com/minio/minio-go/blob/master/examples/s3/deletebucketencryption.go) ### Full Examples : Bucket replication Operations + * [setbucketreplication.go](https://github.com/minio/minio-go/blob/master/examples/s3/setbucketreplication.go) * [getbucketreplication.go](https://github.com/minio/minio-go/blob/master/examples/s3/getbucketreplication.go) * [removebucketreplication.go](https://github.com/minio/minio-go/blob/master/examples/s3/removebucketreplication.go) ### Full Examples : Bucket notification Operations + * [setbucketnotification.go](https://github.com/minio/minio-go/blob/master/examples/s3/setbucketnotification.go) * [getbucketnotification.go](https://github.com/minio/minio-go/blob/master/examples/s3/getbucketnotification.go) * [removeallbucketnotification.go](https://github.com/minio/minio-go/blob/master/examples/s3/removeallbucketnotification.go) @@ -213,10 +270,12 @@ The full API Reference is available here. * [listennotification.go](https://github.com/minio/minio-go/blob/master/examples/minio/listen-notification.go) (MinIO Extension) ### Full Examples : File Object Operations + * [fputobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/fputobject.go) * [fgetobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/fgetobject.go) ### Full Examples : Object Operations + * [putobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/putobject.go) * [getobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/getobject.go) * [statobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/statobject.go) @@ -226,23 +285,28 @@ The full API Reference is available here. * [removeobjects.go](https://github.com/minio/minio-go/blob/master/examples/s3/removeobjects.go) ### Full Examples : Encrypted Object Operations + * [put-encrypted-object.go](https://github.com/minio/minio-go/blob/master/examples/s3/put-encrypted-object.go) * [get-encrypted-object.go](https://github.com/minio/minio-go/blob/master/examples/s3/get-encrypted-object.go) * [fput-encrypted-object.go](https://github.com/minio/minio-go/blob/master/examples/s3/fputencrypted-object.go) ### Full Examples : Presigned Operations + * [presignedgetobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/presignedgetobject.go) * [presignedputobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/presignedputobject.go) * [presignedheadobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/presignedheadobject.go) * [presignedpostpolicy.go](https://github.com/minio/minio-go/blob/master/examples/s3/presignedpostpolicy.go) ## Explore Further + * [Godoc Documentation](https://pkg.go.dev/github.com/minio/minio-go/v7) * [Complete Documentation](https://min.io/docs/minio/kubernetes/upstream/index.html) * [MinIO Go Client SDK API Reference](https://min.io/docs/minio/linux/developers/go/API.html) ## Contribute + [Contributors Guide](https://github.com/minio/minio-go/blob/master/CONTRIBUTING.md) ## License + This SDK is distributed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0), see [LICENSE](https://github.com/minio/minio-go/blob/master/LICENSE) and [NOTICE](https://github.com/minio/minio-go/blob/master/NOTICE) for more information.