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.

Request

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

type Request struct { Config aws.Config ClientInfo metadata.ClientInfo Handlers Handlers Retryer AttemptTime time.Time Time time.Time Operation *Operation HTTPRequest *http.Request HTTPResponse *http.Response Body io.ReadSeeker BodyStart int64 // offset from beginning of Body that the request body starts Params interface{} Error error Data interface{} RequestID string RetryCount int Retryable *bool RetryDelay time.Duration NotHoist bool SignedHeaderVals http.Header LastSignedAt time.Time DisableFollowRedirects bool ExpireTime time.Duration }

A Request is the service request to be made.

Config

Type: aws.Config

ClientInfo

Type: metadata.ClientInfo

Handlers

A Handlers provides a collection of request handlers for various stages of handling requests.

Retryer

Retryer is an interface to control retry logic for a given service. The default implementation used by most services is the client.DefaultRetryer structure, which contains basic retry logic using exponential backoff.

AttemptTime

Type: time.Time

Time

Type: time.Time

Operation

An Operation is the service API operation to be made.

HTTPRequest

Type: type Request struct { Config aws.Config ClientInfo metadata.ClientInfo Handlers Handlers Retryer AttemptTime time.Time Time time.Time Operation *Operation HTTPRequest *http.Request HTTPResponse *http.Response Body io.ReadSeeker BodyStart int64 // offset from beginning of Body that the request body starts Params interface{} Error error Data interface{} RequestID string RetryCount int Retryable *bool RetryDelay time.Duration NotHoist bool SignedHeaderVals http.Header LastSignedAt time.Time DisableFollowRedirects bool ExpireTime time.Duration }

A Request is the service request to be made.

HTTPResponse

Type: *http.Response

Body

Type: io.ReadSeeker

BodyStart

Type: int64

Params

Type: interface{}

Error

Type: error

Data

Type: interface{}

RequestID

Type: string

RetryCount

Type: int

Retryable

Type: *bool

RetryDelay

Type: time.Duration

NotHoist

Type: bool

SignedHeaderVals

Type: http.Header

LastSignedAt

Type: time.Time

DisableFollowRedirects

Type: bool

ExpireTime

Type: time.Duration

A value greater than 0 instructs the request to be signed as Presigned URL You should not set this field directly. Instead use Request's Presign or PresignRequest methods.

Method

ApplyOptions

func (r *Request) ApplyOptions(opts ...Option)

ApplyOptions will apply each option to the request calling them in the order the were provided.

Build

func (r *Request) Build() error

Build will build the request's object so it can be signed and sent to the service. Build will also validate all the request's parameters. Any additional build Handlers set on this request will be run in the order they were set.

The request will only be built once. Multiple calls to build will have no effect.

If any Validate or Build errors occur the build will stop and the error which occurred will be returned.

Context

func (r *Request) Context() aws.Context

Context will always returns a non-nil context. If Request does not have a context aws.BackgroundContext will be returned.

DataFilled

func (r *Request) DataFilled() bool

DataFilled returns true if the request's data for response deserialization target has been set and is a valid. False is returned if data is not set, or is invalid.

EachPage

func (r *Request) EachPage(fn func(data interface{}, isLastPage bool) (shouldContinue bool)) error

EachPage iterates over each page of a paginated request object. The fn parameter should be a function with the following sample signature:

func(page *T, lastPage bool) bool { return true // return false to stop iterating }

Where "T" is the structure type matching the output structure of the given operation. For example, a request object generated by DynamoDB.ListTablesRequest() would expect to see dynamodb.ListTablesOutput as the structure "T". The lastPage value represents whether the page is the last page of data or not. The return value of this function should return true to keep iterating or false to stop.

Deprecated Use Pagination type for configurable pagination of API operations

GetBody

func (r *Request) GetBody() io.ReadSeeker

GetBody will return an io.ReadSeeker of the Request's underlying input body with a concurrency safe wrapper.

HasNextPage

func (r *Request) HasNextPage() bool

HasNextPage returns true if this request has more pages of data available.

Deprecated Use Pagination type for configurable pagination of API operations

IsErrorExpired

func (r *Request) IsErrorExpired() bool

IsErrorExpired returns whether the error code is a credential expiry error. Returns false if the request has no Error set.

Alias for the utility function IsErrorExpiredCreds

IsErrorRetryable

func (r *Request) IsErrorRetryable() bool

IsErrorRetryable returns whether the error is retryable, based on its Code. Returns false if the request has no Error set.

Alias for the utility function IsErrorRetryable

IsErrorThrottle

func (r *Request) IsErrorThrottle() bool

IsErrorThrottle returns whether the error is to be throttled based on its code. Returns false if the request has no Error set

Alias for the utility function IsErrorThrottle

IsPresigned

func (r *Request) IsPresigned() bool

IsPresigned returns true if the request represents a presigned API url.

NextPage

func (r *Request) NextPage() *Request

NextPage returns a new Request that can be executed to return the next page of result data. Call .Send() on this request to execute it.

Deprecated Use Pagination type for configurable pagination of API operations

ParamsFilled

func (r *Request) ParamsFilled() bool

ParamsFilled returns if the request's parameters have been populated and the parameters are valid. False is returned if no parameters are provided or invalid.

Presign

func (r *Request) Presign(expire time.Duration) (string, error)

Presign returns the request's signed URL. Error will be returned if the signing fails. The expire parameter is only used for presigned Amazon S3 API requests. All other AWS services will use a fixed expiration time of 15 minutes.

It is invalid to create a presigned URL with a expire duration 0 or less. An error is returned if expire duration is 0 or less.

PresignRequest

func (r *Request) PresignRequest(expire time.Duration) (string, http.Header, error)

PresignRequest behaves just like presign, with the addition of returning a set of headers that were signed. The expire parameter is only used for presigned Amazon S3 API requests. All other AWS services will use a fixed expiration time of 15 minutes.

It is invalid to create a presigned URL with a expire duration 0 or less. An error is returned if expire duration is 0 or less.

Returns the URL string for the API operation with signature in the query string, and the HTTP headers that were included in the signature. These headers must be included in any HTTP request made with the presigned URL.

To prevent hoisting any headers to the query string set NotHoist to true on this Request value prior to calling PresignRequest.

ResetBody

func (r *Request) ResetBody()

ResetBody rewinds the request body back to its starting position, and sets the HTTP Request body reference. When the body is read prior to being sent in the HTTP request it will need to be rewound.

ResetBody will automatically be called by the SDK's build handler, but if the request is being used directly ResetBody must be called before the request is Sent. SetStringBody, SetBufferBody, and SetReaderBody will automatically call ResetBody.

Will also set the Go 1.8's http.Request.GetBody member to allow retrying PUT/POST redirects.

Send

func (r *Request) Send() error

Send will send the request, returning error if errors are encountered.

Send will sign the request prior to sending. All Send Handlers will be executed in the order they were set.

Canceling a request is non-deterministic. If a request has been canceled, then the transport will choose, randomly, one of the state channels during reads or getting the connection.

readLoop() and getConn(req *Request, cm connectMethod) https://github.com/golang/go/blob/master/src/net/http/transport.go

Send will not close the request.Request's body.

SetBufferBody

func (r *Request) SetBufferBody(buf []byte)

SetBufferBody will set the request's body bytes that will be sent to the service API.

SetContext

func (r *Request) SetContext(ctx aws.Context)

SetContext adds a Context to the current request that can be used to cancel a in-flight request. The Context value must not be nil, or this method will panic.

Unlike http.Request.WithContext, SetContext does not return a copy of the Request. It is not safe to use use a single Request value for multiple requests. A new Request should be created for each API operation request.

Go 1.6 and below: The http.Request's Cancel field will be set to the Done() value of the context. This will overwrite the Cancel field's value.

Go 1.7 and above: The http.Request.WithContext will be used to set the context on the underlying http.Request. This will create a shallow copy of the http.Request. The SDK may create sub contexts in the future for nested requests such as retries.

SetReaderBody

func (r *Request) SetReaderBody(reader io.ReadSeeker)

SetReaderBody will set the request's body reader.

SetStringBody

func (r *Request) SetStringBody(s string)

SetStringBody sets the body of the request to be backed by a string.

Sign

func (r *Request) Sign() error

Sign will sign the request, returning error if errors are encountered.

Sign will build the request prior to signing. All Sign Handlers will be executed in the order they were set.

WillRetry

func (r *Request) WillRetry() bool

WillRetry returns if the request's can be retried.

On this page: