AWS SDK for Go (PILOT)
API Reference

PREVIEW DOCUMENTATION - This is a preview of a new format for the AWS SDK for Go API Reference documentation. For the current AWS SDK for Go API Reference, see https://docs.aws.amazon.com/sdk-for-go/api/.

We welcome your feedback on this new version of the documentation. Send your comments to aws-sdkdocs-feedback@amazon.com.

Config

import "github.com/aws/aws-sdk-go/aws"

type Config struct { CredentialsChainVerboseErrors *bool Credentials *credentials.Credentials Endpoint *string EndpointResolver endpoints.Resolver EnforceShouldRetryCheck *bool Region *string DisableSSL *bool HTTPClient *http.Client LogLevel *LogLevelType Logger Logger MaxRetries *int Retryer RequestRetryer DisableParamValidation *bool DisableComputeChecksums *bool S3ForcePathStyle *bool S3Disable100Continue *bool S3UseAccelerate *bool S3DisableContentMD5Validation *bool EC2MetadataDisableTimeoutOverride *bool UseDualStack *bool SleepDelay func(time.Duration) DisableRestProtocolURICleaning *bool EnableEndpointDiscovery *bool DisableEndpointHostPrefix *bool }

A Config provides service configuration for service clients. By default, all clients will use the defaults.DefaultConfig structure.

// Create Session with MaxRetry configuration to be shared by multiple // service clients. sess := session.Must(session.NewSession(&aws.Config{ MaxRetries: aws.Int(3), })) // Create S3 service client with a specific Region. svc := s3.New(sess, &aws.Config{ Region: aws.String("us-west-2"), })

CredentialsChainVerboseErrors

Type: *bool

Enables verbose error printing of all credential chain errors. Should be used when wanting to see all errors while attempting to retrieve credentials.

Credentials

Type: *credentials.Credentials

The credentials object to use when signing requests. Defaults to a chain of credential providers to search for credentials in environment variables, shared credential file, and EC2 Instance Roles.

Endpoint

Type: *string

An optional endpoint URL (hostname only or fully qualified URI) that overrides the default generated endpoint for a client. Set this to `""` to use the default generated endpoint.

Note: You must still provide a `Region` value when specifying an endpoint for a client.

EndpointResolver

Type: endpoints.Resolver

The resolver to use for looking up endpoints for AWS service clients to use based on region.

EnforceShouldRetryCheck

Type: *bool

EnforceShouldRetryCheck is used in the AfterRetryHandler to always call ShouldRetry regardless of whether or not if request.Retryable is set. This will utilize ShouldRetry method of custom retryers. If EnforceShouldRetryCheck is not set, then ShouldRetry will only be called if request.Retryable is nil. Proper handling of the request.Retryable field is important when setting this field.

Region

Type: *string

The region to send requests to. This parameter is required and must be configured globally or on a per-client basis unless otherwise noted. A full list of regions is found in the "Regions and Endpoints" document.

See https://docs.aws.amazon.com/general/latest/gr/rande.html for AWS Regions and Endpoints.

DisableSSL

Type: *bool

Set this to `true` to disable SSL when sending requests. Defaults to `false`.

HTTPClient

Type: *http.Client

The HTTP client to use when sending requests. Defaults to `http.DefaultClient`.

LogLevel

A LogLevelType defines the level logging should be performed at. Used to instruct the SDK which statements should be logged.

Logger

A Logger is a minimalistic interface for the SDK to log messages to. Should be used to provide custom logging writers for the SDK to use.

MaxRetries

Type: *int

The maximum number of times that a request will be retried for failures. Defaults to -1, which defers the max retry setting to the service specific configuration.

Retryer

RequestRetryer is an alias for a type that implements the request.Retryer interface.

DisableParamValidation

Type: *bool

Disables semantic parameter validation, which validates input for missing required fields and/or other semantic request input errors.

DisableComputeChecksums

Type: *bool

Disables the computation of request and response checksums, e.g., CRC32 checksums in Amazon DynamoDB.

S3ForcePathStyle

Type: *bool

Set this to `true` to force the request to use path-style addressing, i.e., `http://s3.amazonaws.com/BUCKET/KEY`. By default, the S3 client will use virtual hosted bucket addressing when possible (`http://BUCKET.s3.amazonaws.com/KEY`).

