• Home
  • History
  • Annotate
  • only in this directory
Name Date Size

..11-Jan-20224 KiB

.github/H11-Jan-20224 KiB

.gitignoreH A D11-Jan-2022204

.godoc_configH A D11-Jan-2022492

.travis.ymlH A D11-Jan-20221.3 KiB

aws/H11-Jan-20224 KiB

awsmigrate/awsmigrate-renamer/H11-Jan-20224 KiB

awstesting/H11-Jan-20224 KiB

buildspec.ymlH A D11-Jan-2022514

CHANGELOG.mdH A D11-Jan-2022534.6 KiB

CHANGELOG_PENDING.mdH A D11-Jan-202253

CODE_OF_CONDUCT.mdH A D11-Jan-2022309

CONTRIBUTING.mdH A D11-Jan-20225.1 KiB

doc.goH A D11-Jan-202218.7 KiB

example/H11-Jan-20224 KiB

go.modH A D11-Jan-2022109

go.sumH A D11-Jan-2022237

Gopkg.lockH A D11-Jan-2022452

Gopkg.tomlH A D11-Jan-20221.1 KiB

internal/H11-Jan-20224 KiB

LICENSE.txtH A D11-Jan-202211.1 KiB

MakefileH A D11-Jan-20228.4 KiB

models/H11-Jan-20224 KiB

NOTICE.txtH A D11-Jan-2022120

private/H11-Jan-20224 KiB

README.mdH A D11-Jan-202221.9 KiB

service/H11-Jan-202212 KiB

vendor/H11-Jan-20224 KiB

README.md

