1// Package sdk is the official AWS SDK for the Go programming language. 2// 3// The AWS SDK for Go provides APIs and utilities that developers can use to 4// build Go applications that use AWS services, such as Amazon Elastic Compute 5// Cloud (Amazon EC2) and Amazon Simple Storage Service (Amazon S3). 6// 7// The SDK removes the complexity of coding directly against a web service 8// interface. It hides a lot of the lower-level plumbing, such as authentication, 9// request retries, and error handling. 10// 11// The SDK also includes helpful utilities on top of the AWS APIs that add additional 12// capabilities and functionality. For example, the Amazon S3 Download and Upload 13// Manager will automatically split up large objects into multiple parts and 14// transfer them concurrently. 15// 16// See the s3manager package documentation for more information. 17// https://docs.aws.amazon.com/sdk-for-go/api/service/s3/s3manager/ 18// 19// Getting More Information 20// 21// Checkout the Getting Started Guide and API Reference Docs detailed the SDK's 22// components and details on each AWS client the SDK supports. 23// 24// The Getting Started Guide provides examples and detailed description of how 25// to get setup with the SDK. 26// https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/welcome.html 27// 28// The API Reference Docs include a detailed breakdown of the SDK's components 29// such as utilities and AWS clients. Use this as a reference of the Go types 30// included with the SDK, such as AWS clients, API operations, and API parameters. 31// https://docs.aws.amazon.com/sdk-for-go/api/ 32// 33// Overview of SDK's Packages 34// 35// The SDK is composed of two main components, SDK core, and service clients. 36// The SDK core packages are all available under the aws package at the root of 37// the SDK. Each client for a supported AWS service is available within its own 38// package under the service folder at the root of the SDK. 39// 40// * aws - SDK core, provides common shared types such as Config, Logger, 41// and utilities to make working with API parameters easier. 42// 43// * awserr - Provides the error interface that the SDK will use for all 44// errors that occur in the SDK's processing. This includes service API 45// response errors as well. The Error type is made up of a code and message. 46// Cast the SDK's returned error type to awserr.Error and call the Code 47// method to compare returned error to specific error codes. See the package's 48// documentation for additional values that can be extracted such as RequestId. 49// 50// * credentials - Provides the types and built in credentials providers 51// the SDK will use to retrieve AWS credentials to make API requests with. 52// Nested under this folder are also additional credentials providers such as 53// stscreds for assuming IAM roles, and ec2rolecreds for EC2 Instance roles. 54// 55// * endpoints - Provides the AWS Regions and Endpoints metadata for the SDK. 56// Use this to lookup AWS service endpoint information such as which services 57// are in a region, and what regions a service is in. Constants are also provided 58// for all region identifiers, e.g UsWest2RegionID for "us-west-2". 59// 60// * session - Provides initial default configuration, and load 61// configuration from external sources such as environment and shared 62// credentials file. 63// 64// * request - Provides the API request sending, and retry logic for the SDK. 65// This package also includes utilities for defining your own request 66// retryer, and configuring how the SDK processes the request. 67// 68// * service - Clients for AWS services. All services supported by the SDK are 69// available under this folder. 70// 71// How to Use the SDK's AWS Service Clients 72// 73// The SDK includes the Go types and utilities you can use to make requests to 74// AWS service APIs. Within the service folder at the root of the SDK you'll find 75// a package for each AWS service the SDK supports. All service clients follows 76// a common pattern of creation and usage. 77// 78// When creating a client for an AWS service you'll first need to have a Session 79// value constructed. The Session provides shared configuration that can be shared 80// between your service clients. When service clients are created you can pass 81// in additional configuration via the aws.Config type to override configuration 82// provided by in the Session to create service client instances with custom 83// configuration. 84// 85// Once the service's client is created you can use it to make API requests the 86// AWS service. These clients are safe to use concurrently. 87// 88// Configuring the SDK 89// 90// In the AWS SDK for Go, you can configure settings for service clients, such 91// as the log level and maximum number of retries. Most settings are optional; 92// however, for each service client, you must specify a region and your credentials. 93// The SDK uses these values to send requests to the correct AWS region and sign 94// requests with the correct credentials. You can specify these values as part 95// of a session or as environment variables. 96// 97// See the SDK's configuration guide for more information. 98// https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html 99// 100// See the session package documentation for more information on how to use Session 101// with the SDK. 102// https://docs.aws.amazon.com/sdk-for-go/api/aws/session/ 103// 104// See the Config type in the aws package for more information on configuration 105// options. 106// https://docs.aws.amazon.com/sdk-for-go/api/aws/#Config 107// 108// Configuring Credentials 109// 110// When using the SDK you'll generally need your AWS credentials to authenticate 111// with AWS services. The SDK supports multiple methods of supporting these 112// credentials. By default the SDK will source credentials automatically from 113// its default credential chain. See the session package for more information 114// on this chain, and how to configure it. The common items in the credential 115// chain are the following: 116// 117// * Environment Credentials - Set of environment variables that are useful 118// when sub processes are created for specific roles. 119// 120// * Shared Credentials file (~/.aws/credentials) - This file stores your 121// credentials based on a profile name and is useful for local development. 122// 123// * EC2 Instance Role Credentials - Use EC2 Instance Role to assign credentials 124// to application running on an EC2 instance. This removes the need to manage 125// credential files in production. 126// 127// Credentials can be configured in code as well by setting the Config's Credentials 128// value to a custom provider or using one of the providers included with the 129// SDK to bypass the default credential chain and use a custom one. This is 130// helpful when you want to instruct the SDK to only use a specific set of 131// credentials or providers. 132// 133// This example creates a credential provider for assuming an IAM role, "myRoleARN" 134// and configures the S3 service client to use that role for API requests. 135// 136// // Initial credentials loaded from SDK's default credential chain. Such as 137// // the environment, shared credentials (~/.aws/credentials), or EC2 Instance 138// // Role. These credentials will be used to to make the STS Assume Role API. 139// sess := session.Must(session.NewSession()) 140// 141// // Create the credentials from AssumeRoleProvider to assume the role 142// // referenced by the "myRoleARN" ARN. 143// creds := stscreds.NewCredentials(sess, "myRoleArn") 144// 145// // Create service client value configured for credentials 146// // from assumed role. 147// svc := s3.New(sess, &aws.Config{Credentials: creds})/ 148// 149// See the credentials package documentation for more information on credential 150// providers included with the SDK, and how to customize the SDK's usage of 151// credentials. 152// https://docs.aws.amazon.com/sdk-for-go/api/aws/credentials 153// 154// The SDK has support for the shared configuration file (~/.aws/config). This 155// support can be enabled by setting the environment variable, "AWS_SDK_LOAD_CONFIG=1", 156// or enabling the feature in code when creating a Session via the 157// Option's SharedConfigState parameter. 158// 159// sess := session.Must(session.NewSessionWithOptions(session.Options{ 160// SharedConfigState: session.SharedConfigEnable, 161// })) 162// 163// Configuring AWS Region 164// 165// In addition to the credentials you'll need to specify the region the SDK 166// will use to make AWS API requests to. In the SDK you can specify the region 167// either with an environment variable, or directly in code when a Session or 168// service client is created. The last value specified in code wins if the region 169// is specified multiple ways. 170// 171// To set the region via the environment variable set the "AWS_REGION" to the 172// region you want to the SDK to use. Using this method to set the region will 173// allow you to run your application in multiple regions without needing additional 174// code in the application to select the region. 175// 176// AWS_REGION=us-west-2 177// 178// The endpoints package includes constants for all regions the SDK knows. The 179// values are all suffixed with RegionID. These values are helpful, because they 180// reduce the need to type the region string manually. 181// 182// To set the region on a Session use the aws package's Config struct parameter 183// Region to the AWS region you want the service clients created from the session to 184// use. This is helpful when you want to create multiple service clients, and 185// all of the clients make API requests to the same region. 186// 187// sess := session.Must(session.NewSession(&aws.Config{ 188// Region: aws.String(endpoints.UsWest2RegionID), 189// })) 190// 191// See the endpoints package for the AWS Regions and Endpoints metadata. 192// https://docs.aws.amazon.com/sdk-for-go/api/aws/endpoints/ 193// 194// In addition to setting the region when creating a Session you can also set 195// the region on a per service client bases. This overrides the region of a 196// Session. This is helpful when you want to create service clients in specific 197// regions different from the Session's region. 198// 199// svc := s3.New(sess, &aws.Config{ 200// Region: aws.String(endpoints.UsWest2RegionID), 201// }) 202// 203// See the Config type in the aws package for more information and additional 204// options such as setting the Endpoint, and other service client configuration options. 205// https://docs.aws.amazon.com/sdk-for-go/api/aws/#Config 206// 207// Making API Requests 208// 209// Once the client is created you can make an API request to the service. 210// Each API method takes a input parameter, and returns the service response 211// and an error. The SDK provides methods for making the API call in multiple ways. 212// 213// In this list we'll use the S3 ListObjects API as an example for the different 214// ways of making API requests. 215// 216// * ListObjects - Base API operation that will make the API request to the service. 217// 218// * ListObjectsRequest - API methods suffixed with Request will construct the 219// API request, but not send it. This is also helpful when you want to get a 220// presigned URL for a request, and share the presigned URL instead of your 221// application making the request directly. 222// 223// * ListObjectsPages - Same as the base API operation, but uses a callback to 224// automatically handle pagination of the API's response. 225// 226// * ListObjectsWithContext - Same as base API operation, but adds support for 227// the Context pattern. This is helpful for controlling the canceling of in 228// flight requests. See the Go standard library context package for more 229// information. This method also takes request package's Option functional 230// options as the variadic argument for modifying how the request will be 231// made, or extracting information from the raw HTTP response. 232// 233// * ListObjectsPagesWithContext - same as ListObjectsPages, but adds support for 234// the Context pattern. Similar to ListObjectsWithContext this method also 235// takes the request package's Option function option types as the variadic 236// argument. 237// 238// In addition to the API operations the SDK also includes several higher level 239// methods that abstract checking for and waiting for an AWS resource to be in 240// a desired state. In this list we'll use WaitUntilBucketExists to demonstrate 241// the different forms of waiters. 242// 243// * WaitUntilBucketExists. - Method to make API request to query an AWS service for 244// a resource's state. Will return successfully when that state is accomplished. 245// 246// * WaitUntilBucketExistsWithContext - Same as WaitUntilBucketExists, but adds 247// support for the Context pattern. In addition these methods take request 248// package's WaiterOptions to configure the waiter, and how underlying request 249// will be made by the SDK. 250// 251// The API method will document which error codes the service might return for 252// the operation. These errors will also be available as const strings prefixed 253// with "ErrCode" in the service client's package. If there are no errors listed 254// in the API's SDK documentation you'll need to consult the AWS service's API 255// documentation for the errors that could be returned. 256// 257// ctx := context.Background() 258// 259// result, err := svc.GetObjectWithContext(ctx, &s3.GetObjectInput{ 260// Bucket: aws.String("my-bucket"), 261// Key: aws.String("my-key"), 262// }) 263// if err != nil { 264// // Cast err to awserr.Error to handle specific error codes. 265// aerr, ok := err.(awserr.Error) 266// if ok && aerr.Code() == s3.ErrCodeNoSuchKey { 267// // Specific error code handling 268// } 269// return err 270// } 271// 272// // Make sure to close the body when done with it for S3 GetObject APIs or 273// // will leak connections. 274// defer result.Body.Close() 275// 276// fmt.Println("Object Size:", aws.StringValue(result.ContentLength)) 277// 278// API Request Pagination and Resource Waiters 279// 280// Pagination helper methods are suffixed with "Pages", and provide the 281// functionality needed to round trip API page requests. Pagination methods 282// take a callback function that will be called for each page of the API's response. 283// 284// objects := []string{} 285// err := svc.ListObjectsPagesWithContext(ctx, &s3.ListObjectsInput{ 286// Bucket: aws.String(myBucket), 287// }, func(p *s3.ListObjectsOutput, lastPage bool) bool { 288// for _, o := range p.Contents { 289// objects = append(objects, aws.StringValue(o.Key)) 290// } 291// return true // continue paging 292// }) 293// if err != nil { 294// panic(fmt.Sprintf("failed to list objects for bucket, %s, %v", myBucket, err)) 295// } 296// 297// fmt.Println("Objects in bucket:", objects) 298// 299// Waiter helper methods provide the functionality to wait for an AWS resource 300// state. These methods abstract the logic needed to to check the state of an 301// AWS resource, and wait until that resource is in a desired state. The waiter 302// will block until the resource is in the state that is desired, an error occurs, 303// or the waiter times out. If a resource times out the error code returned will 304// be request.WaiterResourceNotReadyErrorCode. 305// 306// err := svc.WaitUntilBucketExistsWithContext(ctx, &s3.HeadBucketInput{ 307// Bucket: aws.String(myBucket), 308// }) 309// if err != nil { 310// aerr, ok := err.(awserr.Error) 311// if ok && aerr.Code() == request.WaiterResourceNotReadyErrorCode { 312// fmt.Fprintf(os.Stderr, "timed out while waiting for bucket to exist") 313// } 314// panic(fmt.Errorf("failed to wait for bucket to exist, %v", err)) 315// } 316// fmt.Println("Bucket", myBucket, "exists") 317// 318// Complete SDK Example 319// 320// This example shows a complete working Go file which will upload a file to S3 321// and use the Context pattern to implement timeout logic that will cancel the 322// request if it takes too long. This example highlights how to use sessions, 323// create a service client, make a request, handle the error, and process the 324// response. 325// 326// package main 327// 328// import ( 329// "context" 330// "flag" 331// "fmt" 332// "os" 333// "time" 334// 335// "github.com/aws/aws-sdk-go/aws" 336// "github.com/aws/aws-sdk-go/aws/awserr" 337// "github.com/aws/aws-sdk-go/aws/request" 338// "github.com/aws/aws-sdk-go/aws/session" 339// "github.com/aws/aws-sdk-go/service/s3" 340// ) 341// 342// // Uploads a file to S3 given a bucket and object key. Also takes a duration 343// // value to terminate the update if it doesn't complete within that time. 344// // 345// // The AWS Region needs to be provided in the AWS shared config or on the 346// // environment variable as `AWS_REGION`. Credentials also must be provided 347// // Will default to shared config file, but can load from environment if provided. 348// // 349// // Usage: 350// // # Upload myfile.txt to myBucket/myKey. Must complete within 10 minutes or will fail 351// // go run withContext.go -b mybucket -k myKey -d 10m < myfile.txt 352// func main() { 353// var bucket, key string 354// var timeout time.Duration 355// 356// flag.StringVar(&bucket, "b", "", "Bucket name.") 357// flag.StringVar(&key, "k", "", "Object key name.") 358// flag.DurationVar(&timeout, "d", 0, "Upload timeout.") 359// flag.Parse() 360// 361// // All clients require a Session. The Session provides the client with 362// // shared configuration such as region, endpoint, and credentials. A 363// // Session should be shared where possible to take advantage of 364// // configuration and credential caching. See the session package for 365// // more information. 366// sess := session.Must(session.NewSession()) 367// 368// // Create a new instance of the service's client with a Session. 369// // Optional aws.Config values can also be provided as variadic arguments 370// // to the New function. This option allows you to provide service 371// // specific configuration. 372// svc := s3.New(sess) 373// 374// // Create a context with a timeout that will abort the upload if it takes 375// // more than the passed in timeout. 376// ctx := context.Background() 377// var cancelFn func() 378// if timeout > 0 { 379// ctx, cancelFn = context.WithTimeout(ctx, timeout) 380// } 381// // Ensure the context is canceled to prevent leaking. 382// // See context package for more information, https://golang.org/pkg/context/ 383// defer cancelFn() 384// 385// // Uploads the object to S3. The Context will interrupt the request if the 386// // timeout expires. 387// _, err := svc.PutObjectWithContext(ctx, &s3.PutObjectInput{ 388// Bucket: aws.String(bucket), 389// Key: aws.String(key), 390// Body: os.Stdin, 391// }) 392// if err != nil { 393// if aerr, ok := err.(awserr.Error); ok && aerr.Code() == request.CanceledErrorCode { 394// // If the SDK can determine the request or retry delay was canceled 395// // by a context the CanceledErrorCode error code will be returned. 396// fmt.Fprintf(os.Stderr, "upload canceled due to timeout, %v\n", err) 397// } else { 398// fmt.Fprintf(os.Stderr, "failed to upload object, %v\n", err) 399// } 400// os.Exit(1) 401// } 402// 403// fmt.Printf("successfully uploaded file to %s/%s\n", bucket, key) 404// } 405package sdk 406 407import ( 408 "github.com/jmespath/go-jmespath" 409) 410 411const _ = jmespath.ASTEmpty 412