doc.go

// Package sdk is the official AWS SDK for the Go programming language.
//
// The AWS SDK for Go provides APIs and utilities that developers can use to
// build Go applications that use AWS services, such as Amazon Elastic Compute
// Cloud (Amazon EC2) and Amazon Simple Storage Service (Amazon S3).
//
// The SDK removes the complexity of coding directly against a web service
// interface. It hides a lot of the lower-level plumbing, such as authentication,
// request retries, and error handling.
//
// The SDK also includes helpful utilities on top of the AWS APIs that add additional
// capabilities and functionality. For example, the Amazon S3 Download and Upload
// Manager will automatically split up large objects into multiple parts and
// transfer them concurrently.
//
// See the s3manager package documentation for more information.
// https://docs.aws.amazon.com/sdk-for-go/api/service/s3/s3manager/
//
// Getting More Information
//
// Checkout the Getting Started Guide and API Reference Docs detailed the SDK's
// components and details on each AWS client the SDK supports.
//
// The Getting Started Guide provides examples and detailed description of how
// to get setup with the SDK.
// https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/welcome.html
//
// The API Reference Docs include a detailed breakdown of the SDK's components
// such as utilities and AWS clients. Use this as a reference of the Go types
// included with the SDK, such as AWS clients, API operations, and API parameters.
// https://docs.aws.amazon.com/sdk-for-go/api/
//
// Overview of SDK's Packages
//
// The SDK is composed of two main components, SDK core, and service clients.
// The SDK core packages are all available under the aws package at the root of
// the SDK. Each client for a supported AWS service is available within its own
// package under the service folder at the root of the SDK.
//
//   * aws - SDK core, provides common shared types such as Config, Logger,
//     and utilities to make working with API parameters easier.
//
//       * awserr - Provides the error interface that the SDK will use for all
//         errors that occur in the SDK's processing. This includes service API
//         response errors as well. The Error type is made up of a code and message.
//         Cast the SDK's returned error type to awserr.Error and call the Code
//         method to compare returned error to specific error codes. See the package's
//         documentation for additional values that can be extracted such as RequestId.
//
//       * credentials - Provides the types and built in credentials providers
//         the SDK will use to retrieve AWS credentials to make API requests with.
//         Nested under this folder are also additional credentials providers such as
//         stscreds for assuming IAM roles, and ec2rolecreds for EC2 Instance roles.
//
//       * endpoints - Provides the AWS Regions and Endpoints metadata for the SDK.
//         Use this to lookup AWS service endpoint information such as which services
//         are in a region, and what regions a service is in. Constants are also provided
//         for all region identifiers, e.g UsWest2RegionID for "us-west-2".
//
//       * session - Provides initial default configuration, and load
//         configuration from external sources such as environment and shared
//         credentials file.
//
//       * request - Provides the API request sending, and retry logic for the SDK.
//         This package also includes utilities for defining your own request
//         retryer, and configuring how the SDK processes the request.
//
//   * service - Clients for AWS services. All services supported by the SDK are
//     available under this folder.
//
// How to Use the SDK's AWS Service Clients
//
// The SDK includes the Go types and utilities you can use to make requests to
// AWS service APIs. Within the service folder at the root of the SDK you'll find
// a package for each AWS service the SDK supports. All service clients follows
// a common pattern of creation and usage.
//
// When creating a client for an AWS service you'll first need to have a Session
// value constructed. The Session provides shared configuration that can be shared
// between your service clients. When service clients are created you can pass
// in additional configuration via the aws.Config type to override configuration
// provided by in the Session to create service client instances with custom
// configuration.
//
// Once the service's client is created you can use it to make API requests the
// AWS service. These clients are safe to use concurrently.
//
// Configuring the SDK
//
// In the AWS SDK for Go, you can configure settings for service clients, such
// as the log level and maximum number of retries. Most settings are optional;
// however, for each service client, you must specify a region and your credentials.
// The SDK uses these values to send requests to the correct AWS region and sign
// requests with the correct credentials. You can specify these values as part
// of a session or as environment variables.
//
// See the SDK's configuration guide for more information.
// https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html
//
// See the session package documentation for more information on how to use Session
// with the SDK.
// https://docs.aws.amazon.com/sdk-for-go/api/aws/session/
//
// See the Config type in the aws package for more information on configuration
// options.
// https://docs.aws.amazon.com/sdk-for-go/api/aws/#Config
//
// Configuring Credentials
//
// When using the SDK you'll generally need your AWS credentials to authenticate
// with AWS services. The SDK supports multiple methods of supporting these
// credentials. By default the SDK will source credentials automatically from
// its default credential chain. See the session package for more information
// on this chain, and how to configure it. The common items in the credential
// chain are the following:
//
//   * Environment Credentials - Set of environment variables that are useful
//     when sub processes are created for specific roles.
//
//   * Shared Credentials file (~/.aws/credentials) - This file stores your
//     credentials based on a profile name and is useful for local development.
//
//   * EC2 Instance Role Credentials - Use EC2 Instance Role to assign credentials
//     to application running on an EC2 instance. This removes the need to manage
//     credential files in production.
//
// Credentials can be configured in code as well by setting the Config's Credentials
// value to a custom provider or using one of the providers included with the
// SDK to bypass the default credential chain and use a custom one. This is
// helpful when you want to instruct the SDK to only use a specific set of
// credentials or providers.
//
// This example creates a credential provider for assuming an IAM role, "myRoleARN"
// and configures the S3 service client to use that role for API requests.
//
//   // Initial credentials loaded from SDK's default credential chain. Such as
//   // the environment, shared credentials (~/.aws/credentials), or EC2 Instance
//   // Role. These credentials will be used to to make the STS Assume Role API.
//   sess := session.Must(session.NewSession())
//
//   // Create the credentials from AssumeRoleProvider to assume the role
//   // referenced by the "myRoleARN" ARN.
//   creds := stscreds.NewCredentials(sess, "myRoleArn")
//
//   // Create service client value configured for credentials
//   // from assumed role.
//   svc := s3.New(sess, &aws.Config{Credentials: creds})/
//
// See the credentials package documentation for more information on credential
// providers included with the SDK, and how to customize the SDK's usage of
// credentials.
// https://docs.aws.amazon.com/sdk-for-go/api/aws/credentials
//
// The SDK has support for the shared configuration file (~/.aws/config). This
// support can be enabled by setting the environment variable, "AWS_SDK_LOAD_CONFIG=1",
// or enabling the feature in code when creating a Session via the
// Option's SharedConfigState parameter.
//
//   sess := session.Must(session.NewSessionWithOptions(session.Options{
//       SharedConfigState: session.SharedConfigEnable,
//   }))
//
// Configuring AWS Region
//
// In addition to the credentials you'll need to specify the region the SDK
// will use to make AWS API requests to. In the SDK you can specify the region
// either with an environment variable, or directly in code when a Session or
// service client is created. The last value specified in code wins if the region
// is specified multiple ways.
//
// To set the region via the environment variable set the "AWS_REGION" to the
// region you want to the SDK to use. Using this method to set the region will
// allow you to run your application in multiple regions without needing additional
// code in the application to select the region.
//
//   AWS_REGION=us-west-2
//
// The endpoints package includes constants for all regions the SDK knows. The
// values are all suffixed with RegionID. These values are helpful, because they
// reduce the need to type the region string manually.
//
// To set the region on a Session use the aws package's Config struct parameter
// Region to the AWS region you want the service clients created from the session to
// use. This is helpful when you want to create multiple service clients, and
// all of the clients make API requests to the same region.
//
//   sess := session.Must(session.NewSession(&aws.Config{
//       Region: aws.String(endpoints.UsWest2RegionID),
//   }))
//
// See the endpoints package for the AWS Regions and Endpoints metadata.
// https://docs.aws.amazon.com/sdk-for-go/api/aws/endpoints/
//
// In addition to setting the region when creating a Session you can also set
// the region on a per service client bases. This overrides the region of a
// Session. This is helpful when you want to create service clients in specific
// regions different from the Session's region.
//
//   svc := s3.New(sess, &aws.Config{
//       Region: aws.String(endpoints.UsWest2RegionID),
//   })
//
// See the Config type in the aws package for more information and additional
// options such as setting the Endpoint, and other service client configuration options.
// https://docs.aws.amazon.com/sdk-for-go/api/aws/#Config
//
// Making API Requests
//
// Once the client is created you can make an API request to the service.
// Each API method takes a input parameter, and returns the service response
// and an error. The SDK provides methods for making the API call in multiple ways.
//
// In this list we'll use the S3 ListObjects API as an example for the different
// ways of making API requests.
//
//   * ListObjects - Base API operation that will make the API request to the service.
//
//   * ListObjectsRequest - API methods suffixed with Request will construct the
//     API request, but not send it. This is also helpful when you want to get a
//     presigned URL for a request, and share the presigned URL instead of your
//     application making the request directly.
//
//   * ListObjectsPages - Same as the base API operation, but uses a callback to
//     automatically handle pagination of the API's response.
//
//   * ListObjectsWithContext - Same as base API operation, but adds support for
//     the Context pattern. This is helpful for controlling the canceling of in
//     flight requests. See the Go standard library context package for more
//     information. This method also takes request package's Option functional
//     options as the variadic argument for modifying how the request will be
//     made, or extracting information from the raw HTTP response.
//
//   * ListObjectsPagesWithContext - same as ListObjectsPages, but adds support for
//     the Context pattern. Similar to ListObjectsWithContext this method also
//     takes the request package's Option function option types as the variadic
//     argument.
//
// In addition to the API operations the SDK also includes several higher level
// methods that abstract checking for and waiting for an AWS resource to be in
// a desired state. In this list we'll use WaitUntilBucketExists to demonstrate
// the different forms of waiters.
//
//   * WaitUntilBucketExists. - Method to make API request to query an AWS service for
//     a resource's state. Will return successfully when that state is accomplished.
//
//   * WaitUntilBucketExistsWithContext - Same as WaitUntilBucketExists, but adds
//     support for the Context pattern. In addition these methods take request
//     package's WaiterOptions to configure the waiter, and how underlying request
//     will be made by the SDK.
//
// The API method will document which error codes the service might return for
// the operation. These errors will also be available as const strings prefixed
// with "ErrCode" in the service client's package. If there are no errors listed
// in the API's SDK documentation you'll need to consult the AWS service's API
// documentation for the errors that could be returned.
//
//   ctx := context.Background()
//
//   result, err := svc.GetObjectWithContext(ctx, &s3.GetObjectInput{
//       Bucket: aws.String("my-bucket"),
//       Key: aws.String("my-key"),
//   })
//   if err != nil {
//       // Cast err to awserr.Error to handle specific error codes.
//       aerr, ok := err.(awserr.Error)
//       if ok && aerr.Code() == s3.ErrCodeNoSuchKey {
//           // Specific error code handling
//       }
//       return err
//   }
//
//   // Make sure to close the body when done with it for S3 GetObject APIs or
//   // will leak connections.
//   defer result.Body.Close()
//
//   fmt.Println("Object Size:", aws.StringValue(result.ContentLength))
//
// API Request Pagination and Resource Waiters
//
// Pagination helper methods are suffixed with "Pages", and provide the
// functionality needed to round trip API page requests. Pagination methods
// take a callback function that will be called for each page of the API's response.
//
//    objects := []string{}
//    err := svc.ListObjectsPagesWithContext(ctx, &s3.ListObjectsInput{
//        Bucket: aws.String(myBucket),
//    }, func(p *s3.ListObjectsOutput, lastPage bool) bool {
//        for _, o := range p.Contents {
//            objects = append(objects, aws.StringValue(o.Key))
//        }
//        return true // continue paging
//    })
//    if err != nil {
//        panic(fmt.Sprintf("failed to list objects for bucket, %s, %v", myBucket, err))
//    }
//
//    fmt.Println("Objects in bucket:", objects)
//
// Waiter helper methods provide the functionality to wait for an AWS resource
// state. These methods abstract the logic needed to to check the state of an
// AWS resource, and wait until that resource is in a desired state. The waiter
// will block until the resource is in the state that is desired, an error occurs,
// or the waiter times out. If a resource times out the error code returned will
// be request.WaiterResourceNotReadyErrorCode.
//
//   err := svc.WaitUntilBucketExistsWithContext(ctx, &s3.HeadBucketInput{
//       Bucket: aws.String(myBucket),
//   })
//   if err != nil {
//       aerr, ok := err.(awserr.Error)
//       if ok && aerr.Code() == request.WaiterResourceNotReadyErrorCode {
//           fmt.Fprintf(os.Stderr, "timed out while waiting for bucket to exist")
//       }
//       panic(fmt.Errorf("failed to wait for bucket to exist, %v", err))
//   }
//   fmt.Println("Bucket", myBucket, "exists")
//
// Complete SDK Example
//
// This example shows a complete working Go file which will upload a file to S3
// and use the Context pattern to implement timeout logic that will cancel the
// request if it takes too long. This example highlights how to use sessions,
// create a service client, make a request, handle the error, and process the
// response.
//
//   package main
//
//   import (
//   	"context"
//   	"flag"
//   	"fmt"
//   	"os"
//   	"time"
//
//   	"github.com/aws/aws-sdk-go/aws"
//   	"github.com/aws/aws-sdk-go/aws/awserr"
//   	"github.com/aws/aws-sdk-go/aws/request"
//   	"github.com/aws/aws-sdk-go/aws/session"
//   	"github.com/aws/aws-sdk-go/service/s3"
//   )
//
//   // Uploads a file to S3 given a bucket and object key. Also takes a duration
//   // value to terminate the update if it doesn't complete within that time.
//   //
//   // The AWS Region needs to be provided in the AWS shared config or on the
//   // environment variable as `AWS_REGION`. Credentials also must be provided
//   // Will default to shared config file, but can load from environment if provided.
//   //
//   // Usage:
//   //   # Upload myfile.txt to myBucket/myKey. Must complete within 10 minutes or will fail
//   //   go run withContext.go -b mybucket -k myKey -d 10m < myfile.txt
//   func main() {
//   	var bucket, key string
//   	var timeout time.Duration
//
//   	flag.StringVar(&bucket, "b", "", "Bucket name.")
//   	flag.StringVar(&key, "k", "", "Object key name.")
//   	flag.DurationVar(&timeout, "d", 0, "Upload timeout.")
//   	flag.Parse()
//
//   	// All clients require a Session. The Session provides the client with
//  	// shared configuration such as region, endpoint, and credentials. A
//  	// Session should be shared where possible to take advantage of
//  	// configuration and credential caching. See the session package for
//  	// more information.
//   	sess := session.Must(session.NewSession())
//
//  	// Create a new instance of the service's client with a Session.
//  	// Optional aws.Config values can also be provided as variadic arguments
//  	// to the New function. This option allows you to provide service
//  	// specific configuration.
//   	svc := s3.New(sess)
//
//   	// Create a context with a timeout that will abort the upload if it takes
//   	// more than the passed in timeout.
//   	ctx := context.Background()
//   	var cancelFn func()
//   	if timeout > 0 {
//   		ctx, cancelFn = context.WithTimeout(ctx, timeout)
//   	}
//   	// Ensure the context is canceled to prevent leaking.
//   	// See context package for more information, https://golang.org/pkg/context/
//   	defer cancelFn()
//
//   	// Uploads the object to S3. The Context will interrupt the request if the
//   	// timeout expires.
//   	_, err := svc.PutObjectWithContext(ctx, &s3.PutObjectInput{
//   		Bucket: aws.String(bucket),
//   		Key:    aws.String(key),
//   		Body:   os.Stdin,
//   	})
//   	if err != nil {
//   		if aerr, ok := err.(awserr.Error); ok && aerr.Code() == request.CanceledErrorCode {
//   			// If the SDK can determine the request or retry delay was canceled
//   			// by a context the CanceledErrorCode error code will be returned.
//   			fmt.Fprintf(os.Stderr, "upload canceled due to timeout, %v\n", err)
//   		} else {
//   			fmt.Fprintf(os.Stderr, "failed to upload object, %v\n", err)
//   		}
//   		os.Exit(1)
//   	}
//
//   	fmt.Printf("successfully uploaded file to %s/%s\n", bucket, key)
//   }
package sdk