diff --git a/docs/docs/sdk-utilities/ec2-imds/index.html b/docs/docs/sdk-utilities/ec2-imds/index.html
index a8b10218c50..5ad140b2dbc 100644
--- a/docs/docs/sdk-utilities/ec2-imds/index.html
+++ b/docs/docs/sdk-utilities/ec2-imds/index.html
@@ -104,7 +104,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -126,7 +126,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -602,7 +602,7 @@
Retrieving an Instance’s Region
- © 2023 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
+ © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
diff --git a/docs/docs/sdk-utilities/index.html b/docs/docs/sdk-utilities/index.html
index 7721e922f3f..af3a2269a5e 100644
--- a/docs/docs/sdk-utilities/index.html
+++ b/docs/docs/sdk-utilities/index.html
@@ -100,7 +100,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -122,7 +122,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -578,7 +578,7 @@
- © 2023 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
+ © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
diff --git a/docs/docs/sdk-utilities/rds/index.html b/docs/docs/sdk-utilities/rds/index.html
index 3fd39ad387f..535dadc0e19 100644
--- a/docs/docs/sdk-utilities/rds/index.html
+++ b/docs/docs/sdk-utilities/rds/index.html
@@ -104,7 +104,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -126,7 +126,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -572,7 +572,7 @@
IAM Authentication
- © 2023 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
+ © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
diff --git a/docs/docs/sdk-utilities/s3/index.html b/docs/docs/sdk-utilities/s3/index.html
index c576ebfe5a0..f9a964bd462 100644
--- a/docs/docs/sdk-utilities/s3/index.html
+++ b/docs/docs/sdk-utilities/s3/index.html
@@ -109,7 +109,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -131,7 +131,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -954,7 +954,7 @@
- © 2023 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
+ © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
diff --git a/docs/docs/security/compliance-validation/index.html b/docs/docs/security/compliance-validation/index.html
index 29b411eca14..47714b01396 100644
--- a/docs/docs/security/compliance-validation/index.html
+++ b/docs/docs/security/compliance-validation/index.html
@@ -111,7 +111,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -133,7 +133,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -574,7 +574,7 @@
Compliance Validation for this AWS Product or Service
- © 2023 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
+ © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
diff --git a/docs/docs/security/data-protection/index.html b/docs/docs/security/data-protection/index.html
index 8a56bdd7a0f..75caffa0285 100644
--- a/docs/docs/security/data-protection/index.html
+++ b/docs/docs/security/data-protection/index.html
@@ -105,7 +105,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -127,7 +127,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -566,7 +566,7 @@
Data Protection in this AWS Product or Service
- © 2023 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
+ © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
diff --git a/docs/docs/security/disaster-recovery-resiliency/index.html b/docs/docs/security/disaster-recovery-resiliency/index.html
index b3a2c4fbd13..811f895a197 100644
--- a/docs/docs/security/disaster-recovery-resiliency/index.html
+++ b/docs/docs/security/disaster-recovery-resiliency/index.html
@@ -111,7 +111,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -133,7 +133,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -558,7 +558,7 @@
Resilience for this AWS Product or Service
- © 2023 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
+ © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
diff --git a/docs/docs/security/iam/index.html b/docs/docs/security/iam/index.html
index 8fc747f36f2..78d1e0e5a86 100644
--- a/docs/docs/security/iam/index.html
+++ b/docs/docs/security/iam/index.html
@@ -108,7 +108,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -130,7 +130,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -558,7 +558,7 @@
Identity and Access Management for this AWS Product or Service
- © 2023 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
+ © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
diff --git a/docs/docs/security/index.html b/docs/docs/security/index.html
index fb00c8a7a71..c704320629f 100644
--- a/docs/docs/security/index.html
+++ b/docs/docs/security/index.html
@@ -101,7 +101,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -123,7 +123,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -605,7 +605,7 @@
- © 2023 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
+ © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
diff --git a/docs/docs/security/infrastructure-security/index.html b/docs/docs/security/infrastructure-security/index.html
index 97180600363..d7ba27e85e4 100644
--- a/docs/docs/security/infrastructure-security/index.html
+++ b/docs/docs/security/infrastructure-security/index.html
@@ -110,7 +110,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -132,7 +132,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -553,7 +553,7 @@
Infrastructure Security for this AWS Product or Service
- © 2023 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
+ © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
diff --git a/docs/docs/security/tls/index.html b/docs/docs/security/tls/index.html
index 13f447ccf87..a48a8f85ec0 100644
--- a/docs/docs/security/tls/index.html
+++ b/docs/docs/security/tls/index.html
@@ -108,7 +108,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -130,7 +130,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -595,7 +595,7 @@
Enforcing a Minimum TLS Version
- © 2023 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
+ © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
diff --git a/docs/docs/unit-testing/index.html b/docs/docs/unit-testing/index.html
index 9a2b67cfc78..b244cba83c0 100644
--- a/docs/docs/unit-testing/index.html
+++ b/docs/docs/unit-testing/index.html
@@ -104,7 +104,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -126,7 +126,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -720,7 +720,7 @@
Mocking Client Operations
- © 2023 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
+ © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
diff --git a/docs/index.html b/docs/index.html
index 530e9941cc6..3286fece39c 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -124,7 +124,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f367ad73ebaf545fd290f98fd7fb18f5.json"
+ data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
@@ -303,7 +303,7 @@
Extensible
- © 2023 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
+ © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved
diff --git a/docs/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json b/docs/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json
new file mode 100644
index 00000000000..609b653ee54
--- /dev/null
+++ b/docs/offline-search-index.f7b818cc28b8e9e5e837a0faaac05d9e.json
@@ -0,0 +1 @@
+[{"body":"Welcome to the AWS SDK for Go. The AWS SDK for Go V2 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).\nThe 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.\nThe SDK also includes helpful utilities. For example, the Amazon S3 download and upload manager can automatically break up large objects into multiple parts and transfer them in parallel.\nUse the AWS SDK for Go Developer Guide to help you install, configure, and use the SDK. The guide provides configuration information, sample code, and an introduction to the SDK utilities.\nMaintenance and support for SDK major versions For information about maintenance and support for SDK major versions and their underlying dependencies, see the following in the AWS SDKs and Tools Shared Configuration and Credentials Reference Guide:\nAWS SDKs and Tools Maintenance Policy AWS SDKs and Tools Version Support Matrix ","categories":"","description":"","excerpt":"Welcome to the AWS SDK for Go. The AWS SDK for Go V2 provides APIs and …","ref":"/aws-sdk-go-v2/docs/","tags":"","title":"Developer Guide"},{"body":"When debugging timeout / latency issues in the SDK, it is critical to identify the components of the operation lifecycle which are taking more time to execute than expected. As a starting point, you will generally need to inspect the timing breakdown between the overall operation call and the HTTP call itself.\nThe following sample program implements a basic instrumentation probe in terms of smithy-go middleware for SQS clients and demonstrates how it is used. The probe emits the following information for each operation call:\nAWS request ID service ID operation name operation invocation time http call time Each emitted message is prefixed with a unique (to a single operation) “invocation ID” which is set at the beginning of the handler stack.\nThe entry point for instrumentation is exposed as WithOperationTiming, which is parameterized to accept a message handling function which will receive instrumentation “events” as formatted strings. PrintfMSGHandler is provided as a convenience which will simply dump messages to stdout.\nThe service used here is interchangeable - ALL service client options accept APIOptions and an HTTPClient as configuration. For example, WithOperationTiming could instead be declared as:\nfunc WithOperationTiming(msgHandler func(string)) func(*s3.Options) func WithOperationTiming(msgHandler func(string)) func(*dynamodb.Options) // etc. If you change it, be sure to change the signature of the function it returns as well.\nimport ( \"context\" \"fmt\" \"log\" \"net/http\" \"sync\" \"time\" awsmiddleware \"github.com/aws/aws-sdk-go-v2/aws/middleware\" awshttp \"github.com/aws/aws-sdk-go-v2/aws/transport/http\" \"github.com/aws/aws-sdk-go-v2/config\" \"github.com/aws/aws-sdk-go-v2/service/sqs\" \"github.com/aws/smithy-go/middleware\" smithyrand \"github.com/aws/smithy-go/rand\" ) // WithOperationTiming instruments an SQS client to dump timing information for // the following spans: // - overall operation time // - HTTPClient call time // // This instrumentation will also emit the request ID, service name, and // operation name for each invocation. // // Accepts a message \"handler\" which is invoked with formatted messages to be // handled externally, you can use the declared PrintfMSGHandler to simply dump // these values to stdout. func WithOperationTiming(msgHandler func(string)) func(*sqs.Options) { return func(o *sqs.Options) { o.APIOptions = append(o.APIOptions, addTimingMiddlewares(msgHandler)) o.HTTPClient = \u0026timedHTTPClient{ client: awshttp.NewBuildableClient(), msgHandler: msgHandler, } } } // PrintfMSGHandler writes messages to stdout. func PrintfMSGHandler(msg string) { fmt.Printf(\"%s\\n\", msg) } type invokeIDKey struct{} func setInvokeID(ctx context.Context, id string) context.Context { return middleware.WithStackValue(ctx, invokeIDKey{}, id) } func getInvokeID(ctx context.Context) string { id, _ := middleware.GetStackValue(ctx, invokeIDKey{}).(string) return id } // Records the current time, and returns a function to be called when the // target span of events is completed. The return function will emit the given // span name and time elapsed to the given message consumer. func timeSpan(ctx context.Context, name string, consumer func(string)) func() { start := time.Now() return func() { elapsed := time.Now().Sub(start) consumer(fmt.Sprintf(\"[%s] %s: %s\", getInvokeID(ctx), name, elapsed)) } } type timedHTTPClient struct { client *awshttp.BuildableClient msgHandler func(string) } func (c *timedHTTPClient) Do(r *http.Request) (*http.Response, error) { defer timeSpan(r.Context(), \"http\", c.msgHandler)() resp, err := c.client.Do(r) if err != nil { return nil, fmt.Errorf(\"inner client do: %v\", err) } return resp, nil } type addInvokeIDMiddleware struct { msgHandler func(string) } func (*addInvokeIDMiddleware) ID() string { return \"addInvokeID\" } func (*addInvokeIDMiddleware) HandleInitialize(ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler) ( out middleware.InitializeOutput, md middleware.Metadata, err error, ) { id, err := smithyrand.NewUUID(smithyrand.Reader).GetUUID() if err != nil { return out, md, fmt.Errorf(\"new uuid: %v\", err) } return next.HandleInitialize(setInvokeID(ctx, id), in) } type timeOperationMiddleware struct { msgHandler func(string) } func (*timeOperationMiddleware) ID() string { return \"timeOperation\" } func (m *timeOperationMiddleware) HandleInitialize(ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler) ( middleware.InitializeOutput, middleware.Metadata, error, ) { defer timeSpan(ctx, \"operation\", m.msgHandler)() return next.HandleInitialize(ctx, in) } type emitMetadataMiddleware struct { msgHandler func(string) } func (*emitMetadataMiddleware) ID() string { return \"emitMetadata\" } func (m *emitMetadataMiddleware) HandleInitialize(ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler) ( middleware.InitializeOutput, middleware.Metadata, error, ) { out, md, err := next.HandleInitialize(ctx, in) invokeID := getInvokeID(ctx) requestID, _ := awsmiddleware.GetRequestIDMetadata(md) service := awsmiddleware.GetServiceID(ctx) operation := awsmiddleware.GetOperationName(ctx) m.msgHandler(fmt.Sprintf(`[%s] requestID = \"%s\"`, invokeID, requestID)) m.msgHandler(fmt.Sprintf(`[%s] service = \"%s\"`, invokeID, service)) m.msgHandler(fmt.Sprintf(`[%s] operation = \"%s\"`, invokeID, operation)) return out, md, err } func addTimingMiddlewares(mh func(string)) func(*middleware.Stack) error { return func(s *middleware.Stack) error { if err := s.Initialize.Add(\u0026timeOperationMiddleware{msgHandler: mh}, middleware.Before); err != nil { return fmt.Errorf(\"add time operation middleware: %v\", err) } if err := s.Initialize.Add(\u0026addInvokeIDMiddleware{msgHandler: mh}, middleware.Before); err != nil { return fmt.Errorf(\"add invoke id middleware: %v\", err) } if err := s.Initialize.Insert(\u0026emitMetadataMiddleware{msgHandler: mh}, \"RegisterServiceMetadata\", middleware.After); err != nil { return fmt.Errorf(\"add emit metadata middleware: %v\", err) } return nil } } func main() { cfg, err := config.LoadDefaultConfig(context.Background()) if err != nil { log.Fatal(fmt.Errorf(\"load default config: %v\", err)) } svc := sqs.NewFromConfig(cfg, WithOperationTiming(PrintfMSGHandler)) var wg sync.WaitGroup for i := 0; i \u003c 6; i++ { wg.Add(1) go func() { defer wg.Done() _, err = svc.ListQueues(context.Background(), nil) if err != nil { fmt.Println(fmt.Errorf(\"list queues: %v\", err)) } }() } wg.Wait() } A sample output of this program:\n[e9a801bb-c51d-45c8-8e9f-a202e263fde8] http: 192.24067ms [e9a801bb-c51d-45c8-8e9f-a202e263fde8] requestID = \"dbee3082-96a3-5b23-adca-6d005696fa94\" [e9a801bb-c51d-45c8-8e9f-a202e263fde8] service = \"SQS\" [e9a801bb-c51d-45c8-8e9f-a202e263fde8] operation = \"ListQueues\" [e9a801bb-c51d-45c8-8e9f-a202e263fde8] operation: 193.098393ms [0740f0e0-953e-4328-94fc-830a5052e763] http: 195.185732ms [0740f0e0-953e-4328-94fc-830a5052e763] requestID = \"48b301fa-fc9f-5f1f-9007-5c783caa9322\" [0740f0e0-953e-4328-94fc-830a5052e763] service = \"SQS\" [0740f0e0-953e-4328-94fc-830a5052e763] operation = \"ListQueues\" [0740f0e0-953e-4328-94fc-830a5052e763] operation: 195.725491ms [c0589832-f351-4cc7-84f1-c656eb79dbd7] http: 200.52383ms [444030d0-6743-4de5-bd91-bc40b2b94c55] http: 200.525919ms [c0589832-f351-4cc7-84f1-c656eb79dbd7] requestID = \"4a73cc82-b47b-56e1-b327-9100744e1b1f\" [c0589832-f351-4cc7-84f1-c656eb79dbd7] service = \"SQS\" [c0589832-f351-4cc7-84f1-c656eb79dbd7] operation = \"ListQueues\" [c0589832-f351-4cc7-84f1-c656eb79dbd7] operation: 201.214365ms [444030d0-6743-4de5-bd91-bc40b2b94c55] requestID = \"ca1523ed-1879-5610-bf5d-7e6fd84cabee\" [444030d0-6743-4de5-bd91-bc40b2b94c55] service = \"SQS\" [444030d0-6743-4de5-bd91-bc40b2b94c55] operation = \"ListQueues\" [444030d0-6743-4de5-bd91-bc40b2b94c55] operation: 201.197071ms [079e8dbd-bb93-43ab-89e5-a7bb392b86a5] http: 206.449568ms [12b2b39d-df86-4648-a436-ff0482d13340] http: 206.526603ms [079e8dbd-bb93-43ab-89e5-a7bb392b86a5] requestID = \"64229710-b552-56ed-8f96-ca927567ec7b\" [079e8dbd-bb93-43ab-89e5-a7bb392b86a5] service = \"SQS\" [079e8dbd-bb93-43ab-89e5-a7bb392b86a5] operation = \"ListQueues\" [079e8dbd-bb93-43ab-89e5-a7bb392b86a5] operation: 207.252357ms [12b2b39d-df86-4648-a436-ff0482d13340] requestID = \"76d9cbc0-07aa-58aa-98b7-9642c79f9851\" [12b2b39d-df86-4648-a436-ff0482d13340] service = \"SQS\" [12b2b39d-df86-4648-a436-ff0482d13340] operation = \"ListQueues\" [12b2b39d-df86-4648-a436-ff0482d13340] operation: 207.360621ms ","categories":"","description":"How to perform basic instrumentation in the {{% alias sdk-go %}} to time SDK operations","excerpt":"How to perform basic instrumentation in the {{% alias sdk-go %}} to …","ref":"/aws-sdk-go-v2/docs/faq/timing-operations/","tags":"","title":"Timing SDK operations"},{"body":"The AWS SDK for Go requires Go 1.20 or later. You can view your current version of Go by running the following command:\ngo version For information about installing or upgrading your version of Go, see https://golang.org/doc/install.\nGet an Amazon Account Before you can use the AWS SDK for Go V2, you must have an Amazon account. See How do I create and activate a new AWS account? for details.\nInstall the AWS SDK for Go V2 The AWS SDK for Go V2 uses Go Modules, which was a feature introduced in Go 1.11. To get started initialize your local project by running the following Go command.\ngo mod init example After initializing your Go Module project you will be able to retrieve the SDK, and its required dependencies using the go get command. These dependencies will be recorded in the go.mod file which was created by the previous command.\nThe following commands show how to retrieve the standard set of SDK modules to use in your application.\ngo get github.com/aws/aws-sdk-go-v2 go get github.com/aws/aws-sdk-go-v2/config This will retrieve the core SDK module, and the config module which is used for loading the AWS shared configuration.\nNext you can install one or more AWS service API clients required by your application. All API clients are located under github.com/aws/aws-sdk-go-v2/service import hierarchy. A complete set of currently supported API clients can be found here. To install a service client, execute the following command to retrieve the module and record the dependency in your go.mod file. In this example we retrieve the Amazon S3 API client.\ngo get github.com/aws/aws-sdk-go-v2/service/s3 Get your AWS access keys Access keys consist of an access key ID and secret access key, which are used to sign programmatic requests that you make to AWS. If you don’t have access keys, you can create them by using the AWS Management Console. We recommend that you use IAM access keys instead of AWS root account access keys. IAM lets you securely control access to AWS services and resources in your AWS account. Note\nTo create access keys, you must have permissions to perform the required IAM actions. For more information, see Granting IAM User Permission to Manage Password Policy and Credentials in the IAM User Guide.\nTo get your access key ID and secret access key. Open the IAM console On the navigation menu, choose Users. Choose your IAM user name (not the check box). Open the Security credentials tab, and then choose Create access key. To see the new access key, choose Show. Your credentials resemble the following: Access key ID: AKIAIOSFODNN7EXAMPLE Secret access key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY To download the key pair, choose Download .csv file. Store the keys in a secure location. Keep the keys confidential to protect your AWS account, and never email them. Do not share them outside your organization, even if an inquiry appears to come from AWS or Amazon.com. No one who legitimately represents Amazon will ever ask you for your secret key.\nRelated topics What Is IAM? in IAM User Guide. AWS Security Credentials in Amazon Web Services General Reference. Invoke an Operation After you have installed the SDK, you import AWS packages into your Go applications to use the SDK, as shown in the following example, which imports the AWS, Config, and Amazon S3 libraries. After importing the SDK packages, the AWS SDK Shared Configuration is loaded, a client is constructed, and an API operation is invoked.\npackage main import ( \"context\" \"log\" \"github.com/aws/aws-sdk-go-v2/aws\" \"github.com/aws/aws-sdk-go-v2/config\" \"github.com/aws/aws-sdk-go-v2/service/s3\" ) func main() { // Load the Shared AWS Configuration (~/.aws/config) cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { log.Fatal(err) } // Create an Amazon S3 service client client := s3.NewFromConfig(cfg) // Get the first page of results for ListObjectsV2 for a bucket output, err := client.ListObjectsV2(context.TODO(), \u0026s3.ListObjectsV2Input{ Bucket: aws.String(\"my-bucket\"), }) if err != nil { log.Fatal(err) } log.Println(\"first page results:\") for _, object := range output.Contents { log.Printf(\"key=%s size=%d\", aws.ToString(object.Key), object.Size) } } ","categories":"","description":"","excerpt":"The AWS SDK for Go requires Go 1.20 or later. You can view your …","ref":"/aws-sdk-go-v2/docs/getting-started/","tags":"","title":"Getting Started with the AWS SDK for Go V2"},{"body":"This section contains code examples for Amazon CloudWatch using version 2 of the AWS SDK for Go.\n","categories":"","description":"","excerpt":"This section contains code examples for Amazon CloudWatch using …","ref":"/aws-sdk-go-v2/docs/code-examples/cloudwatch/","tags":"","title":"Amazon CloudWatch Examples"},{"body":"This section contains code examples for Amazon DynamoDB using version 2 of the AWS SDK for Go.\n","categories":"","description":"","excerpt":"This section contains code examples for Amazon DynamoDB using version …","ref":"/aws-sdk-go-v2/docs/code-examples/dynamodb/","tags":"","title":"Amazon DynamoDB Examples"},{"body":"This section contains code examples for Amazon EC2 using version 2 of the AWS SDK for Go.\n","categories":"","description":"","excerpt":"This section contains code examples for Amazon EC2 using version 2 of …","ref":"/aws-sdk-go-v2/docs/code-examples/ec2/","tags":"","title":"Amazon EC2 Examples"},{"body":"This section contains code examples for Amazon S3 using version 2 of the AWS SDK for Go.\n","categories":"","description":"","excerpt":"This section contains code examples for Amazon S3 using version 2 of …","ref":"/aws-sdk-go-v2/docs/code-examples/s3/","tags":"","title":"Amazon S3 Examples"},{"body":"This section contains code examples for Amazon SNS using version 2 of the AWS SDK for Go.\n","categories":"","description":"","excerpt":"This section contains code examples for Amazon SNS using version 2 of …","ref":"/aws-sdk-go-v2/docs/code-examples/sns/","tags":"","title":"Amazon SNS Examples"},{"body":"This section contains code examples for Amazon SQS using version 2 of the AWS SDK for Go.\n","categories":"","description":"","excerpt":"This section contains code examples for Amazon SQS using version 2 of …","ref":"/aws-sdk-go-v2/docs/code-examples/sqs/","tags":"","title":"Amazon SQS Examples"},{"body":"This section contains code examples for AWS KMS using version 2 of the AWS SDK for Go.\n","categories":"","description":"","excerpt":"This section contains code examples for AWS KMS using version 2 of the …","ref":"/aws-sdk-go-v2/docs/code-examples/kms/","tags":"","title":"AWS KMS Examples"},{"body":"This section contains code examples for AWS STS using version 2 of the AWS SDK for Go.\n","categories":"","description":"","excerpt":"This section contains code examples for AWS STS using version 2 of the …","ref":"/aws-sdk-go-v2/docs/code-examples/sts/","tags":"","title":"AWS STS Examples"},{"body":"This section contains code examples for AWS Systems Manager using version 2 of the AWS SDK for Go.\n","categories":"","description":"","excerpt":"This section contains code examples for AWS Systems Manager using …","ref":"/aws-sdk-go-v2/docs/code-examples/ssm/","tags":"","title":"AWS Systems Manager Examples"},{"body":"In the AWS SDK for Go V2, you can configure common settings for service clients, such as the logger, log level, and retry configuration. Most settings are optional. However, for each service client, you must specify an AWS Region and your credentials. The SDK uses these values to send requests to the correct Region and sign requests with the correct credentials. You can specify these values as programmatically in code, or via the execution environment.\nLoading AWS Shared Configuration There are a number of ways to initialize a service API client, but the following is the most common pattern recommended to users.\nTo configure the SDK to use the AWS shared configuration use the following code:\nimport ( \"context\" \"log\" \"github.com/aws/aws-sdk-go-v2/config\" ) // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { log.Fatalf(\"failed to load configuration, %v\", err) } config.LoadDefaultConfig(context.TODO()) will construct an aws.Config using the AWS shared configuration sources. This includes configuring a credential provider, configuring the AWS Region, and loading service specific configuration. Service clients can be constructed using the loaded aws.Config, providing a consistent pattern for constructing clients.\nFor more information about AWS Shared Configuration see the AWS Tools and SDKs Shared Configuration and Credentials Reference Guide Specifying the AWS Region When you specify the Region, you specify where to send requests, such as us-west-2 or us-east-2. For a list of Regions for each service, see Regions and Endpoints in the Amazon Web Services General Reference.\nThe SDK does not have a default Region. To specify a Region:\nSet the AWS_REGION environment variable to the default Region\nSet the region explicitly using config.WithRegion as an argument to config.LoadDefaultConfig when loading configuration.\nIf you set a Region using all of these techniques, the SDK uses the Region you explicitly specified.\nConfigure Region with Environment Variable Linux, macOS, or Unix export AWS_REGION=us-west-2 Windows set AWS_REGION=us-west-2 Specify Region Programmatically cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion(\"us-west-2\")) Specifying Credentials The AWS SDK for Go V2 requires credentials (an access key and secret access key) to sign requests to AWS. You can specify your credentials in several locations, depending on your particular use case. For information about obtaining credentials, see Getting Started.\nWhen you initialize an aws.Config instance using config.LoadDefaultConfig, the SDK uses its default credential chain to find AWS credentials. This default credential chain looks for credentials in the following order:\nEnvironment variables. Static Credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN) Web Identity Token (AWS_WEB_IDENTITY_TOKEN_FILE) Shared configuration files. SDK defaults to credentials file under .aws folder that is placed in the home folder on your computer. SDK defaults to config file under .aws folder that is placed in the home folder on your computer. If your application uses an ECS task definition or RunTask API operation, IAM role for tasks. If your application is running on an Amazon EC2 instance, IAM role for Amazon EC2. The SDK detects and uses the built-in providers automatically, without requiring manual configurations. For example, if you use IAM roles for Amazon EC2 instances, your applications automatically use the instance’s credentials. You don’t need to manually configure credentials in your application.\nAs a best practice, AWS recommends that you specify credentials in the following order:\nUse IAM roles for tasks if your application uses an ECS task definition or RunTask API operation.\nUse IAM roles for Amazon EC2 (if your application is running on an Amazon EC2 instance).\nIAM roles provide applications on the instance temporary security credentials to make AWS calls. IAM roles provide an easy way to distribute and manage credentials on multiple Amazon EC2 instances.\nUse shared credentials or config files.\nThe credentials and config files are shared across other AWS SDKs and AWS CLI. As a security best practice, we recommend using credentials file for setting sensitive values such as access key IDs and secret keys. Here are the formatting requirements for each of these files.\nUse environment variables.\nSetting environment variables is useful if you’re doing development work on a machine other than an Amazon EC2 instance.\nIAM Roles for Tasks If your application uses an Amazon ECS task definition or RunTask operation, use IAM Roles for Tasks to specify an IAM role that can be used by the containers in a task.\nIAM Roles for Amazon EC2 Instances If you are running your application on an Amazon EC2 instance, use the instance’s IAM role to get temporary security credentials to make calls to AWS.\nIf you have configured your instance to use IAM roles, the SDK uses these credentials for your application automatically. You don’t need to manually specify these credentials.\nShared Credentials and Configuration The shared credentials and config files can be used to share common configuration amongst AWS SDKs and other tools. If you use different credentials for different tools or applications, you can use profiles to configure multiple access keys in the same configuration file.\nYou can provide multiple credential or config files locations using config.LoadOptions, by default the SDK loads files stored at default locations mentioned in the specifying credentials section.\nimport ( \"context\" \"github.com/aws/aws-sdk-go-v2/config\" ) // ... cfg , err := config.LoadDefaultConfig(context.TODO(), config.WithSharedCredentialsFiles( []string{\"test/credentials\", \"data/credentials\"}, ), config.WithSharedConfigFiles( []string{\"test/config\", \"data/config\"}, )\t) When working with shared credentials and config files, if duplicate profiles are specified they are merged to resolve a profile. In case of merge conflict,\nIf duplicate profiles are specified within a same credentials/config file, the profile properties specified in the latter profile takes precedence.\nIf duplicate profiles are specified across either multiple credentials files or across multiple config files, the profile properties are resolved as per the order of file input to the config.LoadOptions. The profile properties in the latter files take precedence.\nIf a profile exists in both credentials file and config file, the credentials file properties take precedence.\nIf need be, you can enable LogConfigurationWarnings on config.LoadOptions, and log the profile resolution steps.\nCreating the Credentials File If you don’t have a shared credentials file (.aws/credentials), you can use any text editor to create one in your home directory. Add the following content to your credentials file, replacing \u003cYOUR_ACCESS_KEY_ID\u003e and \u003cYOUR_SECRET_ACCESS_KEY\u003e with your credentials.\n[default] aws_access_key_id = \u003cYOUR_ACCESS_KEY_ID\u003e aws_secret_access_key = \u003cYOUR_SECRET_ACCESS_KEY\u003e The [default] heading defines credentials for the default profile, which the SDK will use unless you configure it to use another profile.\nYou can also use temporary security credentials by adding the session tokens to your profile, as shown in the following example:\n[temp] aws_access_key_id = \u003cYOUR_TEMP_ACCESS_KEY_ID\u003e aws_secret_access_key = \u003cYOUR_TEMP_SECRET_ACCESS_KEY\u003e aws_session_token = \u003cYOUR_SESSION_TOKEN\u003e The section name for a non-default profile within a credentials file must not begin with the word profile. You can read more at AWS Tools and SDKs Shared Configuration and Credentials Reference Guide.\nCreating the Config File If you don’t have a shared credentials file (.aws/config), you can use any text editor to create one in your home directory. Add the following content to your config file, replacing \u003cREGION\u003e with the desired region.\n[default] region = \u003cREGION\u003e The [default] heading defines config for the default profile, which the SDK will use unless you configure it to use another profile.\nYou use named profiles, as shown in the following example:\n[profile named-profile] region = \u003cREGION\u003e The section name for a non-default profile within a config file must always begin with the word profile , followed by the intended profile name. You can read more at AWS Tools and SDKs Shared Configuration and Credentials Reference Guide.\nSpecifying Profiles You can include multiple access keys in the same configuration file by associating each set of access keys with a profile. For example, in your credentials file, you can declare multiple profiles, as follows.\n[default] aws_access_key_id = \u003cYOUR_DEFAULT_ACCESS_KEY_ID\u003e aws_secret_access_key = \u003cYOUR_DEFAULT_SECRET_ACCESS_KEY\u003e [test-account] aws_access_key_id = \u003cYOUR_TEST_ACCESS_KEY_ID\u003e aws_secret_access_key = \u003cYOUR_TEST_SECRET_ACCESS_KEY\u003e [prod-account] ; work profile aws_access_key_id = \u003cYOUR_PROD_ACCESS_KEY_ID\u003e aws_secret_access_key = \u003cYOUR_PROD_SECRET_ACCESS_KEY\u003e By default, the SDK checks the AWS_PROFILE environment variable to determine which profile to use. If no AWS_PROFILE variable is set, the SDK uses the default profile.\nSometimes, you may want to use a different profile with your application. For example let’s say you want to use the test-account credentials with your myapp application. You can, use this profile by using the following command:\n$ AWS_PROFILE=test-account myapp You can also use instruct the SDK to select a profile by either os.Setenv(\"AWS_PROFILE\", \"test-account\") before calling config.LoadDefaultConfig, or by passing an explicit profile as an argument as shown in the following example:\ncfg, err := config.LoadDefaultConfig(context.TODO(), config.WithSharedConfigProfile(\"test-account\")) If you specify credentials in environment variables, the SDK always uses those credentials, no matter which profile you specify.\nEnvironment Variables By default, the SDK detects AWS credentials set in your environment and uses them to sign requests to AWS. That way you don’t need to manage credentials in your applications.\nThe SDK looks for credentials in the following environment variables:\nAWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN (optional) The following examples show how you configure the environment variables.\nLinux, OS X, or Unix $ export AWS_ACCESS_KEY_ID=YOUR_AKID $ export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY $ export AWS_SESSION_TOKEN=TOKEN Windows \u003e set AWS_ACCESS_KEY_ID=YOUR_AKID \u003e set AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY \u003e set AWS_SESSION_TOKEN=TOKEN Specify Credentials Programmatically config.LoadDefaultConfig allows you to provide an explicit aws.CredentialProvider when loading the shared configuration sources. To pass an explicity credential provider when loading shared configuration use config.WithCredentialsProvider. For example, if customProvider references an instance of aws.CredentialProvider implementation, it can be passed during configuration loading like so:\ncfg, err := config.LoadDefaultConfig(context.TODO(), config.WithCredentialsProvider(customProvider)) If you explicitly provide credentials, as in this example, the SDK uses only those credentials.\nAll credential providers passed to or returned by LoadDefaultConfig are wrapped in a CredentialsCache automatically. This enables caching and concurrency safe credential access. If you explicitly configure a provider on aws.Config directly you must explicitly wrap the provider with this type using NewCredentialsCache.\nStatic Credentials You can hard-code credentials in your application by using the credentials.NewStaticCredentialsProvider credential provider to explicitly set the access keys to be used. For example:\ncfg, err := config.LoadDefaultConfig(context.TODO(), config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(\"AKID\", \"SECRET_KEY\", \"TOKEN\")), ) Do not embed credentials inside an application. Use this method only for testing purposes.\nSingle Sign-on Credentials The SDK provides a credential provider for retrieving temporary AWS credentials using AWS IAM Identity Center (successor to AWS Single Sign-On). Using the AWS CLI, you authenticate with the AWS access portal and authorize access to temporary AWS credentials. You then configure your application to load the single sign-on (SSO) profile, and the SDK uses your SSO credentials to retrieve temporary AWS credentials that will be automatically renewed if expired. If your SSO credentials expire, you must explicitly renew them by logging in to your IAM Identity Center account again using the AWS CLI.\nFor example, you can create a profile, dev-profile, authenticate and authorize that profile using the AWS CLI, and configure your application as shown below.\nFirst create the profile and sso-session [profile dev-profile] sso_session = dev-session sso_account_id = 012345678901 sso_role_name = Developer region = us-east-1 [sso-session dev-session] sso_region = us-west-2 sso_start_url = https://company-sso-portal.awsapps.com/start sso_registration_scopes = sso:account:access Login using the AWS CLI to authenticate and authorize the SSO profile. $ aws --profile dev-profile sso login Attempting to automatically open the SSO authorization page in your default browser. If the browser does not open or you wish to use a different device to authorize this request, open the following URL: https://device.sso.us-west-2.amazonaws.com/ Then enter the code: ABCD-EFGH Successully logged into Start URL: https://company-sso-portal.awsapps.com/start Next configure your application to use the SSO profile. import \"github.com/aws/aws-sdk-go-v2/config\" // ... cfg, err := config.LoadDefaultConfig( context.Background(), config.WithSharedConfigProfile(\"dev-profile\"), ) if err != nil { return err } For more information on configuring SSO profiles and authenticating using the AWS CLI see Configuring the AWS CLI to use AWS IAM Identity Center (successor to AWS Single Sign-On) in the AWS CLI User Guide. For more information on programmatically constructing the SSO credential provider see the ssocreds API reference documentation.\nOther Credentials Providers The SDK provides other methods for retrieving credentials in the credentials module. For example, you can retrieve temporary security credentials from AWS Security Token Service or credentials from encrypted storage.\nAvailable Credential Providers:\nec2rolecreds – Retrieve Credentials from Amazon EC2 Instances Roles via Amazon EC2 IMDS.\nendpointcreds – Retrieve Credentials from an arbitrary HTTP endpoint.\nprocesscreds – Retrieve Credentials from an external process that will be invoked by the host environment’s shell.\nstscreds – Retrieve Credentials from AWS STS\n","categories":"","description":"","excerpt":"In the AWS SDK for Go V2, you can configure common settings for …","ref":"/aws-sdk-go-v2/docs/configuring-sdk/","tags":"","title":"Configuring the AWS SDK for Go V2"},{"body":"This section contains code examples for IAM using version 2 of the AWS SDK for Go.\n","categories":"","description":"","excerpt":"This section contains code examples for IAM using version 2 of the AWS …","ref":"/aws-sdk-go-v2/docs/code-examples/iam/","tags":"","title":"IAM Examples"},{"body":"Minimum Go Version The AWS SDK for Go V2 requires a minimum Go version of 1.20. Migration from v1 to v2 The latest version of Go can be downloaded on the Downloads page. See the Release History for more information about each Go version release, and relevant information required for upgrading.\nModularization The AWS SDK for Go V2 has been updated to take advantage of the Go modules which became the default development mode in Go 1.13. A number of packages provided by the SDK have been modularized and are independently versioned and released respectively. This change enables improved application dependency modeling, and enables the SDK to provide new features and functionality that follows the Go module versioning strategy.\nThe following list are some Go modules provided by the SDK:\nModule Description github.com/aws/aws-sdk-go-v2 The SDK core github.com/aws/aws-sdk-go-v2/config Shared Configuration Loading github.com/aws/aws-sdk-go-v2/credentials AWS Credential Providers github.com/aws/aws-sdk-go-v2/feature/ec2/imds Amazon EC2 Instance Metadata Service Client The SDK’s service clients and higher level utilities modules are nested under the following import paths:\nImport Root Description github.com/aws/aws-sdk-go-v2/service/ Service Client Modules github.com/aws/aws-sdk-go-v2/feature/ High-Level utilities for services, for example the Amazon S3 Transfer Manager Configuration Loading The session package and associated functionality are replaced with a simplified configuration system provided by the config package. The config package is a separate Go module, and can be included in your applications dependencies by with go get.\ngo get github.com/aws/aws-sdk-go-v2/config The session.New, session.NewSession, NewSessionWithOptions, and session.Must must be migrated to config.LoadDefaultConfig.\nThe config package provides several helper functions that aid in overriding the shared configuration loading programmatically. These function names are prefixed with With followed by option that they override. Let’s look at some examples of how to migrate usage of the session package.\nFor more information on loading shared configuration see Configuring the AWS SDK for Go V2.\nExamples Migrating from NewSession to LoadDefaultConfig The following example shows how usage of session.NewSession without additional argument parameters is migrated to config.LoadDefaultConfig.\n// V1 using NewSession import \"github.com/aws/aws-sdk-go/aws/session\" // ... sess, err := session.NewSession() if err != nil { // handle error } // V2 using LoadDefaultConfig import \"context\" import \"github.com/aws/aws-sdk-go-v2/config\" // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { // handle error } Migrating from NewSession with aws.Config options The example shows how to migrate overriding of aws.Config values during configuration loading. One or more config.With* helper functions can be provided to config.LoadDefaultConfig to override the loaded configuration values. In this example the AWS Region is overridden to us-west-2 using the config.WithRegion helper function.\n// V1 import \"github.com/aws/aws-sdk-go/aws\" import \"github.com/aws/aws-sdk-go/aws/session\" // ... sess, err := session.NewSession(aws.Config{ Region: aws.String(\"us-west-2\") }) if err != nil { // handle error } // V2 import \"context\" import \"github.com/aws/aws-sdk-go-v2/config\" // ... cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion(\"us-west-2\"), ) if err != nil { // handle error } Migrating from NewSessionWithOptions This example shows how to migrate overriding values during configuration loading. Zero or more config.With* helper functions can be provided to config.LoadDefaultConfig to override the loaded configuration values. In this example we show how to override the target profile that is used when loading the AWS SDK shared configuration.\n// V1 import \"github.com/aws/aws-sdk-go/aws\" import \"github.com/aws/aws-sdk-go/aws/session\" // ... sess, err := session.NewSessionWithOptions(aws.Config{ Profile: \"my-application-profile\" }) if err != nil { // handle error } // V2 import \"context\" import \"github.com/aws/aws-sdk-go-v2/config\" // ... cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithSharedConfigProfile(\"my-application-profile\"), ) if err != nil { // handle error } Mocking and *iface The *iface packages and interfaces therein (e.g. s3iface.S3API) have been removed. These interface definitions are not stable since they are broken every time a service adds a new operation.\nUsage of *iface should be replaced by scoped caller-defined interfaces for the service operations being used:\n// V1 import \"io\" import \"github.com/aws/aws-sdk-go/service/s3\" import \"github.com/aws/aws-sdk-go/service/s3/s3iface\" func GetObjectBytes(client s3iface.S3API, bucket, key string) ([]byte, error) { object, err := client.GetObject(\u0026s3.GetObjectInput{ Bucket: \u0026bucket, Key: \u0026key, }) if err != nil { return nil, err } defer object.Body.Close() return io.ReadAll(object.Body) } // V2 import \"context\" import \"io\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" type GetObjectAPIClient interface { GetObject(context.Context, *s3.GetObjectInput, ...func(*s3.Options)) (*s3.GetObjectOutput, error) } func GetObjectBytes(ctx context.Context, client GetObjectAPIClient, bucket, key string) ([]byte, error) { object, err := api.GetObject(ctx, \u0026s3.GetObjectInput{ Bucket: \u0026bucket, Key: \u0026key, }) if err != nil { return nil, err } defer object.Body.Close() return io.ReadAll(object.Body) } See the testing guide for more information.\nCredentials \u0026 Credential Providers The aws/credentials package and associated credential providers have been relocated to the credentials package location. The credentials package is a Go module that you retrieve by using go get.\ngo get github.com/aws/aws-sdk-go-v2/credentials The AWS SDK for Go V2 release updates the AWS Credential Providers to provide a consistent interface for retrieving AWS Credentials. Each provider implements the aws.CredentialsProvider interface, which defines a Retrieve method that returns a (aws.Credentials, error). aws.Credentials that is analogous to the AWS SDK for Go credentials.Value type.\nYou must wrap aws.CredentialsProvider objects with aws.CredentialsCache to allow credential caching to occur. You use NewCredentialsCache to construct a aws.CredentialsCache object. By default, credentials configured by config.LoadDefaultConfig are wrapped with aws.CredentialsCache.\nThe following table list the location changes of the AWS credential providers from AWS SDK for Go V1 to AWS SDK for Go V2.\nName V1 Import V2 Import Amazon EC2 IAM Role Credentials github.com/aws/aws-sdk-go/aws/credentials/ec2rolecreds github.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds Endpoint Credentials github.com/aws/aws-sdk-go/aws/credentials/endpointcreds github.com/aws/aws-sdk-go-v2/credentials/endpointcreds Process Credentials github.com/aws/aws-sdk-go/aws/credentials/processcreds github.com/aws/aws-sdk-go-v2/credentials/processcreds AWS Security Token Service github.com/aws/aws-sdk-go/aws/credentials/stscreds github.com/aws/aws-sdk-go-v2/credentials/stscreds Static Credentials Applications that use credentials.NewStaticCredentials to construct static credential programmatically must use credentials.NewStaticCredentialsProvider.\nExample // V1 import \"github.com/aws/aws-sdk-go/aws/credentials\" // ... appCreds := credentials.NewStaticCredentials(accessKey, secretKey, sessionToken) value, err := appCreds.Get() if err != nil { // handle error } // V2 import \"context\" import \"github.com/aws/aws-sdk-go-v2/aws\" import \"github.com/aws/aws-sdk-go-v2/credentials\" // ... appCreds := aws.NewCredentialsCache(credentials.NewStaticCredentialsProvider(accessKey, secretKey, sessionToken)) value, err := appCreds.Retrieve(context.TODO()) if err != nil { // handle error } Amazon EC2 IAM Role Credentials You must migrate usage of NewCredentials and NewCredentialsWithClient to use New.\nThe ec2rolecreds package’s ec2rolecreds.New takes functional options of ec2rolecreds.Options as input, allowing you override the specific Amazon EC2 Instance Metadata Service client to use, or to override the credential expiry window.\nExample // V1 import \"github.com/aws/aws-sdk-go/aws/credentials/ec2rolecreds\" // ... appCreds := ec2rolecreds.NewCredentials(sess) value, err := appCreds.Get() if err != nil { // handle error } // V2 import \"context\" import \"github.com/aws/aws-sdk-go-v2/aws\" import \"github.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds\" // ... // New returns an object of a type that satisfies the aws.CredentialProvider interface appCreds := aws.NewCredentialsCache(ec2rolecreds.New()) value, err := appCreds.Retrieve(context.TODO()) if err != nil { // handle error } Endpoint Credentials You must migrate usage of NewCredentialsClient and NewProviderClient to use New.\nThe endpointcreds package’s New function takes a string argument containing the URL of an HTTP or HTTPS endpoint to retrieve credentials from, and functional options of endpointcreds.Options to mutate the credentials provider and override specific configuration settings.\nProcess Credentials You must migrate usage of NewCredentials, NewCredentialsCommand, and NewCredentialsTimeout to use NewProvider or NewProviderCommand.\nThe processcreds package’s NewProvider function takes a string argument that is the command to be executed in the host environment’s shell, and functional options of Options to mutate the credentials provider and override specific configuration settings.\nNewProviderCommand takes an implementation of the NewCommandBuilder interface that defines more complex process commands that might take one or more command-line arguments, or have certain execution environment requirements. DefaultNewCommandBuilder implements this interface, and defines a command builder for a process that requires multiple command-line arguments.\nExample // V1 import \"github.com/aws/aws-sdk-go/aws/credentials/processcreds\" // ... appCreds := processcreds.NewCredentials(\"/path/to/command\") value, err := appCreds.Get() if err != nil { // handle error } // V2 import \"context\" import \"github.com/aws/aws-sdk-go-v2/aws\" import \"github.com/aws/aws-sdk-go-v2/credentials/processcreds\" // ... appCreds := aws.NewCredentialsCache(processcreds.NewProvider(\"/path/to/command\")) value, err := appCreds.Retrieve(context.TODO()) if err != nil { // handle error } AWS Security Token Service Credentials AssumeRole You must migrate usage of NewCredentials, and NewCredentialsWithClient to use NewAssumeRoleProvider.\nThe stscreds package’s NewAssumeRoleProvider function must be called with a sts.Client, and the AWS Identity and Access Management Role ARN to be assumed from the provided sts.Client’s configured credentials. You can also provide a set of functional options of AssumeRoleOptions to modify other optional settings of the provider.\nExample // V1 import \"github.com/aws/aws-sdk-go/aws/credentials/stscreds\" // ... appCreds := stscreds.NewCredentials(sess, \"arn:aws:iam::123456789012:role/demo\") value, err := appCreds.Get() if err != nil { // handle error } // V2 import \"context\" import \"github.com/aws/aws-sdk-go-v2/credentials/stscreds\" import \"github.com/aws/aws-sdk-go-v2/service/sts\" // ... client := sts.NewFromConfig(cfg) appCreds := stscreds.NewAssumeRoleProvider(client, \"arn:aws:iam::123456789012:role/demo\") value, err := appCreds.Retrieve(context.TODO()) if err != nil { // handle error } AssumeRoleWithWebIdentity You must migrate usage of NewWebIdentityCredentials, NewWebIdentityRoleProvider, and NewWebIdentityRoleProviderWithToken to use NewWebIdentityRoleProvider.\nThe stscreds package’s NewWebIdentityRoleProvider function must be called with a sts.Client, and the AWS Identity and Access Management Role ARN to be assumed using the provided sts.Client’s configured credentials, and an implementation of a IdentityTokenRetriever for providing the OAuth 2.0 or OpenID Connect ID token. IdentityTokenFile is an IdentityTokenRetriever that can be used to provide the web identity token from a file located on the application’s host file-system. You can also provide a set of functional options of WebIdentityRoleOptions to modify other optional settings for the provider.\nExample // V1 import \"github.com/aws/aws-sdk-go/aws/credentials/stscreds\" // ... appCreds := stscreds.NewWebIdentityRoleProvider(sess, \"arn:aws:iam::123456789012:role/demo\", \"sessionName\", \"/path/to/token\") value, err := appCreds.Get() if err != nil { // handle error } // V2 import \"context\" import \"github.com/aws/aws-sdk-go-v2/aws\" import \"github.com/aws/aws-sdk-go-v2/credentials/stscreds\" import \"github.com/aws/aws-sdk-go-v2/service/sts\" // ... client := sts.NewFromConfig(cfg) appCreds := aws.NewCredentialsCache(stscreds.NewWebIdentityRoleProvider( client, \"arn:aws:iam::123456789012:role/demo\", stscreds.IdentityTokenFile(\"/path/to/file\"), func(o *stscreds.WebIdentityRoleOptions) { o.RoleSessionName = \"sessionName\" })) value, err := appCreds.Retrieve(context.TODO()) if err != nil { // handle error } Service Clients AWS SDK for Go V2 provides service client modules nested under the github.com/aws/aws-sdk-go-v2/service import path. Each service client is contained in a Go package using each service’s unique identifier. The following table provides some examples of service import paths in the AWS SDK for Go V2.\nService Name V1 Import Path V2 Import Path Amazon S3 github.com/aws/aws-sdk-go/service/s3 github.com/aws/aws-sdk-go-v2/service/s3 Amazon DynamoDB github.com/aws/aws-sdk-go/service/dynamodb github.com/aws/aws-sdk-go-v2/service/dynamodb Amazon CloudWatch Logs github.com/aws/aws-sdk-go/service/cloudwatchlogs github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs Each service client package is an independently versioned Go module. To add the service client as a dependency of your application, use the go get command with the service’s import path. For example, to add the Amazon S3 client to your dependencies use\ngo get github.com/aws/aws-sdk-go-v2/service/s3 Client Construction You can construct clients in the AWS SDK for Go V2 using either the New or NewFromConfig constructor functions in the client’s package. When migrating from the AWS SDK for Go we recommend that you use the NewFromConfig variant, which will return a new service client using values from an aws.Config. The aws.Config value will have been created while loading the SDK shared configuration using config.LoadDefaultConfig. For details on creating service clients see Using AWS Services.\nExample 1 // V1 import \"github.com/aws/aws-sdk-go/aws/session\" import \"github.com/aws/aws-sdk-go/service/s3\" // ... sess, err := session.NewSession() if err != nil { // handle error } client := s3.New(sess) // V2 import \"context\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { // handle error } client := s3.NewFromConfig(cfg) Example 2: Overriding Client Settings // V1 import \"github.com/aws/aws-sdk-go/aws\" import \"github.com/aws/aws-sdk-go/aws/session\" import \"github.com/aws/aws-sdk-go/service/s3\" // ... sess, err := session.NewSession() if err != nil { // handle error } client := s3.New(sess, \u0026aws.Config{ Region: aws.String(\"us-west-2\"), }) // V2 import \"context\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { // handle error } client := s3.NewFromConfig(cfg, func(o *s3.Options) { o.Region = \"us-west-2\" }) Endpoints The endpoints package no longer exists in the AWS SDK for Go V2. Each service client now embeds its required AWS endpoint metadata within the client package. This reduces the overall binary size of compiled applications by no longer including endpoint metadata for services not used by your application.\nAdditionally, each service now exposes its own interface for endpoint resolution in EndpointResolverV2. Each API takes a unique set of parameters for a service EndpointParameters, the values of which are sourced by the SDK from various locations when an operation is invoked.\nBy default, service clients use their configured AWS Region to resolve the service endpoint for the target Region. If your application requires a custom endpoint, you can specify custom behavior on EndpointResolverV2 field on the aws.Config structure. If your application implements a custom endpoints.Resolver you must migrate it to conform to this new per-service interface.\nFor more information on endpoints and implementing a custom resolver, see Configuring Client Endpoints.\nAuthentication The AWS SDK for Go V2 supports more advanced authentication behavior, which enables the use of newer AWS service features such as codecatalyst and S3 Express One Zone. Additionally, this behavior can be customized on a per-client basis.\nInvoking API Operations The number of service client operation methods have been reduced significantly. The \u003cOperationName\u003eRequest, \u003cOperationName\u003eWithContext, and \u003cOperationName\u003e methods have all been consolidated into single operation method, \u003cOperationName\u003e.\nExample The following example shows how calls to the \u003cnil\u003e PutObject operation would be migrated from AWS SDK for Go to AWS SDK for Go V2.\n// V1 import \"context\" import \"github.com/aws/aws-sdk-go/service/s3\" // ... client := s3.New(sess) // Pattern 1 output, err := client.PutObject(\u0026s3.PutObjectInput{ // input parameters }) // Pattern 2 output, err := client.PutObjectWithContext(context.TODO(), \u0026s3.PutObjectInput{ // input parameters }) // Pattern 3 req, output := client.PutObjectRequest(context.TODO(), \u0026s3.PutObjectInput{ // input parameters }) err := req.Send() // V2 import \"context\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... client : s3.NewFromConfig(cfg) output, err := client.PutObject(context.TODO(), \u0026s3.PutObjectInput{ // input parameters }) Service Data Types The top-level input and output types of an operation are found in the service client package. The input and output type for a given operation follow the pattern of \u003cOperationName\u003eInput and \u003cOperationName\u003eOutput, where OperationName is the name of the operation you are invoking. For example the input and output shape for the Amazon S3 PutObject operation are PutObjectInput and PutObjectOutput respectively.\nAll other service data types, other than input and output types, have been migrated to the types package located under the service client package import path hierarchy. For example, the s3.AccessControlPolicy type is now located at types.AccessControlPolicy.\nEnumeration Values The SDK now provides a typed experience for all API enumeration fields. Rather than using a string literal value copied from the service API reference documentation, you can now use one of the concrete types found in the service client’s types package. For example, you can provide the Amazon S3 PutObjectInput operation with an ACL to be applied on an object. In the AWS SDK for Go V1, this parameter was a *string type. In the {{\u0026 alias sdk-go %}} this parameter is now a types.ObjectCannedACL. The types package provides generated constants for the valid enumeration values that can be assigned to this field. For example types.ObjectCannedACLPrivate is the constant for the “private” canned ACL value. This value can be used in place of managing string constants within your application.\nPointer Parameters The AWS SDK for Go v1 required pointer references to be passed for all input parameters to service operations. The AWS SDK for Go V2 has simplified the experience with most services by removing the need to pass input values as pointers where possible. This change means that many service clients operations no longer require your application to pass pointer references for the following types: uint8, uint16, uint32, int8, int16, int32, float32, float64, bool. Similarly, slice and map element types have been updated accordingly to reflect whether their elements must be passed as pointer references.\nThe aws package contains helper functions for creating pointers for the Go built-in types, these helpers should be used to more easily handle creating pointer types for these Go types. Similarly, helper methods are provided for safely de-referencing pointer values for these types. For example, the aws.String function converts from string ⇒ *string. Inversely, the aws.ToString converts from *string ⇒ string. When upgrading your application from AWS SDK for Go V1 to AWS SDK for Go V2, you must migrate usage of the helpers for converting from the pointer types to the non-pointer variants. For example, aws.StringValue must be updated to aws.ToString.\nErrors Types The AWS SDK for Go V2 takes full advantage of the error wrapping functionality introduced in Go 1.13. Services that model error responses have generated types available in their client’s types package that can be used to test whether a client operation error was caused by one of these types. For example Amazon S3 GetObject operation can return a NoSuchKey error if attempting to retrieve an object key that doesn’t exist. You can use errors.As to test whether the returned operation error is a types.NoSuchKey error. In the event a service does not model a specific type for an error, you can utilize the smithy.APIError interface type for inspecting the returned error code and message from the service. This functionality replaces awserr.Error and the other awserr functionality from the AWS SDK for Go V1. For more details information on handling errors see Handling Errors.\nExample // V1 import \"github.com/aws/aws-sdk-go/aws/awserr\" import \"github.com/aws/aws-sdk-go/service/s3\" // ... client := s3.New(sess) output, err := s3.GetObject(\u0026s3.GetObjectInput{ // input parameters }) if err != nil { if awsErr, ok := err.(awserr.Error); ok { if awsErr.Code() == \"NoSuchKey\" { // handle NoSuchKey } else { // handle other codes } return } // handle a error } // V2 import \"context\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" import \"github.com/aws/aws-sdk-go-v2/service/s3/types\" import \"github.com/aws/smithy-go\" // ... client := s3.NewFromConfig(cfg) output, err := s3.GetObject(context.TODO(), \u0026s3.GetObjectInput{ // input parameters }) if err != nil { var nsk *types.NoSuchKey if errors.As(err, \u0026nsk) { // handle NoSuchKey error return } var apiErr smithy.APIError if errors.As(err, \u0026apiErr) { code := apiErr.ErrorCode() message := apiErr.ErrorMessage() // handle error code return } // handle error return } Paginators Service operation paginators are no longer invoked as methods on the service client. To use a paginator for an operation you must construct a paginator for an operation using one of the paginator constructor methods. For example, to use paginate over the Amazon S3 ListObjectsV2 operation you must construct its paginator using the s3.NewListObjectsV2Paginator. This constructor returns a ListObjectsV2Paginator which provides the methods HasMorePages, and NextPage for determining whether there are more pages to retrieve and invoking the operation to retrieve the next page respectively. More details on using the SDK paginators can be found at .\nLet’s look at an example of how to migrate from a AWS SDK for Go paginator to the AWS SDK for Go V2 equivalent.\nExample // V1 import \"fmt\" import \"github.com/aws/aws-sdk-go/service/s3\" // ... client := s3.New(sess) params := \u0026s3.ListObjectsV2Input{ // input parameters } totalObjects := 0 err := client.ListObjectsV2Pages(params, func(output *s3.ListObjectsV2Output, lastPage bool) bool { totalObjects += len(output.Contents) return !lastPage }) if err != nil { // handle error } fmt.Println(\"total objects:\", totalObjects) // V2 import \"context\" import \"fmt\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... client := s3.NewFromConfig(cfg) params := \u0026s3.ListObjectsV2Input{ // input parameters } totalObjects := 0 paginator := s3.NewListObjectsV2Paginator(client, params) for paginator.HasMorePages() { output, err := paginator.NextPage(context.TODO()) if err != nil { // handle error } totalObjects += len(output.Contents) } fmt.Println(\"total objects:\", totalObjects) Waiters Service operation waiters are no longer invoked as methods on the service client. To use a waiter you first construct the desired waiter type, and then invoke the wait method. For example, to wait for a Amazon S3 Bucket to exist, you must construct a BucketExists waiter. Use the s3.NewBucketExistsWaiter constructor to create a s3.BucketExistsWaiter. The s3.BucketExistsWaiter provides a Wait method which can be used to wait for a bucket to become available.\nPresigned Requests The V1 SDK technically supported presigning any AWS SDK operation, however, this does not accurately represent what is actually supported at the service level (and in reality most AWS service operations do not support presigning).\nAWS SDK for Go V2 resolves this by exposing specific PresignClient implementations in service packages with specific APIs for supported presignable operations.\nNote: If a service is missing presigning support for an operation that you were successfully using in SDK v1, please let us know by filing an issue on GitHub.\nUses of Presign and PresignRequest must be converted to use service-specific presigning clients.\nThe following example shows how to migrate presigning of an S3 GetObject request:\n// V1 import ( \"fmt\" \"time\" \"github.com/aws/aws-sdk-go/aws\" \"github.com/aws/aws-sdk-go/aws/session\" \"github.com/aws/aws-sdk-go/service/s3\" ) func main() { sess := session.Must(session.NewSessionWithOptions(session.Options{ SharedConfigState: session.SharedConfigEnable, })) svc := s3.New(sess) req, _ := svc.GetObjectRequest(\u0026s3.GetObjectInput{ Bucket: aws.String(\"bucket\"), Key: aws.String(\"key\"), }) // pattern 1 url1, err := req.Presign(20 * time.Minute) if err != nil { panic(err) } fmt.Println(url1) // pattern 2 url2, header, err := req.PresignRequest(20 * time.Minute) if err != nil { panic(err) } fmt.Println(url2, header) } // V2 import ( \"context\" \"fmt\" \"time\" \"github.com/aws/aws-sdk-go-v2/aws\" \"github.com/aws/aws-sdk-go-v2/config\" \"github.com/aws/aws-sdk-go-v2/service/s3\" ) func main() { cfg, err := config.LoadDefaultConfig(context.Background()) if err != nil { panic(err) } svc := s3.NewPresignClient(s3.NewFromConfig(cfg)) req, err := svc.PresignGetObject(context.Background(), \u0026s3.GetObjectInput{ Bucket: aws.String(\"bucket\"), Key: aws.String(\"key\"), }, func(o *s3.PresignOptions) { o.Expires = 20 * time.Minute }) if err != nil { panic(err) } fmt.Println(req.Method, req.URL, req.SignedHeader) } Request customization The monolithic request.Request API has been re-compartmentalized.\nOperation input/output The opaque Request fields Params and Data, which hold the operation input and output structures respectively, are now accessible within specific middleware phases as input/output:\nRequest handlers which reference Request.Params and Request.Data must be migrated to middleware.\nmigrating Params // V1 import ( \"github.com/aws/aws-sdk-go/aws\" \"github.com/aws/aws-sdk-go/aws/request\" \"github.com/aws/aws-sdk-go/aws/session\" \"github.com/aws/aws-sdk-go/service/s3\" ) func withPutObjectDefaultACL(acl string) request.Option { return func(r *request.Request) { in, ok := r.Params.(*s3.PutObjectInput) if !ok { return } if in.ACL == nil { in.ACL = aws.String(acl) } r.Params = in } } func main() { sess := session.Must(session.NewSession()) sess.Handlers.Validate.PushBack(withPutObjectDefaultACL(s3.ObjectCannedACLBucketOwnerFullControl)) // ... } // V2 import ( \"context\" \"github.com/aws/aws-sdk-go-v2/service/s3\" \"github.com/aws/aws-sdk-go-v2/service/s3/types\" \"github.com/aws/smithy-go/middleware\" smithyhttp \"github.com/aws/smithy-go/transport/http\" ) type withPutObjectDefaultACL struct { acl types.ObjectCannedACL } // implements middleware.InitializeMiddleware, which runs BEFORE a request has // been serialized and can act on the operation input var _ middleware.InitializeMiddleware = (*withPutObjectDefaultACL)(nil) func (*withPutObjectDefaultACL) ID() string { return \"withPutObjectDefaultACL\" } func (m *withPutObjectDefaultACL) HandleInitialize(ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler) ( out middleware.InitializeOutput, metadata middleware.Metadata, err error, ) { input, ok := in.Parameters.(*s3.PutObjectInput) if !ok { return next.HandleInitialize(ctx, in) } if len(input.ACL) == 0 { input.ACL = m.acl } in.Parameters = input return next.HandleInitialize(ctx, in) } // create a helper function to simplify instrumentation of our middleware func WithPutObjectDefaultACL(acl types.ObjectCannedACL) func (*s3.Options) { return func(o *s3.Options) { o.APIOptions = append(o.APIOptions, func (s *middleware.Stack) error { return s.Initialize.Add(\u0026withPutObjectDefaultACL{acl: acl}, middleware.After) }) } } func main() { cfg, err := config.LoadDefaultConfig(context.Background()) if err != nil { // ... } svc := s3.NewFromConfig(cfg, WithPutObjectDefaultACL(types.ObjectCannedACLBucketOwnerFullControl)) // ... } migrating Data // V1 import ( \"github.com/aws/aws-sdk-go/aws\" \"github.com/aws/aws-sdk-go/aws/request\" \"github.com/aws/aws-sdk-go/aws/session\" \"github.com/aws/aws-sdk-go/service/s3\" ) func readPutObjectOutput(r *request.Request) { output, ok := r.Data.(*s3.PutObjectOutput) if !ok { return } // ... } } func main() { sess := session.Must(session.NewSession()) sess.Handlers.Unmarshal.PushBack(readPutObjectOutput) svc := s3.New(sess) // ... } // V2 import ( \"context\" \"github.com/aws/aws-sdk-go-v2/config\" \"github.com/aws/aws-sdk-go-v2/service/s3\" \"github.com/aws/smithy-go/middleware\" smithyhttp \"github.com/aws/smithy-go/transport/http\" ) type readPutObjectOutput struct{} var _ middleware.DeserializeMiddleware = (*readPutObjectOutput)(nil) func (*readPutObjectOutput) ID() string { return \"readPutObjectOutput\" } func (*readPutObjectOutput) HandleDeserialize(ctx context.Context, in middleware.DeserializeInput, next middleware.DeserializeHandler) ( out middleware.DeserializeOutput, metadata middleware.Metadata, err error, ) { out, metadata, err = next.HandleDeserialize(ctx, in) if err != nil { // ... } output, ok := in.Parameters.(*s3.PutObjectOutput) if !ok { return out, metadata, err } // inspect output... return out, metadata, err } func WithReadPutObjectOutput(o *s3.Options) { o.APIOptions = append(o.APIOptions, func (s *middleware.Stack) error { return s.Initialize.Add(\u0026withReadPutObjectOutput{}, middleware.Before) }) } func main() { cfg, err := config.LoadDefaultConfig(context.Background()) if err != nil { // ... } svc := s3.NewFromConfig(cfg, WithReadPutObjectOutput) // ... } HTTP request/response The HTTPRequest and HTTPResponse fields from Request are now exposed in specific middleware phases. Since middleware is transport-agnostic, you must perform a type assertion on the middleware input or output to reveal the underlying HTTP request or response.\nRequest handlers which reference Request.HTTPRequest and Request.HTTPResponse must be migrated to middleware.\nmigrating HTTPRequest // V1 import ( \"github.com/aws/aws-sdk-go/aws/request\" \"github.com/aws/aws-sdk-go/aws/session\" ) func withHeader(header, val string) request.Option { return func(r *request.Request) { request.HTTPRequest.Header.Set(header, val) } } func main() { sess := session.Must(session.NewSession()) sess.Handlers.Build.PushBack(withHeader(\"x-user-header\", \"...\")) svc := s3.New(sess) // ... } // V2 import ( \"context\" \"fmt\" \"github.com/aws/aws-sdk-go-v2/config\" \"github.com/aws/aws-sdk-go-v2/service/s3\" \"github.com/aws/smithy-go/middleware\" smithyhttp \"github.com/aws/smithy-go/transport/http\" ) type withHeader struct { header, val string } // implements middleware.BuildMiddleware, which runs AFTER a request has been // serialized and can operate on the transport request var _ middleware.BuildMiddleware = (*withHeader)(nil) func (*withHeader) ID() string { return \"withHeader\" } func (m *withHeader) HandleBuild(ctx context.Context, in middleware.BuildInput, next middleware.BuildHandler) ( out middleware.BuildOutput, metadata middleware.Metadata, err error, ) { req, ok := in.Request.(*smithyhttp.Request) if !ok { return out, metadata, fmt.Errorf(\"unrecognized transport type %T\", in.Request) } req.Header.Set(m.header, m.val) return next.HandleBuild(ctx, in) } func WithHeader(header, val string) func (*s3.Options) { return func(o *s3.Options) { o.APIOptions = append(o.APIOptions, func (s *middleware.Stack) error { return s.Build.Add(\u0026withHeader{ header: header, val: val, }, middleware.After) }) } } func main() { cfg, err := config.LoadDefaultConfig(context.Background()) if err != nil { // ... } svc := s3.NewFromConfig(cfg, WithHeader(\"x-user-header\", \"...\")) // ... } Handler phases SDK v2 middleware phases are the successor to v1 handler phases.\nThe following table provides a rough mapping of v1 handler phases to their equivalent location within the V2 middleware stack:\nv1 handler name v2 middleware phase Validate Initialize Build Serialize Sign Finalize Send n/a (1) ValidateResponse Deserialize Unmarshal Deserialize UnmarshalMetadata Deserialize UnmarshalError Deserialize Retry Finalize, after \"Retry\" middleware (2) AfterRetry Finalize, before \"Retry\" middleware, post-next.HandleFinalize() (2,3) CompleteAttempt Finalize, end of step Complete Initialize, start of step, post-next.HandleInitialize() (3) (1) The Send phase in v1 is effectively the wrapped HTTP client round-trip in v2. This behavior is controlled by the HTTPClient field on client options.\n(2) Any middleware after the \"Retry\" middleware in the Finalize step will be part of the retry loop.\n(3) The middleware “stack” at operation time is built into a repeatedly-decorated handler function. Each handler is responsible for calling the next one in the chain. This implicitly means that a middleware step can also take action AFTER its next step has been called.\nFor example, for the Initialize step, which is at the top of the stack, this means Initialize middlewares that take action after calling the next handler effectively operate at the end of the request:\n// V2 import ( \"context\" \"github.com/aws/smithy-go/middleware\" ) type onComplete struct{} var _ middleware.InitializeMiddleware = (*onComplete)(nil) func (*onComplete) ID() string { return \"onComplete\" } func (*onComplete) HandleInitialize(ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler) ( out middleware.InitializeOutput, metadata middleware.Metadata, err error, ) { out, metadata, err = next.HandleInitialize(ctx, in) // the entire operation was invoked above - the deserialized response is // available opaquely in out.Result, run post-op actions here... return out, metadata, err } Features Amazon EC2 Instance Metadata Service The AWS SDK for Go V2 provides an Amazon EC2 Instance Metadata Service (IMDS) client that you can use to query the local IMDS when executing your application on an Amazon EC2 instance. The IMDS client is a separate Go module that can be added to your application by using\ngo get github.com/aws/aws-sdk-go-v2/feature/ec2/imds The client constructor and method operations have been updated to match the design of the other SDK service clients.\nExample // V1 import \"github.com/aws/aws-sdk-go/aws/ec2metadata\" // ... client := ec2metadata.New(sess) region, err := client.Region() if err != nil { // handle error } // V2 import \"context\" import \"github.com/aws/aws-sdk-go-v2/feature/ec2/imds\" // ... client := imds.NewFromConfig(cfg) region, err := client.GetRegion(context.TODO()) if err != nil { // handle error } Amazon S3 Transfer Manager The Amazon S3 transfer manager is available for managing uploads and downloads of objects concurrently. This package is located in a Go module outside the service client import path. This module can be retrieved by using go get github.com/aws/aws-sdk-go-v2/feature/s3/manager.\ns3.NewUploader and s3.NewUploaderWithClient have been replaced with the constructor method manager.NewUploader for creating an Upload manager client.\ns3.NewDownloader and s3.NewDownloaderWithClient have been replaced with a single constructor method manager.NewDownloader for creating a Download manager client.\nAmazon CloudFront Signing Utilities The AWS SDK for Go V2 provides Amazon CloudFront signing utilities in a Go module outside the service client import path. This module can be retrieved by using go get.\ngo get github.com/aws/aws-sdk-go-v2/feature/cloudfront/sign Amazon S3 Encryption Client Starting in AWS SDK for Go V2, the Amazon S3 encryption client is a separate module under AWS Crypto Tools. The latest version of the S3 encryption client for Go, 3.x, is now available at https://github.com/aws/amazon-s3-encryption-client-go. This module can be retrieved by using go get:\ngo get github.com/aws/amazon-s3-encryption-client-go/v3 The separate EncryptionClient (v1, v2) and DecryptionClient (v1, v2) APIs have been replaced with a single client, S3EncryptionClientV3, that exposes both encrypt and decrypt functionality.\nLike other service clients in AWS SDK for Go V2, the operation APIs have been condensed:\nThe GetObject, GetObjectRequest, and GetObjectWithContext decryption APIs are replaced by GetObject. The PutObject, PutObjectRequest, and PutObjectWithContext encryption APIs are replaced by PutObject. To learn how to migrate to the 3.x major version of the encryption client, see this guide.\n","categories":"","description":"How to migrate to the AWS SDK for Go V2 from AWS SDK for Go V1.","excerpt":"How to migrate to the AWS SDK for Go V2 from AWS SDK for Go V1.","ref":"/aws-sdk-go-v2/docs/migrating/","tags":"","title":"Migrating to the AWS SDK for Go V2"},{"body":"To make calls to an AWS service, you must first construct a service client instance. A service client provides low-level access to every API action for that service. For example, you create an Amazon S3 service client to make calls to Amazon S3 APIs.\nWhen you call service operations, you pass in input parameters as a struct. A successful call will result in an output struct containing the service API response. For example, after you successfully call an Amazon S3 create bucket action, the action returns an output struct with the bucket’s location.\nFor the list of service clients, including their methods and parameters, see the AWS SDK for Go V2 API Reference\nConstructing a Service Client Service clients can be constructed using either the New or NewFromConfig functions available in service client’s Go package. Each function will return a Client struct type containing the methods for invoking the service APIs. The New and NewFromConfig each provide the same set of configurable options for constructing a service client, but provide slightly different construction patterns that we will look at in the following sections.\nNewFromConfig NewFromConfig function provides a consistent interface for constructing service clients using the aws.Config. An aws.Config can be loaded using the config.LoadDefaultConfig. For more information on constructing an aws.Config see Configure the SDK. The following example shows how to construct an Amazon S3 service client using the aws.Configand the NewFromConfig function:\nimport \"context\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { panic(err) } client := s3.NewFromConfig(cfg) Overriding Configuration NewFromConfig can take one or more functional arguments that can mutate a client’s configuration Options struct. This allows you to make specific overrides such as changing the Region, or modifying service specific options such as Amazon S3 UseAccelerate option. For example:\nimport \"context\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { panic(err) } client := s3.NewFromConfig(cfg, func(o *s3.Options) { o.Region = \"us-west-2\" o.UseAccelerate = true }) Overrides to the client Options value is determined by the order that the functional arguments are given to NewFromConfig.\nNew New is considered a more advanced form of client construction. We recommend you use NewFromConfig for client construction, as it allows construction using the aws.Config struct. This removes the need to construct an Options struct instance for each service client your application requires.\nNew function is a client constructor provides an interface for constructing clients using only the client packages Options struct for defining the client’s configuration options. For example to construct Amazon S3 client using New:\nimport \"github.com/aws/aws-sdk-go-v2/aws\" import \"github.com/aws/aws-sdk-go-v2/credentials\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... client := s3.New(s3.Options{ Region: \"us-west-2\", Credentials: aws.NewCredentialsCache(credentials.NewStaticCredentialsProvider(accessKey, secretKey, \"\")), }) Overriding Configuration New can take one or more functional arguments that can mutate a client’s configuration Options struct. This allows you to make specific overrides such as changing the Region or modifying service specific options such as Amazon S3 UseAccelerate option. For example:\nimport \"github.com/aws/aws-sdk-go-v2/aws\" import \"github.com/aws/aws-sdk-go-v2/credentials\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... options := s3.Options{ Region: \"us-west-2\", Credentials: aws.NewCredentialsCache(credentials.NewStaticCredentialsProvider(accessKey, secretKey, \"\")), } client := s3.New(options, func(o *s3.Options) { o.Region = \"us-east-1\" o.UseAccelerate = true }) Overrides to the client Options value is determined by the order that the functional arguments are given to New.\nCalling Service Operations After you have a service client instance, you can use it to call a service’s operations. For example to call the Amazon S3 GetObject operation:\nresponse, err := client.GetObject(context.TODO(), \u0026s3.GetObjectInput{ Bucket: aws.String(\"my-bucket\"), Key: aws.String(\"obj-key\"), }) When you call a service operation, the SDK synchronously validates the input, serializes the request, signs it with your credentials, sends it to AWS, and then deserializes a response or an error. In most cases, you can call service operations directly. Each service operation client method will return an operation response struct, and an error interface type. You should always check error type to determine if an error occurred before attempting to access the service operation’s response struct.\nPassing Parameters to a Service Operation Each service operation method takes a context.Context value that can be used for setting request deadlines that will be honored by the SDK. In addition, each service operation will take a \u003cOperationName\u003eInput struct found in the service’s respective Go package. You pass in API input parameters using the operation input struct.\nOperation input structures can have input parameters such as the standard Go numerics, boolean, string, map, and list types. In more complex API operations a service might have more complex modeling of input parameters. These other types such as service specific structures and enum values are found in the service’s types Go package.\nIn addition, services might distinguish between the default value of a Go type and whether the value was set or not by the user. In these cases, input parameters might require you to pass a pointer reference to the type in question. For standard Go types like numerics, boolean, and string there are \u003cType\u003e and From\u003cType\u003e convenience functions available in the aws to ease this conversion. For example aws.String can be used to convert a string to a *string type for input parameters that require a pointer to a string. Inversely aws.ToString can be used to transform a *string to a string while providing protection from dereferencing a nil pointer. The To\u003cType\u003e functions are helpful when handling service responses.\nLet’s look at an example of how we can use an Amazon S3 client to call the GetObject API, and construct our input using the types package, and aws.\u003cType\u003e helpers.\nimport \"context\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" import \"github.com/aws/aws-sdk-go-v2/service/s3/types\" // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { panic(err) } client := s3.NewFromConfig(cfg) resp, err := client.GetObject(context.TODO(), \u0026s3.GetObjectInput{ Bucket: aws.String(\"my-bucket\"), Key: aws.String(\"keyName\"), RequestPayer: types.RequestPayerRequester, }) Overriding Client Options For Operation Call Similar to how client operation options can be modified during construction of a client using functional arguments, the client options can be modified at the time the operation method is called by providing one or more functional arguments to the service operation method. This action is concurrency safe and will not affect other concurrent operations on the client.\nFor example to override the client region from “us-west-2” to “us-east-1”:\ncfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion(\"us-west-2\")) if err != nil { log.Printf(\"error: %v\", err) return } client := s3.NewFromConfig(cfg) params := \u0026s3.GetObjectInput{ // ... } resp, err := client.GetObject(context.TODO(), params, func(o *Options) { o.Region = \"us-east-1\" }) Handling Operation Responses Each service operation has an associated output struct that contains the service’s operation response members. The output struct follows the following naming pattern \u003cOperationName\u003eOutput. Some operations might have no members defined for their operation output. After calling a service operation, the return error argument type should always be checked to determine if an error occurred while invoking the service operation. Errors returned can range from client-side input validation errors to service-side error responses returned to the client. The operation’s output struct should not be accessed in the event that a non-nil error is returned by the client.\nFor example to log an operation error and prematurely return from the calling function:\nresponse, err := client.GetObject(context.TODO()) if err != nil { log.Printf(\"GetObject error: %v\", err) return } For more information on error handling, including how to inspect for specific error types, see the Handling Errors documentation.\nResponses with io.ReadCloser Some API operations return a response struct that contain an output member that is an io.ReadCloser. This will be the case for API operations that expose some element of their output in the body of the HTTP response itself.\nFor example, Amazon S3 GetObject operation returns a response whose Body member is an io.ReadCloser for accessing the object payload.\nYou MUST ALWAYS Close() any io.ReadCloser output members, regardless of whether you’ve consumed its content. Failure to do so can leak resources and potentially create issues with reading response bodies for operations called in the future.\nresp, err := s3svc.GetObject(context.TODO(), \u0026s3.GetObjectInput{...}) if err != nil { // handle error return } // Make sure to always close the response Body when finished defer resp.Body.Close() decoder := json.NewDecoder(resp.Body) if err := decoder.Decode(\u0026myStruct); err != nil { // handle error return } Response Metadata All service operation output structs include a ResultMetadata member of type middleware.Metadata. middleware.Metadata is used by the SDK middleware to provide additional information from a service response that is not modeled by the service. This includes metadata like the RequestID. For example to retrieve the RequestID associated with a service response to assist AWS Support in troubleshooting a request:\nimport \"fmt\" import \"log\" import \"github.com/aws/aws-sdk-go-v2/aws/middleware\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // .. resp, err := client.GetObject(context.TODO(), \u0026s3.GetObjectInput{ // ... }) if err != nil { log.Printf(\"error: %v\", err) return } requestID, ok := middleware.GetRequestIDMetadata(resp.ResultMetadata) if !ok { fmt.Println(\"RequestID not included with request\") } fmt.Printf(\"RequestID: %s\\n\", requestID) Concurrently Using Service Clients You can create goroutines that concurrently use the same service client to send multiple requests. You can use a service client with as many goroutines as you want.\nIn the following example, an service client is used in multiple goroutines. This example concurrently uploads two objects to an Amazon S3 bucket.\nimport \"context\" import \"log\" import \"strings\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { log.Printf(\"error: %v\", err) return } client := s3.NewFromConfig(cfg) type result struct { Output *s3.PutObjectOutput Err error } results := make(chan result, 2) var wg sync.WaitGroup wg.Add(2) go func() { defer wg.Done() output, err := client.PutObject(context.TODO(), \u0026s3.PutObjectInput{ Bucket: aws.String(\"my-bucket\"), Key: aws.String(\"foo\"), Body: strings.NewReader(\"foo body content\"), }) results \u003c- result{Output: output, Err: err} }() go func() { defer wg.Done() output, err := client.PutObject(context.TODO(), \u0026s3.PutObjectInput{ Bucket: aws.String(\"my-bucket\"), Key: aws.String(\"bar\"), Body: strings.NewReader(\"bar body content\"), }) results \u003c- result{Output: output, Err: err} }() wg.Wait() close(results) for result := range results { if result.Err != nil { log.Printf(\"error: %v\", result.Err) continue } fmt.Printf(\"etag: %v\", aws.ToString(result.Output.ETag)) } Using Operation Paginators Typically, when you retrieve a list of items, you might need to check the output struct for a token or marker to confirm whether the AWS service returned all results from your request. If the token or marker is present, you use it to request the next page of results. Instead of managing these tokens or markers, you can use the service package’s available paginator types.\nPaginator helpers are available for supported service operations, and can be found in the service client’s Go package. To construct a paginator for a supported operation, use the New\u003cOperationName\u003ePaginator function. Paginator construct functions take the service Client, the operation’s \u003cOperationName\u003eInput input parameters, and an optional set of functional arguments allowing you to configure other optional paginator settings.\nThe returned operation paginator type provides a convenient way to iterate over a paginated operation until you have reached the last page, or you have found the item(s) that your application was searching for. A paginator type has two methods: HasMorePages and NextPage. HasMorePages returns a boolean value of true if the first page has not been retrieved, or if additional pages available to retrieve using the operation. To retrieve the first or subsequent pages of the operation, the NextPage operation must be called. NextPage takes context.Context and returns the operation output and any corresponding error. Like the client operation method return parameters, the return error should always be checked before attempting to use the returned response structure. See Handling Operation Responses\nThe following example uses the ListObjectsV2 paginator to list up to three pages of object keys from the ListObjectV2operation. Each page consists of up to 10 keys, which is defined by the Limit paginator option.\nimport \"context\" import \"log\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/aws\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { log.Printf(\"error: %v\", err) return } client := s3.NewFromConfig(cfg) params := \u0026s3.ListObjectsV2Input{ Bucket: aws.String(\"my-bucket\"), } paginator := s3.NewListObjectsV2Paginator(client, params, func(o *s3.ListObjectsV2PaginatorOptions) { o.Limit = 10 }) pageNum := 0 for paginator.HasMorePages() \u0026\u0026 pageNum \u003c 3 { output, err := paginator.NextPage(context.TODO()) if err != nil { log.Printf(\"error: %v\", err) return } for _, value := range output.Contents { fmt.Println(*value.Key) } pageNum++ } Similar to client operation method, the client options like the request Region can be modified by providing one or more functional arguments to NextPage. For more information about overriding client options when calling an operation see Overriding Clients For Operation\nUsing Waiters When interacting with AWS APIs that are asynchronous, you often need to wait for a particular resource to become available in order to perform further actions on it.\nFor example, the Amazon DynamoDB CreateTable API returns immediately with a TableStatus of CREATING, and you can’t invoke read or write operations until the table status has been transitioned to ACTIVE.\nWriting logic to continuously poll the table status can be cumbersome and error-prone. The waiters help take the complexity out of it and are simple APIs that handle the polling task for you.\nFor example, you can use waiters to poll if a DynamoDB table is created and ready for a write operation.\nimport \"context\" import \"fmt\" import \"log\" import \"time\" import \"github.com/aws/aws-sdk-go-v2/aws\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/service/dynamodb\" // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { log.Printf(\"error: %v\", err) return } client := dynamodb.NewFromConfig(cfg) // we create a waiter instance by directly passing in a client // that satisfies the waiters client Interface. waiter := dynamodb.NewTableExistsWaiter(client) // params is the input to api operation used by the waiter params := \u0026dynamodb.DescribeTableInput { TableName: aws.String(\"test-table\") } // maxWaitTime is the maximum wait time, the waiter will wait for // the resource status. maxWaitTime := 5 * time.Minutes // Wait will poll until it gets the resource status, or max wait time // expires. err := waiter.Wait(context.TODO(), params, maxWaitTime) if err != nil { log.Printf(\"error: %v\", err) return } fmt.Println(\"Dynamodb table is now ready for write operations\") Overriding waiter configuration By default, the SDK uses the minimum delay and maximum delay value configured with optimal values defined by AWS services for different APIs. You can override waiter configuration by providing functional options during waiter construction, or when invoking a waiter operation.\nFor example, to override waiter configuration during waiter construction\nimport \"context\" import \"fmt\" import \"log\" import \"time\" import \"github.com/aws/aws-sdk-go-v2/aws\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/service/dynamodb\" // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { log.Printf(\"error: %v\", err) return } client := dynamodb.NewFromConfig(cfg) // we create a waiter instance by directly passing in a client // that satisfies the waiters client Interface. waiter := dynamodb.NewTableExistsWaiter(client, func (o *dynamodb.TableExistsWaiterOptions) { // override minimum delay to 10 seconds o.MinDelay = 10 * time.Second // override maximum default delay to 300 seconds o.MaxDelay = 300 * time.Second }) The Wait function on each waiter also takes in functional options.\nSimilar to the above example, you can override waiter configuration per Wait request.\n// params is the input to api operation used by the waiter params := \u0026dynamodb.DescribeTableInput { TableName: aws.String(\"test-table\") } // maxWaitTime is the maximum wait time, the waiter will wait for // the resource status. maxWaitTime := 5 * time.Minutes // Wait will poll until it gets the resource status, or max wait time // expires. err := waiter.Wait(context.TODO(), params, maxWaitTime, func (o *dynamodb.TableExistsWaiterOptions) { // override minimum delay to 5 seconds o.MinDelay = 5 * time.Second // override maximum default delay to 120 seconds o.MaxDelay = 120 * time.Second }) if err != nil { log.Printf(\"error: %v\", err) return } fmt.Println(\"Dynamodb table is now ready for write operations\") Advanced waiter configuration overrides You can additionally customize the waiter default behavior by providing a custom retryable function. The waiter-specific options also provides APIOptions to customize operation middlewares.\nFor example, to configure advanced waiter overrides.\nimport \"context\" import \"fmt\" import \"log\" import \"time\" import \"github.com/aws/aws-sdk-go-v2/aws\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/service/dynamodb\" import \"github.com/aws/aws-sdk-go-v2/service/dynamodb/types\" // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { log.Printf(\"error: %v\", err) return } client := dynamodb.NewFromConfig(cfg) // custom retryable defines if a waiter state is retryable or a terminal state. // For example purposes, we will configure the waiter to not wait // if table status is returned as `UPDATING` customRetryable := func(ctx context.Context, params *dynamodb.DescribeTableInput, output *dynamodb.DescribeTableOutput, err error) (bool, error) { if output.Table != nil { if output.Table.TableStatus == types.TableStatusUpdating { // if table status is `UPDATING`, no need to wait return false, nil\t} } } // we create a waiter instance by directly passing in a client // that satisfies the waiters client Interface. waiter := dynamodb.NewTableExistsWaiter(client, func (o *dynamodb.TableExistsWaiterOptions) { // override the service defined waiter-behavior o.Retryable = customRetryable }) ","categories":"","description":"Construct service clients and make operation calls to send requests to AWS services.","excerpt":"Construct service clients and make operation calls to send requests to …","ref":"/aws-sdk-go-v2/docs/making-requests/","tags":"","title":"Using the AWS SDK for Go V2 with AWS Services"},{"body":"The AWS SDK for Go V2 returns errors that satisfy the Go error interface type. You can use the Error() method to get a formatted string of the SDK error message without any special handling. Errors returned by the SDK may implement an Unwrap method. The Unwrap method is used by the SDK to provide additional contextual information to errors, while providing access to the underlying error or chain of errors. The Unwrap method should be used with the errors.As to handle unwrapping error chains.\nIt is important that your application check whether an error occurred after invoking a function or method that can return an error interface type. The most basic form of error handling looks similar to the following example:\nif err != nil { // Handle error return } Logging Errors The simplest form of error handling is traditionally to log or print the error message before returning or exiting from the application. For example:\nimport \"log\" // ... if err != nil { log.Printf(\"error: %s\", err.Error()) return } Service Client Errors The SDK wraps all errors returned by service clients with the smithy.OperationError error type. OperationError provides contextual information about the service name and operation that is associated with an underlying error. This information can be useful for applications that perform batches of operations to one or more services, with a centralized error handling mechanism. Your application can use errors.As to access this OperationError metadata.\nFor example:\nimport \"log\" import \"github.com/aws/smithy-go\" // ... if err != nil { var oe *smithy.OperationError if errors.As(err, \u0026oe) { log.Printf(\"failed to call service: %s, operation: %s, error: %v\", oe.Service(), oe.Operation(), oe.Unwrap()) } return } API Error Responses Service operations can return modeled error types to indicate specific errors. These modeled types can be used with errors.As to unwrap and determine if the operation failure was due to a specific error. For example Amazon S3 CreateBucket can return a BucketAlreadyExists error if a bucket of the same name already exists.\nFor example, to check if an error was a BucketAlreadyExists error:\nimport \"log\" import \"github.com/aws/aws-sdk-go-v2/service/s3/types\" // ... if err != nil { var bne *types.BucketAlreadyExists if errors.As(err, \u0026bne) { log.Println(\"error:\", bne) } return } All service API response errors implement the smithy.APIError interface type. This interface can be used to handle both modeled or un-modeled service error responses. This type provides access to the error code and message returned by the service. Additionally, this type provides indication of whether the fault of the error was due to the client or server if known. For example:\nimport \"log\" import \"github.com/aws/smithy-go\" // ... if err != nil { var ae smithy.APIError if errors.As(err, \u0026ae) { log.Printf(\"code: %s, message: %s, fault: %s\", ae.ErrorCode(), ae.ErrorMessage(), ae.ErrorFault().String()) } return } Retrieving Request Identifiers When working with AWS Support, you may be asked to provide the request identifier that identifies the request you are attempting to troubleshoot. You can use http.ResponseError and use the ServiceRequestID() method to retrieve the request identifier associated with error response.\nFor example:\nimport \"log\" import awshttp \"github.com/aws/aws-sdk-go-v2/aws/transport/http\" // ... if err != nil { var re *awshttp.ResponseError if errors.As(err, \u0026re) { log.Printf(\"requestID: %s, error: %v\", re.ServiceRequestID(), re.Unwrap()); } return } Amazon S3 Request Identifiers Amazon S3 requests contain additional identifiers that can be used to assist AWS Support with troubleshooting your request. You can use s3.ResponseError and call ServiceRequestID() and ServiceHostID() to retrieve the request ID and host ID.\nFor example:\nimport \"log\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... if err != nil { var re s3.ResponseError if errors.As(err, \u0026re) { log.Printf(\"requestID: %s, hostID: %s request failure\", re.ServiceRequestID(), re.ServiceHostID()); } return } ","categories":"","description":"Use the Error interface to handle errors from the AWS SDK for Go V2 or AWS service.","excerpt":"Use the Error interface to handle errors from the AWS SDK for Go V2 or …","ref":"/aws-sdk-go-v2/docs/handling-errors/","tags":"","title":"Handling Errors in the AWS SDK for Go V2"},{"body":"The AWS SDK for Go V2 includes the following utilities to help you more easily use AWS services. Find the SDK utilities in their related AWS service package.\n","categories":"","description":"Use the AWS SDK for Go V2 utilities to help use AWS services.","excerpt":"Use the AWS SDK for Go V2 utilities to help use AWS services.","ref":"/aws-sdk-go-v2/docs/sdk-utilities/","tags":"","title":"Using the AWS SDK for Go V2 Utilities"},{"body":" Modifying the client request pipeline can result in malformed/invalid requests, or can result in unexpected application errors. This functionality is meant for advanced uses cases not provided by the SDK interface by default.\nYou can customize AWS SDK for Go V2 client requests by registering one or more middleware to a service operation’s stack. The stack is composed of a series of steps: Initialize, Serialize, Build, Finalize, and Deserialize. Each step contains zero or more middleware that operate on that step’s input and output types. The following diagram and table provide an overview of how an operation’s request and response traverses the stack.\nStack Step Description Initialize Prepares the input, and sets any default parameters as needed. Serialize Serializes the input to a protocol format suitable for the target transport layer. Build Attach additional metadata to the serialized input, such as HTTP Content-Length. Finalize Final message preparation, including retries and authentication (SigV4 signing). Deserialize Deserialize responses from the protocol format into a structured type or error. Each middleware within a given step must have a unique identifier, which is determined by the middleware’s ID method. Middleware identifiers ensure that only one instance of a given middleware is registered to a step, and allows other step middleware to be inserted relative to it.\nYou attach step middleware by using a step’s Insert or Add methods. You use Add to attach a middleware to the beginning of a step by specifying middleware.Before as the RelativePosition, and middleware.After to attach to the end of the step. You use Insert to attach a middleware to a step by inserting the middleware relative to another step middleware.\nYou must use the Add method to safely insert custom step middleware. Using Insert creates a dependency between your custom middleware, and the middleware that you are inserting relative to. The middleware within a stack step must be considered opaque to avoid breaking changes occurring to your application.\nWriting a Custom Middleware Each stack step has an interface that you must satisfy in order attach a middleware to a given step. You can use one of the provided \u003cStep\u003eMiddlewareFunc functions to quickly satisfy this interface. The following table outlines the steps, their interface, and the helper function that can be used to satisfy the interface.\nStep Interface Helper Function Initialize InitializeMiddleware InitializeMiddlewareFunc Build BuildMiddleware BuildMiddlewareFunc Serialize SerializeMiddleware SerializeMiddlewareFunc Finalize FinalizeMiddleware FinalizeMiddlewareFunc Deserialize DeserializeMiddleware DeserializeMiddlewareFunc The following examples show how you can write a custom middleware to populate the Bucket member of the Amazon S3 GetObject API calls if one is not provided. This middleware will be referenced in proceeding examples to show how to attach step middleware to the stack.\nimport \"github.com/aws/smithy-go/aws\" import \"github.com/aws/smithy-go/middleware\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... var defaultBucket = middleware.InitializeMiddlewareFunc(\"DefaultBucket\", func( ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler, ) ( out middleware.InitializeOutput, metadata middleware.Metadata, err error, ) { // Type switch to check if the input is s3.GetObjectInput, if so and the bucket is not set, populate it with // our default. switch v := in.Parameters.(type) { case *s3.GetObjectInput: if v.Bucket == nil { v.Bucket = aws.String(\"my-default-bucket\") } } // Middleware must call the next middleware to be executed in order to continue execution of the stack. // If an error occurs, you can return to prevent further execution. return next.HandleInitialize(ctx, in) }) Attaching Middleware to All Clients You can attach your custom step middleware to every client by adding the middleware using the APIOptions member of the aws.Config type. The following examples attaches the defaultBucket middleware to every client constructed using your applications aws.Config object:\nimport \"context\" import \"github.com/aws/aws-sdk-go-v2/aws\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" import \"github.com/aws/smithy-go/middleware\" // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { // handle error } cfg.APIOptions = append(cfg.APIOptions, func(stack *middleware.Stack) error { // Attach the custom middleware to the beginning of the Initialize step return stack.Initialize.Add(defaultBucket, middleware.Before) }) client := s3.NewFromConfig(cfg) Attaching Middleware to a Specific Operation You can attach your custom step middleware to a specific client operation by modifying the client’s APIOptions member using the variadic argument list for an operation. The following examples attaches the defaultBucket middleware to a specific Amazon S3 GetObject operation invocation:\nimport \"context\" import \"github.com/aws/aws-sdk-go-v2/aws\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" import \"github.com/aws/smithy-go/middleware\" // ... // registerDefaultBucketMiddleware registers the defaultBucket middleware with the provided stack. func registerDefaultBucketMiddleware(stack *middleware.Stack) error { // Attach the custom middleware to the beginning of the Initialize step return stack.Initialize.Add(defaultBucket, middleware.Before) } // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { // handle error } client := s3.NewFromConfig(cfg) object, err := client.GetObject(context.TODO(), \u0026s3.GetObjectInput{ Key: aws.String(\"my-key\"), }, func(options *s3.Options) { // Register the defaultBucketMiddleware for this operation only options.APIOptions = append(options.APIOptions, registerDefaultBucketMiddleware) }) Passing Metadata Down the Stack In certain situations, you may find that you require two or more middleware to function in tandem by sharing information or state. You can use context.Context to pass this metadata by using middleware.WithStackValue. middleware.WithStackValue attaches the given key-value pair to the provided context, and safely limits the scope to the currently executing stack. These stack-scoped values can be retrieved from a context using middleware.GetStackValue and providing the key used to stored the corresponding value. Keys must be comparable, and you must define your own types as context keys to avoid collisions. The following examples shows how two middleware can use context.Context to pass information down the stack.\nimport \"context\" import \"github.com/aws/smithy-go/middleware\" // ... type customKey struct {} func GetCustomKey(ctx context.Context) (v string) { v, _ = middleware.GetStackValue(ctx, customKey{}).(string) return v } func SetCustomKey(ctx context.Context, value string) context.Context { return middleware.WithStackValue(ctx, customKey{}, value) } // ... var customInitalize = middleware.InitializeMiddlewareFunc(\"customInitialize\", func( ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler, ) ( out middleware.InitializeOutput, metadata middleware.Metadata, err error, ) { ctx = SetCustomKey(ctx, \"my-custom-value\") return next.HandleInitialize(ctx, in) }) var customBuild = middleware.BuildMiddlewareFunc(\"customBuild\", func( ctx context.Context, in middleware.BuildInput, next middleware.BuildHandler, ) ( out middleware.BuildOutput, metadata middleware.Metadata, err error, ) { customValue := GetCustomKey(ctx) // use customValue return next.HandleBuild(ctx, in) }) Metadata Provided by the SDK The AWS SDK for Go V2 provides several metadata values that can be retrieved from the provided context. These values can be used to enable more dynamic middleware that modifies its behavior based on the executing service, operation, or target region. A few of the available keys are provided in the table below:\nKey Retriever Description ServiceID GetServiceID Retrieve the service identifier for the executing stack. This can be compared to the service client package’s ServiceID constant. OperationName GetOperationName Retrieve the operation name for the executing stack. Logger GetLogger Retrieve the logger that can be used for logging message from the middleware. Passing Metadata Up the Stack You can pass metadata up through the stack by adding metadata key and value pairs using the middleware.Metadata. Each middleware step returns an output structure, metadata, and an error. Your custom middleware must return the metadata received from calling the next handler in the step. This ensures that metadata added by downstream middleware propagates to the application invoking the service operation. The resulting metadata is accessible to the invoking application by either the operation’s output shape via the ResultMetadata structure member.\nThe following examples shows how a custom middleware can add metadata that is returned as part of the operation output.\nimport \"context\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" import \"github.com/aws/smithy-go/middleware\" // ... type customKey struct{} func GetCustomKey(metadata middleware.Metadata) (v string) { v, _ = metadata.Get(customKey{}).(string) return v } func SetCustomKey(metadata *middleware.Metadata, value string) { metadata.Set(customKey{}, value) } // ... var customInitalize = middleware.InitializeMiddlewareFunc(\"customInitialize\", func ( ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler, ) ( out middleware.InitializeOutput, metadata middleware.Metadata, err error, ) { out, metadata, err = next.HandleInitialize(ctx, in) if err != nil { return out, metadata, err } SetCustomKey(\u0026metadata, \"my-custom-value\") return out, metadata, nil }) // ... client := s3.NewFromConfig(cfg, func (options *s3.Options) { options.APIOptions = append(options.APIOptions, func(stack *middleware.Stack) error { return stack.Initialize.Add(customInitalize, middleware.After) }) }) out, err := client.GetObject(context.TODO(), \u0026s3.GetObjectInput{ // input parameters }) if err != nil { // handle error } customValue := GetCustomKey(out.ResponseMetadata) ","categories":"","description":"How to use stack step middleware to customize AWS SDK for Go V2 client requests.","excerpt":"How to use stack step middleware to customize AWS SDK for Go V2 client …","ref":"/aws-sdk-go-v2/docs/middleware/","tags":"","title":"Customizing the AWS SDK for Go V2 Client Requests"},{"body":"How do I configure my SDK’s HTTP client? Are there any guidelines or best practices? We are unable to provide guidance to customers on how to configure their HTTP workflow in a manner that is most effective for their particular workload. The answer to this is the product of a multivariate equation, with input factors including but not limited to:\nthe network footprint of the application (TPS, throughput, etc.) the services being used the compute characteristics of the deployment the geographical nature of the deployment the desired application behavior or needs of the application itself (SLAs, timings, etc.) How should I configure operation timeouts? Much like the previous question, it depends. Elements to consider here include the following:\nAll of the above factors concerning HTTP client config Your own application timing or SLA constraints (e.g. if you yourself serve traffic to other consumers) The answer to this question should almost NEVER be based on pure empirical observation of upstream behavior - e.g. “I made 1000 calls to this operation, it took at most 5 seconds so I will set the timeout based on that with a safety factor of 2x to 10 seconds”. Environment conditions can change, services can temporarily degrade, and these types of assumptions can become wrong without warning.\nRequests made by the SDK are timing out or taking too long, how do I fix this? We are unable to assist with extended or timed-out operation calls due to extended time spent on the wire. “Wire time” in the SDK is defined as any of the following:\nTime spent in an SDK client’s HTTPClient.Do() method Time spent in Read()s on an HTTP response body that has been forwarded to the caller (e.g. GetObject) If you are experiencing issues due to operation latency or timeouts, your first course of action should be to obtain telemetry of the SDK operation lifecycle to determine the timing breakdown between time spent on the wire and the surrounding overhead of the operation. See the guide on timing SDK operations, which contains a reusable code snippet that can achieve this.\nHow do I fix a read: connection reset error? The SDK retries any errors matching the connection reset pattern by default. This will cover error handling for most operations, where the operation’s HTTP response is fully consumed and deserialized into its modeled result type.\nHowever, this error can still occur in a context outside of the retry loop: certain service operations directly forward the API’s HTTP response body to the caller to be consumed from the wire directly via io.ReadCloser (e.g. GetObject’s object payload). You may encounter this error when performing a Read on the response body.\nThis error indicates that your host, the service or any intermediary party (e.g. NAT gateways, proxies, load balancers) closed the connection while attempting to read the response.\nThis can occur for several reasons:\nYou did not consume the response body for some time after the response itself was received (after the service operation was called). We recommend you consume the HTTP response body as soon as possible for these types of operations. You did not close a previously-received response body. This can cause connection resets on certain platforms. You MUST close any io.ReadCloser instances provided in an operation’s response, regardless of whether you consume its contents. Beyond that, try running a tcpdump for an affected connection at the edge of your network (e.g. after any proxies that you control). If you see that the AWS endpoint seems to be sending a TCP RST, you should use the AWS support console to open a case against the offending service. Be prepared to provide request IDs and specific timestamps of when the issue occured.\nWhy am I getting “invalid signature” errors when using an HTTP proxy with the SDK? The signature algorithm for AWS services (generally sigv4) is tied to the serialized request’s headers, more specifically most headers prefixed with X-. Proxies are prone to modifying the outgoing request by adding additional forwarding information (often via an X-Forwarded-For header) which effectively breaks the signature that the SDK calculated.\nIf you’re using an HTTP proxy and experiencing signature errors, you should work to capture the request as it appears outgoing from the proxy and determine whether it is different.\n","categories":"","description":"Answers to some commonly-asked questions about the {{% alias sdk-go %}}","excerpt":"Answers to some commonly-asked questions about the {{% alias sdk-go …","ref":"/aws-sdk-go-v2/docs/faq/","tags":"","title":"Frequently Asked Questions"},{"body":"When using the SDK in your application, you’ll want to mock out the SDK for your application’s unit test. Mocking out the SDK allows your test to be focused on what you want to test, not the internals of the SDK.\nTo support mocking use Go interfaces instead of concrete service client, paginators, and waiter types, (e.g. s3.Client). This allows your application to use patterns like dependency injection to test your application logic.\nMocking Client Operations In this example, S3GetObjectAPI is an interface that defines the set of Amazon S3 API operations required by the GetObjectFromS3 function. S3GetObjectAPI is satisfied by the Amazon S3 client’s GetObject method.\nimport \"context\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... type S3GetObjectAPI interface { GetObject(ctx context.Context, params *s3.GetObjectInput, optFns ...func(*s3.Options)) (*s3.GetObjectOutput, error) } func GetObjectFromS3(ctx context.Context, api S3GetObjectAPI, bucket, key string) ([]byte, error) { object, err := api.GetObject(ctx, \u0026s3.GetObjectInput{ Bucket: \u0026bucket, Key: \u0026key, }) if err != nil { return nil, err } defer object.Body.Close() return ioutil.ReadAll(object.Body) } To test the GetObjectFromS3 function, use the mockGetObjectAPI to satisfy the S3GetObjectAPI interface definition. Then use the mockGetObjectAPI type to mock output and error responses returned from the service client.\nimport \"testing\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... type mockGetObjectAPI func(ctx context.Context, params *s3.GetObjectInput, optFns ...func(*s3.Options)) (*s3.GetObjectOutput, error) func (m mockGetObjectAPI) GetObject(ctx context.Context, params *s3.GetObjectInput, optFns ...func(*s3.Options)) (*s3.GetObjectOutput, error) { return m(ctx, params, optFns...) } func TestGetObjectFromS3(t *testing.T) { cases := []struct { client func(t *testing.T) S3GetObjectAPI bucket string key\tstring expect []byte }{ { client: func(t *testing.T) S3GetObjectAPI { return mockGetObjectAPI(func(ctx context.Context, params *s3.GetObjectInput, optFns ...func(*s3.Options)) (*s3.GetObjectOutput, error) { t.Helper() if params.Bucket == nil { t.Fatal(\"expect bucket to not be nil\") } if e, a := \"fooBucket\", *params.Bucket; e != a { t.Errorf(\"expect %v, got %v\", e, a) } if params.Key == nil { t.Fatal(\"expect key to not be nil\") } if e, a := \"barKey\", *params.Key; e != a { t.Errorf(\"expect %v, got %v\", e, a) } return \u0026s3.GetObjectOutput{ Body: ioutil.NopCloser(bytes.NewReader([]byte(\"this is the body foo bar baz\"))), }, nil }) }, bucket: \"fooBucket\", key:\t\"barKey\", expect: []byte(\"this is the body foo bar baz\"), }, } for i, tt := range cases { t.Run(strconv.Itoa(i), func(t *testing.T) { ctx := context.TODO() content, err := GetObjectFromS3(ctx, tt.client(t), tt.bucket, tt.key) if err != nil { t.Fatalf(\"expect no error, got %v\", err) } if e, a := tt.expect, content; bytes.Compare(e, a) != 0 { t.Errorf(\"expect %v, got %v\", e, a) } }) } } Mocking Paginators Similar to service clients, paginators can be mocked by defining a Go interface for the paginator. That interface would be used by your application’s code. This allows the SDK’s implementation to be used when your application is running, and a mocked implementation for testing.\nIn the following example, ListObjectsV2Pager is an interface that defines the behaviors for the Amazon S3 ListObjectsV2Paginator. required by CountObjects function.\nimport \"context\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... type ListObjectsV2Pager interface { HasMorePages() bool NextPage(context.Context, ...func(*s3.Options)) (*s3.ListObjectsV2Output, error) } func CountObjects(ctx context.Context, pager ListObjectsV2Pager) (count int, err error) { for pager.HasMorePages() { var output *s3.ListObjectsV2Output output, err = pager.NextPage(ctx) if err != nil { return count, err } count += int(output.KeyCount) } return count, nil } To test CountObjects, create the mockListObjectsV2Pager type to satisfy the ListObjectsV2Pager interface definition. Then use mockListObjectsV2Pager to replicate the paging behavior of output and error responses from the service operation paginator.\nimport \"context\" import\t\"fmt\" import \"testing\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... type mockListObjectsV2Pager struct { PageNum int Pages []*s3.ListObjectsV2Output } func (m *mockListObjectsV2Pager) HasMorePages() bool { return m.PageNum \u003c len(m.Pages) } func (m *mockListObjectsV2Pager) NextPage(ctx context.Context, f ...func(*s3.Options)) (output *s3.ListObjectsV2Output, err error) { if m.PageNum \u003e= len(m.Pages) { return nil, fmt.Errorf(\"no more pages\") } output = m.Pages[m.PageNum] m.PageNum++ return output, nil } func TestCountObjects(t *testing.T) { pager := \u0026mockListObjectsV2Pager{ Pages: []*s3.ListObjectsV2Output{ { KeyCount: 5, }, { KeyCount: 10, }, { KeyCount: 15, }, }, } objects, err := CountObjects(context.TODO(), pager) if err != nil { t.Fatalf(\"expect no error, got %v\", err) } if expect, actual := 30, objects; expect != actual { t.Errorf(\"expect %v, got %v\", expect, actual) } } ","categories":"","description":"How to mock the AWS SDK for Go V2 when unit testing your application.","excerpt":"How to mock the AWS SDK for Go V2 when unit testing your application.","ref":"/aws-sdk-go-v2/docs/unit-testing/","tags":"","title":"Unit Testing with the AWS SDK for Go V2"},{"body":"You can use AWS Cloud9 with the AWS SDK for Go V2 to write and run your Go code using just a browser. AWS Cloud9 includes tools such as a code editor and terminal. The AWS Cloud9 IDE is cloud based, so you can work on your projects from your office, home, or anywhere using an internet-connected machine. For general information about AWS Cloud9, see the AWS Cloud9 User Guide.\nFollow the instructions below to set up AWS Cloud9 with the AWS SDK for Go V2:\nSet up Your AWS Account to Use AWS Cloud9 To start using AWS Cloud9, sign in to the AWS Cloud9 console as an AWS Identity and Access Management (IAM) entity (for example, an IAM user) in your AWS account which has access permissions for AWS Cloud9.\nReview Team Setup for AWS Cloud9 in the AWS Cloud9 User Guide, for help with setting up an IAM entity in your AWS account to access AWS Cloud9, and to sign in to the AWS Cloud9 console.\nSet up Your AWS Cloud9 Development Environment After you sign in to the AWS Cloud9 console, use the console to create an AWS Cloud9 development environment. After you create the environment, AWS Cloud9 opens the IDE for that environment.\nSee Creating an Environment in AWS Cloud9 in the AWS Cloud9 User Guide for details.\nAs you create your environment in the console for the first time, we recommend that you choose the option to Create a new instance for environment (EC2). This option tells AWS Cloud9 to create an environment, launch an Amazon EC2 instance, and then connect the new instance to the new environment. This is the fastest way to begin using AWS Cloud9.\nSet up the AWS SDK for Go V2 After AWS Cloud9 opens the IDE for your development environment, use the IDE to set up the AWS SDK for Go V2 in your environment, as follows.\nIf the terminal isn’t already open in the IDE, open it. On the menu bar in the IDE, choose Window, New Terminal.\nValidate the AWS Cloud9 available Go version.\ngo version If the Go version reports a version less than 1.15, or the IDE can’t find the Go binary follow the guide to Install/Upgrade Go.\nFollow the Getting Started guide to set up a Go project under ~/environment, or follow the steps to Download Example Code\nDownload Example Code Use the terminal you opened in the previous step to download example code for the AWS SDK for Go V2 into the AWS Cloud9 development environment.\nTo do this, run the following command. This command downloads a copy of all the code examples used in the official AWS SDK documentation into your environment’s root directory.\ngit clone https://github.com/awsdocs/aws-doc-sdk-examples.git To find code examples for the AWS SDK for Go V2, use the Environment window to open the ENVIRONMENT_NAME/aws-doc-sdk-examples/gov2 directory, where ENVIRONMENT_NAME is the name of your development environment.\nRun Example Code To run code in your AWS Cloud9 development environment, see Run Your Code in the AWS Cloud9 User Guide.\nInstalling/Upgrading AWS Cloud9 Go Version If the IDE can’t find Go or version of Go doesn’t meet the minimum require version, run the following commands, one at a time in this order, to install it. (These commands assume you chose the option to Create a new instance for environment (EC2), earlier in this topic. Also, these commands assume the latest stable version of Go at the time this topic was written; for more information, see Downloads on The Go Programming Language website.)\nwget https://golang.org/dl/go1.15.5.linux-amd64.tar.gz # Download the Go installer. sudo tar -C /usr/local -xzf ./go1.15.5.linux-amd64.tar.gz # Install Go. rm ./go1.15.5.linux-amd64.tar.gz # Delete the Go installer, as you no longer need it. After you install Go, add the path to the Go binary to your PATH environment variable. To do this, add the following code to the end of your shell profile file (for example, ~/.bashrc in Amazon Linux, assuming you chose the option to Create a new instance for environment (EC2), earlier in this topic), and then save the file.\nPATH=$PATH:/usr/local/go/bin After you save the file, source the ~/.bashrc file so that the terminal can now find the Go binary you just referenced. To do this, run the following command. (This command assumes you chose the option to Create a new instance for environment (EC2), earlier in this topic.)\n. ~/.bashrc ","categories":"","description":"","excerpt":"You can use AWS Cloud9 with the AWS SDK for Go V2 to write and run …","ref":"/aws-sdk-go-v2/docs/cloud9-go/","tags":"","title":"Using AWS Cloud9 with the AWS SDK for Go V2"},{"body":"Cloud security at Amazon Web Services (AWS) is the highest priority. As an AWS customer, you benefit from a data center and network architecture that is built to meet the requirements of the most security-sensitive organizations. Security is a shared responsibility between AWS and you. The Shared Responsibility Model describes this as Security of the Cloud and Security in the Cloud.\nSecurity of the Cloud– AWS is responsible for protecting the infrastructure that runs all of the services offered in the AWS Cloud and providing you with services that you can use securely. Our security responsibility is the highest priority at AWS, and the effectiveness of our security is regularly tested and verified by third-party auditors as part of the AWS Compliance Programs.\nSecurity in the Cloud– Your responsibility is determined by the AWS service you are using, and other factors including the sensitivity of your data, your organization’s requirements, and applicable laws and regulations.\n","categories":"","description":"","excerpt":"Cloud security at Amazon Web Services (AWS) is the highest priority. …","ref":"/aws-sdk-go-v2/docs/security/","tags":"","title":"Security for this AWS Product or Service"},{"body":"The AWS SDK for Go V2 examples can help you write your own Go applications that use Amazon Web Services. The examples assume you have already set up and configured the SDK (that is, you have imported all required packages and set your credentials and region). For more information, see Getting Started and Configuring the SDK.\nFind the source code for these examples and others in the AWS documentation code examples repository on GitHub. To propose a new code example for the AWS documentation team to consider producing, create a new request. The team is looking to produce code examples that cover broader scenarios and use cases, versus simple code snippets that cover only individual API calls. For instructions, see the Proposing new code examples section in the Readme on GitHub.\n","categories":"","description":"","excerpt":"The AWS SDK for Go V2 examples can help you write your own Go …","ref":"/aws-sdk-go-v2/docs/code-examples/","tags":"","title":"Code Examples"},{"body":"The AWS SDK for Go V2 provides the ability to configure the authentication behavior service. In most cases, the default configuration will suffice, but configuring custom authentication allows for additional behavior such as working with pre-release service features.\nDefinitions This section provides a high-level description of authentication components in the AWS SDK for Go V2.\nAuthScheme An AuthScheme is the interface that defines the workflow through which the SDK retrieves a caller identity and attaches it to an operation request.\nAn auth scheme uses the following components, described in detail further below:\nA unique ID which identifies the scheme An identity resolver, which returns a caller identity used in the signing process (e.g. your AWS credentials) A signer, which performs the actual injection of caller identity into the operation’s transport request (e.g. the Authorization HTTP header) Each service client options includes an AuthSchemes field, which by default is populated with the list of auth schemes supported by that service.\nAuthSchemeResolver Each service client options includes an AuthSchemeResolver field. This interface, defined per-service, is the API called by the SDK to determine the possible authentication options for each operation.\nIMPORTANT: The auth scheme resolver does NOT dictate what auth scheme is used. It returns a list of schemes that can be used (“options”), the final scheme is selected through a fixed algorithm described here.\nOption Returned from a call to ResolverAuthSchemes, an Option represents a possible authentication option.\nAn option consists of three sets of information:\nAn ID representing the possible scheme An opaque set of properties to be provided to the scheme’s identity resolver An opaque set of properties to be provided to the scheme’s signer a note on properties For 99% of use cases, callers need not be concerned with the opaque properties for identity resolution and signing. The SDK will pull out the necessary properties for each scheme and pass them to the strongly-typed interfaces exposed in the SDK. For example, the default auth resolver for services encode the SigV4 option to have signer properties for the signing name and region, the values of which are passed to the client’s configured v4.HTTPSigner implementation when SigV4 is selected.\nIdentity An Identity is an abstract representation of who the SDK caller is.\nThe most common type of identity used in the SDK is a set of aws.Credentials. For most use cases, the caller need not concern themselves with Identity as an abstraction and can work with the concrete types directly.\nNote: to preserve backwards compatibility and prevent API confusion, the AWS SDK-specific identity type aws.Credentials does not directly satisfy the Identity interface. This mapping is handled internally.\nIdentityResolver IdentityResolver is the interface through which an Identity is retrieved.\nConcrete versions of IdentityResolver exist in the SDK in strongly-typed form (e.g. aws.CredentialsProvider), the SDK handles this mapping internally.\nA caller will only need to directly implement the IdentityResolver interface when defining an external auth scheme.\nSigner Signer is the interface through which a request is supplemented with the retrieved caller Identity.\nConcrete versions of Signer exist in the SDK in strongly-typed form (e.g. v4.HTTPSigner), the SDK handles this mapping internally.\nA caller will only need to directly implement the Signer interface when defining an external auth scheme.\nAuthResolverParameters Each service takes a specific set of inputs which are passed to its resolution function, defined in each service package as AuthResolverParameters.\nThe base resolver parameters are as follows:\nname type description Operation string The name of the operation being invoked. Region string The client’s AWS region. Only present for services that use SigV4[A]. If you are implementing your own resolver, you should never need to construct your own instance of its parameters. The SDK will source these values per-request and pass them to your implementation.\nAuth scheme resolution workflow When you call an AWS service operation through the SDK, the following sequence of actions occurs after the request has been serialized:\nThe SDK calls the client’s AuthSchemeResolver.ResolveAuthSchemes() API, sourcing the input parameters as necessary, to obtain a list of possible Options for the operation. The SDK iterates over that list and selects the first scheme that satisfies the following conditions. A scheme with matching ID is present in the client’s own AuthSchemes list The scheme’s identity resolver exists (is non-nil) on the client’s Options (checked via the scheme’s GetIdentityResolver method, the mapping to the concrete identity resolver types described above is handled internally) (1) Assuming a viable scheme was selected, the SDK invokes its GetIdentityResolver() API to retrieve the caller’s identity. For example, the builtin SigV4 auth scheme will map to the client’s Credentials provider internally. The SDK calls the identity resolver’s GetIdentity() (e.g. aws.CredentialProvider.Retrieve() for SigV4). The SDK calls the endpoint resolver’s ResolveEndpoint() to find the endpoint for the request. The endpoint may include additional metadata that influences the signing process (e.g. unique signing name for S3 Object Lambda). The SDK calls the auth scheme’s Signer() API to retrieve its signer, and uses its SignRequest() API to sign the request with the previously-retrieved caller identity. (1) If the SDK encounters the anonymous option (ID smithy.api#noAuth) in the list, it is selected automatically, as there is no corresponding identity resolver.\nNatively-supported AuthSchemes The following auth schemes are natively supported by AWS SDK for Go V2.\nName Scheme ID Identity resolver Signer Notes SigV4 aws.auth#sigv4 aws.CredentialsProvider v4.HTTPSigner The current default for most AWS service operations. SigV4A aws.auth#sigv4a aws.CredentialsProvider n/a SigV4A usage is limited at this time, the signer implementation is internal. SigV4Express com.amazonaws.s3#sigv4express s3.ExpressCredentialsProvider v4.HTTPSigner Used for Express One Zone. HTTP Bearer smithy.api#httpBearerAuth smithybearer.TokenProvider smithybearer.Signer Used by codecatalyst. Anonymous smithy.api#noAuth n/a n/a No authentication - no identity is required, and the request is not signed or authenticated. Identity configuration In AWS SDK for Go V2, the identity components of an auth scheme are configured in SDK client Options. The SDK will automatically pick up and use the values for these components for the scheme it selects when an operation is called.\nNote: For backwards compatibility reasons, the SDK implicitly allows the use of the anonymous auth scheme if no identity resolvers are configured. This can be manually achieved by setting all identity resolvers on a client’s Options to nil (the sigv4 identity resolver can also be set to aws.AnonymousCredentials{}).\nSigner configuration In AWS SDK for Go V2, the signer components of an auth scheme are configured in SDK client Options. The SDK will automatically pick up and use the values for these components for the scheme it selects when an operation is called. No additional configuration is necessary.\nCustom auth scheme In order to define a custom auth scheme and configure it for use, the caller must do the following:\nDefine an AuthScheme implementation Register the scheme on the SDK client’s AuthSchemes list Instrument the SDK client’s AuthSchemeResolver to return an auth Option with the scheme’s ID where applicable The following services have unique or customized authentication behavior. We recommend you delegate to the default implementation and wrap accordingly if you require custom authentication behavior therein:\nService Notes S3 Conditional use of SigV4A and SigV4Express depending on operation input. EventBridge Conditional use of SigV4A depending on operation input. Cognito Certain operations are anonymous-only. SSO Certain operations are anonymous-only. STS Certain operations are anonymous-only. ","categories":"","description":"Customizing service client authentication.","excerpt":"Customizing service client authentication.","ref":"/aws-sdk-go-v2/docs/configuring-sdk/auth/","tags":"","title":"Configuring Authentication"},{"body":"IAM Authentication The auth package provides utilities for generating authentication tokens for connecting to Amazon RDS MySQL and PostgreSQL database instances. Using the BuildAuthToken method, you generate a database authorization token by providing the database endpoint, AWS Region, username, and a aws.CredentialProvider implementation that returns IAM credentials with permission to connect to the database using IAM database authentication. To learn more about configuring Amazon RDS with IAM authentication see the following Amazon RDS Developer Guide resources:\nEnabling and disabling IAM database authentication Creating and using an IAM policy for IAM database access Creating a database account using IAM authentication The following examples shows how to generate an authentication token to connect to an Amazon RDS database:\nimport \"context\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/feature/rds/auth\" // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { panic(\"configuration error: \" + err.Error()) } authenticationToken, err := auth.BuildAuthToken( context.TODO(), \"mydb.123456789012.us-east-1.rds.amazonaws.com:3306\", // Database Endpoint (With Port) \"us-east-1\", // AWS Region \"jane_doe\", // Database Account cfg.Credentials, ) if err != nil { panic(\"failed to create authentication token: \" + err.Error()) } ","categories":"","description":"Using the AWS SDK for Go V2 Amazon RDS Utilities","excerpt":"Using the AWS SDK for Go V2 Amazon RDS Utilities","ref":"/aws-sdk-go-v2/docs/sdk-utilities/rds/","tags":"","title":"Amazon RDS Utilities"},{"body":"Amazon CloudFront URL Signer The Amazon CloudFront URL signer simplifies the process of creating signed URLs. A signed URL includes information, such as an expiration date and time, that enables you to control access to your content. Signed URLs are useful when you want to distribute content through the internet, but want to restrict access to certain users (for example, to users who have paid a fee).\nTo sign a URL, create a URLSigner instance with your CloudFront key pair ID and the associated private key. Then call the Sign or SignWithPolicy method and include the URL to sign. For more information about Amazon CloudFront key pairs, see Creating CloudFront Key Pairs for Your Trusted Signers in the CloudFront Developer Guide.\nThe following example creates a signed URL that’s valid for one hour after it is created.\nimport \"github.com/aws/aws-sdk-go-v2/feature/cloudfront/sign\" // ... signer := sign.NewURLSigner(keyID, privKey) signedURL, err := signer.Sign(rawURL, time.Now().Add(1*time.Hour)) if err != nil { log.Fatalf(\"Failed to sign url, err: %s\\n\", err.Error()) return } For more information about the signing utility, see the sign package in the AWS SDK for Go V2 API Reference.\n","categories":"","description":"Using the AWS SDK for Go V2 Amazon CloudFront Utilities","excerpt":"Using the AWS SDK for Go V2 Amazon CloudFront Utilities","ref":"/aws-sdk-go-v2/docs/sdk-utilities/cloudfront/","tags":"","title":"Amazon CloudFront Utilities"},{"body":"This AWS product or service follows the shared responsibility model through the specific Amazon Web Services (AWS) services it supports. For AWS service security information, see the AWS service security documentation page and AWS services that are in scope of AWS compliance efforts by compliance program.\nThe security and compliance of Amazon Web Services (AWS) services is assessed by third-party auditors as part of multiple AWS compliance programs. These include SOC, PCI, FedRAMP, HIPAA, and others. AWS provides a frequently updated list of AWS services in scope of specific compliance programs at AWS Services in Scope by Compliance Program.\nThird-party audit reports are available for you to download using AWS Artifact. For more information, see Downloading Reports in AWS Artifact.\nFor more information about AWS compliance programs, see AWS Compliance Programs.\nYour compliance responsibility when using this AWS product or service to access an AWS service is determined by the sensitivity of your data, your organization’s compliance objectives, and applicable laws and regulations. If your use of an AWS service is subject to compliance with standards such as HIPAA, PCI, or FedRAMP, AWS provides resources to help:\nSecurity and Compliance Quick Start Guides – Deployment guides that discuss architectural considerations and provide steps for deploying security-focused and compliance-focused baseline environments on AWS. Architecting for HIPAA Security and Compliance Whitepaper – A whitepaper that describes how companies can use AWS to create HIPAA-compliant applications. AWS Compliance Resources – A collection of workbooks and guides that might apply to your industry and location. AWS Config – A service that assesses how well your resource configurations comply with internal practices, industry guidelines, and regulations. AWS Security Hub – A comprehensive view of your security state within AWS that helps you check your compliance with security industry standards and best practices. ","categories":"","description":"","excerpt":"This AWS product or service follows the shared responsibility model …","ref":"/aws-sdk-go-v2/docs/security/compliance-validation/","tags":"","title":"Compliance Validation for this AWS Product or Service"},{"body":" Endpoint resolution is an advanced SDK topic. By changing these settings you risk breaking your code. The default settings should be applicable to most users in production environments.\nThe AWS SDK for Go V2 provides the ability to configure a custom endpoint to be used for a service. In most cases, the default configuration will suffice. Configuring custom endpoints allows for additional behavior, such as working with pre-release versions of a service.\nCustomization There are two “versions” of endpoint resolution config within the SDK.\nv2, released in Q3 of 2023, configured via: EndpointResolverV2 BaseEndpoint v1, released alongside the SDK, configured via: EndpointResolver We recommend users of v1 endpoint resolution migrate to v2 to obtain access to newer endpoint-related service features.\nV2: EndpointResolverV2 + BaseEndpoint In resolution v2, EndpointResolverV2 is the definitive mechanism through which endpoint resolution occurs. The resolver’s ResolveEndpoint method is invoked as part of the workflow for every request you make in the SDK. The hostname of the Endpoint returned by the resolver is used as-is when making the request (operation serializers can still append to the HTTP path, however).\nResolution v2 includes an additional client-level config, BaseEndpoint, which is used to specify a “base” hostname for the instance of your service. The value set here is not definitive– it is ultimately passed as a parameter to the client’s EndpointResolverV2 when final resolution occurs (read on for more information about EndpointResolverV2 parameters). The resolver implementation then has the opportunity to inspect and potentially modify that value to determine the final endpoint.\nFor example, if you perform an S3 GetObject request against a given bucket with a client where you’ve specified a BaseEndpoint, the default resolver will inject the bucket into the hostname if it is virtual-host compatible (assuming you haven’t disabled virtual-hosting in client config).\nIn practice, BaseEndpoint will most likely be used to point your client at a development or preview instance of a service.\nEndpointResolverV2 parameters Each service takes a specific set of inputs which are passed to its resolution function, defined in each service package as EndpointParameters.\nEvery service includes the following base parameters, which are used to facilitate general endpoint resolution within AWS:\nname type description Region string The client’s AWS region Endpoint string The value set for BaseEndpoint in client config UseFips bool Whether FIPS endpoints are enabled in client config UseDualStack bool Whether dual-stack endpoints are enabled in client config Services can specify additional parameters required for resolution. For example, S3’s EndpointParameters include the bucket name, as well as several S3-specific feature settings such as whether virtual host addressing is enabled.\nIf you are implementing your own EndpointResolverV2, you should never need to construct your own instance of EndpointParameters. The SDK will source the values per-request and pass them to your implementation.\nA note about Amazon S3 Amazon S3 is a complex service with many of its features modeled through complex endpoint customizations, such as bucket virtual hosting, S3 MRAP, and more.\nBecause of this, we recommend that you don’t replace the EndpointResolverV2 implementation in your S3 client. If you need to extend its resolution behavior, perhaps by sending requests to a local development stack with additional endpoint considerations, we recommend wrapping the default implementation such that it delegates back to the default as a fallback (shown in examples below).\nExamples With BaseEndpoint The following code snippet shows how to point your S3 client at a local instance of a service, which in this example is hosted on the loopback device at port 8080.\nclient := s3.NewFromConfig(cfg, func (o *svc.Options) { o.BaseEndpoint = aws.String(\"https://localhost:8080/\") }) With EndpointResolverV2 The following code snippet shows how to inject custom behavior into S3’s endpoint resolution using EndpointResolverV2.\nimport ( \"context\" \"net/url\" \"github.com/aws/aws-sdk-go-v2/service/s3\" smithyendpoints \"github.com/aws/smithy-go/endpoints\" ) type resolverV2 struct { // you could inject additional application context here as well } func (*resolverV2) ResolveEndpoint(ctx context.Context, params s3.EndpointParameters) ( smithyendpoints.Endpoint, error, ) { if /* input params or caller context indicate we must route somewhere */ { u, err := url.Parse(\"https://custom.service.endpoint/\") if err != nil { return smithyendpoints.Endpoint{}, err } return smithyendpoints.Endpoint{ URI: *u, }, nil } // delegate back to the default v2 resolver otherwise return s3.NewDefaultEndpointResolverV2().ResolveEndpoint(ctx, params) } func main() { // load config... client := s3.NewFromConfig(cfg, func (o *s3.Options) { o.EndpointResolverV2 = \u0026resolverV2{ // ... } }) } With both The following sample program demonstrates the interaction between BaseEndpoint and EndpointResolverV2. This is an advanced use case:\nimport ( \"context\" \"fmt\" \"log\" \"net/url\" \"github.com/aws/aws-sdk-go-v2\" \"github.com/aws/aws-sdk-go-v2/config\" \"github.com/aws/aws-sdk-go-v2/service/s3\" smithyendpoints \"github.com/aws/smithy-go/endpoints\" ) type resolverV2 struct {} func (*resolverV2) ResolveEndpoint(ctx context.Context, params s3.EndpointParameters) ( smithyendpoints.Endpoint, error, ) { // s3.Options.BaseEndpoint is accessible here: fmt.Printf(\"The endpoint provided in config is %s\\n\", *params.Endpoint) // fallback to default return s3.NewDefaultEndpointResolverV2().ResolveEndpoint(ctx, params) } func main() { cfg, err := config.LoadDefaultConfig(context.Background() if (err != nil) { log.Fatal(err) } client := s3.NewFromConfig(cfg, func (o *s3.Options) { o.BaseEndpoint = aws.String(\"https://endpoint.dev/\") o.EndpointResolverV2 = \u0026resolverV2{} }) // ignore the output, this is just for demonstration client.ListBuckets(context.Background(), nil) } When run, the above program outputs the following:\nThe endpoint provided in config is https://endpoint.dev/ V1: EndpointResolver Endpoint resolution v1 is retained for backwards compatibility and is isolated from the modern behavior in endpoint resolution v2. It will only be used if the EndpointResolver field is set by the caller.\nUse of v1 will most likely prevent you from accessing endpoint-related service features introduced with or after the release of v2 resolution. See “Migration” for instructions on how to upgrade.\nA EndpointResolver can be configured to provide custom endpoint resolution logic for service clients. You can use a custom endpoint resolver to override a service’s endpoint resolution logic for all endpoints, or a just specific regional endpoint. Custom endpoint resolver can trigger the service’s endpoint resolution logic to fallback if a custom resolver does not wish to resolve a requested endpoint. EndpointResolverWithOptionsFunc can be used to easily wrap functions to satisfy the EndpointResolverWithOptions interface.\nA EndpointResolver can be easily configured by passing the resolver wrapped with WithEndpointResolverWithOptions to LoadDefaultConfig, allowing for the ability to override endpoints when loading credentials, as well as configuring the resulting aws.Config with your custom endpoint resolver.\nThe endpoint resolver is given the service and region as a string, allowing for the resolver to dynamically drive its behavior. Each service client package has an exported ServiceID constant which can be used to determine which service client is invoking your endpoint resolver.\nAn endpoint resolver can use the EndpointNotFoundError sentinel error value to trigger fallback resolution to the service clients default resolution logic. This allows you to selectively override one or more endpoints seamlessly without having to handle fallback logic.\nIf your endpoint resolver implementation returns an error other than EndpointNotFoundError, endpoint resolution will stop and the service operation returns an error to your application.\nExamples With fallback The following code snippet shows how a single service endpoint can be overridden for DynamoDB with fallback behavior for other endpoints:\ncustomResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) { if service == dynamodb.ServiceID \u0026\u0026 region == \"us-west-2\" { return aws.Endpoint{ PartitionID: \"aws\", URL: \"https://test.us-west-2.amazonaws.com\", SigningRegion: \"us-west-2\", }, nil } // returning EndpointNotFoundError will allow the service to fallback to it's default resolution return aws.Endpoint{}, \u0026aws.EndpointNotFoundError{} }) cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithEndpointResolverWithOptions(customResolver)) Without fallback The following code snippet shows how a single service endpoint can be overridden for DynamoDB without fallback behavior for other endpoints:\ncustomResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) { if service == dynamodb.ServiceID \u0026\u0026 region == \"us-west-2\" { return aws.Endpoint{ PartitionID: \"aws\", URL: \"https://test.us-west-2.amazonaws.com\", SigningRegion: \"us-west-2\", }, nil } return aws.Endpoint{}, fmt.Errorf(\"unknown endpoint requested\") }) cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithEndpointResolverWithOptions(customResolver)) Immutable endpoints Setting an endpoint as immutable may prevent some service client features from functioning correctly, and could result in undefined behavior. Caution should be taken when defining an endpoint as immutable.\nSome service clients, such as Amazon S3, may modify the endpoint returned by the resolver for certain service operations. For example, Amazon S3 will automatically handle Virtual Bucket Addressing by mutating the resolved endpoint. You can prevent the SDK from mutating your custom endpoints by setting HostnameImmutable to true. For example:\ncustomResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) { if service == dynamodb.ServiceID \u0026\u0026 region == \"us-west-2\" { return aws.Endpoint{ PartitionID: \"aws\", URL: \"https://test.us-west-2.amazonaws.com\", SigningRegion: \"us-west-2\", HostnameImmutable: true, }, nil } return aws.Endpoint{}, fmt.Errorf(\"unknown endpoint requested\") }) cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithEndpointResolverWithOptions(customResolver)) Migration When migrating from v1 to v2 of endpoint resolution, the following general principles apply:\nReturning an Endpoint with HostnameImmutable set to false is roughly equivalent to setting BaseEndpoint to the originally returned URL from v1 and leaving EndpointResolverV2 as the default. Returning an Endpoint with HostnameImmutable set to true is roughly equivalent to implementing an EndpointResolverV2 which returns the originally returned URL from v1. Examples for these cases are provided below.\nV1 immutable endpoints and V2 resolution are not equivalent in behavior. For example, signing overrides for custom features like S3 Object Lambda would still be set for immutable endpoints returned via v1 code, but the same will not be done for v2.\nExamples Mutable endpoint The following code sample demonstrates how to migrate a basic v1 endpoint resolver that returns a modifiable endpoint:\n// v1 client := svc.NewFromConfig(cfg, func (o *svc.Options) { o.EndpointResolver = svc.EndpointResolverFromURL(\"https://custom.endpoint.api/\") }) // v2 client := svc.NewFromConfig(cfg, func (o *svc.Options) { // the value of BaseEndpoint is passed to the default EndpointResolverV2 // implementation, which will handle routing for features such as S3 accelerate, // MRAP, etc. o.BaseEndpoint = aws.String(\"https://custom.endpoint.api/\") }) Immutable endpoint // v1 client := svc.NewFromConfig(cfg, func (o *svc.Options) { o.EndpointResolver = svc.EndpointResolverFromURL(\"https://custom.endpoint.api/\", func (e *aws.Endpoint) { e.HostnameImmutable = true }) }) // v2 import ( smithyendpoints \"github.com/aws/smithy-go/endpoints\" ) type staticResolver struct {} func (*staticResolver) ResolveEndpoint(ctx context.Context, params svc.EndpointParameters) ( smithyendpoints.Endpoint, error, ) { // This value will be used as-is when making the request. u, err := url.Parse(\"https://custom.endpoint.api/\") if err != nil { return smithyendpoints.Endpoint{}, err } return smithyendpoints.Endpoint{ URI: *u, }, nil } client := svc.NewFromConfig(cfg, func (o *svc.Options) { o.EndpointResolverV2 = \u0026staticResolver{} }) ","categories":"","description":"Customizing service client endpoints.","excerpt":"Customizing service client endpoints.","ref":"/aws-sdk-go-v2/docs/configuring-sdk/endpoints/","tags":"","title":"Configuring Client Endpoints"},{"body":"The AWS SDK for Go V2 uses a default HTTP client with default configuration values. Although you can change some of these configuration values, the default HTTP client and transport are not sufficiently configured for customers using the AWS SDK for Go V2 in an environment with high throughput and low latency requirements. This section describes how to configure a custom HTTP client, and use that client to create AWS SDK for Go V2 calls.\nTo assist you in creating a custom HTTP client, this section describes how to the NewBuildableClient to configure custom settings, and use that client with an AWS SDK for Go V2 service client.\nLet’s define what we want to customize.\nOverriding During Configuration Loading Custom HTTP clients can be provided when calling LoadDefaultConfig by wrapping the client using WithHTTPClient and passing the resulting value to LoadDefaultConfig. For example to pass customClient as our client:\ncfg, err := config.LoadDefaultConfig(context.TODO(), config.WithHTTPClient(customClient)) Timeout The BuildableHTTPClient can be configured with a request timeout limit. This timeout includes the time to connect, process any redirects, and read the complete response body. For example to modify the client timeout:\nimport \"github.com/aws/aws-sdk-go-v2/aws/transport/http\" // ... httpClient := http.NewBuildableClient().WithTimeout(time.Second*5) Dialer The BuildableHTTPClient provides a builder mechanics for constructing clients with modified Dialer options. The following example shows how to configure a clients Dialer settings.\nimport awshttp \"github.com/aws/aws-sdk-go-v2/aws/transport/http\" import \"net\" // ... httpClient := awshttp.NewBuildableClient().WithDialerOptions(func(d *net.Dialer) { d.KeepAlive = -1 d.Timeout = time.Millisecond*500 }) Settings Dialer.KeepAlive This setting represents the keep-alive period for an active network connection.\nSet to a negative value to disable keep-alives.\nSet to 0 to enable keep-alives if supported by the protocol and operating system.\nNetwork protocols or operating systems that do not support keep-alives ignore this field. By default, TCP enables keep alive.\nSee https://golang.org/pkg/net/#Dialer.KeepAlive\nSet KeepAlive as time.Duration.\nDialer.Timeout This setting represents the maximum amount of time a dial waits for a connection to be created.\nDefault is 30 seconds.\nSee https://golang.org/pkg/net/#Dialer.Timeout\nSet Timeout as time.Duration.\nTransport The BuildableHTTPClient provides a builder mechanics for constructing clients with modified Transport options.\nConfiguring a Proxy If you cannot directly connect to the internet, you can use Go-supported environment variables (HTTP_PROXY / HTTPS_PROXY) or create a custom HTTP client to configure your proxy. The following example configures the client to use PROXY_URL as the proxy endpoint:\nimport awshttp \"github.com/aws/aws-sdk-go-v2/aws/transport/http\" import \"net/http\" // ... httpClient := awshttp.NewBuildableClient().WithTransportOptions(func(tr *http.Transport) { proxyURL, err := url.Parse(\"PROXY_URL\") if err != nil { log.Fatal(err) } tr.Proxy = http.ProxyURL(proxyURL) }) Other Settings Below are a few other Transport settings that can be modified to tune the HTTP client. Any additional settings not described here can be found in the Transport type documentation. These settings can be applied as shown in the following example:\nimport awshttp \"github.com/aws/aws-sdk-go-v2/aws/transport/http\" import \"net/http\" // ... httpClient := awshttp.NewBuildableClient().WithTransportOptions(func(tr *http.Transport) { tr.ExpectContinueTimeout = 0 tr.MaxIdleConns = 10 }) Transport.ExpectContinueTimeout If the request has an “Expect: 100-continue” header, this setting represents the maximum amount of time to wait for a server’s first response headers after fully writing the request headers, This time does not include the time to send the request header. The HTTP client sends its payload after this timeout is exhausted.\nDefault 1 second.\nSet to 0 for no timeout and send request payload without waiting. One use case is when you run into issues with proxies or third party services that take a session similar to the use of Amazon S3 in the function shown later.\nSee https://golang.org/pkg/net/http/#Transport.ExpectContinueTimeout\nSet ExpectContinue as time.Duration.\nTransport.IdleConnTimeout This setting represents the maximum amount of time to keep an idle network connection alive between HTTP requests.\nSet to 0 for no limit.\nSee https://golang.org/pkg/net/http/#Transport.IdleConnTimeout\nSet IdleConnTimeout as time.Duration.\nTransport.MaxIdleConns This setting represents the maximum number of idle (keep-alive) connections across all hosts. One use case for increasing this value is when you are seeing many connections in a short period from the same clients\n0 means no limit.\nSee https://golang.org/pkg/net/http/#Transport.MaxIdleConns\nSetMaxIdleConns as int.\nTransport.MaxIdleConnsPerHost This setting represents the maximum number of idle (keep-alive) connections to keep per-host. One use case for increasing this value is when you are seeing many connections in a short period from the same clients\nDefault is two idle connections per host.\nSet to 0 to use DefaultMaxIdleConnsPerHost (2).\nSee https://golang.org/pkg/net/http/#Transport.MaxIdleConnsPerHost\nSet MaxIdleConnsPerHost as int.\nTransport.ResponseHeaderTimeout This setting represents the maximum amount of time to wait for a client to read the response header.\nIf the client isn’t able to read the response’s header within this duration, the request fails with a timeout error.\nBe careful setting this value when using long-running Lambda functions, as the operation does not return any response headers until the Lambda function has finished or timed out. However, you can still use this option with the ** InvokeAsync** API operation.\nDefault is no timeout; wait forever.\nSee https://golang.org/pkg/net/http/#Transport.ResponseHeaderTimeout\nSet ResponseHeaderTimeout as time.Duration.\nTransport.TLSHandshakeTimeout This setting represents the maximum amount of time waiting for a TLS handshake to be completed.\nDefault is 10 seconds.\nZero means no timeout.\nSee https://golang.org/pkg/net/http/#Transport.TLSHandshakeTimeout\nSet TLSHandshakeTimeout as time.Duration.\n","categories":"","description":"Create a custom HTTP client with the AWS SDK for Go V2 to specify custom timeout values.","excerpt":"Create a custom HTTP client with the AWS SDK for Go V2 to specify …","ref":"/aws-sdk-go-v2/docs/configuring-sdk/custom-http/","tags":"","title":"Customizing the HTTP Client"},{"body":"AWS Identity and Access Management (IAM) is an Amazon Web Services (AWS) service that helps an administrator securely control access to AWS resources. IAM administrators control who can be authenticated (signed in) and authorized (have permissions) to use resources AWS services. IAM is an AWS service that you can use with no additional charge.\nTo use this AWS product or service to access AWS, you need an AWS account and AWS credentials. To increase the security of your AWS account, we recommend that you use an IAM user to provide access credentials instead of using your AWS account credentials.\nFor details about working with IAM, see IAM.\nFor an overview of IAM users and why they are important for the security of your account, see AWS Security Credentials in the Amazon Web Services General Reference.\nThis AWS product or service follows the shared responsibility model through the specific Amazon Web Services (AWS) services it supports. For AWS service security information, see the AWS service security documentation page and AWS services that are in scope of AWS compliance efforts by compliance program.\n","categories":"","description":"","excerpt":"AWS Identity and Access Management (IAM) is an Amazon Web Services …","ref":"/aws-sdk-go-v2/docs/security/iam/","tags":"","title":"Identity and Access Management for this AWS Product or Service"},{"body":"This AWS product or service follows the shared responsibility model through the specific Amazon Web Services (AWS) services it supports. For AWS service security information, see the AWS service security documentation page and AWS services that are in scope of AWS compliance efforts by compliance program .\nFor information about AWS security processes, see the AWS: Overview of Security Processes whitepaper.\n","categories":"","description":"","excerpt":"This AWS product or service follows the shared responsibility model …","ref":"/aws-sdk-go-v2/docs/security/infrastructure-security/","tags":"","title":"Infrastructure Security for this AWS Product or Service"},{"body":"The AWS SDK for Go V2 has logging facilities available that allow your application to enable debugging information for debugging and diagnosing request issues or failures. The Logger interface and ClientLogMode are the main components available to you for determining how and what should be logged by clients.\nLogger When constructing an Config using LoadDefaultConfig a default Logger is configured to send log messages to the process’ standard error (stderr). A custom logger that satisfies the Logger interface can be passed as an argument to LoadDefaultConfig by wrapping it with config.WithLogger.\nFor example to configure our clients to use our applicationLogger:\ncfg, err := config.LoadDefaultConfig(context.TODO(), config.WithLogger(applicationLogger)) Now clients configured using the constructed aws.Config will send log messages to applicationLogger.\nContext-Aware Loggers A Logger implementation may implement the optional ContextLogger interface. Loggers that implement this interface will have their WithContext methods invoked with the current context. This allows your logging implementations to return a new Logger that can write additional logging metadata based on values present in the context.\nClientLogMode By default, service clients do not produce log messages. To configure clients to send log messages for debugging purposes, use the ClientLogMode member on Config. ClientLogMode can be set to enable debugging messaging for:\nSignature Version 4 (SigV4) Signing Request Retries HTTP Requests HTTP Responses For example to enable logging of HTTP requests and retries:\ncfg, err := config.LoadDefaultConfig(context.TODO(), config.WithClientLogMode(aws.LogRetries | aws.LogRequest)) See ClientLogMode for the different client log modes available.\n","categories":"","description":"Using Logging facilities for debugging SDK requests.","excerpt":"Using Logging facilities for debugging SDK requests.","ref":"/aws-sdk-go-v2/docs/configuring-sdk/logging/","tags":"","title":"Logging"},{"body":"The Amazon Web Services (AWS) global infrastructure is built around AWS Regions and Availability Zones.\nAWS Regions provide multiple physically separated and isolated Availability Zones, which are connected with low-latency, high-throughput, and highly redundant networking.\nWith Availability Zones, you can design and operate applications and databases that automatically fail over between Availability Zones without interruption. Availability Zones are more highly available, fault tolerant, and scalable than traditional single or multiple data center infrastructures.\nFor more information about AWS Regions and Availability Zones, see AWS Global Infrastructure.\nThis AWS product or service follows the shared responsibility model through the specific Amazon Web Services (AWS) services it supports. For AWS service security information, see the AWS service security documentation page and AWS services that are in scope of AWS compliance efforts by compliance program.\n","categories":"","description":"","excerpt":"The Amazon Web Services (AWS) global infrastructure is built around …","ref":"/aws-sdk-go-v2/docs/security/disaster-recovery-resiliency/","tags":"","title":"Resilience for this AWS Product or Service"},{"body":"The shared responsibility model applies to data protection in this AWS product or service. As described in this model, AWS is responsible for protecting the global infrastructure that runs all of the AWS Cloud. You are responsible for maintaining control over your content that is hosted on this infrastructure. This content includes the security configuration and management tasks for the AWS services that you use. For more information about data privacy, see the Data Privacy FAQ. For information about data protection in Europe, see the AWS Shared Responsibility Model and GDPR blog post on the AWS Security Blog.\nFor data protection purposes, we recommend that you protect AWS account credentials and set up individual user accounts with AWS Identity and Access Management (IAM). That way each user is given only the permissions necessary to fulfill their job duties. We also recommend that you secure your data in the following ways:\nUse multi-factor authentication (MFA) with each account. Use SSL/TLS to communicate with AWS resources. We recommend TLS 1.2 or later. Set up API and user activity logging with AWS CloudTrail. Use AWS encryption solutions, with all default security controls within AWS services. Use advanced managed security services such as Amazon Macie, which assists in discovering and securing personal data that is stored in Amazon S3. If you require FIPS 140-2 validated cryptographic modules when accessing AWS through a command line interface or an API, use a FIPS endpoint. For more information about the available FIPS endpoints, see Federal Information Processing Standard (FIPS) 140-2. We strongly recommend that you never put sensitive identifying information, such as your customers’ account numbers, into free-form fields such as a Name field. This includes when you work with AWS SDK for Go V2 or other AWS services using the console, API, AWS CLI, or AWS SDKs. Any data that you enter into AWS SDK for Go V2 or other services might get picked up for inclusion in diagnostic logs. When you provide a URL to an external server, don’t include credentials information in the URL to validate your request to that server.\n","categories":"","description":"","excerpt":"The shared responsibility model applies to data protection in this AWS …","ref":"/aws-sdk-go-v2/docs/security/data-protection/","tags":"","title":"Data Protection in this AWS Product or Service"},{"body":"The AWS SDK for Go V2 configures the default HTTP client used by the SDK service clients to require a minimum version of TLS 1.2 or greater. When using the http.BuildableClient to customize the SDK HTTP client, the minimum TLS value is configured as TLS 1.2.\nIf your application constructs an HTTP client using a method other than the provided BuildableClient, you must configure your client to set the minimum TLS version to 1.2.\nEnforcing a Minimum TLS Version You can construct a custom an http.Client or use the SDK provided http.BuildableClient builder. The following example demonstrates how to specify a minimum TLS version of 1.3 using the http.BuildableClient.\nSome AWS Services do not yet support TLS 1.3; configuring this as your minimum version may affect SDK interoperability. We recommend testing this change with each service prior to production deployment.\npackage main import ( \"context\" \"crypto/tls\" \"net/http\" awshttp \"github.com/aws/aws-sdk-go-v2/aws/transport/http\" \"github.com/aws/aws-sdk-go-v2/config\" ) func main() { // Create the custom HTTP client, configured for TLS 1.3 specified as the // minimum TLS version. httpClient := awshttp.NewBuildableClient().WithTransportOptions(func(tr *http.Transport) { if tr.TLSClientConfig == nil { tr.TLSClientConfig = \u0026tls.Config{} } tr.TLSClientConfig.MinVersion = tls.VersionTLS13 }) // Load the SDK's configuration, and specify the custom HTTP client to be used // by all SDK API clients created from this configuration. cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithHTTPClient(httpClient)) // Use the loaded config and custom HTTP client to create SDK API client(s). // ... } ","categories":"","description":"","excerpt":"The AWS SDK for Go V2 configures the default HTTP client used by the …","ref":"/aws-sdk-go-v2/docs/security/tls/","tags":"","title":"TLS Version in AWS SDK for Go V2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/accesskeylastused/","tags":"","title":"AccessKeyLastUsedv2"},{"body":"You can use the AWS SDK for Go V2 to access the Amazon EC2 Instance Metadata Service. The feature/ec2/imds Go package provides a Client type that can be used to access the Amazon EC2 Instance Metadata Service. The Client and associated operations can be used similar to the other AWS service clients provided by the SDK. To learn more information on how to configure the SDK, and use service clients see Configuring the SDK and Using AWS Services.\nThe client can help you easily retrieve information about instances on which your applications run, such as its AWS Region or local IP address. Typically, you must create and submit HTTP requests to retrieve instance metadata. Instead, create an imds.Client to access the Amazon EC2 Instance Metadata Service using a programmatic client like other AWS Services.\nFor example to construct a client:\nimport \"context\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/feature/ec2/imds\" // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { log.Printf(\"error: %v\", err) return } client := imds.NewFromConfig(cfg) Then use the service client to retrieve information from a metadata category such as local-ipv4 (the private IP address of the instance).\nlocalip, err := client.GetMetadata(context.TODO(), \u0026imds.GetMetadataInput{ Path: \"local-ipv4\", }) if err != nil { log.Printf(\"Unable to retrieve the private IP address from the EC2 instance: %s\\n\", err) return } fmt.Printf(\"local-ip: %v\\n\", localip) For a list of all metadata categories, see Instance Metadata Categories in the Amazon EC2 User Guide.\nRetrieving an Instance’s Region There’s no instance metadata category that returns only the Region of an instance. Instead, use the included Region method to easily return an instance’s Region.\nresponse, err := client.GetRegion(context.TODO(), \u0026imds.GetRegionInput{}) if err != nil { log.Printf(\"Unable to retrieve the region from the EC2 instance %v\\n\", err) } fmt.Printf(\"region: %v\\n\", response.Region) For more information about the EC2 metadata utility, see the feature/ec2/imds package in the AWS SDK for Go V2 API Reference.\n","categories":"","description":"Using the AWS SDK for Go V2 Amazon EC2 Instance Metadata Service Client","excerpt":"Using the AWS SDK for Go V2 Amazon EC2 Instance Metadata Service …","ref":"/aws-sdk-go-v2/docs/sdk-utilities/ec2-imds/","tags":"","title":"Amazon EC2 Instance Metadata Service"},{"body":"Transfer Managers The Amazon Simple Storage Service upload and download managers can break up large objects, so they can be transferred in multiple parts, in parallel. This makes it easy to resume interrupted transfers.\nUpload Manager The Amazon Simple Storage Service upload manager determines if a file can be split into smaller parts and uploaded in parallel. You can customize the number of parallel uploads and the size of the uploaded parts.\nThe following example uses the Amazon S3 Uploader to upload a file. Using Uploader is similar to the s3.PutObject() operation.\nimport \"context\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" import \"github.com/aws/aws-sdk-go-v2/feature/s3/manager\" // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { log.Printf(\"error: %v\", err) return } client := s3.NewFromConfig(cfg) uploader := manager.NewUploader(client) result, err := uploader.Upload(context.TODO(), \u0026s3.PutObjectInput{ Bucket: aws.String(\"my-bucket\"), Key: aws.String(\"my-object-key\"), Body: uploadFile, }) Configuration Options When you instantiate an Uploader instance using NewUploader, you can specify several configuration options to customize how objects are uploaded. Options are overridden by providing one or more arguments to NewUploader. These options include:\nPartSize – Specifies the buffer size, in bytes, of each part to upload. The minimum size per part is 5 MiB. Concurrency – Specifies the number of parts to upload in parallel. LeavePartsOnError – Indicates whether to leave successfully uploaded parts in Amazon S3. The Concurrency value limits the concurrent number of part uploads that can occur for a given Upload call. This is not a global client concurrency limit. Tweak the PartSize and Concurrency configuration values to find the optimal configuration. For example, systems with high-bandwidth connections can send bigger parts and more uploads in parallel.\nFor example, your application configures Uploader with a Concurrency of setting of 5. If your application then calls Upload from two different goroutines, the result is 10 concurrent part uploads (2 goroutines * 5 Concurrency).\nYour application is expected to limit the concurrent calls to Upload to prevent application resource exhaustion.\nBelow is an example to set the default part size during Uploader creation:\nuploader := manager.NewUploader(client, func(u *Uploader) { u.PartSize = 10 * 1024 * 1024, // 10 MiB }) For more information about Uploader and its configurations, see Uploader in the AWS SDK for Go V2 API Reference.\nPutObjectInput Body Field (io.ReadSeeker vs. io.Reader) The Body field of the s3.PutObjectInput struct is an io.Reader type. However, this field can be populated with a type that satisfies both the io.ReadSeeker and io.ReaderAt interface to improve application resource utilization of the host environment. The following example creates the type ReadSeekerAt that satisfies both interfaces:\ntype ReadSeekerAt interface { io.ReadSeeker io.ReaderAt } For io.Reader types, the bytes of the reader must be buffered in memory before the part can be uploaded. When you increase the PartSize or Concurrency value, the required memory (RAM) for the Uploader increases significantly. The required memory is approximately PartSize * Concurrency. For example, specifying 100 MB for PartSize and 10 for Concurrency, requires at least 1 GB.\nBecause an io.Reader type cannot determine its size before reading its bytes, Uploader cannot calculate how many parts will be uploaded. Consequently, Uploader can reach the Amazon S3 upload limit of 10,000 parts for large files if you set the PartSize too low. If you try to upload more than 10,000 parts, the upload stops and returns an error.\nFor body values that implement the ReadSeekerAt type, the Uploader doesn’t buffer the body contents in memory before sending it to Amazon S3. Uploader calculates the expected number of parts before uploading the file to Amazon S3. If the current value of PartSize requires more than 10,000 parts to upload the file, Uploader increases the part size value so that fewer parts are required.\nHandling Failed Uploads If an upload to Amazon S3 fails, by default, Uploader uses the Amazon S3 AbortMultipartUpload operation to remove the uploaded parts. This functionality ensures that failed uploads do not consume Amazon S3 storage.\nYou can set LeavePartsOnError to true so that the Uploader doesn’t delete successfully uploaded parts. This is useful for resuming partially completed uploads. To operate on uploaded parts, you must get the UploadID of the failed upload. The following example demonstrates how to use the manager.MultiUploadFailure error interface type to get the UploadID.\nresult, err := uploader.Upload(context.TODO(), \u0026s3.PutObjectInput{ Bucket: aws.String(\"my-bucket\"), Key: aws.String(\"my-object-key\"), Body: uploadFile, }) output, err := u.upload(input) if err != nil { var mu manager.MultiUploadFailure if errors.As(err, \u0026mu) { // Process error and its associated uploadID fmt.Println(\"Error:\", mu) _ = mu.UploadID() // retrieve the associated UploadID } else { // Process error generically fmt.Println(\"Error:\", err.Error()) } return } Overriding Uploader Options Per Upload You can override the Uploader options when calling Upload by providing one or more arguments to the method. These overrides are concurrency-safe modifications and do not affect ongoing uploads, or subsequent Upload calls to the manager. For example, to override the PartSize configuration for a specific upload request:\nparams := \u0026s3.PutObjectInput{ Bucket: aws.String(\"my-bucket\"), Key: aws.String(\"my-key\"), Body: myBody, } resp, err := uploader.Upload(context.TODO(), params, func(u *manager.Uploader) { u.PartSize = 10 * 1024 * 1024, // 10 MiB }) Examples Upload a Folder to Amazon S3 The following example uses the path/filepath package to recursively gather a list of files and upload them to the specified Amazon S3 bucket. The keys of the Amazon S3 objects are prefixed with the file’s relative path.\npackage main import ( \"context\" \"log\" \"os\" \"path/filepath\" \"github.com/aws/aws-sdk-go-v2/aws\" \"github.com/aws/aws-sdk-go-v2/config\" \"github.com/aws/aws-sdk-go-v2/feature/s3/manager\" \"github.com/aws/aws-sdk-go-v2/service/s3\" ) var ( localPath string bucket string prefix string ) func init() { if len(os.Args) != 4 { log.Fatalln(\"Usage:\", os.Args[0], \"\u003clocal path\u003e \u003cbucket\u003e \u003cprefix\u003e\") } localPath = os.Args[1] bucket = os.Args[2] prefix = os.Args[3] } func main() { walker := make(fileWalk) go func() { // Gather the files to upload by walking the path recursively if err := filepath.Walk(localPath, walker.Walk); err != nil { log.Fatalln(\"Walk failed:\", err) } close(walker) }() cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { log.Fatalln(\"error:\", err) } // For each file found walking, upload it to Amazon S3 uploader := manager.NewUploader(s3.NewFromConfig(cfg)) for path := range walker { rel, err := filepath.Rel(localPath, path) if err != nil { log.Fatalln(\"Unable to get relative path:\", path, err) } file, err := os.Open(path) if err != nil { log.Println(\"Failed opening file\", path, err) continue } defer file.Close() result, err := uploader.Upload(context.TODO(), \u0026s3.PutObjectInput{ Bucket: \u0026bucket, Key: aws.String(filepath.Join(prefix, rel)), Body: file, }) if err != nil { log.Fatalln(\"Failed to upload\", path, err) } log.Println(\"Uploaded\", path, result.Location) } } type fileWalk chan string func (f fileWalk) Walk(path string, info os.FileInfo, err error) error { if err != nil { return err } if !info.IsDir() { f \u003c- path } return nil } Download Manager The Amazon S3 Downloader manager determines if a file can be split into smaller parts and downloaded in parallel. You can customize the number of parallel downloads and the size of the downloaded parts.\nExample: Download a File The following example uses the Amazon S3 Downloader to download a file. Using Downloader is similar to the s3.GetObject operation.\nimport \"context\" import \"github.com/aws/aws-sdk-go-v2/aws\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" import \"github.com/aws/aws-sdk-go-v2/feature/s3/manager\" // ... cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { log.Println(\"error:\", err) return } client := s3.NewFromConfig(cfg) downloader := manager.NewDownloader(client) numBytes, err := downloader.Download(context.TODO(), downloadFile, \u0026s3.GetObjectInput{ Bucket: aws.String(\"my-bucket\"), Key: aws.String(\"my-key\"), }) The downloadFile parameter is an io.WriterAt type. The WriterAt interface enables the Downloader to write multiple parts of the file in parallel.\nConfiguration Options When you instantiate a Downloader instance, you can specify configuration options to customize how objects are downloaded:\nPartSize – Specifies the buffer size, in bytes, of each part to download. The minimum size per part is 5 MB. Concurrency – Specifies the number of parts to download in parallel. The Concurrency value limits the concurrent number of part download that can occur for a given Download call. This is not a global client concurrency limit. Tweak the PartSize and Concurrency configuration values to find the optimal configuration. For example, systems with high-bandwidth connections can receive bigger parts and more downloads in parallel.\nFor example, your application configures Downloader with a Concurrency of 5. Your application then calls Download from two different goroutines, the result will be 10 concurrent part downloads (2 goroutines * 5 Concurrency).\nYour application is expected to limit the concurrent calls to Download to prevent application resource exhaustion.\nFor more information about Downloader and its other configuration options, see manager.Downloader in the AWS SDK for Go V2 API Reference.\nOverriding Downloader Options Per Download You can override the Downloader options when calling Download by providing one or more functional arguments to the method. These overrides are concurrency safe modifications and do not affect ongoing uploads, or subsequent Download calls to the manager. For example, to override the PartSize configuration for a specific upload request:\nparams := \u0026s3.GetObjectInput{ Bucket: aws.String(\"my-bucket\"), Key: aws.String(\"my-key\"), } resp, err := downloader.Download(context.TODO(), targetWriter, params, func(u *manager.Downloader) { u.PartSize = 10 * 1024 * 1024, // 10 MiB }) Examples Download All Objects in a Bucket The following example uses pagination to gather a list of objects from an Amazon S3 bucket. Then it downloads each object to a local file.\npackage main import ( \"context\" \"fmt\" \"log\" \"os\" \"path/filepath\" \"github.com/aws/aws-sdk-go-v2/aws\" \"github.com/aws/aws-sdk-go-v2/config\" \"github.com/aws/aws-sdk-go-v2/feature/s3/manager\" \"github.com/aws/aws-sdk-go-v2/service/s3\" ) var ( Bucket = \"MyBucket\" // Download from this bucket Prefix = \"logs/\" // Using this key prefix LocalDirectory = \"s3logs\" // Into this directory ) func main() { cfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { log.Fatalln(\"error:\", err) } client := s3.NewFromConfig(cfg) manager := manager.NewDownloader(client) paginator := s3.NewListObjectsV2Paginator(client, \u0026s3.ListObjectsV2Input{ Bucket: \u0026Bucket, Prefix: \u0026Prefix, }) for paginator.HasMorePages() { page, err := paginator.NextPage(context.TODO()) if err != nil { log.Fatalln(\"error:\", err) } for _, obj := range page.Contents { if err := downloadToFile(manager, LocalDirectory, Bucket, aws.ToString(obj.Key)); err != nil { log.Fatalln(\"error:\", err) } } } } func downloadToFile(downloader *manager.Downloader, targetDirectory, bucket, key string) error { // Create the directories in the path file := filepath.Join(targetDirectory, key) if err := os.MkdirAll(filepath.Dir(file), 0775); err != nil { return err } // Set up the local file fd, err := os.Create(file) if err != nil { return err } defer fd.Close() // Download the file using the AWS SDK for Go fmt.Printf(\"Downloading s3://%s/%s to %s...\\n\", bucket, key, file) _, err = downloader.Download(context.TODO(), fd, \u0026s3.GetObjectInput{Bucket: \u0026bucket, Key: \u0026key}) return err } GetBucketRegion The GetBucketRegion is a utility function for determining the AWS Region location of an Amazon S3 Bucket. GetBucketRegion takes an Amazon S3 client and uses it to determine the location of the requested Bucket within the AWS Partition associated with the client’s configured Region.\nFor example to find the Region for the Bucket my-bucket:\ncfg, err := config.LoadDefaultConfig(context.TODO()) if err != nil { log.Println(\"error:\", err) return } bucket := \"my-bucket\" region, err := manager.GetBucketRegion(ctx, s3.NewFromConfig(cfg), bucket) if err != nil { var bnf manager.BucketNotFound if errors.As(err, \u0026bnf) { log.Printf(\"unable to find bucket %s's Region\\n\", bucket) } else { log.Println(\"error:\", err) } return } fmt.Printf(\"Bucket %s is in %s region\\n\", bucket, region) If GetBucketRegion is not able to resolve the location of a Bucket, the function returns a BucketNotFound error type as shown in the example.\nUnseekable Streaming Input For API operations like PutObject and UploadPart, the Amazon S3 client expects the value of the Body input parameter to implement the io.Seeker interface by default. The io.Seeker interface is used by the client to determine the length of the value to upload, and to compute payload hash for the request signature. If the Body input parameter value does not implement io.Seeker, your application will receive an error.\noperation error S3: PutObject, failed to compute payload hash: failed to seek body to start, request stream is not seekable You can change this behavior by modifying the operation method’s Middleware using functional options. The WithAPIOptions helper returns a functional option for zero or more middleware mutators. To disable the client computing the payload hash and use Unsigned Payload request signature add v4.SwapComputePayloadSHA256ForUnsignedPayloadMiddleware.\nresp, err := client.PutObject(context.TODO(), \u0026s3.PutObjectInput{ Bucket: \u0026bucketName, Key: \u0026objectName, Body: bytes.NewBuffer([]byte(`example object!`)), ContentLength: 15, // length of body }, s3.WithAPIOptions( v4.SwapComputePayloadSHA256ForUnsignedPayloadMiddleware, )) Amazon S3 requires the content length to be provided for all object’s uploaded to a bucket. Since the Body input parameter does not implement io.Seeker interface the client will not be able to compute the ContentLength parameter for the request. The parameter must be provided by the application. The request will fail if the ContentLength parameter is not provided.\nUse the SDK’s Amazon S3 Upload Manager for uploads that are not seekable, and do not have a known length.\n","categories":"","description":"","excerpt":"Transfer Managers The Amazon Simple Storage Service upload and …","ref":"/aws-sdk-go-v2/docs/sdk-utilities/s3/","tags":"","title":"Amazon S3 Utilities"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sts/assumerole/","tags":"","title":"AssumeRolev2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/attachuserpolicy/","tags":"","title":"AttachUserPolicyv2"},{"body":" Welcome to the AWS SDK for Go V2 Learn More Download Modularized Model service dependencies in your application, and independently control service client updates using Go modules.\nPaginators Easily iterate over API results that span multiple pages.\nWaiters Validate AWS resources states before performing additional actions.\nUtilities Amazon S3 Transfer Manager provides seamless concurrent multi-part file uploads. Amazon DynamoDB AttributeValue and Expression utilities allow easy integration of your application Go types.\nExtensible Middleware allows you to extend or customize the transport request pipeline to fit your applications requirements.\n","categories":"","description":"","excerpt":" Welcome to the AWS SDK for Go V2 Learn More Download Modularized …","ref":"/aws-sdk-go-v2/","tags":"","title":"AWS SDK for Go V2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sqs/changemsgvisibility/","tags":"","title":"ChangeMsgVisibilityv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sqs/configurelpqueue/","tags":"","title":"ConfigureLPQueuev2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/s3/copyobject/","tags":"","title":"CopyObjectv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/createaccesskey/","tags":"","title":"CreateAccessKeyv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/createaccountalias/","tags":"","title":"CreateAccountAliasv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/s3/createbucket/","tags":"","title":"CreateBucketv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/cloudwatch/createcustommetric/","tags":"","title":"CreateCustomMetricv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/cloudwatch/createenablemetricalarm/","tags":"","title":"CreateEnableMetricAlarmv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/ec2/createimage/","tags":"","title":"CreateImagev2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/ec2/createinstance/","tags":"","title":"CreateInstancev2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/kms/createkey/","tags":"","title":"CreateKeyv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sqs/createlpqueue/","tags":"","title":"CreateLPQueuev2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/createpolicy/","tags":"","title":"CreatePolicyv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sqs/createqueue/","tags":"","title":"CreateQueuev2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sns/createtopic/","tags":"","title":"CreateTopicv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/createuser/","tags":"","title":"CreateUserv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sqs/deadletterqueue/","tags":"","title":"DeadLetterQueuev2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/kms/decryptdata/","tags":"","title":"DecryptDatav2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/deleteaccesskey/","tags":"","title":"DeleteAccessKeyv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/deleteaccountalias/","tags":"","title":"DeleteAccountAliasv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/s3/deletebucket/","tags":"","title":"DeleteBucketv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sqs/deletemessage/","tags":"","title":"DeleteMessagev2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/s3/deleteobject/","tags":"","title":"DeleteObjectv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/ssm/deleteparameter/","tags":"","title":"DeleteParameterv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sqs/deletequeue/","tags":"","title":"DeleteQueuev2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/deleteservercert/","tags":"","title":"DeleteServerCertv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/deleteuser/","tags":"","title":"DeleteUserv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/cloudwatch/describealarms/","tags":"","title":"DescribeAlarmsv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/ec2/describeinstances/","tags":"","title":"DescribeInstancesv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/dynamodb/describetable/","tags":"","title":"DescribeTablev2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/ec2/describevpcendpoints/","tags":"","title":"DescribeVpcEndpointsv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/detachuserpolicy/","tags":"","title":"DetachUserPolicyv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/cloudwatch/disablealarm/","tags":"","title":"DisableAlarmv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/kms/encryptdata/","tags":"","title":"EncryptDatav2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/s3/generatepresignedurl/","tags":"","title":"GeneratePresignedURLv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/s3/getbucketacl/","tags":"","title":"GetBucketAclv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/s3/getobjectacl/","tags":"","title":"GetObjectAclv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/ssm/getparameter/","tags":"","title":"GetParameterv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/getpolicy/","tags":"","title":"GetPolicyv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sqs/getqueueurl/","tags":"","title":"GetQueueURLv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/getservercert/","tags":"","title":"GetServerCertv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/listaccesskeys/","tags":"","title":"ListAccessKeysv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/listaccountaliases/","tags":"","title":"ListAccountAliasesv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/listadmins/","tags":"","title":"ListAdminsv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/s3/listbuckets/","tags":"","title":"ListBucketsv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/cloudwatch/listmetrics/","tags":"","title":"ListMetricsv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/s3/listobjects/","tags":"","title":"ListObjectsv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sqs/listqueues/","tags":"","title":"ListQueuesv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/listservercerts/","tags":"","title":"ListServerCertsv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sns/listsubscriptions/","tags":"","title":"ListSubscriptionsv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sns/listtopics/","tags":"","title":"ListTopicsv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/listusers/","tags":"","title":"ListUsersv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/ec2/monitorinstances/","tags":"","title":"MonitorInstancesv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sns/publish/","tags":"","title":"Publishv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/cloudwatch/putevent/","tags":"","title":"PutEventv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/s3/putobject/","tags":"","title":"PutObjectv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/ssm/putparameter/","tags":"","title":"PutParameterv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/ec2/rebootinstances/","tags":"","title":"RebootInstancesv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sqs/receivelpmessage/","tags":"","title":"ReceiveLPMessagev2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sqs/receivemessage/","tags":"","title":"ReceiveMessagev2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/kms/reencryptdata/","tags":"","title":"ReEncryptDatav2"},{"body":"The AWS SDK for Go V2 enables you to configure the retry behavior of requests to HTTP services. By default, service clients use retry.Standard as their default retryer. If the default configuration or behavior does not meet your application requirements, you can adjust the retryer configuration or provide your own retryer implementation.\nThe AWS SDK for Go V2 provides a aws.Retryer interface that defines the set of methods required by a retry implementation to implement. The SDK provides two implementations for retries: retry.Standard and aws.NoOpRetryer.\nStandard Retryer The retry.Standard retryer is the default aws.Retryer implementation used by SDK clients. The standard retryer is a rate limited retryer with a configurable number of max attempts, and the ability to tune the request back off policy.\nThe following table defines the default values for this retryer:\nProperty Default Max Number of Attempts 3 Max Back Off Delay 20 seconds When a retryable error occurs while invoking your request, the standard retryer will use its provided configuration to delay and subsequently retry the request. Retries add to the overall latency of your request, and you must configure retryer if the default configuration does not meet your application requirements.\nSee the retry package documentation for details on what errors are considered as retryable by the standard retryer implementation.\nNopRetryer The aws.NopRetryer is a aws.Retryer implementation that is provided if you wish to disable all retry attempts. When invoking a service client operation, this retryer will only allow the request to be attempted once, and any resulting error will be returned to the calling application.\nCustomizing Behavior The SDK provides a set of helper utilities that wrap an aws.Retryer implementation, and returns the provided retryer wrapped with the desired retry behavior. You can override the default retryer for all clients, per client, or per operation depending on your applications requirements. To see additional examples showing how to do this see the retry package documentation examples.\nIf specifying a global aws.Retryer implementation using config.WithRetryer, you must ensure that you return a new instance of the aws.Retryer each invocation. This will ensure that you won’t create a global retry token bucket across all service clients. Limiting the max number of attempts You use retry.AddWithMaxAttempts to wrap an aws.Retryer implementation to set the max number attempts to your desired value. Setting max attempts to zero will allow the SDK to retry all retryable errors until the request succeeds, or a non-retryable error is returned.\nFor example, you can the following code to wrap the standard client retryer with a maximum of five attempts:\nimport \"context\" import \"github.com/aws/aws-sdk-go-v2/aws/retry\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRetryer(func() aws.Retryer { return retry.AddWithMaxAttempts(retry.NewStandard(), 5) })) if err != nil { return err } client := s3.NewFromConfig(cfg) Limiting the max back off delay You use retry.AddWithMaxBackoffDelay to wrap an aws.Retryer implementation and limit the max back off delay that is allowed to occur between retrying a failed request.\nFor example, you can the following code to wrap the standard client retryer with a desired max delay of five seconds:\nimport \"context\" import \"time\" import \"github.com/aws/aws-sdk-go-v2/aws/retry\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" // ... cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRetryer(func() aws.Retryer { return retry.AddWithMaxBackoffDelay(retry.NewStandard(), time.Second*5) })) if err != nil { return err } client := s3.NewFromConfig(cfg) Retry additional API error codes You use retry.AddWithErrorCodes to wrap an aws.Retryer implementation and include additional API error codes that should be considered retryable.\nFor example, you can the following code to wrap the standard client retryer to include the Amazon S3 NoSuchBucketException exception as retryable.\nimport \"context\" import \"time\" import \"github.com/aws/aws-sdk-go-v2/aws/retry\" import \"github.com/aws/aws-sdk-go-v2/config\" import \"github.com/aws/aws-sdk-go-v2/service/s3\" import \"github.com/aws/aws-sdk-go-v2/service/s3/types\" // ... cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRetryer(func() aws.Retryer { return retry.AddWithErrorCodes(retry.NewStandard(), (*types.NoSuchBucketException)(nil).ErrorCode()) })) if err != nil { return err } client := s3.NewFromConfig(cfg) Timeouts You use the context package to set timeouts or deadlines when invoking a service client operation. Use the context.WithDeadline to wrap your applications context and set a deadline to a specific time by which the invoked operation must be completed. To set a timeout after a certain time.Duration use context.WithTimeout. The SDK passes the provided context.Context to the HTTP transport client when invoking a service API. If the context passed to the SDK is cancelled or becomes cancelled while invoking the operation, the SDK will not retry the request further and will return to the calling application. You must handle context cancellation appropriately in your application in cases where the context provided to the SDK has become cancelled.\nSetting a timeout The following example shows how to set a timeout for a service client operation.\nimport \"context\" import \"time\" // ... ctx := context.TODO() // or appropriate context.Context value for your application client := s3.NewFromConfig(cfg) // create a new context from the previous ctx with a timeout, e.g. 5 seconds ctx, cancel := context.WithTimeout(ctx, 5*time.Second) defer cancel() resp, err := client.GetObject(ctx, \u0026s3.GetObjectInput{ // input parameters }) if err != nil { // handle error } ","categories":"","description":"","excerpt":"The AWS SDK for Go V2 enables you to configure the retry behavior of …","ref":"/aws-sdk-go-v2/docs/configuring-sdk/retries-timeouts/","tags":"","title":"Retries and Timeouts"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/dynamodb/scanitems/","tags":"","title":"ScanItemsv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sqs/sendmessage/","tags":"","title":"SendMessagev2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/ec2/startinstances/","tags":"","title":"StartInstancesv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/ec2/stopinstances/","tags":"","title":"StopInstancesv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/sns/subscribe/","tags":"","title":"Subscribev2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/updateaccesskey/","tags":"","title":"UpdateAccessKeyv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/updateservercert/","tags":"","title":"UpdateServerCertv2"},{"body":"","categories":"","description":"","excerpt":"","ref":"/aws-sdk-go-v2/docs/code-examples/iam/updateuser/","tags":"","title":"UpdateUserv2"}]
\ No newline at end of file
diff --git a/docs/sitemap.xml b/docs/sitemap.xml
index 331a47cd47f..3a9c9fd9514 100644
--- a/docs/sitemap.xml
+++ b/docs/sitemap.xml
@@ -57,7 +57,7 @@
2020-12-23T13:28:16-08:00
https://aws.github.io/aws-sdk-go-v2/docs/middleware/
- 2021-01-15T13:01:18-08:00
+ 2024-01-31T23:50:06+07:00
https://aws.github.io/aws-sdk-go-v2/docs/faq/
2023-12-21T16:57:52-05:00