1[![API Reference](https://img.shields.io/badge/api-reference-blue.svg)](https://docs.aws.amazon.com/sdk-for-go/api) [![Join the chat at https://gitter.im/aws/aws-sdk-go](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/aws/aws-sdk-go?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Build Status](https://img.shields.io/travis/aws/aws-sdk-go.svg)](https://travis-ci.org/aws/aws-sdk-go) [![Apache V2 License](https://img.shields.io/badge/license-Apache%20V2-blue.svg)](https://github.com/aws/aws-sdk-go/blob/master/LICENSE.txt)
2
3# AWS SDK for Go
4
5aws-sdk-go is the official AWS SDK for the Go programming language.
6
7Checkout our [release notes](https://github.com/aws/aws-sdk-go/releases) for
8information about the latest bug fixes, updates, and features added to the SDK.
9
10We [announced](https://aws.amazon.com/blogs/developer/aws-sdk-for-go-2-0-developer-preview/) the Developer Preview for the [v2 AWS SDK for Go](https://github.com/aws/aws-sdk-go-v2). The v2 SDK source is available at https://github.com/aws/aws-sdk-go-v2, and add it to your project with `go get github.com/aws/aws-sdk-go-v2`. Check out the v2 SDK's [changes and updates](https://github.com/aws/aws-sdk-go-v2/blob/master/CHANGELOG.md), and let us know what you think. We want your feedback.
11
12We have a pilot redesign of the [AWS SDK for Go API reference documentation](https://docs.aws.amazon.com/sdk-for-go/v1/api/gosdk-apiref.html). Let us know what you think.
13
14## Installing
15
16Use `go get` to retrieve the SDK to add it to your `GOPATH` workspace, or
17project's Go module dependencies.
18
19	go get github.com/aws/aws-sdk-go
20
21To update the SDK use `go get -u` to retrieve the latest version of the SDK.
22
23	go get -u github.com/aws/aws-sdk-go
24
25### Dependencies
26
27The SDK includes a `vendor` folder containing the runtime dependencies of the
28SDK. The metadata of the SDK's dependencies can be found in the Go module file
29`go.mod` or Dep file `Gopkg.toml`.
30
31### Go Modules
32
33If you are using Go modules, your `go get` will default to the latest tagged
34release version of the SDK. To get a specific release version of the SDK use
35`@<tag>` in your `go get` command.
36
37	go get github.com/aws/aws-sdk-go@v1.15.77
38
39To get the latest SDK repository change use `@latest`.
40
41	go get github.com/aws/aws-sdk-go@latest
42
43### Go 1.5
44
45If you are using Go 1.5 without vendoring enabled, (`GO15VENDOREXPERIMENT=1`),
46you will need to use `...` when retrieving the SDK to get its dependencies.
47
48	go get github.com/aws/aws-sdk-go/...
49
50This will still include the `vendor` folder. The `vendor` folder can be deleted
51if not used by your environment.
52
53    rm -rf $GOPATH/src/github.com/aws/aws-sdk-go/vendor
54
55## Getting Help
56
57Please use these community resources for getting help. We use the GitHub issues
58for tracking bugs and feature requests.
59
60* Ask a question on [StackOverflow](http://stackoverflow.com/) and tag it with the [`aws-sdk-go`](http://stackoverflow.com/questions/tagged/aws-sdk-go) tag.
61* Come join the AWS SDK for Go community chat on [gitter](https://gitter.im/aws/aws-sdk-go).
62* Open a support ticket with [AWS Support](http://docs.aws.amazon.com/awssupport/latest/user/getting-started.html).
63* If you think you may have found a bug, please open an [issue](https://github.com/aws/aws-sdk-go/issues/new).
64
65## Opening Issues
66
67If you encounter a bug with the AWS SDK for Go we would like to hear about it.
68Search the [existing issues](https://github.com/aws/aws-sdk-go/issues) and see
69if others are also experiencing the issue before opening a new issue. Please
70include the version of AWS SDK for Go, Go language, and OS you’re using. Please
71also include reproduction case when appropriate.
72
73The GitHub issues are intended for bug reports and feature requests. For help
74and questions with using AWS SDK for GO please make use of the resources listed
75in the [Getting Help](https://github.com/aws/aws-sdk-go#getting-help) section.
76Keeping the list of open issues lean will help us respond in a timely manner.
77
78## Reference Documentation
79
80[`Getting Started Guide`](https://aws.amazon.com/sdk-for-go/) - This document
81is a general introduction on how to configure and make requests with the SDK.
82If this is your first time using the SDK, this documentation and the API
83documentation will help you get started. This document focuses on the syntax
84and behavior of the SDK. The [Service Developer
85Guide](https://aws.amazon.com/documentation/) will help you get started using
86specific AWS services.
87
88[`SDK API Reference
89Documentation`](https://docs.aws.amazon.com/sdk-for-go/api/) - Use this
90document to look up all API operation input and output parameters for AWS
91services supported by the SDK. The API reference also includes documentation of
92the SDK, and examples how to using the SDK, service client API operations, and
93API operation require parameters.
94
95[`Service Developer Guide`](https://aws.amazon.com/documentation/) - Use this
96documentation to learn how to interface with AWS services. These guides are
97great for getting started with a service, or when looking for more 
98information about a service. While this document is not required for coding, 
99services may supply helpful samples to look out for.
100
101[`SDK Examples`](https://github.com/aws/aws-sdk-go/tree/master/example) -
102Included in the SDK's repo are several hand crafted examples using the SDK
103features and AWS services.
104
105## Overview of SDK's Packages
106
107The SDK is composed of two main components, SDK core, and service clients.
108The SDK core packages are all available under the aws package at the root of
109the SDK. Each client for a supported AWS service is available within its own
110package under the service folder at the root of the SDK.
111
112  * aws - SDK core, provides common shared types such as Config, Logger,
113    and utilities to make working with API parameters easier.
114
115      * awserr - Provides the error interface that the SDK will use for all
116        errors that occur in the SDK's processing. This includes service API
117        response errors as well. The Error type is made up of a code and message.
118        Cast the SDK's returned error type to awserr.Error and call the Code
119        method to compare returned error to specific error codes. See the package's
120        documentation for additional values that can be extracted such as RequestID.
121
122      * credentials - Provides the types and built in credentials providers
123        the SDK will use to retrieve AWS credentials to make API requests with.
124        Nested under this folder are also additional credentials providers such as
125        stscreds for assuming IAM roles, and ec2rolecreds for EC2 Instance roles.
126
127      * endpoints - Provides the AWS Regions and Endpoints metadata for the SDK.
128        Use this to lookup AWS service endpoint information such as which services
129        are in a region, and what regions a service is in. Constants are also provided
130        for all region identifiers, e.g UsWest2RegionID for "us-west-2".
131
132      * session - Provides initial default configuration, and load
133        configuration from external sources such as environment and shared
134        credentials file.
135
136      * request - Provides the API request sending, and retry logic for the SDK.
137        This package also includes utilities for defining your own request
138        retryer, and configuring how the SDK processes the request.
139
140  * service - Clients for AWS services. All services supported by the SDK are
141    available under this folder.
142
143## How to Use the SDK's AWS Service Clients
144
145The SDK includes the Go types and utilities you can use to make requests to
146AWS service APIs. Within the service folder at the root of the SDK you'll find
147a package for each AWS service the SDK supports. All service clients follow common pattern of creation and usage.
148
149When creating a client for an AWS service you'll first need to have a Session
150value constructed. The Session provides shared configuration that can be shared
151between your service clients. When service clients are created you can pass
152in additional configuration via the aws.Config type to override configuration
153provided by in the Session to create service client instances with custom
154configuration.
155
156Once the service's client is created you can use it to make API requests the
157AWS service. These clients are safe to use concurrently.
158
159## Configuring the SDK
160
161In the AWS SDK for Go, you can configure settings for service clients, such
162as the log level and maximum number of retries. Most settings are optional;
163however, for each service client, you must specify a region and your credentials.
164The SDK uses these values to send requests to the correct AWS region and sign
165requests with the correct credentials. You can specify these values as part
166of a session or as environment variables.
167
168See the SDK's [configuration guide][config_guide] for more information.
169
170See the [session][session_pkg] package documentation for more information on how to use Session
171with the SDK.
172
173See the [Config][config_typ] type in the [aws][aws_pkg] package for more information on configuration
174options.
175
176[config_guide]: https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html
177[session_pkg]: https://docs.aws.amazon.com/sdk-for-go/api/aws/session/
178[config_typ]: https://docs.aws.amazon.com/sdk-for-go/api/aws/#Config
179[aws_pkg]: https://docs.aws.amazon.com/sdk-for-go/api/aws/
180
181### Configuring Credentials
182
183When using the SDK you'll generally need your AWS credentials to authenticate
184with AWS services. The SDK supports multiple methods of supporting these
185credentials. By default the SDK will source credentials automatically from
186its default credential chain. See the session package for more information
187on this chain, and how to configure it. The common items in the credential
188chain are the following:
189
190  * Environment Credentials - Set of environment variables that are useful
191    when sub processes are created for specific roles.
192
193  * Shared Credentials file (~/.aws/credentials) - This file stores your
194    credentials based on a profile name and is useful for local development.
195
196  * EC2 Instance Role Credentials - Use EC2 Instance Role to assign credentials
197    to application running on an EC2 instance. This removes the need to manage
198    credential files in production.
199
200Credentials can be configured in code as well by setting the Config's Credentials
201value to a custom provider or using one of the providers included with the
202SDK to bypass the default credential chain and use a custom one. This is
203helpful when you want to instruct the SDK to only use a specific set of
204credentials or providers.
205
206This example creates a credential provider for assuming an IAM role, "myRoleARN"
207and configures the S3 service client to use that role for API requests.
208
209```go
210  // Initial credentials loaded from SDK's default credential chain. Such as
211  // the environment, shared credentials (~/.aws/credentials), or EC2 Instance
212  // Role. These credentials will be used to to make the STS Assume Role API.
213  sess := session.Must(session.NewSession())
214
215  // Create the credentials from AssumeRoleProvider to assume the role
216  // referenced by the "myRoleARN" ARN.
217  creds := stscreds.NewCredentials(sess, "myRoleArn")
218
219  // Create service client value configured for credentials
220  // from assumed role.
221  svc := s3.New(sess, &aws.Config{Credentials: creds})
222```
223
224See the [credentials][credentials_pkg] package documentation for more information on credential
225providers included with the SDK, and how to customize the SDK's usage of
226credentials.
227
228The SDK has support for the shared configuration file (~/.aws/config). This
229support can be enabled by setting the environment variable, "AWS_SDK_LOAD_CONFIG=1",
230or enabling the feature in code when creating a Session via the
231Option's SharedConfigState parameter.
232
233```go
234  sess := session.Must(session.NewSessionWithOptions(session.Options{
235      SharedConfigState: session.SharedConfigEnable,
236  }))
237```
238
239[credentials_pkg]: https://docs.aws.amazon.com/sdk-for-go/api/aws/credentials
240
241### Configuring AWS Region
242
243In addition to the credentials you'll need to specify the region the SDK
244will use to make AWS API requests to. In the SDK you can specify the region
245either with an environment variable, or directly in code when a Session or
246service client is created. The last value specified in code wins if the region
247is specified multiple ways.
248
249To set the region via the environment variable set the "AWS_REGION" to the
250region you want to the SDK to use. Using this method to set the region will
251allow you to run your application in multiple regions without needing additional
252code in the application to select the region.
253
254    AWS_REGION=us-west-2
255
256The endpoints package includes constants for all regions the SDK knows. The
257values are all suffixed with RegionID. These values are helpful, because they
258reduce the need to type the region string manually.
259
260To set the region on a Session use the aws package's Config struct parameter
261Region to the AWS region you want the service clients created from the session to
262use. This is helpful when you want to create multiple service clients, and
263all of the clients make API requests to the same region.
264
265```go
266  sess := session.Must(session.NewSession(&aws.Config{
267      Region: aws.String(endpoints.UsWest2RegionID),
268  }))
269```
270
271See the [endpoints][endpoints_pkg] package for the AWS Regions and Endpoints metadata.
272
273In addition to setting the region when creating a Session you can also set
274the region on a per service client bases. This overrides the region of a
275Session. This is helpful when you want to create service clients in specific
276regions different from the Session's region.
277
278```go
279  svc := s3.New(sess, &aws.Config{
280      Region: aws.String(endpoints.UsWest2RegionID),
281  })
282```
283
284See the [Config][config_typ] type in the [aws][aws_pkg] package for more information and additional
285options such as setting the Endpoint, and other service client configuration options.
286
287[endpoints_pkg]: https://docs.aws.amazon.com/sdk-for-go/api/aws/endpoints/
288
289## Making API Requests
290
291Once the client is created you can make an API request to the service.
292Each API method takes a input parameter, and returns the service response
293and an error. The SDK provides methods for making the API call in multiple ways.
294
295In this list we'll use the S3 ListObjects API as an example for the different
296ways of making API requests.
297
298  * ListObjects - Base API operation that will make the API request to the service.
299
300  * ListObjectsRequest - API methods suffixed with Request will construct the
301    API request, but not send it. This is also helpful when you want to get a
302    presigned URL for a request, and share the presigned URL instead of your
303    application making the request directly.
304
305  * ListObjectsPages - Same as the base API operation, but uses a callback to
306    automatically handle pagination of the API's response.
307
308  * ListObjectsWithContext - Same as base API operation, but adds support for
309    the Context pattern. This is helpful for controlling the canceling of in
310    flight requests. See the Go standard library context package for more
311    information. This method also takes request package's Option functional
312    options as the variadic argument for modifying how the request will be
313    made, or extracting information from the raw HTTP response.
314
315  * ListObjectsPagesWithContext - same as ListObjectsPages, but adds support for
316    the Context pattern. Similar to ListObjectsWithContext this method also
317    takes the request package's Option function option types as the variadic
318    argument.
319
320In addition to the API operations the SDK also includes several higher level
321methods that abstract checking for and waiting for an AWS resource to be in
322a desired state. In this list we'll use WaitUntilBucketExists to demonstrate
323the different forms of waiters.
324
325  * WaitUntilBucketExists. - Method to make API request to query an AWS service for
326    a resource's state. Will return successfully when that state is accomplished.
327
328  * WaitUntilBucketExistsWithContext - Same as WaitUntilBucketExists, but adds
329    support for the Context pattern. In addition these methods take request
330    package's WaiterOptions to configure the waiter, and how underlying request
331    will be made by the SDK.
332
333The API method will document which error codes the service might return for
334the operation. These errors will also be available as const strings prefixed
335with "ErrCode" in the service client's package. If there are no errors listed
336in the API's SDK documentation you'll need to consult the AWS service's API
337documentation for the errors that could be returned.
338
339```go
340  ctx := context.Background()
341
342  result, err := svc.GetObjectWithContext(ctx, &s3.GetObjectInput{
343      Bucket: aws.String("my-bucket"),
344      Key: aws.String("my-key"),
345  })
346  if err != nil {
347      // Cast err to awserr.Error to handle specific error codes.
348      aerr, ok := err.(awserr.Error)
349      if ok && aerr.Code() == s3.ErrCodeNoSuchKey {
350          // Specific error code handling
351      }
352      return err
353  }
354
355  // Make sure to close the body when done with it for S3 GetObject APIs or
356  // will leak connections.
357  defer result.Body.Close()
358
359  fmt.Println("Object Size:", aws.Int64Value(result.ContentLength))
360```
361
362### API Request Pagination and Resource Waiters
363
364Pagination helper methods are suffixed with "Pages", and provide the
365functionality needed to round trip API page requests. Pagination methods
366take a callback function that will be called for each page of the API's response.
367
368```go
369   objects := []string{}
370   err := svc.ListObjectsPagesWithContext(ctx, &s3.ListObjectsInput{
371       Bucket: aws.String(myBucket),
372   }, func(p *s3.ListObjectsOutput, lastPage bool) bool {
373       for _, o := range p.Contents {
374           objects = append(objects, aws.StringValue(o.Key))
375       }
376       return true // continue paging
377   })
378   if err != nil {
379       panic(fmt.Sprintf("failed to list objects for bucket, %s, %v", myBucket, err))
380   }
381
382   fmt.Println("Objects in bucket:", objects)
383```
384
385Waiter helper methods provide the functionality to wait for an AWS resource
386state. These methods abstract the logic needed to check the state of an
387AWS resource, and wait until that resource is in a desired state. The waiter
388will block until the resource is in the state that is desired, an error occurs,
389or the waiter times out. If a resource times out the error code returned will
390be request.WaiterResourceNotReadyErrorCode.
391
392```go
393  err := svc.WaitUntilBucketExistsWithContext(ctx, &s3.HeadBucketInput{
394      Bucket: aws.String(myBucket),
395  })
396  if err != nil {
397      aerr, ok := err.(awserr.Error)
398      if ok && aerr.Code() == request.WaiterResourceNotReadyErrorCode {
399          fmt.Fprintf(os.Stderr, "timed out while waiting for bucket to exist")
400      }
401      panic(fmt.Errorf("failed to wait for bucket to exist, %v", err))
402  }
403  fmt.Println("Bucket", myBucket, "exists")
404```
405
406## Complete SDK Example
407
408This example shows a complete working Go file which will upload a file to S3
409and use the Context pattern to implement timeout logic that will cancel the
410request if it takes too long. This example highlights how to use sessions,
411create a service client, make a request, handle the error, and process the
412response.
413
414```go
415  package main
416
417  import (
418  	"context"
419  	"flag"
420  	"fmt"
421  	"os"
422  	"time"
423
424  	"github.com/aws/aws-sdk-go/aws"
425  	"github.com/aws/aws-sdk-go/aws/awserr"
426  	"github.com/aws/aws-sdk-go/aws/request"
427  	"github.com/aws/aws-sdk-go/aws/session"
428  	"github.com/aws/aws-sdk-go/service/s3"
429  )
430
431  // Uploads a file to S3 given a bucket and object key. Also takes a duration
432  // value to terminate the update if it doesn't complete within that time.
433  //
434  // The AWS Region needs to be provided in the AWS shared config or on the
435  // environment variable as `AWS_REGION`. Credentials also must be provided
436  // Will default to shared config file, but can load from environment if provided.
437  //
438  // Usage:
439  //   # Upload myfile.txt to myBucket/myKey. Must complete within 10 minutes or will fail
440  //   go run withContext.go -b mybucket -k myKey -d 10m < myfile.txt
441  func main() {
442  	var bucket, key string
443  	var timeout time.Duration
444
445  	flag.StringVar(&bucket, "b", "", "Bucket name.")
446  	flag.StringVar(&key, "k", "", "Object key name.")
447  	flag.DurationVar(&timeout, "d", 0, "Upload timeout.")
448  	flag.Parse()
449
450  	// All clients require a Session. The Session provides the client with
451 	// shared configuration such as region, endpoint, and credentials. A
452 	// Session should be shared where possible to take advantage of
453 	// configuration and credential caching. See the session package for
454 	// more information.
455  	sess := session.Must(session.NewSession())
456
457 	// Create a new instance of the service's client with a Session.
458 	// Optional aws.Config values can also be provided as variadic arguments
459 	// to the New function. This option allows you to provide service
460 	// specific configuration.
461  	svc := s3.New(sess)
462
463  	// Create a context with a timeout that will abort the upload if it takes
464  	// more than the passed in timeout.
465  	ctx := context.Background()
466  	var cancelFn func()
467  	if timeout > 0 {
468  		ctx, cancelFn = context.WithTimeout(ctx, timeout)
469  	}
470  	// Ensure the context is canceled to prevent leaking.
471  	// See context package for more information, https://golang.org/pkg/context/
472	if cancelFn != nil {
473  		defer cancelFn()
474	}
475
476  	// Uploads the object to S3. The Context will interrupt the request if the
477  	// timeout expires.
478  	_, err := svc.PutObjectWithContext(ctx, &s3.PutObjectInput{
479  		Bucket: aws.String(bucket),
480  		Key:    aws.String(key),
481  		Body:   os.Stdin,
482  	})
483  	if err != nil {
484  		if aerr, ok := err.(awserr.Error); ok && aerr.Code() == request.CanceledErrorCode {
485  			// If the SDK can determine the request or retry delay was canceled
486  			// by a context the CanceledErrorCode error code will be returned.
487  			fmt.Fprintf(os.Stderr, "upload canceled due to timeout, %v\n", err)
488  		} else {
489  			fmt.Fprintf(os.Stderr, "failed to upload object, %v\n", err)
490  		}
491  		os.Exit(1)
492  	}
493
494  	fmt.Printf("successfully uploaded file to %s/%s\n", bucket, key)
495  }
496```
497
498## License
499
500This SDK is distributed under the
501[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0),
502see LICENSE.txt and NOTICE.txt for more information.
503