Note: This configuration option is specific to the Amazon S3 service.

See https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html for Amazon S3: Virtual Hosting of Buckets

S3Disable100Continue

Type: *bool

Set this to `true` to disable the SDK adding the `Expect: 100-Continue` header to PUT requests over 2MB of content. 100-Continue instructs the HTTP client not to send the body until the service responds with a `continue` status. This is useful to prevent sending the request body until after the request is authenticated, and validated.

https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUT.html

100-Continue is only enabled for Go 1.6 and above. See `http.Transport`'s `ExpectContinueTimeout` for information on adjusting the continue wait timeout. https://golang.org/pkg/net/http/#Transport

You should use this flag to disble 100-Continue if you experience issues with proxies or third party S3 compatible services.

S3UseAccelerate

Type: *bool

Set this to `true` to enable S3 Accelerate feature. For all operations compatible with S3 Accelerate will use the accelerate endpoint for requests. Requests not compatible will fall back to normal S3 requests.

The bucket must be enable for accelerate to be used with S3 client with accelerate enabled. If the bucket is not enabled for accelerate an error will be returned. The bucket name must be DNS compatible to also work with accelerate.

S3DisableContentMD5Validation

Type: *bool

S3DisableContentMD5Validation config option is temporarily disabled, For S3 GetObject API calls, #1837.

Set this to `true` to disable the S3 service client from automatically adding the ContentMD5 to S3 Object Put and Upload API calls. This option will also disable the SDK from performing object ContentMD5 validation on GetObject API calls.

EC2MetadataDisableTimeoutOverride

Type: *bool

Set this to `true` to disable the EC2Metadata client from overriding the default http.Client's Timeout. This is helpful if you do not want the EC2Metadata client to create a new http.Client. This options is only meaningful if you're not already using a custom HTTP client with the SDK. Enabled by default.

Must be set and provided to the session.NewSession() in order to disable the EC2Metadata overriding the timeout for default credentials chain.

Example:

sess := session.Must(session.NewSession(aws.NewConfig() .WithEC2MetadataDiableTimeoutOverride(true))) svc := s3.New(sess)
UseDualStack

Type: *bool

Instructs the endpoint to be generated for a service client to be the dual stack endpoint. The dual stack endpoint will support both IPv4 and IPv6 addressing.

Setting this for a service which does not support dual stack will fail to make requets. It is not recommended to set this value on the session as it will apply to all service clients created with the session. Even services which don't support dual stack endpoints.

If the Endpoint config value is also provided the UseDualStack flag will be ignored.

Only supported with.

sess := session.Must(session.NewSession()) svc := s3.New(sess, &aws.Config{ UseDualStack: aws.Bool(true), })
SleepDelay

Type: func(time.Duration)

SleepDelay is an override for the func the SDK will call when sleeping during the lifecycle of a request. Specifically this will be used for request delays. This value should only be used for testing. To adjust the delay of a request see the aws/client.DefaultRetryer and aws/request.Retryer.

SleepDelay will prevent any Context from being used for canceling retry delay of an API operation. It is recommended to not use SleepDelay at all and specify a Retryer instead.

DisableRestProtocolURICleaning

Type: *bool

DisableRestProtocolURICleaning will not clean the URL path when making rest protocol requests. Will default to false. This would only be used for empty directory names in s3 requests.

Example:

sess := session.Must(session.NewSession(&aws.Config{ DisableRestProtocolURICleaning: aws.Bool(true), })) svc := s3.New(sess) out, err := svc.GetObject(&s3.GetObjectInput { Bucket: aws.String("bucketname"), Key: aws.String("//foo//bar//moo"), })
EnableEndpointDiscovery

Type: *bool

EnableEndpointDiscovery will allow for endpoint discovery on operations that have the definition in its model. By default, endpoint discovery is off.

Example:

sess := session.Must(session.NewSession(&aws.Config{ EnableEndpointDiscovery: aws.Bool(true), })) svc := s3.New(sess) out, err := svc.GetObject(&s3.GetObjectInput { Bucket: aws.String("bucketname"), Key: aws.String("/foo/bar/moo"), })
DisableEndpointHostPrefix

Type: *bool

DisableEndpointHostPrefix will disable the SDK's behavior of prefixing request endpoint hosts with modeled information.

Disabling this feature is useful when you want to use local endpoints for testing that do not support the modeled host prefix pattern.

