github.com/aavshr/aws-sdk-go@v1.41.3/example/service/s3/presignURL/README.md (about)

     1  # Presigned Amazon S3 API Operation Example
     2  
     3  This example demonstrates how you can build a client application to retrieve and
     4  upload object data from Amazon S3 without needing to know anything about Amazon
     5  S3 or have access to any AWS credentials. Only the service would have knowledge
     6  of how and where the objects are stored in Amazon S3.
     7  
     8  The example is split into two parts `server.go` and `client.go`. These two parts
     9  simulate the client/server architecture. In this example the client will represent
    10  a third part user that will request resource URLs from the service. The service
    11  will generate presigned S3 URLs which the client can use to download and
    12  upload S3 object content.
    13  
    14  The service supports generating presigned URLs for two S3 APIs; `GetObject` and
    15  `PutObject`. The client will request a presigned URL from the service with an
    16  object Key. In this example the value is the S3 object's `key`. Alternatively,
    17  you could use your own pattern with no visible relation to the S3 object's key.
    18  The server would then perform a cross reference with client provided value to
    19  one that maps to the S3 object's key.
    20  
    21  Before using the client to upload and download S3 objects you'll need to start the
    22  service. The service will use the SDK's default credential chain to source your
    23  AWS credentials. See the [`Configuring Credentials`](http://docs.aws.amazon.com/sdk-for-go/api/)
    24  section of the SDK's API Reference guide on how the SDK loads your AWS credentials.
    25  
    26  The server requires the S3 `-b bucket` the presigned URLs will be generated for. A
    27  `-r region` is only needed if the bucket is in AWS China or AWS Gov Cloud. For
    28  buckets in AWS the server will use the [`s3manager.GetBucketRegion`](http://docs.aws.amazon.com/sdk-for-go/api/service/s3/s3manager/#GetBucketRegion) utility to lookup the bucket's region.
    29  
    30  You should run the service in the background or in a separate terminal tab before
    31  moving onto the client.
    32  
    33  
    34  ```sh
    35  go run -tags example server/server.go -b mybucket
    36  > Starting Server On: 127.0.0.1:8080
    37  ```
    38  
    39  Use the `--help` flag to see a list of additional configuration flags, and their
    40  defaults.
    41  
    42  ## Downloading an Amazon S3 Object
    43  
    44  Use the client application to request a presigned URL from the server and use
    45  that presigned URL to download the object from S3. Calling the client with the
    46  `-get key` flag will do this. An optional `-f filename` flag can be provided as
    47  well to write the object to. If no flag is provided the object will be written
    48  to `stdout`
    49  
    50  ```sh
    51  go run -tags example client/client.go -get "my-object/key" -f outputfilename
    52  ```
    53  
    54  Use the `--help` flag to see a list of additional configuration flags, and their
    55  defaults.
    56  
    57  The following curl request demonstrates the request the client makes to the server
    58  for the presigned URL for the `my-object/key` S3 object. The `method` query
    59  parameter lets the server know that we are requesting the `GetObject`'s presigned
    60  URL. The `method` value can be `GET` or `PUT` for the `GetObject` or `PutObject` APIs.
    61  
    62  ```sh
    63  curl -v "http://127.0.0.1:8080/presign/my-object/key?method=GET"
    64  ```
    65  
    66  The server will respond with a JSON value. The value contains three pieces of
    67  information that the client will need to correctly make the request. First is
    68  the presigned URL. This is the URL the client will make the request to. Second
    69  is the HTTP method the request should be sent as. This is included to simplify
    70  the client's request building. Finally the response will include a list of
    71  additional headers that the client should include that the presigned request
    72  was signed with.
    73  
    74  ```json
    75  {
    76  	"URL": "https://mybucket.s3-us-west-2.amazonaws.com/my-object/key?<signature>",
    77  	"Method": "GET",
    78  	"Header": {
    79  		"x-amz-content-sha256":["UNSIGNED-PAYLOAD"]
    80  	}
    81  }
    82  ```
    83  
    84  With this URL our client will build a HTTP request for the S3 object's data. The
    85  `client.go` will then write the object's data to the `filename` if one is provided,
    86  or to `stdout` of a filename is not set in the command line arguments.
    87  
    88  ## Uploading a File to Amazon S3
    89  
    90  Just like the download, uploading a file to S3 will use a presigned URL requested
    91  from the server. The resigned URL will be built into an HTTP request using the
    92  URL, Method, and Headers. The `-put key` flag will upload the content of `-f filename`
    93  or stdin if no filename is provided to S3 using a presigned URL provided by the
    94  service
    95  
    96  ```sh
    97  go run -tags example client/client.go -put "my-object/key" -f filename
    98  ```
    99  
   100  Like the download case this will make a HTTP request to the server for the
   101  presigned URL. The Server will respond with a presigned URL for S3's `PutObject`
   102  API operation. In addition the `method` query parameter the client will also
   103  include a `contentLength` this value instructs the server to generate the presigned
   104  PutObject request with a `Content-Length` header value included in the signature.
   105  This is done so the content that is uploaded by the client can only be the size
   106  the presigned request was generated for.
   107  
   108  ```sh
   109  curl -v "http://127.0.0.1:8080/presign/my-object/key?method=PUT&contentLength=1024"
   110  ```
   111  
   112  ## Expanding the Example
   113  
   114  This example provides a spring board you can use to vend presigned URLs to your
   115  clients instead of streaming the object's content through your service. This
   116  client and server example can be expanded and customized. Adding new functionality
   117  such as additional constraints the server puts on the presigned URLs like
   118  `Content-Type`.
   119  
   120  In addition to adding constraints to the presigned URLs the service could be
   121  updated to obfuscate S3 object's key. Instead of the client knowing the object's
   122  key, a lookup system could be used instead. This could be substitution based,
   123  or lookup into an external data store such as DynamoDB.
   124