Method

Copy

func (c *Config) Copy(cfgs ...*Config) *Config

Copy will return a shallow copy of the Config object. If any additional configurations are provided they will be merged into the new config returned.

MergeIn

func (c *Config) MergeIn(cfgs ...*Config)

MergeIn merges the passed in configs into the existing config object.

WithCredentials

func (c *Config) WithCredentials(creds *credentials.Credentials) *Config

WithCredentials sets a config Credentials value returning a Config pointer for chaining.

WithCredentialsChainVerboseErrors

func (c *Config) WithCredentialsChainVerboseErrors(verboseErrs bool) *Config

WithCredentialsChainVerboseErrors sets a config verbose errors boolean and returning a Config pointer.

WithDisableComputeChecksums

func (c *Config) WithDisableComputeChecksums(disable bool) *Config

WithDisableComputeChecksums sets a config DisableComputeChecksums value returning a Config pointer for chaining.

WithDisableEndpointHostPrefix

func (c *Config) WithDisableEndpointHostPrefix(t bool) *Config

WithDisableEndpointHostPrefix will set whether or not to use modeled host prefix when making requests.

WithDisableParamValidation

func (c *Config) WithDisableParamValidation(disable bool) *Config

WithDisableParamValidation sets a config DisableParamValidation value returning a Config pointer for chaining.

WithDisableSSL

func (c *Config) WithDisableSSL(disable bool) *Config

WithDisableSSL sets a config DisableSSL value returning a Config pointer for chaining.

WithEC2MetadataDisableTimeoutOverride

func (c *Config) WithEC2MetadataDisableTimeoutOverride(enable bool) *Config

WithEC2MetadataDisableTimeoutOverride sets a config EC2MetadataDisableTimeoutOverride value returning a Config pointer for chaining.

WithEndpoint

func (c *Config) WithEndpoint(endpoint string) *Config

WithEndpoint sets a config Endpoint value returning a Config pointer for chaining.

WithEndpointDiscovery

func (c *Config) WithEndpointDiscovery(t bool) *Config

WithEndpointDiscovery will set whether or not to use endpoint discovery.

WithEndpointResolver

func (c *Config) WithEndpointResolver(resolver endpoints.Resolver) *Config

WithEndpointResolver sets a config EndpointResolver value returning a Config pointer for chaining.

WithHTTPClient

func (c *Config) WithHTTPClient(client *http.Client) *Config

WithHTTPClient sets a config HTTPClient value returning a Config pointer for chaining.

WithLogLevel

func (c *Config) WithLogLevel(level LogLevelType) *Config

WithLogLevel sets a config LogLevel value returning a Config pointer for chaining.

WithLogger

func (c *Config) WithLogger(logger Logger) *Config

WithLogger sets a config Logger value returning a Config pointer for chaining.

WithMaxRetries

func (c *Config) WithMaxRetries(max int) *Config

WithMaxRetries sets a config MaxRetries value returning a Config pointer for chaining.

WithRegion

func (c *Config) WithRegion(region string) *Config

WithRegion sets a config Region value returning a Config pointer for chaining.

WithS3Disable100Continue

func (c *Config) WithS3Disable100Continue(disable bool) *Config

WithS3Disable100Continue sets a config S3Disable100Continue value returning a Config pointer for chaining.

WithS3DisableContentMD5Validation

func (c *Config) WithS3DisableContentMD5Validation(enable bool) *Config

WithS3DisableContentMD5Validation sets a config S3DisableContentMD5Validation value returning a Config pointer for chaining.

WithS3ForcePathStyle

func (c *Config) WithS3ForcePathStyle(force bool) *Config

WithS3ForcePathStyle sets a config S3ForcePathStyle value returning a Config pointer for chaining.

WithS3UseAccelerate

func (c *Config) WithS3UseAccelerate(enable bool) *Config

WithS3UseAccelerate sets a config S3UseAccelerate value returning a Config pointer for chaining.

WithSleepDelay

func (c *Config) WithSleepDelay(fn func(time.Duration)) *Config

WithSleepDelay overrides the function used to sleep while waiting for the next retry. Defaults to time.Sleep.

WithUseDualStack

func (c *Config) WithUseDualStack(enable bool) *Config

WithUseDualStack sets a config UseDualStack value returning a Config pointer for chaining.

On this page: