diff --git a/.github/workflows/validate-documentation-generation.yml b/.github/workflows/validate-documentation-generation.yml deleted file mode 100644 index 0becbb76348..00000000000 --- a/.github/workflows/validate-documentation-generation.yml +++ /dev/null @@ -1,14 +0,0 @@ -name: Validate Documentation Static Content Generation -on: - push: - branches: [ documentation ] - pull_request: - branches: [ documentation ] -jobs: - build: - name: Hugo Documentation Build - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - name: Build Hugo Static Content image - run: make container-generate diff --git a/Dockerfile b/Dockerfile deleted file mode 100644 index 6be028afece..00000000000 --- a/Dockerfile +++ /dev/null @@ -1,41 +0,0 @@ -FROM public.ecr.aws/amazonlinux/amazonlinux:latest AS hugo_build_env - -ARG NODEJS_LTS_DOWNLOAD_URL=https://nodejs.org/dist/v16.16.0/node-v16.16.0-linux-x64.tar.xz -ARG NODEJS_LTS_DOWNLOAD_SHA256=edcb6e9bb049ae365611aa209fc03c4bfc7e0295dbcc5b2f1e710ac70384a8ec - -ARG HUGO_DOWNLOAD_URL=https://github.com/gohugoio/hugo/releases/download/v0.101.0/hugo_extended_0.101.0_Linux-64bit.tar.gz -ARG HUGO_DOWNLOAD_SHA256=8c3adf2ace1604468325a6dd094bcc41c141c4a28a0c1ebbeb0022e714897595 - -ARG GO_VERSION=go1.19 - -RUN yum update -y && yum install -y tar xz gzip git make golang - -RUN curl -L -o nodejs.tar.xz ${NODEJS_LTS_DOWNLOAD_URL} && \ - echo "${NODEJS_LTS_DOWNLOAD_SHA256} nodejs.tar.xz" | sha256sum -c - - -RUN mkdir -p /opt/nodejs && \ - tar --strip-components=1 -xJf nodejs.tar.xz -C /opt/nodejs && rm -f nodejs.tar.xz - -RUN go install golang.org/dl/${GO_VERSION}@latest && \ - $HOME/go/bin/${GO_VERSION} download - -RUN curl -L -o hugo.tar.gz ${HUGO_DOWNLOAD_URL} && \ - echo "${HUGO_DOWNLOAD_SHA256} hugo.tar.gz" | sha256sum -c - - -RUN tar -xzf hugo.tar.gz hugo && \ - mv hugo /usr/local/bin && rm -f hugo.tar.gz - -FROM hugo_build_env - -ARG GO_VERSION=go1.19 -ARG SITE_ENV=production -ENV SITE_ENV=${SITE_ENV} -ENV PATH="${HOME}/sdk/${GO_VERSION}:${PATH}" - -ADD . /aws-sdk-go-v2-docs - -WORKDIR /aws-sdk-go-v2-docs - -ENV PATH /opt/nodejs/bin:${PATH} - -CMD ["make", "setup", "generate"] diff --git a/Makefile b/Makefile deleted file mode 100644 index 5dd724fe1a1..00000000000 --- a/Makefile +++ /dev/null @@ -1,46 +0,0 @@ -DOC_SRC=$(shell pwd) -SITE_ENV?=production -PREVIEW_HOST?=127.0.0.1 -PREVIEW_PORT?=1313 - -COMMON_DOCKER_BUILD_ARGS=--build-arg SITE_ENV=$(SITE_ENV) - -setup: init-node-modules - -init-node-modules: - npm install - -generate: - hugo --environment $(SITE_ENV) -d docs --gc - -container-generate: - docker build \ - $(COMMON_DOCKER_BUILD_ARGS) \ - -t aws-sdk-go-v2-docs \ - -f ./Dockerfile \ - . - docker run \ - -t aws-sdk-go-v2-docs \ - make setup generate - -preview: - hugo server \ - --bind $(PREVIEW_HOST) \ - --port $(PREVIEW_PORT) \ - --environment $(SITE_ENV) \ - -d docs - -container-preview: - docker build \ - $(COMMON_DOCKER_BUILD_ARGS) \ - -t aws-sdk-go-v2-docs \ - -f ./Dockerfile \ - . - docker run \ - -p 127.0.0.1:$(PREVIEW_PORT):$(PREVIEW_PORT) \ - --env PREVIEW_HOST=0.0.0.0 \ - --env PREVIEW_PORT=$(PREVIEW_PORT) \ - -i -t aws-sdk-go-v2-docs \ - make setup preview - -.PHONY: setup init-node-modules init-submodules generate container-generate validate preview preview container-preview diff --git a/README.md b/README.md index 1c020676298..db863b1ac07 100644 --- a/README.md +++ b/README.md @@ -1,85 +1 @@ -# AWS SDK for Go V2 Documentation - -This source tree contains the AWS SDK for Go V2 developer and migration guides. - -The documentation is generated using [Hugo](https://gohugo.io/), which is a -static website generator. This project uses the [Docsy](https://www.docsy.dev/) -Hugo theme for presentation and formatting of the docs content type. - -## Development - -### Getting Started - -1. [Install Hugo](https://gohugo.io/getting-started/installing) -1. Verify Hugo - ```bash - hugo version - ``` - **Output**: - ``` - hugo v0.91.2-1798BD3F+extended darwin/amd64 BuildDate=2021-12-23T15:33:34Z VendorInfo=gohugoio - ``` - - This project requires that the `extended` version of Hugo is installed. - Follow the download instructions to ensure the correct version is present. -1. Fork the SDK [repository](https://github.com/aws/aws-sdk-go-v2) -1. Checkout the documentation branch replacing `USERNAME` with your GitHub username. - ```bash - git clone --single-branch -b documentation git@github.com:USERNAME/aws-sdk-go-v2.git aws-sdk-go-v2-docs - cd aws-sdk-go-v2-docs - ``` -1. Install [NodeJS (LTS)](https://nodejs.org/en/) -1. Initialize project submodules and dependencies - ```bash - make setup - ``` - -### Previewing Changes - -Hugo comes with a built-in development server that allows you to iterate and -preview your documentation changes in realtime. This can be done by using the -following Hugo command: - -```bash -make preview -``` -The Hugo test server will print the endpoint to the terminal after it has -started, (e.g. http://localhost:1313). Use `ctrl+c` to terminate the preview -server. - -#### Preview without Hugo installed -The content of the docs can be previewed without installing Hugo or NodeJS, but -Docker is required instead. The following command will run the Hugo preview -server in a sandboxed container, with the preview endpoint expose locally. -``` -make container-preview -``` - -The Hugo test server will print the endpoint to the terminal after it has -started, (e.g. http://localhost:1313). Use `ctrl+c` to terminate the preview -server, and container. - -### Submitting PRs -Pull requests should be submitted to the [SDK Repository][sdkrepo], to help -speed up the process and reduce the time to merge please ensure that `Allow -edits and access to secrets by maintainers` is checked before submitting your -PR. This will allow the project maintainers to make minor adjustments or -improvements to the submitted PR, allow us to reduce the roundtrip time for -merging your request. - -### Building Content for Release -To generate the documentation content in preparation for releasing the updates, -the following command should be run. - -``` -make generate -``` - -This command will update the static version of the documentation into the -`docs/` folder. - -### References -* [Hugo Documentation](https://gohugo.io/documentation/) -* [Docsy Documentation](https://www.docsy.dev/docs/) - -[sdkrepo]: https://github.com/aws/aws-sdk-go-v2 +The aws-sdk-go-v2 developer guide has [migrated](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/welcome.html). diff --git a/archetypes/default.md b/archetypes/default.md deleted file mode 100644 index 00e77bd79be..00000000000 --- a/archetypes/default.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "{{ replace .Name "-" " " | title }}" -date: {{ .Date }} -draft: true ---- - diff --git a/assets/icons/logo.svg b/assets/icons/logo.svg deleted file mode 100644 index 7ec259dd81d..00000000000 --- a/assets/icons/logo.svg +++ /dev/null @@ -1,38 +0,0 @@ - - - - - - - - - - - - diff --git a/assets/scss/_variables_project.scss b/assets/scss/_variables_project.scss deleted file mode 100644 index d924ca50df4..00000000000 --- a/assets/scss/_variables_project.scss +++ /dev/null @@ -1,13 +0,0 @@ -$primary: #232F3E; -$secondary: #FF9900; -$success: #2e27ad; -$info: #16bf9f; -$warning: #ff5252; -$danger: #ff5252; -$white: #FFFFFF; -$light: #76eacc; - -$dark: #232F3E; -$blue: #527FFF; -$orange: #FF9900; -$black: #232F3E; diff --git a/builddocs.sh b/builddocs.sh deleted file mode 100755 index 4281a0b8b48..00000000000 --- a/builddocs.sh +++ /dev/null @@ -1,14 +0,0 @@ -#!/usr/bin/env bash - -set -eax - -DOCS_IMAGE_TAG="aws-sdk-go-v2-docs" -DOCS_BUILD_CONTAINER_NAME="aws-sdk-go-v2-docs-build" -SITE_ENV=${1:-production} - -rm -rf ./docs - -docker build -t $DOCS_IMAGE_TAG --build-arg SITE_ENV="${SITE_ENV}" . -docker container create --name $DOCS_BUILD_CONTAINER_NAME $DOCS_IMAGE_TAG -docker container cp $DOCS_BUILD_CONTAINER_NAME:/aws-sdk-go-v2-docs/docs . -docker container rm -f $DOCS_BUILD_CONTAINER_NAME diff --git a/config.toml b/config.toml deleted file mode 100644 index 534a36d1743..00000000000 --- a/config.toml +++ /dev/null @@ -1,186 +0,0 @@ -baseURL = "https://aws.github.io/aws-sdk-go-v2" -title = "AWS SDK for Go V2" - -enableRobotsTXT = true - -# Will give values to .Lastmod etc. -enableGitInfo = true - -# Language settings -contentDir = "content/en" -defaultContentLanguage = "en" -defaultContentLanguageInSubdir = false -# Useful when translating. -enableMissingTranslationPlaceholders = true - -disableKinds = ["taxonomy", "taxonomyTerm"] - -# Highlighting config -pygmentsCodeFences = true -pygmentsUseClasses = false -# Use the new Chroma Go highlighter in Hugo. -pygmentsUseClassic = false -#pygmentsOptions = "linenos=table" -# See https://help.farbox.com/pygments.html -pygmentsStyle = "tango" - -## Configuration for BlackFriday markdown parser: https://github.com/russross/blackfriday -[blackfriday] -plainIDAnchors = true -hrefTargetBlank = true -angledQuotes = false -latexDashes = true - -# Image processing configuration. -[imaging] -resampleFilter = "CatmullRom" -quality = 75 -anchor = "smart" - -# Language configuration - -[languages] -[languages.en] -title = "AWS SDK for Go V2" -description = "The AWS SDK for Go V2 provides APIs and utilities that developers can use to build Go applications that use AWS services." -languageName = "English" -# Weight used for sorting. -weight = 1 - -[markup] - [markup.goldmark] - [markup.goldmark.renderer] - unsafe = true - [markup.highlight] - # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html - style = "tango" - # Uncomment if you want your chosen highlight style used for code blocks without a specified language - # guessSyntax = "true" - [markup.tableOfContents] - endLevel = 3 - ordered = false - startLevel = 1 - -# Everything below this are Site Params - -[params] -copyright = "Amazon Web Services, Inc. or its affiliates." - -# First one is picked as the Twitter card image if not set on page. -# images = ["images/project-illustration.png"] - -# Menu title if your navbar has a versions selector to access old versions of your site. -# This menu appears only if you have at least one [params.versions] set. -version_menu = "Releases" - -# Flag used in the "version-banner" partial to decide whether to display a -# banner on every page indicating that this is an archived version of the docs. -# Set this flag to "true" if you want to display the banner. -archived_version = false - -# The version number for the version of the docs represented in this doc set. -# Used in the "version-banner" partial to display a version number for the -# current doc set. -version = "0.0" - -# A link to latest version of the docs. Used in the "version-banner" partial to -# point people to the main doc site. -url_latest_version = "https://aws.github.io/aws-sdk-go-v2" - -# Repository configuration (URLs for in-page links to opening issues and suggesting changes) -github_repo = "https://github.com/aws/aws-sdk-go-v2" -github_branch = "documentation" -# An optional link to a related project repo. For example, the sibling repository where your product code lives. -github_project_repo = "https://github.com/aws/aws-sdk-go-v2" - -# Enable Algolia DocSearch -algolia_docsearch = false - -# Enable Lunr.js offline search -offlineSearch = true - -# Enable syntax highlighting and copy buttons on code blocks with Prism -prism_syntax_highlighting = false - -# User interface configuration -[params.ui] -# Enable to show the side bar menu in its compact state. -sidebar_menu_compact = true -# Set to true to disable breadcrumb navigation. -breadcrumb_disable = false -# Set to true to hide the sidebar search box (the top nav search box is displayed if search is enabled) -sidebar_search_disable = false -# Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top nav bar -navbar_logo = true -# Set to true to disable the About link in the site footer -footer_about_disable = false - -# Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events. -# This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set. -# If you want this feature, but occasionally need to remove the "Feedback" section from a single page, -# add "hide_feedback: true" to the page's front matter. -[params.ui.feedback] -enable = true -# The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful). -yes = 'Glad to hear it! Please tell us how we can improve.' -no = 'Sorry to hear that. Please tell us how we can improve.' - -# Adds a reading time to the top of each doc. -# If you want this feature, but occasionally need to remove the Reading time from a single page, -# add "hide_readingtime: true" to the page's front matter -[params.ui.readingtime] -enable = false - -[[menu.main]] -identifier = "APIRef" -name = "API Reference" -url = "https://pkg.go.dev/github.com/aws/aws-sdk-go-v2" - -[[menu.main]] -identifier = "GitHubRepo" -name = "GitHub" -url = "https://github.com/aws/aws-sdk-go-v2" - - -[params.links] -# End user relevant links. These will show up on left side of footer and in the community page if you have one. -[[params.links.user]] -name = "Blog" -url = "https://aws.amazon.com/blogs/developer/category/developer-tools/aws-sdk-for-go/" -icon = "fa fa-rss" -desc = "Latest AWS SDK for Go V2 News" -# Developer relevant links. These will show up on right side of footer and in the community page if you have one. -[[params.links.developer]] -name = "GitHub" -url = "https://github.com/aws/aws-sdk-go-v2" -icon = "fab fa-github" -desc = "Development takes place here!" - -[privacy] -[privacy.disqus] -disable = true -[privacy.googleAnalytics] -disable = true -[privacy.instagram] -disable = true -[privacy.twitter] -disable = true -[privacy.vimeo] -disable = true -[privacy.youtube] -disable = true - -[module] - proxy = "direct" - # uncomment line below for temporary local development of module - # replacements = "github.com/google/docsy -> ../../docsy" - [module.hugoVersion] - extended = true - min = "0.101.0" - [[module.imports]] - path = "github.com/google/docsy" - disable = false - [[module.imports]] - path = "github.com/google/docsy/dependencies" - disable = false - diff --git a/content/en/_index.html b/content/en/_index.html deleted file mode 100644 index d81ac6f91fa..00000000000 --- a/content/en/_index.html +++ /dev/null @@ -1,39 +0,0 @@ -+++ -title = "AWS SDK for Go V2" -+++ - -{{< blocks/cover title="Welcome to the AWS SDK for Go V2" height="auto" >}} -
- }}"> - Learn More - - - Download - -
-{{< /blocks/cover >}} - -{{< blocks/section color="white" >}} - -{{% blocks/feature title="Modularized" icon="fa-th" %}} -Model service dependencies in your application, and independently control service client updates using Go modules. -{{% /blocks/feature %}} - -{{% blocks/feature title="Paginators" icon="fa-file" %}} -Easily iterate over API results that span multiple pages. -{{% /blocks/feature %}} - -{{% blocks/feature title="Waiters" icon="fa-search" %}} -Validate AWS resources states before performing additional actions. -{{% /blocks/feature %}} - -{{% blocks/feature title="Utilities" icon="fa-cog" %}} -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. -{{% /blocks/feature %}} - -{{% blocks/feature title="Extensible" icon="fa-terminal" %}} -Middleware allows you to extend or customize the transport request pipeline to fit your applications requirements. -{{% /blocks/feature %}} - -{{< /blocks/section >}} diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md deleted file mode 100644 index 44b79c7e55b..00000000000 --- a/content/en/docs/_index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: "Developer Guide" -linkTitle: "Developer Guide" -date: "2020-11-12" -weight: 1 -menu: - main: - weight: 20 ---- - -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). - -The SDK removes the complexity of coding directly against a web service interface. It hides a lot of the lower-level -plumbing, such as authentication, request retries, and error handling. - -The SDK also includes helpful utilities. For example, the Amazon S3 download and upload manager can automatically break -up large objects into multiple parts and transfer them in parallel. - -Use 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. - -## Maintenance 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: - -* [AWS SDKs and Tools Maintenance Policy](https://docs.aws.amazon.com/credref/latest/refdocs/maint-policy.html) -* [AWS SDKs and Tools Version Support Matrix](https://docs.aws.amazon.com/credref/latest/refdocs/version-support-matrix.html) diff --git a/content/en/docs/cloud9-go.md b/content/en/docs/cloud9-go.md deleted file mode 100644 index 2d3d22f880f..00000000000 --- a/content/en/docs/cloud9-go.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: "Using AWS Cloud9 with the AWS SDK for Go V2" -linkTitle: "Using Cloud9 with the SDK" -date: "2020-11-12" -weight: 10 ---- - -You can use {{% alias service=AC9long %}} with the {{% alias sdk-go %}} to write and run your Go code using just a -browser. {{% alias service=AC9 %}} includes tools such as a code editor and terminal. The {{% alias service=AC9 -%}} 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 {{% alias service=AC9 %}}, see the {{% alias service=AC9 %}} -[User Guide](https://docs.aws.amazon.com/cloud9/latest/user-guide/welcome.html). - -Follow the instructions below to set up {{% alias service=AC9 %}} with the {{% alias sdk-go %}}: - -## Set up Your AWS Account to Use {{% alias service=AC9 %}} - -To start using {{% alias service=AC9 %}}, sign in to the {{% alias service=AC9 %}} console as an {{% alias -service=IAMlong %}} ({{% alias service=IAM %}}) entity (for example, an {{% alias service=IAM %}} user) in your AWS -account which has access permissions for {{% alias service=AC9 %}}. - -Review [Team Setup for AWS Cloud9](https://docs.aws.amazon.com/cloud9/latest/user-guide/setup.html) in the {{% alias -service=AC9 %}} User Guide, for help with setting up an {{% alias service=IAM %}} entity in your AWS account to access -{{% alias service=AC9 %}}, and to sign in to the {{% alias service=AC9 %}} console. - -## Set up Your {{% alias service=AC9 %}} Development Environment - -After you sign in to the {{% alias service=AC9 %}} console, use the console to create an {{% alias service=AC9 %}} -development environment. After you create the environment, {{% alias service=AC9 %}} opens the IDE for that environment. - -See [Creating an Environment in AWS Cloud9](https://docs.aws.amazon.com/cloud9/latest/user-guide/create-environment.html) -in the {{% alias service=AC9 %}} User Guide for details. - -{{% pageinfo color="info" %}} As 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 {{% alias service=AC9 %}} to -create an environment, launch an {{% alias service=EC2 %}} instance, and then connect the new instance to the new -environment. This is the fastest way to begin using {{% alias service=AC9 %}}. {{% /pageinfo %}} - -## Set up the AWS SDK for Go V2 - -After {{% alias service=AC9 %}} opens the IDE for your development environment, use the IDE to set up the {{% alias -sdk-go %}} in your environment, as follows. - -1. If the terminal isn't already open in the IDE, open it. On the menu bar in the IDE, choose **Window, New Terminal**. - -1. Validate the {{% alias service=AC9 %}} available Go version. - ``` - go 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]({{% ref "#InstallUpgradeGo" %}}). - -1. Follow the [Getting Started]({{% relref "getting-started.md" %}}) guide to set up a Go project under `~/environment`, - or follow the steps to [Download Example Code]({{% ref "#DownloadExample" %}}) - -## Download Example Code {#DownloadExample} - -Use the terminal you opened in the previous step to download example code for the {{% alias sdk-go %}} into the {{% -alias service=AC9 %}} development environment. - -To 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. - -``` -git clone https://github.com/awsdocs/aws-doc-sdk-examples.git -``` - -To find code examples for the {{% alias sdk-go %}}, 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. - -### Run Example Code - -To run code in your {{% alias service=AC9 %}} development environment, see -[Run Your Code](https://docs.aws.amazon.com/cloud9/latest/user-guide/build-run-debug.html#build-run-debug-run) in the -{{% alias service=AC9 %}} User Guide. - -## Installing/Upgrading {{% alias service=AC9 %}} Go Version {#InstallUpgradeGo} - -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](https://golang.org/dl/) on The Go Programming Language -website.) - -``` -wget 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. - -``` - PATH=$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.) - -``` -. ~/.bashrc -``` diff --git a/content/en/docs/code-examples/_index.md b/content/en/docs/code-examples/_index.md deleted file mode 100644 index 9134fa66bb3..00000000000 --- a/content/en/docs/code-examples/_index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Code Examples" -date: "2021-01-14" -weight: 100 ---- - -The {{% alias sdk-go %}} 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]({{< ref "getting-started.md" >}}) and -[Configuring the SDK]({{< ref "configuring-sdk" >}}). - -Find the source code for these examples and others in the AWS documentation code examples repository on -[GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2). -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](https://github.com/awsdocs/aws-doc-sdk-examples). diff --git a/content/en/docs/code-examples/cloudwatch/CreateCustomMetric/_index.md b/content/en/docs/code-examples/cloudwatch/CreateCustomMetric/_index.md deleted file mode 100644 index 1eb4ab58bff..00000000000 --- a/content/en/docs/code-examples/cloudwatch/CreateCustomMetric/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "CreateCustomMetricv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/cloudwatch/CreateEnableMetricAlarm/_index.md b/content/en/docs/code-examples/cloudwatch/CreateEnableMetricAlarm/_index.md deleted file mode 100644 index 302d41517f2..00000000000 --- a/content/en/docs/code-examples/cloudwatch/CreateEnableMetricAlarm/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "CreateEnableMetricAlarmv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/cloudwatch/DescribeAlarms/_index.md b/content/en/docs/code-examples/cloudwatch/DescribeAlarms/_index.md deleted file mode 100644 index 8186e05ee09..00000000000 --- a/content/en/docs/code-examples/cloudwatch/DescribeAlarms/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "DescribeAlarmsv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/cloudwatch/DisableAlarm/_index.md b/content/en/docs/code-examples/cloudwatch/DisableAlarm/_index.md deleted file mode 100644 index aed12bc5e20..00000000000 --- a/content/en/docs/code-examples/cloudwatch/DisableAlarm/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "DisableAlarmv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/cloudwatch/ListMetrics/_index.md b/content/en/docs/code-examples/cloudwatch/ListMetrics/_index.md deleted file mode 100644 index 0233b9987d0..00000000000 --- a/content/en/docs/code-examples/cloudwatch/ListMetrics/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "ListMetricsv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/cloudwatch/PutEvent/_index.md b/content/en/docs/code-examples/cloudwatch/PutEvent/_index.md deleted file mode 100644 index 8e4f935e3d2..00000000000 --- a/content/en/docs/code-examples/cloudwatch/PutEvent/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "PutEventv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/cloudwatch/_index.md b/content/en/docs/code-examples/cloudwatch/_index.md deleted file mode 100644 index 6c9195aac52..00000000000 --- a/content/en/docs/code-examples/cloudwatch/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "Amazon CloudWatch Examples" -linkTitle: "Amazon CloudWatch" -weight: 3 ---- - -This section contains code examples for Amazon CloudWatch using version 2 of the AWS SDK for Go. diff --git a/content/en/docs/code-examples/dynamodb/DescribeTable/_index.md b/content/en/docs/code-examples/dynamodb/DescribeTable/_index.md deleted file mode 100644 index 6fd36a75167..00000000000 --- a/content/en/docs/code-examples/dynamodb/DescribeTable/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "DescribeTablev2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/dynamodb/ScanItems/_index.md b/content/en/docs/code-examples/dynamodb/ScanItems/_index.md deleted file mode 100644 index 0af1a8a16bf..00000000000 --- a/content/en/docs/code-examples/dynamodb/ScanItems/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "ScanItemsv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/dynamodb/_index.md b/content/en/docs/code-examples/dynamodb/_index.md deleted file mode 100644 index 28d6dea288a..00000000000 --- a/content/en/docs/code-examples/dynamodb/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "Amazon DynamoDB Examples" -linkTitle: "Amazon DynamoDB" -weight: 3 ---- - -This section contains code examples for Amazon DynamoDB using version 2 of the AWS SDK for Go. diff --git a/content/en/docs/code-examples/ec2/CreateImage/_index.md b/content/en/docs/code-examples/ec2/CreateImage/_index.md deleted file mode 100644 index 2944753cb2a..00000000000 --- a/content/en/docs/code-examples/ec2/CreateImage/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "CreateImagev2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/ec2/CreateInstance/_index.md b/content/en/docs/code-examples/ec2/CreateInstance/_index.md deleted file mode 100644 index 70564508198..00000000000 --- a/content/en/docs/code-examples/ec2/CreateInstance/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "CreateInstancev2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/ec2/DescribeInstances/_index.md b/content/en/docs/code-examples/ec2/DescribeInstances/_index.md deleted file mode 100644 index 36fc5d7a9d5..00000000000 --- a/content/en/docs/code-examples/ec2/DescribeInstances/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "DescribeInstancesv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/ec2/DescribeVpcEndpoints/_index.md b/content/en/docs/code-examples/ec2/DescribeVpcEndpoints/_index.md deleted file mode 100644 index 6f8604241de..00000000000 --- a/content/en/docs/code-examples/ec2/DescribeVpcEndpoints/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "DescribeVpcEndpointsv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/ec2/MonitorInstances/_index.md b/content/en/docs/code-examples/ec2/MonitorInstances/_index.md deleted file mode 100644 index 9f69bbe73b0..00000000000 --- a/content/en/docs/code-examples/ec2/MonitorInstances/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "MonitorInstancesv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/ec2/RebootInstances/_index.md b/content/en/docs/code-examples/ec2/RebootInstances/_index.md deleted file mode 100644 index acbed846f19..00000000000 --- a/content/en/docs/code-examples/ec2/RebootInstances/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "RebootInstancesv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/ec2/StartInstances/_index.md b/content/en/docs/code-examples/ec2/StartInstances/_index.md deleted file mode 100644 index 6c9f0a57e60..00000000000 --- a/content/en/docs/code-examples/ec2/StartInstances/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "StartInstancesv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/ec2/StopInstances/_index.md b/content/en/docs/code-examples/ec2/StopInstances/_index.md deleted file mode 100644 index f9b3003c56b..00000000000 --- a/content/en/docs/code-examples/ec2/StopInstances/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "StopInstancesv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/ec2/_index.md b/content/en/docs/code-examples/ec2/_index.md deleted file mode 100644 index 06185d38e68..00000000000 --- a/content/en/docs/code-examples/ec2/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "Amazon EC2 Examples" -linkTitle: "Amazon EC2" -weight: 3 ---- - -This section contains code examples for Amazon EC2 using version 2 of the AWS SDK for Go. diff --git a/content/en/docs/code-examples/iam/AccessKeyLastUsed/_index.md b/content/en/docs/code-examples/iam/AccessKeyLastUsed/_index.md deleted file mode 100644 index bdb7a29c7d3..00000000000 --- a/content/en/docs/code-examples/iam/AccessKeyLastUsed/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "AccessKeyLastUsedv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/AttachUserPolicy/_index.md b/content/en/docs/code-examples/iam/AttachUserPolicy/_index.md deleted file mode 100644 index fc4f987fd21..00000000000 --- a/content/en/docs/code-examples/iam/AttachUserPolicy/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "AttachUserPolicyv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/CreateAccessKey/_index.md b/content/en/docs/code-examples/iam/CreateAccessKey/_index.md deleted file mode 100644 index 2d2240947c4..00000000000 --- a/content/en/docs/code-examples/iam/CreateAccessKey/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "CreateAccessKeyv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/CreateAccountAlias/_index.md b/content/en/docs/code-examples/iam/CreateAccountAlias/_index.md deleted file mode 100644 index 29cf3a425df..00000000000 --- a/content/en/docs/code-examples/iam/CreateAccountAlias/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "CreateAccountAliasv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/CreatePolicy/_index.md b/content/en/docs/code-examples/iam/CreatePolicy/_index.md deleted file mode 100644 index d019539d5cf..00000000000 --- a/content/en/docs/code-examples/iam/CreatePolicy/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "CreatePolicyv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/CreateUser/_index.md b/content/en/docs/code-examples/iam/CreateUser/_index.md deleted file mode 100644 index 10b637c6446..00000000000 --- a/content/en/docs/code-examples/iam/CreateUser/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "CreateUserv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/DeleteAccessKey/_index.md b/content/en/docs/code-examples/iam/DeleteAccessKey/_index.md deleted file mode 100644 index 192b45b3896..00000000000 --- a/content/en/docs/code-examples/iam/DeleteAccessKey/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "DeleteAccessKeyv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/DeleteAccountAlias/_index.md b/content/en/docs/code-examples/iam/DeleteAccountAlias/_index.md deleted file mode 100644 index fc4758ad47a..00000000000 --- a/content/en/docs/code-examples/iam/DeleteAccountAlias/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "DeleteAccountAliasv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/DeleteServerCert/_index.md b/content/en/docs/code-examples/iam/DeleteServerCert/_index.md deleted file mode 100644 index 8aff6985140..00000000000 --- a/content/en/docs/code-examples/iam/DeleteServerCert/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "DeleteServerCertv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/DeleteUser/_index.md b/content/en/docs/code-examples/iam/DeleteUser/_index.md deleted file mode 100644 index 2f992cc319d..00000000000 --- a/content/en/docs/code-examples/iam/DeleteUser/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "DeleteUserv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/DetachUserPolicy/_index.md b/content/en/docs/code-examples/iam/DetachUserPolicy/_index.md deleted file mode 100644 index ac8ccd7ba19..00000000000 --- a/content/en/docs/code-examples/iam/DetachUserPolicy/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "DetachUserPolicyv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/GetPolicy/_index.md b/content/en/docs/code-examples/iam/GetPolicy/_index.md deleted file mode 100644 index f4e363678e3..00000000000 --- a/content/en/docs/code-examples/iam/GetPolicy/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "GetPolicyv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/GetServerCert/_index.md b/content/en/docs/code-examples/iam/GetServerCert/_index.md deleted file mode 100644 index 3af6fc6f080..00000000000 --- a/content/en/docs/code-examples/iam/GetServerCert/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "GetServerCertv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/ListAccessKeys/_index.md b/content/en/docs/code-examples/iam/ListAccessKeys/_index.md deleted file mode 100644 index 1ea4d8b7898..00000000000 --- a/content/en/docs/code-examples/iam/ListAccessKeys/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "ListAccessKeysv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/ListAccountAliases/_index.md b/content/en/docs/code-examples/iam/ListAccountAliases/_index.md deleted file mode 100644 index 320b33855b2..00000000000 --- a/content/en/docs/code-examples/iam/ListAccountAliases/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "ListAccountAliasesv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/ListAdmins/_index.md b/content/en/docs/code-examples/iam/ListAdmins/_index.md deleted file mode 100644 index e9ae8b492e6..00000000000 --- a/content/en/docs/code-examples/iam/ListAdmins/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "ListAdminsv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/ListServerCerts/_index.md b/content/en/docs/code-examples/iam/ListServerCerts/_index.md deleted file mode 100644 index 7f0a1fcd250..00000000000 --- a/content/en/docs/code-examples/iam/ListServerCerts/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "ListServerCertsv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/ListUsers/_index.md b/content/en/docs/code-examples/iam/ListUsers/_index.md deleted file mode 100644 index d3c4077978f..00000000000 --- a/content/en/docs/code-examples/iam/ListUsers/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "ListUsersv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/UpdateAccessKey/_index.md b/content/en/docs/code-examples/iam/UpdateAccessKey/_index.md deleted file mode 100644 index 3fdf17128c7..00000000000 --- a/content/en/docs/code-examples/iam/UpdateAccessKey/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "UpdateAccessKeyv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/UpdateServerCert/_index.md b/content/en/docs/code-examples/iam/UpdateServerCert/_index.md deleted file mode 100644 index b17fd63ed58..00000000000 --- a/content/en/docs/code-examples/iam/UpdateServerCert/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "UpdateServerCertv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/UpdateUser/_index.md b/content/en/docs/code-examples/iam/UpdateUser/_index.md deleted file mode 100644 index 979bfc9f245..00000000000 --- a/content/en/docs/code-examples/iam/UpdateUser/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "UpdateUserv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/iam/_index.md b/content/en/docs/code-examples/iam/_index.md deleted file mode 100644 index 22d13c21d46..00000000000 --- a/content/en/docs/code-examples/iam/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "IAM Examples" -linkTitle: "IAM" -weight: 3 ---- - -This section contains code examples for IAM using version 2 of the AWS SDK for Go. diff --git a/content/en/docs/code-examples/kms/CreateKey/_index.md b/content/en/docs/code-examples/kms/CreateKey/_index.md deleted file mode 100644 index d8d385f22ac..00000000000 --- a/content/en/docs/code-examples/kms/CreateKey/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "CreateKeyv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/kms/DecryptData/_index.md b/content/en/docs/code-examples/kms/DecryptData/_index.md deleted file mode 100644 index 53042aacbe4..00000000000 --- a/content/en/docs/code-examples/kms/DecryptData/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "DecryptDatav2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/kms/EncryptData/_index.md b/content/en/docs/code-examples/kms/EncryptData/_index.md deleted file mode 100644 index 54c88c3fd53..00000000000 --- a/content/en/docs/code-examples/kms/EncryptData/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "EncryptDatav2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/kms/ReEncryptData/_index.md b/content/en/docs/code-examples/kms/ReEncryptData/_index.md deleted file mode 100644 index 1fffc3706f0..00000000000 --- a/content/en/docs/code-examples/kms/ReEncryptData/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "ReEncryptDatav2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/kms/_index.md b/content/en/docs/code-examples/kms/_index.md deleted file mode 100644 index 53a4c83ec4c..00000000000 --- a/content/en/docs/code-examples/kms/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "AWS KMS Examples" -linkTitle: "AWS KMS" -weight: 3 ---- - -This section contains code examples for AWS KMS using version 2 of the AWS SDK for Go. diff --git a/content/en/docs/code-examples/s3/CopyObject/_index.md b/content/en/docs/code-examples/s3/CopyObject/_index.md deleted file mode 100644 index 453d324cebd..00000000000 --- a/content/en/docs/code-examples/s3/CopyObject/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "CopyObjectv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/s3/CreateBucket/_index.md b/content/en/docs/code-examples/s3/CreateBucket/_index.md deleted file mode 100644 index 989b4953b13..00000000000 --- a/content/en/docs/code-examples/s3/CreateBucket/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "CreateBucketv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/s3/DeleteBucket/_index.md b/content/en/docs/code-examples/s3/DeleteBucket/_index.md deleted file mode 100644 index 579f3e8f95c..00000000000 --- a/content/en/docs/code-examples/s3/DeleteBucket/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "DeleteBucketv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/s3/DeleteObject/_index.md b/content/en/docs/code-examples/s3/DeleteObject/_index.md deleted file mode 100644 index c0cf5268fe8..00000000000 --- a/content/en/docs/code-examples/s3/DeleteObject/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "DeleteObjectv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/s3/GeneratePresignedURL/_index.md b/content/en/docs/code-examples/s3/GeneratePresignedURL/_index.md deleted file mode 100644 index 86ef9f849ff..00000000000 --- a/content/en/docs/code-examples/s3/GeneratePresignedURL/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "GeneratePresignedURLv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/s3/GetBucketAcl/_index.md b/content/en/docs/code-examples/s3/GetBucketAcl/_index.md deleted file mode 100644 index 361191592e4..00000000000 --- a/content/en/docs/code-examples/s3/GetBucketAcl/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "GetBucketAclv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/s3/GetObjectAcl/_index.md b/content/en/docs/code-examples/s3/GetObjectAcl/_index.md deleted file mode 100644 index e96fe565f06..00000000000 --- a/content/en/docs/code-examples/s3/GetObjectAcl/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "GetObjectAclv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/s3/ListBuckets/_index.md b/content/en/docs/code-examples/s3/ListBuckets/_index.md deleted file mode 100644 index 66931c16175..00000000000 --- a/content/en/docs/code-examples/s3/ListBuckets/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "ListBucketsv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/s3/ListObjects/_index.md b/content/en/docs/code-examples/s3/ListObjects/_index.md deleted file mode 100644 index 447efae0dc6..00000000000 --- a/content/en/docs/code-examples/s3/ListObjects/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "ListObjectsv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/s3/PutObject/_index.md b/content/en/docs/code-examples/s3/PutObject/_index.md deleted file mode 100644 index 61601832b12..00000000000 --- a/content/en/docs/code-examples/s3/PutObject/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "PutObjectv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/s3/_index.md b/content/en/docs/code-examples/s3/_index.md deleted file mode 100644 index 8b91c9f2f35..00000000000 --- a/content/en/docs/code-examples/s3/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "Amazon S3 Examples" -linkTitle: "Amazon S3" -weight: 3 ---- - -This section contains code examples for Amazon S3 using version 2 of the AWS SDK for Go. diff --git a/content/en/docs/code-examples/sns/CreateTopic/_index.md b/content/en/docs/code-examples/sns/CreateTopic/_index.md deleted file mode 100644 index 443b66fa66b..00000000000 --- a/content/en/docs/code-examples/sns/CreateTopic/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "CreateTopicv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sns/ListSubscriptions/_index.md b/content/en/docs/code-examples/sns/ListSubscriptions/_index.md deleted file mode 100644 index b6217288ca9..00000000000 --- a/content/en/docs/code-examples/sns/ListSubscriptions/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "ListSubscriptionsv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sns/ListTopics/_index.md b/content/en/docs/code-examples/sns/ListTopics/_index.md deleted file mode 100644 index b397394f6e1..00000000000 --- a/content/en/docs/code-examples/sns/ListTopics/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "ListTopicsv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sns/Publish/_index.md b/content/en/docs/code-examples/sns/Publish/_index.md deleted file mode 100644 index fc15d3d3d41..00000000000 --- a/content/en/docs/code-examples/sns/Publish/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Publishv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sns/Subscribe/_index.md b/content/en/docs/code-examples/sns/Subscribe/_index.md deleted file mode 100644 index 26794472881..00000000000 --- a/content/en/docs/code-examples/sns/Subscribe/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Subscribev2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sns/_index.md b/content/en/docs/code-examples/sns/_index.md deleted file mode 100644 index 6eaa730414e..00000000000 --- a/content/en/docs/code-examples/sns/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "Amazon SNS Examples" -linkTitle: "Amazon SNS" -weight: 3 ---- - -This section contains code examples for Amazon SNS using version 2 of the AWS SDK for Go. diff --git a/content/en/docs/code-examples/sqs/ChangeMsgVisibility/_index.md b/content/en/docs/code-examples/sqs/ChangeMsgVisibility/_index.md deleted file mode 100644 index b3a9f9269b9..00000000000 --- a/content/en/docs/code-examples/sqs/ChangeMsgVisibility/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "ChangeMsgVisibilityv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sqs/ConfigureLPQueue/_index.md b/content/en/docs/code-examples/sqs/ConfigureLPQueue/_index.md deleted file mode 100644 index dacc916d682..00000000000 --- a/content/en/docs/code-examples/sqs/ConfigureLPQueue/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "ConfigureLPQueuev2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sqs/CreateLPQueue/_index.md b/content/en/docs/code-examples/sqs/CreateLPQueue/_index.md deleted file mode 100644 index e26948a4a16..00000000000 --- a/content/en/docs/code-examples/sqs/CreateLPQueue/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "CreateLPQueuev2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sqs/CreateQueue/_index.md b/content/en/docs/code-examples/sqs/CreateQueue/_index.md deleted file mode 100644 index 71cf7b580d5..00000000000 --- a/content/en/docs/code-examples/sqs/CreateQueue/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "CreateQueuev2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sqs/DeadLetterQueue/_index.md b/content/en/docs/code-examples/sqs/DeadLetterQueue/_index.md deleted file mode 100644 index 5182d52903f..00000000000 --- a/content/en/docs/code-examples/sqs/DeadLetterQueue/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "DeadLetterQueuev2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sqs/DeleteMessage/_index.md b/content/en/docs/code-examples/sqs/DeleteMessage/_index.md deleted file mode 100644 index abf1f52290e..00000000000 --- a/content/en/docs/code-examples/sqs/DeleteMessage/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "DeleteMessagev2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sqs/DeleteQueue/_index.md b/content/en/docs/code-examples/sqs/DeleteQueue/_index.md deleted file mode 100644 index 3c65b072274..00000000000 --- a/content/en/docs/code-examples/sqs/DeleteQueue/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "DeleteQueuev2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sqs/GetQueueURL/_index.md b/content/en/docs/code-examples/sqs/GetQueueURL/_index.md deleted file mode 100644 index a8153d8d955..00000000000 --- a/content/en/docs/code-examples/sqs/GetQueueURL/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "GetQueueURLv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sqs/ListQueues/_index.md b/content/en/docs/code-examples/sqs/ListQueues/_index.md deleted file mode 100644 index 221a8778436..00000000000 --- a/content/en/docs/code-examples/sqs/ListQueues/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "ListQueuesv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sqs/ReceiveLPMessage/_index.md b/content/en/docs/code-examples/sqs/ReceiveLPMessage/_index.md deleted file mode 100644 index 60a025d2c75..00000000000 --- a/content/en/docs/code-examples/sqs/ReceiveLPMessage/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "ReceiveLPMessagev2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sqs/ReceiveMessage/_index.md b/content/en/docs/code-examples/sqs/ReceiveMessage/_index.md deleted file mode 100644 index 4b79dba13ea..00000000000 --- a/content/en/docs/code-examples/sqs/ReceiveMessage/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "ReceiveMessagev2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sqs/SendMessage/_index.md b/content/en/docs/code-examples/sqs/SendMessage/_index.md deleted file mode 100644 index 0ec3277338a..00000000000 --- a/content/en/docs/code-examples/sqs/SendMessage/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "SendMessagev2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sqs/_index.md b/content/en/docs/code-examples/sqs/_index.md deleted file mode 100644 index cd189e1cf2a..00000000000 --- a/content/en/docs/code-examples/sqs/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "Amazon SQS Examples" -linkTitle: "Amazon SQS" -weight: 3 ---- - -This section contains code examples for Amazon SQS using version 2 of the AWS SDK for Go. diff --git a/content/en/docs/code-examples/ssm/DeleteParameter/_index.md b/content/en/docs/code-examples/ssm/DeleteParameter/_index.md deleted file mode 100644 index b9e0d058ee3..00000000000 --- a/content/en/docs/code-examples/ssm/DeleteParameter/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "DeleteParameterv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/ssm/GetParameter/_index.md b/content/en/docs/code-examples/ssm/GetParameter/_index.md deleted file mode 100644 index 1a3795cbd76..00000000000 --- a/content/en/docs/code-examples/ssm/GetParameter/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "GetParameterv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/ssm/PutParameter/_index.md b/content/en/docs/code-examples/ssm/PutParameter/_index.md deleted file mode 100644 index b2c1e5a58f5..00000000000 --- a/content/en/docs/code-examples/ssm/PutParameter/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "PutParameterv2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/ssm/_index.md b/content/en/docs/code-examples/ssm/_index.md deleted file mode 100644 index 7f63f01663a..00000000000 --- a/content/en/docs/code-examples/ssm/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "AWS Systems Manager Examples" -linkTitle: "AWS Systems Manager" -weight: 3 ---- - -This section contains code examples for AWS Systems Manager using version 2 of the AWS SDK for Go. diff --git a/content/en/docs/code-examples/sts/AssumeRole/_index.md b/content/en/docs/code-examples/sts/AssumeRole/_index.md deleted file mode 100644 index 693311dd231..00000000000 --- a/content/en/docs/code-examples/sts/AssumeRole/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "AssumeRolev2" -type: "redirect" -layout: "examples" ---- diff --git a/content/en/docs/code-examples/sts/_index.md b/content/en/docs/code-examples/sts/_index.md deleted file mode 100644 index a9c0d6f5be1..00000000000 --- a/content/en/docs/code-examples/sts/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "AWS STS Examples" -linkTitle: "AWS STS" -weight: 3 ---- - -This section contains code examples for AWS STS using version 2 of the AWS SDK for Go. diff --git a/content/en/docs/configuring-sdk/_index.md b/content/en/docs/configuring-sdk/_index.md deleted file mode 100644 index 57297198410..00000000000 --- a/content/en/docs/configuring-sdk/_index.md +++ /dev/null @@ -1,443 +0,0 @@ ---- -title: "Configuring the AWS SDK for Go V2" -linkTitle: "Configuring the SDK" -weight: 3 ---- - -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. - -## Loading 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. - -To configure the SDK to use the AWS shared configuration use the following code: - -```go -import ( - "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]({{< apiref "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. - -For more information about AWS Shared Configuration see the -[AWS Tools and SDKs Shared Configuration and Credentials Reference Guide ](https://docs.aws.amazon.com/credref/latest/refdocs/overview.html) - -## 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. - -The SDK does not have a default Region. To specify a Region: - -* Set the `AWS_REGION` environment variable to the default Region - -* Set the region explicitly - using [config.WithRegion](https://github.com/aws/aws-sdk-go-v2/blob/config/v0.2.2/config/provider.go#L127) - as an argument to `config.LoadDefaultConfig` when loading configuration. - -If you set a Region using all of these techniques, the SDK uses the Region you explicitly specified. - -##### Configure Region with Environment Variable - -###### Linux, macOS, or Unix - -``` -export AWS_REGION=us-west-2 -``` - -###### Windows - -```batchfile -set AWS_REGION=us-west-2 -``` - -##### Specify Region Programmatically - -```go -cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion("us-west-2")) -``` - -## Specifying Credentials - -The {{% alias sdk-go %}} 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]({{% relref "getting-started.md" %}}). - -When 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: - -1. Environment variables. - 1. Static Credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`) - 2. Web Identity Token (`AWS_WEB_IDENTITY_TOKEN_FILE`) -1. Shared configuration files. - 1. SDK defaults to `credentials` file under `.aws` folder that is placed in the home folder on your computer. - 1. SDK defaults to `config` file under `.aws` folder that is placed in the home folder on your computer. -1. If your application uses an ECS task definition or RunTask API operation, - {{% alias service=IAM %}} role for tasks. -1. If your application is running on an {{% alias service=EC2 %}} instance, {{% alias service=IAM %}} role for {{% alias service=EC2 %}}. - -The SDK detects and uses the built-in providers automatically, without -requiring manual configurations. For example, if you use {{% alias service=IAM %}} roles for -{{% alias service=EC2 %}} instances, your applications automatically use the -instance's credentials. You don't need to manually configure credentials -in your application. - -As a best practice, AWS recommends that you specify credentials in the -following order: - -1. Use {{% alias service=IAM %}} roles for tasks if your application uses an ECS task definition or RunTask API operation. - -1. Use {{% alias service=IAM %}} roles for {{% alias service=EC2 %}} (if your application is running on an - {{% alias service=EC2 %}} instance). - - {{% alias service=IAM %}} roles provide applications on the instance temporary security - credentials to make AWS calls. {{% alias service=IAM %}} roles provide an easy way to - distribute and manage credentials on multiple {{% alias service=EC2 %}} instances. - -1. Use shared credentials or config files. - - The credentials and config files are shared across other AWS SDKs and {{% alias service=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](https://docs.aws.amazon.com/credref/latest/refdocs/file-format.html) for each of these files. - -4. Use environment variables. - - Setting environment variables is useful if you're doing development - work on a machine other than an {{% alias service=EC2 %}} instance. - - -### {{% alias service=IAM %}} Roles for Tasks - -If your application uses an {{% alias service=ECS %}} task definition or `RunTask` operation, -use [IAM Roles for Tasks](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) -to specify an IAM role that can be used by the containers in a task. - -### {{% alias service=IAM %}} Roles for {{% alias service=EC2 %}} Instances - -If you are running your application on an {{% alias service=EC2 %}} instance, -use the instance's [IAM role](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) -to get temporary security credentials to make calls to AWS. - -If you have configured your instance to use {{% alias service=IAM %}} roles, the SDK uses -these credentials for your application automatically. You don't need to -manually specify these credentials. - -### Shared 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. - -You 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](https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/#specifying-credentials) -section. - -```go -import ( - "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"}, - ) -) - -``` - -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, - -1. If duplicate profiles are specified within a same credentials/config file, - the profile properties specified in the latter profile takes precedence. - -1. If 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. - -1. If a profile exists in both credentials file and config file, the credentials file - properties take precedence. - -If need be, you can enable `LogConfigurationWarnings` on `config.LoadOptions`, and -log the profile resolution steps. - -#### Creating 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 -`` and `` with your -credentials. - -```ini -[default] -aws_access_key_id = -aws_secret_access_key = -``` - -The `[default]` heading defines credentials for the default profile, -which the SDK will use unless you configure it to use another profile. - -You can also use temporary security credentials by adding the session -tokens to your profile, as shown in the following example: - -```ini -[temp] -aws_access_key_id = -aws_secret_access_key = -aws_session_token = -``` -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](https://docs.aws.amazon.com/credref/latest/refdocs/file-format.html#file-format-creds). - -#### Creating 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 `` with the -desired region. - -```ini -[default] -region = -``` - -The `[default]` heading defines config for the default profile, -which the SDK will use unless you configure it to use another profile. - -You use named profiles, as shown in the following example: - -```ini -[profile named-profile] -region = -``` - -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](https://docs.aws.amazon.com/credref/latest/refdocs/file-format.html#file-format-config). - -#### Specifying 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. - -```ini -[default] -aws_access_key_id = -aws_secret_access_key = - -[test-account] -aws_access_key_id = -aws_secret_access_key = - -[prod-account] -; work profile -aws_access_key_id = -aws_secret_access_key = -``` - -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. - -Sometimes, 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: - -``` -$ 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: - -```go -cfg, err := config.LoadDefaultConfig(context.TODO(), - config.WithSharedConfigProfile("test-account")) -``` - -{{% pageinfo color="info" %}} -If you specify credentials in environment variables, the SDK -always uses those credentials, no matter which profile you specify. -{{% /pageinfo %}} - -### Environment 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. - -The SDK looks for credentials in the following environment variables: - -* `AWS_ACCESS_KEY_ID` -* `AWS_SECRET_ACCESS_KEY` -* `AWS_SESSION_TOKEN` (optional) - -The following examples show how you configure the environment variables. - -#### Linux, 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 - -```batch -> set AWS_ACCESS_KEY_ID=YOUR_AKID -> set AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY -> set AWS_SESSION_TOKEN=TOKEN -``` - -### Specify Credentials Programmatically -`config.LoadDefaultConfig` allows you to provide an explicit -[aws.CredentialProvider]({{< apiref "aws#CredentialsProvider" >}}) when loading the shared configuration sources. -To pass an explicit credential provider when loading shared configuration use -[config.WithCredentialsProvider]({{< apiref "config#WithCredentialsProvider" >}}). For example, if `customProvider` -references an instance of `aws.CredentialProvider` implementation, it can be passed during configuration loading -like so: - -```go -cfg, err := config.LoadDefaultConfig(context.TODO(), - config.WithCredentialsProvider(customProvider)) -``` - -If you explicitly provide credentials, as in this example, the SDK uses only those credentials. - -{{% pageinfo color="info" %}} -All credential providers passed to or returned by `LoadDefaultConfig` are wrapped in a -[CredentialsCache]({{< apiref "aws#CredentialsCache" >}}) automatically. This enables caching, and credential rotation that is concurrency safe. If you explicitly configure a provider on `aws.Config` directly you must also explicitly wrap the provider -with this type using [NewCredentialsCache]({{< apiref "aws#NewCredentialsCache" >}}). -{{% /pageinfo %}} - -#### Static Credentials - -You can hard-code credentials in your application by using the [credentials.NewStaticCredentialsProvider]({{< apiref "credentials#NewStaticCredentialsProvider" >}}) -credential provider to explicitly set the access keys to be used. For example: - -```go -cfg, err := config.LoadDefaultConfig(context.TODO(), - config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("AKID", "SECRET_KEY", "TOKEN")), -) -``` - -{{% pageinfo color="warning" %}} -Do not embed credentials inside an application. Use this -method only for testing purposes. -{{% /pageinfo %}} - -#### Single Sign-on Credentials - -The SDK provides a credential provider for retrieving temporary AWS credentials using {{% alias service=SSOlong %}}. -Using the {{% alias service=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 -{{% alias service=SSO %}} account again using the {{% alias service=CLI %}}. - -For example, you can create a profile, `dev-profile`, authenticate and authorize that profile using the -{{% alias service=CLI %}}, and configure your application as shown below. - -1. First 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 - -``` -2. Login using the {{% alias service=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 -``` -3. Next configure your application to use the SSO profile. -```go -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 {{% alias service=CLI %}} see -[Configuring the {{% alias service=CLI %}} to use {{% alias service=SSOlong %}}](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html) -in the {{% alias service=CLI %}} User Guide. For more information on programmatically constructing the -SSO credential provider see the [ssocreds]({{< apiref "credentials/ssocreds" >}}) API reference -documentation. - -#### Other Credentials Providers - -The SDK provides other methods for retrieving credentials in the -[credentials]({{< apiref credentials >}}) module. For example, you can retrieve temporary security credentials from {{% -alias service=STSlong %}} or credentials from encrypted storage. - -**Available Credential Providers**: - -* [ec2rolecreds]({{< apiref "credentials/ec2rolecreds" >}}) – Retrieve Credentials from {{< alias service=EC2 >}} - Instances Roles via {{< alias service=EC2 >}} IMDS. - -* [endpointcreds]({{< apiref "credentials/endpointcreds" >}}) – Retrieve Credentials from an arbitrary HTTP - endpoint. - -* [processcreds]({{< apiref "credentials/processcreds" >}}) – Retrieve Credentials from an external process that - will be invoked by the host environment's shell. - -* [stscreds]({{< apiref "credentials/stscreds" >}}) – Retrieve Credentials from {{% alias service=STS %}} diff --git a/content/en/docs/configuring-sdk/auth.md b/content/en/docs/configuring-sdk/auth.md deleted file mode 100644 index b055fbbae23..00000000000 --- a/content/en/docs/configuring-sdk/auth.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: "Configuring Authentication" -linkTitle: "Authentication" -date: "2023-12-01" -description: Customizing service client authentication. ---- - -The {{% alias sdk-go %}} 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. - -## Definitions - -This section provides a high-level description of authentication components in -the {{% alias sdk-go %}}. - -### `AuthScheme` - -An [AuthScheme]({{< apiref smithy="transport/http#AuthScheme" >}}) is the -interface that defines the workflow through which the SDK retrieves a caller -identity and attaches it to an operation request. - -An auth scheme uses the following components, described in detail further -below: - -* A 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. - -### `AuthSchemeResolver` - -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. - -**IMPORTANT:** 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](#auth-scheme-resolution-workflow). - -### `Option` - -Returned from a call to `ResolverAuthSchemes`, an [Option]({{< apiref -smithy="auth#Option" >}}) represents a possible authentication option. - -An option consists of three sets of information: -* An 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. - -### `Identity` - -An [Identity]({{< apiref smithy="auth#Identity" >}}) is an abstract -representation of who the SDK caller is. - -The 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. - -**Note:** 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. - -### `IdentityResolver` - -[IdentityResolver]({{< apiref smithy="auth#IdentityResolver" >}}) is the -interface through which an `Identity` is retrieved. - -Concrete versions of `IdentityResolver` exist in the SDK in strongly-typed form -(e.g. [aws.CredentialsProvider]({{< apiref "aws#CredentialsProvider" >}})), the -SDK handles this mapping internally. - -A caller will only need to directly implement the `IdentityResolver` interface -when defining an external auth scheme. - -### `Signer` - -[Signer]({{< apiref smithy="transport/http#Signer" >}}) is the interface -through which a request is supplemented with the retrieved caller `Identity`. - -Concrete versions of `Signer` exist in the SDK in strongly-typed form -(e.g. [v4.HTTPSigner]({{< apiref "aws/signer/v4#HTTPSigner" >}})), the SDK -handles this mapping internally. - -A caller will only need to directly implement the `Signer` interface -when defining an external auth scheme. - -### `AuthResolverParameters` - -Each service takes a specific set of inputs which are passed to its resolution -function, defined in each service package as `AuthResolverParameters`. - -The base resolver parameters are as follows: - -| name | 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. - -## Auth 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: - -1. The SDK calls the client's `AuthSchemeResolver.ResolveAuthSchemes()` API, - sourcing the input parameters as necessary, to obtain a list of possible - [Options]({{< apiref smithy="auth#Option" >}}) for the operation. -1. 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) -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. -1. The SDK calls the identity resolver's `GetIdentity()` (e.g. - `aws.CredentialProvider.Retrieve()` for SigV4). -1. 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). -1. 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. - -## Natively-supported `AuthScheme`s - -The following auth schemes are natively supported by {{% alias sdk-go %}}. - -| Name | Scheme ID | Identity resolver | Signer | Notes | -| --- | --------- | ----------------- | ------ | ----- | -| [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) | `aws.auth#sigv4` | [aws.CredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Credentials) | [v4.HTTPSigner](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/signer/v4#Signer) | 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](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#ExpressCredentialsProvider) | v4.HTTPSigner | Used for [Express One Zone](https://aws.amazon.com/s3/storage-classes/express-one-zone/). | -| HTTP Bearer | `smithy.api#httpBearerAuth` | [smithybearer.TokenProvider](https://pkg.go.dev/github.com/aws/smithy-go/auth/bearer#TokenProvider) | [smithybearer.Signer](https://pkg.go.dev/github.com/aws/smithy-go/auth/bearer#Signer) | Used by [codecatalyst]({{< apiref "service/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 {{% alias sdk-go %}}, 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. - -**Note:** 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{}`). - -### Signer configuration - -In {{% alias sdk-go %}}, 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. - -#### Custom auth scheme - -In order to define a custom auth scheme and configure it for use, the caller -must do the following: - -1. Define an [AuthScheme]({{< apiref smithy="transport/http#AuthScheme" >}}) - implementation -1. Register the scheme on the SDK client's `AuthSchemes` list -1. Instrument the SDK client's `AuthSchemeResolver` to return an auth `Option` - with the scheme's ID where applicable - -{{% pageinfo color="warning" %}} -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: - -| Service | 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. | -{{% /pageinfo %}} - diff --git a/content/en/docs/configuring-sdk/custom-http.md b/content/en/docs/configuring-sdk/custom-http.md deleted file mode 100644 index 117e754a999..00000000000 --- a/content/en/docs/configuring-sdk/custom-http.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: "Customizing the HTTP Client" -linkTitle: "HTTP Client" -date: "2020-11-12" -description: "Create a custom HTTP client with the AWS SDK for Go V2 to specify custom timeout values." ---- - -The {{% alias sdk-go %}} 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 {{% alias sdk-go %}} in an environment with high throughput and low latency requirements. For more information, please refer to our [FAQ]({{% ref "faq.md" %}}) as configuration recommendations vary based on specific workloads. -This section describes how to configure a custom HTTP client, and use that client to create {{% alias sdk-go %}} calls. - -To assist you in creating a custom HTTP client, this section describes how to the -[NewBuildableClient]({{< apiref "aws/transport/http#NewBuildableClient" >}}) to configure custom settings, and use -that client with an {{% alias sdk-go %}} service client. - -Let's define what we want to customize. - - -## Overriding During Configuration Loading -Custom HTTP clients can be provided when calling [LoadDefaultConfig]({{< apiref "config#LoadDefaultConfig" >}}) by -wrapping the client using [WithHTTPClient]({{< apiref "config#WithHTTP" >}}) and passing the resulting value to -`LoadDefaultConfig`. For example to pass `customClient` as our client: - -```go -cfg, 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: - -```go -import "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](https://golang.org/pkg/net/#Dialer) options. The following example shows how to configure a clients -`Dialer` settings. - -```go -import 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. - -Set to a negative value to disable keep-alives. - -Set to **0** to enable keep-alives if supported by the protocol and operating system. - -Network protocols or operating systems that do not support keep-alives ignore this field. By default, TCP enables keep -alive. - -See - -Set `KeepAlive` as **time.Duration**. - -#### Dialer.Timeout - -This setting represents the maximum amount of time a dial waits for a connection to be created. - -Default is 30 seconds. - -See - -Set `Timeout` as **time.Duration**. - -## Transport - -The `BuildableHTTPClient` provides a builder mechanics for constructing clients with modified -[Transport](https://golang.org/pkg/net/http#Transport) options. - -### Configuring 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: - -```go -import 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](https://golang.org/pkg/net/http/#Transport) type documentation. -These settings can be applied as shown in the following example: - -```go -import 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. - -Default 1 second. - -Set 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. - -See - -Set `ExpectContinue` as **time.Duration**. - -#### Transport.IdleConnTimeout - -This setting represents the maximum amount of time to keep an idle network connection alive between HTTP requests. - -Set to **0** for no limit. - -See - -Set `IdleConnTimeout` as **time.Duration**. - -#### Transport.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 - -**0** means no limit. - -See - -Set`MaxIdleConns` as **int**. - -#### Transport.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 - -Default is two idle connections per host. - -Set to **0** to use DefaultMaxIdleConnsPerHost (2). - -See - -Set `MaxIdleConnsPerHost` as **int**. - -#### Transport.ResponseHeaderTimeout - -This setting represents the maximum amount of time to wait for a client to read the response header. - -If the client isn't able to read the response's header within this duration, the request fails with a timeout error. - -Be 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. - -Default is no timeout; wait forever. - -See - -Set `ResponseHeaderTimeout` as **time.Duration**. - -#### Transport.TLSHandshakeTimeout - -This setting represents the maximum amount of time waiting for a TLS handshake to be completed. - -Default is 10 seconds. - -Zero means no timeout. - -See - -Set `TLSHandshakeTimeout` as **time.Duration**. diff --git a/content/en/docs/configuring-sdk/endpoints.md b/content/en/docs/configuring-sdk/endpoints.md deleted file mode 100644 index 25cad07cf91..00000000000 --- a/content/en/docs/configuring-sdk/endpoints.md +++ /dev/null @@ -1,481 +0,0 @@ ---- -title: "Configuring Client Endpoints" -linkTitle: "Endpoints" -date: "2020-11-12" -description: Customizing service client endpoints. ---- - -{{% pageinfo color="warning" %}} -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. -{{% /pageinfo %}} - -The {{% alias sdk-go %}} 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. - -## Customization - -There are two "versions" of endpoint resolution config within the SDK. -* v2, 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. - -## V2: `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). - -Resolution 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. - -For 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). - -In practice, `BaseEndpoint` will most likely be used to point your client at a -development or preview instance of a service. - -### `EndpointResolverV2` parameters - -Each service takes a specific set of inputs which are passed to its resolution -function, defined in each service package as `EndpointParameters`. - -Every service includes the following base parameters, which are used to -facilitate general endpoint resolution within AWS: - -| name | 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. - -If 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. - -### A 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. - -Because 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). - -### Examples - -#### 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. - -```go -client := 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`. - -```go -import ( - "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 = &resolverV2{ - // ... - } - }) -} -``` - -#### With both - -The following sample program demonstrates the interaction between -`BaseEndpoint` and `EndpointResolverV2`. **This is an advanced use case:** - -```go -import ( - "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 = &resolverV2{} - }) - - // ignore the output, this is just for demonstration - client.ListBuckets(context.Background(), nil) -} -``` - -When run, the above program outputs the following: - -``` -The endpoint provided in config is https://endpoint.dev/ -``` - - -## V1: `EndpointResolver` - -{{% pageinfo color="warning" %}} -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. - -Use 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. -{{% /pageinfo %}} - -A [EndpointResolver]({{< apiref "aws#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]({{< apiref -"aws#EndpointResolverWithOptionsFunc" >}}) can be used to easily wrap functions -to satisfy the `EndpointResolverWithOptions` interface. - -A `EndpointResolver` can be easily configured by passing the resolver wrapped -with [WithEndpointResolverWithOptions]({{< apiref -"config#WithEndpointResolverWithOptions" >}}) to [LoadDefaultConfig]({{< apiref -"config#LoadDefaultConfig" >}}), allowing for the ability to override endpoints -when loading credentials, as well as configuring the resulting `aws.Config` -with your custom endpoint resolver. - -The 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. - -An endpoint resolver can use the [EndpointNotFoundError]({{< apiref -"aws#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. - -If your endpoint resolver implementation returns an error other than -`EndpointNotFoundError`, endpoint resolution will stop and the service -operation returns an error to your application. - -### Examples - -#### With fallback - -The following code snippet shows how a single service endpoint can be -overridden for {{% alias service=DDB %}} with fallback behavior for other -endpoints: - -```go -customResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) { - if service == dynamodb.ServiceID && 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{}, &aws.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 {{% alias service=DDB %}} without fallback behavior for other -endpoints: - -```go -customResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) { - if service == dynamodb.ServiceID && 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 - -{{% pageinfo color="warning" %}} -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. -{{% /pageinfo %}} - -Some service clients, such as {{% alias service=S3 %}}, may modify the endpoint -returned by the resolver for certain service operations. For example, {{% alias -service=S3 %}} will automatically handle [Virtual Bucket -Addressing](https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html) -by mutating the resolved endpoint. You can prevent the SDK from mutating your -custom endpoints by setting [HostnameImmutable]({{< apiref -"aws#Endpoint.HostnameImmutable" >}}) to `true`. For example: - -```go -customResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) { - if service == dynamodb.ServiceID && 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: -* Returning an [Endpoint]({{< apiref "aws#Endpoint" >}}) with [HostnameImmutable]({{< - apiref "aws#Endpoint.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. - * The primary exception is for operations with modeled endpoint prefixes. A - note on this is given further down. - -Examples for these cases are provided below. - -{{% pageinfo color="warning" %}} -V1 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. -{{% /pageinfo %}} - -### Note on host prefixes - -Some operations are modeled with host prefixes to be prepended to the resolved -endpoint. This behavior must work in tandem with the output of -ResolveEndpointV2 and therefore the host prefix will still be applied to that -result. - -You can manually disable endpoint host prefixing by applying a middleware, see -the examples section. - -### Examples - -#### Mutable endpoint - -The following code sample demonstrates how to migrate a basic v1 endpoint -resolver that returns a modifiable endpoint: - -```go -// 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 -```go -// 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 = &staticResolver{} -}) -``` - -#### Disable host prefix - -```go -import ( - "context" - "fmt" - "net/url" - - "github.com/aws/aws-sdk-go-v2/aws" - "github.com/aws/aws-sdk-go-v2/config" - "github.com/aws/aws-sdk-go-v2/service/" - smithyendpoints "github.com/aws/smithy-go/endpoints" - "github.com/aws/smithy-go/middleware" - smithyhttp "github.com/aws/smithy-go/transport/http" -) - -// disableEndpointPrefix applies the flag that will prevent any -// operation-specific host prefix from being applied -type disableEndpointPrefix struct{} - -func (disableEndpointPrefix) ID() string { return "disableEndpointPrefix" } - -func (disableEndpointPrefix) HandleInitialize( - ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler, -) (middleware.InitializeOutput, middleware.Metadata, error) { - ctx = smithyhttp.SetHostnameImmutable(ctx, true) - return next.HandleInitialize(ctx, in) -} - -func addDisableEndpointPrefix(o *.Options) { - o.APIOptions = append(o.APIOptions, (func(stack *middleware.Stack) error { - return stack.Initialize.Add(disableEndpointPrefix{}, middleware.After) - })) -} - -type staticResolver struct{} - -func (staticResolver) ResolveEndpoint(ctx context.Context, params .EndpointParameters) ( - smithyendpoints.Endpoint, error, -) { - u, err := url.Parse("https://custom.endpoint.api/") - if err != nil { - return smithyendpoints.Endpoint{}, err - } - - return smithyendpoints.Endpoint{URI: *u}, nil -} - - -func main() { - cfg, err := config.LoadDefaultConfig(context.Background()) - if err != nil { - panic(err) - } - - svc := .NewFromConfig(cfg, func(o *.Options) { - o.EndpointResolverV2 = staticResolver{} - }) - - _, err = svc.(context.Background(), &.{ /* ... */ }, - addDisableEndpointPrefix) - if err != nil { - panic(err) - } -} -``` - diff --git a/content/en/docs/configuring-sdk/logging.md b/content/en/docs/configuring-sdk/logging.md deleted file mode 100644 index 00bea95176e..00000000000 --- a/content/en/docs/configuring-sdk/logging.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Logging" -linkTitle: "Logging" -date: "2020-11-12" -description: Using Logging facilities for debugging SDK requests. ---- - -The {{% alias sdk-go %}} has logging facilities available that allow your application to enable debugging information -for debugging and diagnosing request issues or failures. The [Logger]({{< apiref smithy="logging#Logger" >}}) interface -and [ClientLogMode]({{< apiref "aws#ClientLogMode" >}}) are the main components available to you for determining how and -what should be logged by clients. - -## Logger - -When constructing an [Config]({{< apiref "aws#Config" >}}) using -[LoadDefaultConfig]({{< apiref "config#LoadDefaultConfig" >}}) a default `Logger` is configured to send log -messages to the process' standard error (stderr). A custom logger that satisfies the -[Logger]({{< apiref smithy="logging#Logger" >}}) interface can be passed as an argument to `LoadDefaultConfig` -by wrapping it with [config.WithLogger]({{< apiref "config#WithLogger" >}}). - -For example to configure our clients to use our `applicationLogger`: - -```go -cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithLogger(applicationLogger)) -``` - -Now clients configured using the constructed `aws.Config` will send log messages to `applicationLogger`. - -### Context-Aware Loggers - -A Logger implementation may implement the optional [ContextLogger]({{< apiref smithy="logging#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. - -## ClientLogMode - -By default, service clients do not produce log messages. To configure clients to send log messages for debugging -purposes, use the [ClientLogMode]({{< apiref "aws#ClientLogMode" >}}) member on `Config`. `ClientLogMode` -can be set to enable debugging messaging for: - -* Signature Version 4 (SigV4) Signing -* Request Retries -* HTTP Requests -* HTTP Responses - -For example to enable logging of HTTP requests and retries: - -```go -cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithClientLogMode(aws.LogRetries | aws.LogRequest)) -``` - -See [ClientLogMode]({{< apiref "aws#ClientLogMode" >}}) for the different client log modes available. - diff --git a/content/en/docs/configuring-sdk/retries-timeouts.md b/content/en/docs/configuring-sdk/retries-timeouts.md deleted file mode 100644 index 96a4321549c..00000000000 --- a/content/en/docs/configuring-sdk/retries-timeouts.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -title: "Retries and Timeouts" -linkTitle: "Retries and Timeouts" ---- - -The {{% alias sdk-go %}} enables you to configure the retry behavior of requests to HTTP services. By default, -service clients use [retry.Standard]({{< apiref "aws/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. - -The {{% alias sdk-go %}} provides a [aws.Retryer]({{< apiref "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]({{< apiref "aws/retry#Standard" >}}) and [aws.NoOpRetryer]({{< apiref "aws#NoOpRetryer" >}}). - -## Standard Retryer - -The [retry.Standard]({{< apiref "aws/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. - -The following table defines the default values for this retryer: -Property | 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. - -See the [retry]({{< apiref "aws/retry" >}}) package documentation for details on what errors are considered as -retryable by the standard retryer implementation. - -## NopRetryer - -The [aws.NopRetryer]({{< apiref "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. - -## Customizing 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]({{< apiref "aws/retry" >}}) package documentation examples. - -{{% alert color="warning" %}} -If 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. -{{% /alert %}} - -### Limiting the max number of attempts - -You use [retry.AddWithMaxAttempts]({{< apiref "aws/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. - -For example, you can the following code to wrap the standard client retryer with a maximum of five attempts: - -```go -import "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]({{< apiref "aws/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. - -For example, you can the following code to wrap the standard client retryer with a desired max delay of five seconds: - -```go -import "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]({{< apiref "aws/retry#AddWithErrorCodes" >}}) to wrap an `aws.Retryer` -implementation and include additional API error codes that should be considered retryable. - -For example, you can the following code to wrap the standard client retryer to include the {{% alias service="S3" %}} -`NoSuchBucketException` exception as retryable. - -```go -import "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) -``` - -### Client-side rate limiting - -The {{% alias sdk-go %}} introduces a new client-side rate-limiting mechanism -in the standard retry policy to align with the behavior of modern SDKs. This is -behavior is controlled by the [RateLimiter]({{< apiref "aws/retry#RateLimiter" >}}) -field on a retryer's [options]({{< apiref "aws/retry#StandardOptions" >}}). - -A RateLimiter operates as a token bucket with a set capacity, where operation -attempt failures consume tokens. A retry that attempts to consume more tokens -than what's available results in operation failure with a -[QuotaExceededError]({{< apiref "aws/ratelimit#QuotaExceededError" >}}). - -The default implementation is parameterized as follows (how to modify each setting): -- a capacity of 500 (set the value of RateLimiter on StandardOptions using [NewTokenRateLimit]({{< apiref "aws/ratelimit#NewTokenRateLimit" >}})) -- a retry caused by a timeout costs 10 tokens (set RetryTimeoutCost on StandardOptions) -- a retry caused by other errors costs 5 tokens (set RetryCost on StandardOptions) -- an operation that succeeds on the 1st attempt adds 1 token (set NoRetryIncrement on StandardOptions) - - operations that succeed on the 2nd or later attempt do not add back any tokens - -If you find that the default behavior does not fit your application's needs, -you can disable it with [ratelimit.None]({{< apiref "aws/ratelimit#pkg-variables" >}}). - -#### Example: modified rate limiter - -```go -import ( - "context" - - "github.com/aws/aws-sdk-go-v2/aws" - "github.com/aws/aws-sdk-go-v2/aws/ratelimit" - "github.com/aws/aws-sdk-go-v2/aws/retry" - "github.com/aws/aws-sdk-go-v2/config" -) - -// ... - -cfg, err := config.LoadDefaultConfig(context.Background(), config.WithRetryer(func() aws.Retryer { - return retry.NewStandard(func(o *retry.StandardOptions) { - // Makes the rate limiter more permissive in general. These values are - // arbitrary for demonstration and may not suit your specific - // application's needs. - o.RateLimiter = ratelimit.NewTokenRateLimit(1000) - o.RetryCost = 1 - o.RetryTimeoutCost = 3 - o.NoRetryIncrement = 10 - }) -})) -``` - -#### Example: no rate limit using ratelimit.None - -```go -import ( - "context" - - "github.com/aws/aws-sdk-go-v2/aws" - "github.com/aws/aws-sdk-go-v2/aws/ratelimit" - "github.com/aws/aws-sdk-go-v2/aws/retry" - "github.com/aws/aws-sdk-go-v2/config" -) - -// ... - -cfg, err := config.LoadDefaultConfig(context.Background(), config.WithRetryer(func() aws.Retryer { - return retry.NewStandard(func(o *retry.StandardOptions) { - o.RateLimiter = ratelimit.None - }) -})) -``` - -## Timeouts - -You use the [context](https://golang.org/pkg/context/) package to set timeouts or deadlines when invoking a service -client operation. Use the [context.WithDeadline](https://golang.org/pkg/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](https://golang.org/pkg/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. - -### Setting a timeout - -The following example shows how to set a timeout for a service client operation. - -```go -import "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, &s3.GetObjectInput{ - // input parameters -}) -if err != nil { - // handle error -} -``` diff --git a/content/en/docs/faq/_index.md b/content/en/docs/faq/_index.md deleted file mode 100644 index 8d057b49bb7..00000000000 --- a/content/en/docs/faq/_index.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "Frequently Asked Questions" -linkTitle: "FAQ / Troubleshooting" -description: "Answers to some commonly-asked questions about the {{% alias sdk-go %}}" -weight: 9 ---- - -### 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: - -* the 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: - -* All 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. - -### Requests 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: -* Time 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]({{< ref "/docs/faq/timing-operations.md" >}}), -which contains a reusable code snippet that can achieve this. - -### How 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. - -However, 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. - -This 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. - -This can occur for several reasons: -* You 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. - -### Why 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. - -If 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. - diff --git a/content/en/docs/faq/timing-operations.md b/content/en/docs/faq/timing-operations.md deleted file mode 100644 index 5e1d4e2dbb0..00000000000 --- a/content/en/docs/faq/timing-operations.md +++ /dev/null @@ -1,250 +0,0 @@ ---- -title: "Timing SDK operations" -linkTitle: "Timing Operations" -description: "How to perform basic instrumentation in the {{% alias sdk-go %}} to time SDK operations" -weight: 1 ---- - -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. - -The 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: - -* AWS 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. - -The 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. - -The service used here is interchangeable - ALL service client options accept -`APIOptions` and an `HTTPClient` as configuration. For example, -`WithOperationTiming` could instead be declared as: - -```go -func 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. - -```go -import ( - "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 = &timedHTTPClient{ - 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(&timeOperationMiddleware{msgHandler: mh}, middleware.Before); err != nil { - return fmt.Errorf("add time operation middleware: %v", err) - } - if err := s.Initialize.Add(&addInvokeIDMiddleware{msgHandler: mh}, middleware.Before); err != nil { - return fmt.Errorf("add invoke id middleware: %v", err) - } - if err := s.Initialize.Insert(&emitMetadataMiddleware{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 < 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: - -``` -[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 -``` diff --git a/content/en/docs/getting-started.md b/content/en/docs/getting-started.md deleted file mode 100644 index 1a7a53deefd..00000000000 --- a/content/en/docs/getting-started.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: "Getting Started with the AWS SDK for Go V2" -linkTitle: "Getting Started" -date: "2020-11-12" -weight: 2 ---- - -The AWS SDK for Go requires Go {{% alias min-go-version %}} or later. You can view your current version of Go by running the following command: - -``` -go version -``` - -For information about installing or upgrading your version of Go, see https://golang.org/doc/install. - -## Get 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?](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/) -for details. - -## Install 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. - -``` -go 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. - -The following commands show how to retrieve the standard set of SDK modules to use in your application. - -``` -go 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. - -Next 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](https://pkg.go.dev/mod/github.com/aws/aws-sdk-go-v2?tab=packages). 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. - -``` -go 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](https://console.aws.amazon.com/console/home). 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 - -{{% pageinfo color="info" %}} To 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_delegate-permissions.html) -in the IAM User Guide. {{% /pageinfo %}} - -### To get your access key ID and secret access key. - -1. Open the [IAM console](https://console.aws.amazon.com/iam/home) -1. On the navigation menu, choose **Users**. -1. Choose your IAM user name (not the check box). -1. Open the **Security credentials** tab, and then choose **Create access key**. -1. To see the new access key, choose **Show**. Your credentials resemble the following: - * Access key ID: `AKIAIOSFODNN7EXAMPLE` - * Secret access key: `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` -1. To download the key pair, choose **Download .csv file**. Store the keys in a secure location. - -{{% pageinfo color="warning" %}} 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. {{% /pageinfo %}} - -### Related topics - -* [What Is IAM?](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) - in IAM User Guide. -* [AWS Security Credentials](https://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html) - 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. - -```go -package 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(), &s3.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) - } -} -``` diff --git a/content/en/docs/handling-errors.md b/content/en/docs/handling-errors.md deleted file mode 100644 index ed2a9def84e..00000000000 --- a/content/en/docs/handling-errors.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: "Handling Errors in the AWS SDK for Go V2" -linkTitle: "Handling Errors" -date: "2020-11-12" -description: "Use the Error interface to handle errors from the AWS SDK for Go V2 or AWS service." -weight: 6 ---- - -The {{% alias sdk-go %}} 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](https://golang.org/pkg/errors#As) to handle unwrapping error chains. - -It 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: - -```go -if 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: - -```go -import "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]({{% apiref 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. - -For example: - -```go -import "log" -import "github.com/aws/smithy-go" - -// ... - -if err != nil { - var oe *smithy.OperationError - if errors.As(err, &oe) { - 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 -{{% alias service=S3 %}} `CreateBucket` can return a -[BucketAlreadyExists]({{< apiref "service/s3/types#BucketAlreadyExists" >}}) error if a bucket of the same name -already exists. - -For example, to check if an error was a `BucketAlreadyExists` error: - -```go -import "log" -import "github.com/aws/aws-sdk-go-v2/service/s3/types" - -// ... - -if err != nil { - var bne *types.BucketAlreadyExists - if errors.As(err, &bne) { - log.Println("error:", bne) - } - return -} -``` - -All service API response errors implement the [smithy.APIError]({{< apiref 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: - -```go -import "log" -import "github.com/aws/smithy-go" - -// ... - -if err != nil { - var ae smithy.APIError - if errors.As(err, &ae) { - 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]({{< apiref "aws/transport/http#ResponseError" >}}) -and use the `ServiceRequestID()` method to retrieve the request identifier associated with error response. - -For example: - -```go -import "log" -import awshttp "github.com/aws/aws-sdk-go-v2/aws/transport/http" - -// ... - -if err != nil { - var re *awshttp.ResponseError - if errors.As(err, &re) { - log.Printf("requestID: %s, error: %v", re.ServiceRequestID(), re.Unwrap()); - } - return -} -``` - -### {{% alias service=S3 %}} Request Identifiers - -{{% alias service=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. - -For example: - -```go -import "log" -import "github.com/aws/aws-sdk-go-v2/service/s3" - -// ... - -if err != nil { - var re s3.ResponseError - if errors.As(err, &re) { - log.Printf("requestID: %s, hostID: %s request failure", re.ServiceRequestID(), re.ServiceHostID()); - } - return -} -``` - diff --git a/content/en/docs/making-requests.md b/content/en/docs/making-requests.md deleted file mode 100644 index 93fe1245f91..00000000000 --- a/content/en/docs/making-requests.md +++ /dev/null @@ -1,615 +0,0 @@ ---- -title: "Using the AWS SDK for Go V2 with AWS Services" -linkTitle: "Using AWS Services" -date: "2020-11-12" -description: "Construct service clients and make operation calls to send requests to AWS services." -weight: 5 ---- - -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 {{% alias service=S3 %}} -service client to make calls to {{% alias service=S3 %}} APIs. - -When 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 {{% alias service=S3 %}} -create bucket action, the action returns an output struct with the bucket's location. - -For the list of service clients, including their methods and parameters, see the [{{% alias sdk-api %}}]({{< apiref "#" >}}) - -## Constructing 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. - -### NewFromConfig - -`NewFromConfig` function provides a consistent interface for constructing service clients using the -[aws.Config]({{< apiref "aws#Config" >}}). An `aws.Config` can be loaded using the -[config.LoadDefaultConfig]({{< apiref "config#LoadDefaultConfig" >}}). For more information on constructing -an `aws.Config` see [Configure the SDK]({{% ref "configuring-sdk" %}}). The following example shows how to construct -an {{% alias service=S3 %}} service client using the `aws.Config`and the `NewFromConfig` function: - -```go -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 { - 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 -{{% alias service=S3 %}} `UseAccelerate` option. For example: - -```go -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 { - 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`. - -### New - -{{% pageinfo color="info" %}} -`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. -{{% /pageinfo %}} - -`New` 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 {{% alias service=S3 %}} -client using `New`: - -```go -import "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 {{% alias service=S3 %}} `UseAccelerate` option. For example: - -```go -import "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`. - -## Calling Service Operations - -After you have a service client instance, you can use it to call a service's operations. For example to call the -{{% alias service=S3 %}} `GetObject` operation: - -```go -response, err := client.GetObject(context.TODO(), &s3.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. - -### Passing Parameters to a Service Operation - -Each service operation method takes a [context.Context](https://golang.org/pkg/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 -`Input` struct found in the service's respective Go package. You pass in API input parameters using -the operation input struct. - -Operation 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. - -In 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 `` and `From` convenience functions available -in the [aws]({{< apiref aws >}}) to ease this conversion. For example [aws.String]({{% apiref "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]({{% apiref "aws#ToString" %}}) can be used to transform a `*string` to a `string` while providing -protection from dereferencing a nil pointer. The `To` functions are helpful when handling service responses. - -Let's look at an example of how we can use an {{% alias service=S3 %}} client to call the `GetObject` API, and construct -our input using the `types` package, and `aws.` helpers. - -```go -import "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(), &s3.GetObjectInput{ - Bucket: aws.String("my-bucket"), - Key: aws.String("keyName"), - RequestPayer: types.RequestPayerRequester, -}) -``` - -### Overriding Client Options For Operation Call {#OverrideClientOptionsForOperation} - -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. - -For example to override the client region from "us-west-2" to "us-east-1": - -```go -cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion("us-west-2")) -if err != nil { - log.Printf("error: %v", err) - return -} - -client := s3.NewFromConfig(cfg) - -params := &s3.GetObjectInput{ - // ... -} - -resp, err := client.GetObject(context.TODO(), params, func(o *Options) { - o.Region = "us-east-1" -}) -``` - -### Handling Operation Responses {#HandlingOperationResponses} - -Each service operation has an associated output struct that contains the service's operation response members. -The output struct follows the following naming pattern `Output`. 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. - -For example to log an operation error and prematurely return from the calling function: -```go -response, 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]({{% ref "handling-errors.md" %}}) documentation. - -#### Responses 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. - -For example, {{% alias service=S3 %}} `GetObject` operation returns a response -whose `Body` member is an `io.ReadCloser` for accessing the object payload. - -{{% pageinfo color="warning" %}} -**You 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.** -{{% /pageinfo %}} - -```go -resp, err := s3svc.GetObject(context.TODO(), &s3.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(&myStruct); err != nil { - // handle error - return -} -``` - -#### Response Metadata - -All service operation output structs include a `ResultMetadata` member of type -[middleware.Metadata]({{< apiref smithy="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: - -```go -import "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(), &s3.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. - -In the following example, an {{% alias=service=S3 %}} service client is used in multiple goroutines. This example -concurrently uploads two objects to an {{% alias service=S3 %}} bucket. - -```go -import "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(), &s3.PutObjectInput{ - Bucket: aws.String("my-bucket"), - Key: aws.String("foo"), - Body: strings.NewReader("foo body content"), - }) - results <- result{Output: output, Err: err} -}() - -go func() { - defer wg.Done() - output, err := client.PutObject(context.TODO(), &s3.PutObjectInput{ - Bucket: aws.String("my-bucket"), - Key: aws.String("bar"), - Body: strings.NewReader("bar body content"), - }) - results <- 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 {id="using-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. - -Paginator 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 `NewPaginator` function. Paginator construct -functions take the service `Client`, the operation's `Input` input parameters, and an optional set of -functional arguments allowing you to configure other optional paginator settings. - -The 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]({{% ref "#HandlingOperationResponses" %}}) - -The following example uses the `ListObjectsV2` paginator to list up to three pages of object keys from the -`ListObjectV2`operation. Each page consists of up to 10 keys, which is defined by the `Limit` paginator option. - -```go -import "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 := &s3.ListObjectsV2Input{ - Bucket: aws.String("my-bucket"), -} - -paginator := s3.NewListObjectsV2Paginator(client, params, func(o *s3.ListObjectsV2PaginatorOptions) { - o.Limit = 10 -}) - -pageNum := 0 -for paginator.HasMorePages() && pageNum < 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]({{% ref "#OverrideClientOptionsForOperation" %}}) - - -## Using 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. - -For example, the {{% alias service=DDBlong %}} `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`. - -Writing 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. - -For example, you can use waiters to poll if a {{% alias service=DDB %}} table -is created and ready for a write operation. - -```go -import "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 := &dynamodb.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. - -For example, to override waiter configuration during waiter construction - -```go -import "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. -Similar to the above example, you can override waiter configuration per `Wait` request. - -```go -// params is the input to api operation used by the waiter -params := &dynamodb.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](https://aws.github.io/aws-sdk-go-v2/docs/middleware/#writing-a-custom-middleware). - -For example, to configure advanced waiter overrides. - -```go -import "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 - } - } -} - -// 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 -}) - -``` diff --git a/content/en/docs/middleware.md b/content/en/docs/middleware.md deleted file mode 100644 index f4762df4007..00000000000 --- a/content/en/docs/middleware.md +++ /dev/null @@ -1,289 +0,0 @@ ---- -title: "Customizing the AWS SDK for Go V2 Client Requests" -linkTitle: "Middleware" -description: "How to use stack step middleware to customize AWS SDK for Go V2 client requests." -weight: 8 ---- - -{{% pageinfo color="warning" %}} -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. -{{% /pageinfo %}} - -You can customize {{% alias sdk-go %}} client requests by registering one or more middleware to a service operation's -[stack]({{< apiref smithy="middleware#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. - -![Middleware](/aws-sdk-go-v2/diagrams/middleware.png) - -Stack 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. - -You 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]({{< apiref smithy="middleware#Before" >}}) as the -[RelativePosition]({{< apiref smithy="middleware#RelativePosition" >}}), and -[middleware.After]({{< apiref smithy="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. - -{{% pageinfo color="warning" %}} -You 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. -{{% /pageinfo %}} - -## Writing 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 `MiddlewareFunc` 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. - -Step | Interface | Helper Function ---- | --- | --- -Initialize | [InitializeMiddleware]({{< apiref smithy="middleware#InitializeMiddleware" >}}) | [InitializeMiddlewareFunc]({{< apiref smithy="middleware#InitializeMiddlewareFunc" >}}) -Build | [BuildMiddleware]({{< apiref smithy="middleware#BuildMiddleware" >}}) | [BuildMiddlewareFunc]({{< apiref smithy="middleware#BuildMiddlewareFunc" >}}) -Serialize | [SerializeMiddleware]({{< apiref smithy="middleware#SerializeMiddleware" >}}) | [SerializeMiddlewareFunc]({{< apiref smithy="middleware#SerializeMiddlewareFunc" >}}) -Finalize | [FinalizeMiddleware]({{< apiref smithy="middleware#FinalizeMiddleware" >}}) | [FinalizeMiddlewareFunc]({{< apiref smithy="middleware#FinalizeMiddlewareFunc" >}}) -Deserialize | [DeserializeMiddleware]({{< apiref smithy="middleware#DeserializeMiddleware" >}}) | [DeserializeMiddlewareFunc]({{< apiref smithy="middleware#DeserializeMiddlewareFunc" >}}) - -The following examples show how you can write a custom middleware to populate the Bucket member of the -{{% alias service=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. - -```go -import "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]({{< apiref "aws#Config" >}}) type. The following examples attaches the `defaultBucket` middleware to every -client constructed using your applications `aws.Config` object: - -```go -import "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 {{% alias service=S3 %}} `GetObject` operation invocation: - -```go -import "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(), &s3.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](https://golang.org/pkg/context/#Context) to pass this metadata by using -[middleware.WithStackValue]({{< apiref smithy="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]({{< apiref smithy="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. - -```go -import "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 {{% alias sdk-go %}} 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: - -Key | Retriever | Description ---- | --- | --- -ServiceID | [GetServiceID]({{< apiref "aws/middleware#GetServiceID" >}}) | Retrieve the service identifier for the executing stack. This can be compared to the service client package's `ServiceID` constant. -OperationName | [GetOperationName]({{< apiref "aws/middleware#GetOperationName" >}}) | Retrieve the operation name for the executing stack. -Logger | [GetLogger]({{< apiref smithy="middleware#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]({{< apiref smithy="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. - -The following examples shows how a custom middleware can add metadata that is returned as part of the operation output. - -```go -import "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(&metadata, "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(), &s3.GetObjectInput{ - // input parameters -}) -if err != nil { - // handle error -} - -customValue := GetCustomKey(out.ResponseMetadata) - -``` diff --git a/content/en/docs/migrating/_index.md b/content/en/docs/migrating/_index.md deleted file mode 100644 index 29a5aa93c58..00000000000 --- a/content/en/docs/migrating/_index.md +++ /dev/null @@ -1,1514 +0,0 @@ ---- -title: "Migrating to the AWS SDK for Go V2" -linkTitle: "Migrating" -description: "How to migrate to the AWS SDK for Go V2 from AWS SDK for Go V1." -weight: 4 ---- - -## Minimum Go Version - -The {{% alias sdk-go %}} requires a minimum Go version of {{% alias min-go-version %}}. Migration from v1 to v2 The latest version of Go can be downloaded on -the [Downloads](https://golang.org/dl/) page. See the [Release History](https://golang.org/doc/devel/release.html) for -more information about each Go version release, and relevant information required for upgrading. - -## Modularization - -The {{% alias sdk-go %}} 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. - -The following list are some Go modules provided by the SDK: -Module | 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` | {{% alias service=EC2 %}} Instance Metadata Service Client - -The SDK's service clients and higher level utilities modules are nested under the following import paths: -Import 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 {{% alias service=S3 %}} Transfer Manager - -## Configuration Loading - -The [session]({{< apiref v1="aws/session" >}}) package and associated functionality are replaced with a simplified -configuration system provided by the [config]({{< apiref "config" >}}) package. The `config` package is a separate Go -module, and can be included in your applications dependencies by with `go get`. -```sh -go get github.com/aws/aws-sdk-go-v2/config -``` - -The [session.New]({{< apiref v1="aws/session#New" >}}), [session.NewSession]({{< apiref v1="aws/session#NewSession" >}}), -[NewSessionWithOptions]({{< apiref v1="aws/session#NewSessionWithOptions" >}}), and -[session.Must]({{< apiref v1="aws/session#Must" >}}) must be migrated to -[config.LoadDefaultConfig]({{< apiref "config#LoadDefaultConfig" >}}). - -The `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. - -For more information on loading shared configuration -see [Configuring the {{% alias sdk-go %}}]({{% ref "configuring-sdk" %}}). - -#### Examples -##### Migrating from NewSession to LoadDefaultConfig -The following example shows how usage of `session.NewSession` without additional argument parameters is migrated to -`config.LoadDefaultConfig`. - -```go -// V1 using NewSession - -import "github.com/aws/aws-sdk-go/aws/session" - -// ... - -sess, err := session.NewSession() -if err != nil { - // handle error -} -``` - -```go -// 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]({{< apiref "config#WithRegion" >}}) helper function. - -```go -// 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 -} -``` - -```go -// 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. - -```go -// 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 -} -``` - -```go -// 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]({{< apiref v1="service/s3/s3iface#S3API" >}})) -have been removed. These interface definitions are not stable since they are -broken every time a service adds a new operation. - -Usage of `*iface` should be replaced by scoped caller-defined interfaces for -the service operations being used: - -```go -// 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(&s3.GetObjectInput{ - Bucket: &bucket, - Key: &key, - }) - if err != nil { - return nil, err - } - defer object.Body.Close() - - return io.ReadAll(object.Body) -} -``` - -```go -// 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 := client.GetObject(ctx, &s3.GetObjectInput{ - Bucket: &bucket, - Key: &key, - }) - if err != nil { - return nil, err - } - defer object.Body.Close() - - return io.ReadAll(object.Body) -} -``` - -See the [testing guide]({{% ref "/docs/unit-testing.md" %}}) for more -information. - -## Credentials & Credential Providers - -The [aws/credentials]({{< apiref v1="aws/credentials" >}}) package and associated credential providers have been -relocated to the [credentials]({{< apiref "credentials" >}}) package location. The `credentials` package is a Go module that -you retrieve by using `go get`. - -```sh -go get github.com/aws/aws-sdk-go-v2/credentials -``` - -The {{% alias sdk-go %}} release updates the AWS Credential Providers to provide a consistent interface for retrieving -AWS Credentials. Each provider implements the [aws.CredentialsProvider]({{< apiref "aws#CredentialsProvider" >}}) -interface, which defines a `Retrieve` method that returns a `(aws.Credentials, error)`. -[aws.Credentials]({{< apiref "aws#Credentials" >}}) that is analogous to the AWS SDK for Go -[credentials.Value]({{< apiref v1="aws/credentials#Value" >}}) type. - -You must wrap `aws.CredentialsProvider` objects with [aws.CredentialsCache]({{< apiref "aws#CredentialsCache" >}}) to -allow credential caching to occur. You use [NewCredentialsCache]({{< apiref "aws#NewCredentialsCache" >}}) to -construct a `aws.CredentialsCache` object. By default, credentials configured by `config.LoadDefaultConfig` are wrapped -with `aws.CredentialsCache`. - -The following table list the location changes of the AWS credential providers from AWS SDK for Go V1 to -{{% alias sdk-go %}}. - -Name | V1 Import | V2 Import ---- | --- | --- -{{% alias service=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` -{{% alias service=STSlong %}} | `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]({{< apiref v1="aws/credentials#NewStaticCredentials" >}}) to -construct static credential programmatically must use -[credentials.NewStaticCredentialsProvider]({{< apiref "credentials#NewStaticCredentialsProvider" >}}). - -#### Example - - -```go -// 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 -} -``` - -```go -// 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 -} -``` - -### {{% alias service=EC2 %}} IAM Role Credentials - -You must migrate usage of [NewCredentials]({{< apiref v1="aws/credentials/ec2rolecreds#NewCredentials" >}}) and -[NewCredentialsWithClient]({{< apiref v1="aws/credentials/ec2rolecreds#NewCredentialsWithClient" >}}) to use -[New]({{< apiref "credentials/ec2rolecreds#New" >}}). - -The `ec2rolecreds` package's `ec2rolecreds.New` takes functional options of -[ec2rolecreds.Options]({{< apiref "credentials/ec2rolecreds#Options" >}}) as -input, allowing you override the specific {{% alias service=EC2 %}} Instance -Metadata Service client to use, or to override the credential expiry window. - -#### Example - -```go -// V1 - -import "github.com/aws/aws-sdk-go/aws/credentials/ec2rolecreds" - -// ... - -appCreds := ec2rolecreds.NewCredentials(sess) -value, err := appCreds.Get() -if err != nil { - // handle error -} -``` - -```go -// 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]({{< apiref v1="aws/credentials/endpointcreds#NewCredentialsClient" >}}) -and [NewProviderClient]({{< apiref v1="aws/credentials/endpointcreds#NewProviderClient" >}}) to use -[New]({{< apiref "credentials/endpointcreds#New" >}}). - -The `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]({{< apiref -"credentials/endpointcreds#Options" >}}) to mutate the credentials provider and -override specific configuration settings. - -### Process Credentials - -You must migrate usage of [NewCredentials]({{< apiref v1="aws/credentials/processcreds#NewCredentials" >}}), -[NewCredentialsCommand]({{< apiref v1="aws/credentials/processcreds#NewCredentialsCommand" >}}), and -[NewCredentialsTimeout]({{< apiref v1="aws/credentials/processcreds#NewCredentialsTimeout" >}}) to use -[NewProvider]({{< apiref "credentials/processcreds#New" >}}) or -[NewProviderCommand]({{< apiref "credentials/processcreds#NewProviderCommand" >}}). - -The `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]({{< apiref "credentials/processcreds#Options" >}}) to mutate the -credentials provider and override specific configuration settings. - -`NewProviderCommand` takes an implementation of the -[NewCommandBuilder]({{< apiref "credentials/processcreds#NewCommandBuilder" >}}) interface that defines -more complex process commands that might take one or more command-line arguments, or have certain execution environment -requirements. [DefaultNewCommandBuilder]({{< apiref "credentials/processcreds#DefaultNewCommandBuilder" >}}) implements -this interface, and defines a command builder for a process that requires multiple command-line arguments. - -#### Example - - -```go -// 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 -} -``` - - -```go -// 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 -} -``` - -### {{% alias service=STSlong %}} Credentials - -#### AssumeRole - -You must migrate usage of [NewCredentials]({{< apiref v1="aws/credentials/stscreds#NewCredentials" >}}), and -[NewCredentialsWithClient]({{< apiref v1="aws/credentials/stscreds#NewCredentialsWithClient" >}}) to -use [NewAssumeRoleProvider]({{< apiref "credentials/stscreds#NewAssumeRoleProvider" >}}). - -The `stscreds` package's `NewAssumeRoleProvider` function must be called with -a [sts.Client]({{< apiref "service/sts#Client" >}}), and the {{% alias -service=IAMlong %}} Role ARN to be assumed from the provided `sts.Client`'s -configured credentials. You can also provide a set of functional options of -[AssumeRoleOptions]({{< apiref "credentials/stscreds#AssumeRoleOptions" >}}) to -modify other optional settings of the provider. - -##### Example - - -```go -// 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 -} -``` - - -```go -// 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]({{< apiref v1="aws/credentials/stscreds#NewWebIdentityCredentials" >}}), -[NewWebIdentityRoleProvider]({{< apiref v1="aws/credentials/stscreds#NewWebIdentityRoleProvider" >}}), and -[NewWebIdentityRoleProviderWithToken]({{< apiref v1="aws/credentials/stscreds#NewWebIdentityRoleProviderWithToken" >}}) -to use [NewWebIdentityRoleProvider]({{< apiref "credentials/stscreds#NewWebIdentityRoleProvider" >}}). - -The `stscreds` package's `NewWebIdentityRoleProvider` function must be called with a [sts.Client]({{< apiref "service/sts#Client" >}}), and the -{{% alias service=IAMlong %}} Role ARN to be assumed using the provided `sts.Client`'s configured credentials, and an -implementation of a [IdentityTokenRetriever]({{< apiref "credentials/stscreds#IdentityTokenRetriever" >}}) for -providing the OAuth 2.0 or OpenID Connect ID token. -[IdentityTokenFile]({{< apiref "credentials/stscreds#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]({{< apiref "credentials/stscreds#WebIdentityRoleOptions" >}}) to modify other optional -settings for the provider. - -##### Example - - -```go -// 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 -} -``` - - -```go -// 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 - -{{% alias sdk-go %}} 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 {{% alias sdk-go %}}. - -Service Name | V1 Import Path | V2 Import Path ---- | --- | --- -{{% alias service=S3 %}} | `github.com/aws/aws-sdk-go/service/s3` | `github.com/aws/aws-sdk-go-v2/service/s3` -{{% alias service=DDBlong %}} | `github.com/aws/aws-sdk-go/service/dynamodb` | `github.com/aws/aws-sdk-go-v2/service/dynamodb` -{{% alias service=CWLlong %}} | `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 {{% alias service=S3 %}} -client to your dependencies use - -```sh -go get github.com/aws/aws-sdk-go-v2/service/s3 -``` - -### Client Construction - -You can construct clients in the {{% alias sdk-go %}} 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]({{% ref "making-requests" %}}). - -##### Example 1 - - -```go -// 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) -``` - - -```go -// 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 - - -```go -// 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, &aws.Config{ - Region: aws.String("us-west-2"), -}) -``` - - -```go -// 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]({{< apiref v1="aws/endpoints" >}}) package no longer exists in the {{% alias sdk-go %}}. 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. - -Additionally, 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. - -By 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]({{< apiref v1="aws/endpoints#Resolver" >}}) you must -migrate it to conform to this new per-service interface. - -For more information on endpoints and implementing a custom resolver, see -[Configuring Client Endpoints]({{% ref "/docs/configuring-sdk/endpoints.md" %}}). - -### Authentication - -The {{% alias sdk-go %}} 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. - -### Invoking API Operations - -The number of service client operation methods have been reduced significantly. The `Request`, -`WithContext`, and `` methods have all been consolidated into single operation method, ``. - -#### Example - -The following example shows how calls to the {{% alias service=s3 %}} PutObject operation would be migrated from -AWS SDK for Go to {{% alias sdk-go %}}. - -```go -// V1 - -import "context" -import "github.com/aws/aws-sdk-go/service/s3" - -// ... - -client := s3.New(sess) - -// Pattern 1 -output, err := client.PutObject(&s3.PutObjectInput{ - // input parameters -}) - -// Pattern 2 -output, err := client.PutObjectWithContext(context.TODO(), &s3.PutObjectInput{ - // input parameters -}) - -// Pattern 3 -req, output := client.PutObjectRequest(context.TODO(), &s3.PutObjectInput{ - // input parameters -}) -err := req.Send() -``` - - -```go -// V2 - -import "context" -import "github.com/aws/aws-sdk-go-v2/service/s3" - -// ... - -client := s3.NewFromConfig(cfg) - -output, err := client.PutObject(context.TODO(), &s3.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 `Input` and `Output`, where `OperationName` -is the name of the operation you are invoking. For example the input and output shape for the -{{% alias service=S3 %}} PutObject operation are [PutObjectInput]({{< apiref "service/s3#PutObjectInput" >}}) and -[PutObjectOutput]({{< apiref "service/s3#PutObjectOutput" >}}) respectively. - -All 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]({{< apiref v1="service/s3#AccessControlPolicy" >}}) type is now located at -[types.AccessControlPolicy]({{< apiref "service/s3/types#AccessControlPolicy" >}}). - -#### Enumeration 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 {{% alias service=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 -{{& alias sdk-go %}} this parameter is now a -[types.ObjectCannedACL]({{< apiref "service/s3/types#ObjectCannedACL" >}}). The `types` package -provides generated constants for the valid enumeration values that can be assigned to this field. For example -[types.ObjectCannedACLPrivate]({{< apiref "service/s3/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. - -### Pointer Parameters - -The AWS SDK for Go v1 required pointer references to be passed for all input parameters to service operations. The -{{% alias sdk-go %}} 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. - -The [aws]({{< apiref "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]({{< apiref "aws#String" >}}) function converts from `string` ⇒ `*string`. Inversely, -the [aws.ToString]({{< apiref "aws#ToString" >}}) converts from `*string` ⇒ `string`. When upgrading your -application from AWS SDK for Go V1 to {{% alias sdk-go %}}, you must migrate usage of the helpers for -converting from the pointer types to the non-pointer variants. For example, -[aws.StringValue]({{< apiref v1="aws#StringValue" >}}) must be updated to `aws.ToString`. - -### Errors Types - -The {{% alias sdk-go %}} takes full advantage of the error wrapping functionality -[introduced in Go 1.13](https://blog.golang.org/go1.13-errors). 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 {{% alias service=S3 %}} `GetObject` operation can return a `NoSuchKey` error if -attempting to retrieve an object key that doesn't exist. You can use [errors.As](https://golang.org/pkg/errors#As) to -test whether the returned operation error is a [types.NoSuchKey]({{< apiref "service/s3/types#NoSuchKey" >}}) error. -In the event a service does not model a specific type for an error, you can utilize the -[smithy.APIError]({{< apiref smithy="#APIError" >}}) interface type for inspecting the returned error code and message -from the service. This functionality replaces [awserr.Error]({{< apiref v1="aws/awserr#Error" >}}) and the other -[awserr]({{< apiref v1="aws/awserr" >}}) functionality from the AWS SDK for Go V1. For more details information on -handling errors see [Handling Errors]({{< ref "handling-errors" >}}). - -#### Example - - -```go -// 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(&s3.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 -} -``` - - -```go -// 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(), &s3.GetObjectInput{ - // input parameters -}) -if err != nil { - var nsk *types.NoSuchKey - if errors.As(err, &nsk) { - // handle NoSuchKey error - return - } - var apiErr smithy.APIError - if errors.As(err, &apiErr) { - 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 {{% alias service=S3 %}} `ListObjectsV2` operation you must construct its paginator using the -[s3.NewListObjectsV2Paginator]({{< apiref "service/s3#NewListObjectsV2Paginator" >}}). This constructor returns a -[ListObjectsV2Paginator]({{< apiref "service/s3#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 -[]({{< ref "making-requests.md#using-paginators" >}}). - -Let's look at an example of how to migrate from a AWS SDK for Go paginator to the {{% alias sdk-go %}} equivalent. - -#### Example - - -```go -// V1 - -import "fmt" -import "github.com/aws/aws-sdk-go/service/s3" - -// ... - -client := s3.New(sess) - -params := &s3.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) -``` - - -```go -// V2 - -import "context" -import "fmt" -import "github.com/aws/aws-sdk-go-v2/service/s3" - -// ... - -client := s3.NewFromConfig(cfg) - -params := &s3.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 {{% alias service=S3 %}} Bucket to exist, you must construct a `BucketExists` waiter. Use the -[s3.NewBucketExistsWaiter]({{< apiref "service/s3#NewBucketExistsWaiter" >}}) constructor to create a -[s3.BucketExistsWaiter]({{< apiref "service/s3#BucketExistsWaiter" >}}). The `s3.BucketExistsWaiter` provides a -`Wait` method which can be used to wait for a bucket to become available. - -### Presigned 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). - -{{% alias sdk-go %}} resolves this by exposing specific `PresignClient` -implementations in service packages with specific APIs for supported -presignable operations. - -**Note: 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](https://github.com/aws/aws-sdk-go-v2/issues).** - -Uses of [Presign]({{< apiref v1="aws/request#Request.Presign" >}}) and -[PresignRequest]({{< apiref v1="aws/request#Request.PresignRequest" >}}) must -be converted to use service-specific presigning clients. - -The following example shows how to migrate presigning of an S3 GetObject -request: - -```go -// 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(&s3.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) -} -``` - -```go -// 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(), &s3.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]({{< apiref v1="aws/request#Request" >}}) API -has been re-compartmentalized. - -### Operation 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: - -Request handlers which reference `Request.Params` and `Request.Data` must be migrated to middleware. - -#### migrating `Params` - -```go -// 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)) - - // ... -} -``` - -```go -// 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(&withPutObjectDefaultACL{acl: acl}, middleware.After) - }) - } -} - -func main() { - cfg, err := config.LoadDefaultConfig(context.Background()) - if err != nil { - // ... - } - - svc := s3.NewFromConfig(cfg, WithPutObjectDefaultACL(types.ObjectCannedACLBucketOwnerFullControl)) - // ... -} -``` - -#### migrating `Data` - -```go -// 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) - // ... -} -``` - -```go -// 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(&withReadPutObjectOutput{}, 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. - -Request handlers which reference `Request.HTTPRequest` and -`Request.HTTPResponse` must be migrated to middleware. - -#### migrating `HTTPRequest` - -```go -// 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) - // ... -} -``` - -```go -// 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(&withHeader{ - 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. - -The following table provides a rough mapping of v1 handler phases to their -equivalent location within the V2 middleware stack: - -| v1 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. - -(2) Any middleware after the `"Retry"` middleware in the Finalize step will be -part of the retry loop. - -(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. - -For 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: - -```go -// 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 - -### {{% alias service=EC2 %}} Instance Metadata Service - -The {{% alias sdk-go %}} provides an {{% alias service=EC2 %}} Instance Metadata Service (IMDS) client that you can use -to query the local IMDS when executing your application on an {{% alias service=EC2 %}} instance. The IMDS client is -a separate Go module that can be added to your application by using - -```sh -go 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. - -#### Example - - -```go -// V1 - -import "github.com/aws/aws-sdk-go/aws/ec2metadata" - -// ... - -client := ec2metadata.New(sess) - -region, err := client.Region() -if err != nil { - // handle error -} -``` - -```go -// 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 -} -``` - -### {{% alias service=S3 %}} Transfer Manager - -The {{% alias service=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`. - -[s3.NewUploader]({{< apiref v1="service/s3/s3manager#NewUploader" >}}) and -[s3.NewUploaderWithClient]({{< apiref v1="service/s3/s3manager#NewUploaderWithClient" >}}) have been replaced with the -constructor method [manager.NewUploader]({{< apiref "feature/s3/manager#" >}}) for creating an Upload manager client. - -[s3.NewDownloader]({{< apiref v1="service/s3/s3manager#NewDownloader" >}}) and -[s3.NewDownloaderWithClient]({{< apiref v1="service/s3/s3manager#NewDownloaderWithClient" >}}) have been replaced with a -single constructor method [manager.NewDownloader]({{< apiref "feature/s3/manager#NewDownloader" >}}) for creating a -Download manager client. - -### {{% alias service=CFlong %}} Signing Utilities - -The {{% alias sdk-go %}} provides {{% alias service=CFlong %}} signing utilities in a Go module outside the service -client import path. This module can be retrieved by using `go get`. - -```sh -go get github.com/aws/aws-sdk-go-v2/feature/cloudfront/sign -``` - -### {{% alias service=S3 %}} Encryption Client - -Starting in {{% alias sdk-go %}}, 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`: - -```sh -go get github.com/aws/amazon-s3-encryption-client-go/v3 -``` - -The separate `EncryptionClient` -([v1]({{< apiref v1="service/s3/s3crypto#EncryptionClient" >}}), [v2]({{< apiref v1="service/s3/s3crypto#EncryptionClientV2" >}})) -and `DecryptionClient` -([v1]({{< apiref v1="service/s3/s3crypto#DecryptionClient" >}}), [v2]({{< apiref v1="service/s3/s3crypto#DecryptionClientV2" >}})) -APIs have been replaced with a single client, -[S3EncryptionClientV3](https://pkg.go.dev/github.com/aws/amazon-s3-encryption-client-go/v3/client#S3EncryptionClientV3), -that exposes both encrypt and decrypt functionality. - -Like other service clients in {{% alias sdk-go %}}, the operation APIs have -been condensed: - -* The `GetObject`, `GetObjectRequest`, and `GetObjectWithContext` decryption - APIs are replaced by - [GetObject](https://pkg.go.dev/github.com/aws/amazon-s3-encryption-client-go/v3/client#S3EncryptionClientV3.GetObject). -* The `PutObject`, `PutObjectRequest`, and `PutObjectWithContext` encryption - APIs are replaced by - [PutObject](https://pkg.go.dev/github.com/aws/amazon-s3-encryption-client-go/v3/client#S3EncryptionClientV3.PutObject). - -To learn how to migrate to the 3.x major version of the encryption client, see -[this guide](https://docs.aws.amazon.com/amazon-s3-encryption-client/latest/developerguide/go-v3-migration.html). - - -## Service Customizations Changes - -### S3 -When migrating from AWS SDK for Go v1 to v2, an important change to be aware of involves the handling of the `SSECustomerKey` used for server-side encryption with customer-provided keys (SSE-C). In Go SDK v1, the encoding of the `SSECustomerKey` to Base64 was handled internally by the SDK. In SDK v2, this automatic encoding has been removed, and it is now required to manually encode the `SSECustomerKey` to Base64 before passing it to the SDK. - -Example Adjustment: - -```go -// V1 - -import ( - "context" - "encoding/base64" - "github.com/aws/aws-sdk-go-v2/config" - "github.com/aws/aws-sdk-go-v2/service/s3" -) -// ... more code - -plainTextKey := "12345678901234567890123456789012" // 32 bytes in length - -// calculate md5.. - -_, err = client.PutObjectWithContext(context.Background(), &s3.PutObjectInput{ - Bucket: aws.String("your-bucket-name"), - Key: aws.String("your-object-key"), - Body: strings.NewReader("hello-world"), - SSECustomerKey: &plainTextKey, - SSECustomerKeyMD5: &base64Md5, - SSECustomerAlgorithm: aws.String("AES256"), -}) - -// ... more code -``` - -```go -// V2 - -import ( - "github.com/aws/aws-sdk-go/aws" - "github.com/aws/aws-sdk-go/aws/session" - "github.com/aws/aws-sdk-go/service/s3" -) - -// ... more code - -plainTextKey := "12345678901234567890123456789012" // 32 bytes in length -base64EncodedKey := base64.StdEncoding.EncodeToString([]byte(plainTextKey)) - -// calculate md5.. - -_, err = client.PutObject(context.Background(), &s3.PutObjectInput{ - Bucket: aws.String("your-bucket-name"), - Key: aws.String("your-object-key"), - Body: strings.NewReader("hello-world"), - SSECustomerKey: &base64EncodedKey, - SSECustomerKeyMD5: &base64Md5, - SSECustomerAlgorithm: aws.String("AES256"), -}) - -// ... more code -``` - diff --git a/content/en/docs/sdk-utilities/_index.md b/content/en/docs/sdk-utilities/_index.md deleted file mode 100644 index 7a1a7f9dd51..00000000000 --- a/content/en/docs/sdk-utilities/_index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "Using the AWS SDK for Go V2 Utilities" -linkTitle: "SDK Utilities" -date: "2020-11-12" -description: "Use the AWS SDK for Go V2 utilities to help use AWS services." -weight: 7 ---- - -The {{% alias sdk-go %}} includes the following utilities to help you more -easily use AWS services. Find the SDK utilities in their related AWS -service package. diff --git a/content/en/docs/sdk-utilities/cloudfront.md b/content/en/docs/sdk-utilities/cloudfront.md deleted file mode 100644 index e1849d2de2c..00000000000 --- a/content/en/docs/sdk-utilities/cloudfront.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: "Amazon CloudFront Utilities" -linkTitle: "Amazon CloudFront" -date: "2020-11-12" -description: "Using the AWS SDK for Go V2 Amazon CloudFront Utilities" ---- - -## {{% alias service="CFlong" %}} URL Signer - -The {{% alias service="CFlong" %}} 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). - -To sign a URL, create a `URLSigner` instance with your {{% alias service="CF" %}} 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 {{% alias service="CFlong" %}} -key pairs, -see [Creating CloudFront Key Pairs for Your Trusted Signers](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html#private-content-creating-cloudfront-key-pairs) -in the {{% alias service="CF" %}} Developer Guide. - -The following example creates a signed URL that's valid for one hour -after it is created. - -```go -import "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]({{% apiref "feature/cloudfront/sign" %}}) package in the -{{% alias sdk-api %}}. - diff --git a/content/en/docs/sdk-utilities/ec2-imds.md b/content/en/docs/sdk-utilities/ec2-imds.md deleted file mode 100644 index fbd543a7ea6..00000000000 --- a/content/en/docs/sdk-utilities/ec2-imds.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "Amazon EC2 Instance Metadata Service" -linkTitle: "Amazon EC2 IMDS" -description: "Using the AWS SDK for Go V2 Amazon EC2 Instance Metadata Service Client" ---- - -You can use the {{% alias sdk-go %}} to access the -[{{% alias service=EC2 %}} Instance Metadata Service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html). -The [feature/ec2/imds]({{% apiref "feature/ec2/imds" %}}) Go package provides a -[Client]({{% apiref "feature/ec2/imds#Client" %}}) type that can be used to access the {{% alias service=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]({{% ref "configuring-sdk" %}}) and [Using AWS Services]({{% ref "making-requests.md" %}}). - -The 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 {{% alias service=EC2 %}} Instance Metadata Service using a programmatic client -like other AWS Services. - -For example to construct a client: -```go -import "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). - -```go -localIp, err := client.GetMetadata(context.TODO(), &imds.GetMetadataInput{ - Path: "local-ipv4", -}) -if err != nil { - log.Printf("Unable to retrieve the private IP address from the EC2 instance: %s\n", err) - return -} -content, _ := io.ReadAll(localIp.Content) -fmt.Printf("local-ip: %v\n", string(content)) -``` - -For a list of all metadata categories, see -[Instance Metadata Categories](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html) -in the {{% alias service="EC2" %}} User Guide. - diff --git a/content/en/docs/sdk-utilities/rds.md b/content/en/docs/sdk-utilities/rds.md deleted file mode 100644 index b0b4593b033..00000000000 --- a/content/en/docs/sdk-utilities/rds.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: "Amazon RDS Utilities" -linkTitle: "Amazon RDS" -date: "2021-04-16" -description: "Using the AWS SDK for Go V2 Amazon RDS Utilities" ---- - -## IAM Authentication - -The [auth]({{< apiref "feature/rds/auth" >}}) package provides utilities for generating authentication tokens for -connecting to {{% alias service="RDS" %}} MySQL and PostgreSQL database instances. Using the [BuildAuthToken]({{< -apiref "feature/rds/auth#BuildAuthToken" >}}) method, you generate a database authorization token by providing the -database endpoint, AWS Region, username, and a [aws.CredentialProvider]({{< apiref "aws#CredentialsProvider" >}}) -implementation that returns IAM credentials with permission to connect to the database using {{< alias service="IAM" >}} -database authentication. To learn more about configuring {{< alias service="RDS" >}} with {{< alias service="IAM" >}} -authentication see the following {{< alias service="RDS" >}} Developer Guide resources: - -* [Enabling and disabling IAM database authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.Enabling.html) -* [Creating and using an IAM policy for IAM database access](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.IAMPolicy.html) -* [Creating a database account using IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html) - -The following examples shows how to generate an authentication token to connect to an {{< alias service="RDS" >}} -database: - -```go -import "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()) -} -``` diff --git a/content/en/docs/sdk-utilities/s3.md b/content/en/docs/sdk-utilities/s3.md deleted file mode 100644 index 97ae90961bc..00000000000 --- a/content/en/docs/sdk-utilities/s3.md +++ /dev/null @@ -1,464 +0,0 @@ ---- -title: "Amazon S3 Utilities" -linkTitle: "Amazon S3" ---- - -# Transfer Managers - -The {{% alias service="S3long" %}} 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. - -## Upload Manager - -The {{% alias service="S3long" %}} 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. - -The following example uses the {{% alias service="S3" %}} `Uploader` to upload a file. -Using `Uploader` is similar to the `s3.PutObject()` operation. - -```go -import "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(), &s3.PutObjectInput{ - Bucket: aws.String("my-bucket"), - Key: aws.String("my-object-key"), - Body: uploadFile, -}) -``` - -### Configuration Options - -When you instantiate an `Uploader` instance using [NewUploader]({{% apiref "feature/s3/manager#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: - -* `PartSize` – 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 {{% alias service="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. - -For 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`). - -{{% pageinfo color="warning" %}} -Your application is expected to limit the concurrent calls to `Upload` to prevent application resource exhaustion. -{{% /pageinfo %}} - -Below is an example to set the default part size during `Uploader` creation: -```go -uploader := manager.NewUploader(client, func(u *Uploader) { - u.PartSize = 10 * 1024 * 1024, // 10 MiB -}) -``` - -For more information about `Uploader` and its configurations, see -[Uploader]({{% apiref "feature/s3/manager/#Uploader" %}}) in the {{% alias sdk-api %}}. - -### PutObjectInput 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: - -```go -type 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. - -Because 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 {{% alias service="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. - -For `body` values that implement the `ReadSeekerAt` type, the `Uploader` doesn't buffer the body contents in memory -before sending it to {{% alias service="S3" %}}. `Uploader` calculates the expected number of parts before uploading the -file to {{% alias service="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. - -### Handling Failed Uploads - -If an upload to {{% alias service="S3" %}} fails, by default, `Uploader` uses the -{{% alias service="S3" %}} `AbortMultipartUpload` operation to remove the uploaded parts. This functionality ensures -that failed uploads do not consume {{% alias service="S3" %}} storage. - -You 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`. - -```go -result, err := uploader.Upload(context.TODO(), &s3.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, &mu) { - // 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: - -```go -params := &s3.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 {{% alias service="S3" %}} - -The following example uses the `path/filepath` package to recursively gather a list of files and upload them to the -specified {{% alias service="S3" %}} bucket. The keys of the {{% alias service="S3" %}} objects are prefixed with the -file's relative path. - -```go -package 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], " ") - } - 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(), &s3.PutObjectInput{ - Bucket: &bucket, - 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 <- path - } - return nil -} -``` - -## Download Manager - -The {{% alias service="S3" %}} [Downloader]({{% apiref "feature/s3/manager#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. - -#### Example: Download a File - -The following example uses the {{% alias service="S3" %}} `Downloader` to download a file. Using `Downloader` is similar -to the [s3.GetObject]({{% apiref "service/s3#Client.GetObject" %}}) operation. - -```go -import "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, &s3.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. - -#### Configuration Options - -When you instantiate a `Downloader` instance, you can specify configuration options to customize how objects are -downloaded: - -* `PartSize` – 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. - -For 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`). - -{{% pageinfo color="warning" %}} -Your application is expected to limit the concurrent calls to `Download` to prevent application resource exhaustion. -{{% /pageinfo %}} - -For more information about `Downloader` and its other configuration options, see -[manager.Downloader]({{< apiref "feature/s3/manager/#Downloader" >}}) in the {{% alias sdk-api %}}. - -### Overriding 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: - -```go -params := &s3.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 {{% alias service=S3 %}} bucket. Then it -downloads each object to a local file. - -```go -package 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, &s3.ListObjectsV2Input{ - Bucket: &Bucket, - Prefix: &Prefix, - }) - - 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, &s3.GetObjectInput{Bucket: &bucket, Key: &key}) - - return err -} -``` - -## GetBucketRegion - -The [GetBucketRegion]({{% apiref "feature/s3/manager#GetBucketRegion" %}}) is a utility function for determining the -AWS Region location of an {{% alias service=S3 %}} Bucket. `GetBucketRegion` takes an {{% alias service=S3 %}} -client and uses it to determine the location of the requested Bucket within the AWS Partition associated with the -client's configured Region. - -For example to find the Region for the Bucket `my-bucket`: - -```go -cfg, 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, &bnf) { - 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]({{% apiref "feature/s3/manager#BucketNotFound" %}}) error type as shown in the example. - - -# Unseekable Streaming Input - -For API operations like `PutObject` and `UploadPart`, the {{% alias service=S3 %}} client expects the value of the `Body` input parameter to implement the [io.Seeker](https://pkg.go.dev/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](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html). If the `Body` input parameter value does not implement `io.Seeker`, your application will receive an error. - -``` -operation 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]({{< ref "docs/middleware" >}}) using functional options. The [WithAPIOptions](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#WithAPIOptions) helper returns a functional option for zero or more middleware mutators. To disable the client computing the payload hash and use [Unsigned Payload](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-header-based-auth.html) request signature add [v4.SwapComputePayloadSHA256ForUnsignedPayloadMiddleware]({{< apiref "aws/signer/v4#SwapComputePayloadSHA256ForUnsignedPayloadMiddleware" >}}). - -```go -resp, err := client.PutObject(context.TODO(), &s3.PutObjectInput{ - Bucket: &bucketName, - Key: &objectName, - Body: bytes.NewBuffer([]byte(`example object!`)), - ContentLength: 15, // length of body -}, s3.WithAPIOptions( - v4.SwapComputePayloadSHA256ForUnsignedPayloadMiddleware, -)) -``` - -{{% pageinfo color="warning" %}} -{{% alias service=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. - -Use the SDK's [Amazon S3 Upload Manager]({{< ref "docs/sdk-utilities/s3#upload-manager" >}}) for uploads that are not seekable, and do not have a known length. -{{% /pageinfo %}} - diff --git a/content/en/docs/security/_index.md b/content/en/docs/security/_index.md deleted file mode 100644 index 25cd19d1170..00000000000 --- a/content/en/docs/security/_index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: "Security for this AWS Product or Service" -linkTitle: "Security" -date: "2020-11-09" -weight: 10 ---- - -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](https://aws.amazon.com/compliance/shared-responsibility-model/) -describes this as Security of the Cloud and Security in the Cloud. - -**Security 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](https://aws.amazon.com/compliance/programs/). - -**Security 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. diff --git a/content/en/docs/security/compliance-validation.md b/content/en/docs/security/compliance-validation.md deleted file mode 100644 index b04453a19cf..00000000000 --- a/content/en/docs/security/compliance-validation.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "Compliance Validation for this AWS Product or Service" -linkTitle: "Compliance Validation" -date: "2020-11-12" ---- - -This AWS product or service follows -the [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model) through the specific -Amazon Web Services (AWS) -services it supports. -For [AWS service security information](https://aws.amazon.com/security/?id=docs_gateway#aws-security), see the AWS -service security documentation page -and [AWS services that are in scope of AWS compliance efforts by compliance program](https://aws.amazon.com/compliance/services-in-scope/). - -The 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. - -Third-party audit reports are available for you to download using AWS Artifact. For more information, -see [Downloading Reports in AWS Artifact](https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html). - -For more information about AWS compliance programs, -see [AWS Compliance Programs](https://aws.amazon.com/compliance/programs/). - -Your 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: - -* [Security and Compliance Quick Start Guides](https://aws.amazon.com/quickstart/?quickstart-all.sort-by=item.additionalFields.updateDate&quickstart-all.sort-order=desc&awsf.quickstart-homepage-filter=categories%23security-identity-compliance) - – 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](https://d0.awsstatic.com/whitepapers/compliance/AWS_HIPAA_Compliance_Whitepaper.pdf) - – A whitepaper that describes how companies can use AWS to create HIPAA-compliant applications. -* [AWS Compliance Resources](https://aws.amazon.com/compliance/resources/) – A collection of workbooks and guides that - might apply to your industry and location. -* [AWS Config](https://aws.amazon.com/config/) – A service that assesses how well your resource configurations comply - with internal practices, industry guidelines, and regulations. -* [AWS Security Hub](https://aws.amazon.com/security-hub) – A comprehensive view of your security state within AWS that - helps you check your compliance with security industry standards and best practices. diff --git a/content/en/docs/security/data-protection.md b/content/en/docs/security/data-protection.md deleted file mode 100644 index 8303829a327..00000000000 --- a/content/en/docs/security/data-protection.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: "Data Protection in this AWS Product or Service" -linkTitle: "Data Protection" -date: "2020-11-09" ---- - -The [shared responsibility model](https://aws.amazon.com/compliance/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](http://aws.amazon.com/compliance/data-privacy-faq). For information about data protection in -Europe, see the -[AWS Shared Responsibility Model and GDPR](http://aws.amazon.com/blogs/security/the-aws-shared-responsibility-model-and-gdpr) -blog post on the AWS Security Blog. - -For 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: - -* Use 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](http://aws.amazon.com/compliance/fips). - -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. diff --git a/content/en/docs/security/disaster-recovery-resiliency.md b/content/en/docs/security/disaster-recovery-resiliency.md deleted file mode 100644 index 6ba772a82fb..00000000000 --- a/content/en/docs/security/disaster-recovery-resiliency.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: "Resilience for this AWS Product or Service" -linkTitle: "Resilience" -date: "2020-11-12" ---- - -The Amazon Web Services (AWS) global infrastructure is built around AWS Regions and Availability Zones. - -AWS Regions provide multiple physically separated and isolated Availability Zones, which are connected with low-latency, -high-throughput, and highly redundant networking. - -With 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. - -For more information about AWS Regions and Availability Zones, -see [AWS Global Infrastructure](https://aws.amazon.com/about-aws/global-infrastructure/). - -This AWS product or service follows -the [shared responsibility model](https://aws.amazon.com/compliance/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](https://aws.amazon.com/security/?id=docs_gateway#aws-security) -and [AWS services that are in scope of AWS compliance efforts by compliance program](https://aws.amazon.com/compliance/services-in-scope/). diff --git a/content/en/docs/security/iam.md b/content/en/docs/security/iam.md deleted file mode 100644 index 2fc8599d4dc..00000000000 --- a/content/en/docs/security/iam.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: "Identity and Access Management for this AWS Product or Service" -linkTitle: "Identity and Access Management" -date: "2020-11-12" ---- - -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. - -To 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. - -For details about working with IAM, see [IAM](https://aws.amazon.com/iam/). - -For an overview of IAM users and why they are important for the security of your account, -see [AWS Security Credentials](https://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html) -in the [Amazon Web Services General Reference](https://docs.aws.amazon.com/general/latest/gr/). - -This AWS product or service follows -the [shared responsibility model](https://aws.amazon.com/compliance/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](https://aws.amazon.com/security/?id=docs_gateway#aws-security) and AWS -services that are in scope -of [AWS compliance efforts by compliance program](https://aws.amazon.com/compliance/services-in-scope/). diff --git a/content/en/docs/security/infrastructure-security.md b/content/en/docs/security/infrastructure-security.md deleted file mode 100644 index 08e548814dd..00000000000 --- a/content/en/docs/security/infrastructure-security.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Infrastructure Security for this AWS Product or Service" -linkTitle: "Infrastructure Security" -date: "2020-11-12" ---- - -This AWS product or service follows -the [shared responsibility model](https://aws.amazon.com/compliance/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](https://aws.amazon.com/security/?id=docs_gateway#aws-security) -and [AWS services that are in scope of AWS compliance efforts by compliance program](https://aws.amazon.com/compliance/services-in-scope/) -. - -For information about AWS security processes, see -the [AWS: Overview of Security Processes](https://d0.awsstatic.com/whitepapers/Security/AWS_Security_Whitepaper.pdf) -whitepaper. diff --git a/content/en/docs/security/tls.md b/content/en/docs/security/tls.md deleted file mode 100644 index fe6b4bee069..00000000000 --- a/content/en/docs/security/tls.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "TLS Version in AWS SDK for Go V2" -linkTitle: "TLS Version" -date: "2020-11-09" ---- - -The {{% alias sdk-go %}} 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]({{< apiref "aws/transport/http#BuildableClient" >}}) to -customize the SDK HTTP client, the minimum TLS value is configured as TLS 1.2. - -{{% pageinfo color="warning" %}} -If 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. -{{% /pageinfo %}} - -## Enforcing a Minimum TLS Version - -You can construct a custom an [http.Client]() or use the SDK provided -[http.BuildableClient]({{< apiref "aws/transport/http#BuildableClient" >}}) -builder. The following example demonstrates how to specify a minimum TLS -version of [1.3](https://pkg.go.dev/crypto/tls#VersionTLS13) using the -[http.BuildableClient]({{< apiref "aws/transport/http#BuildableClient" >}}). - -{{% pageinfo color="warning" %}} -Some 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. -{{% /pageinfo %}} - -```go -package 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 = &tls.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). - // ... -} -``` - diff --git a/content/en/docs/unit-testing.md b/content/en/docs/unit-testing.md deleted file mode 100644 index 1d57b360a6e..00000000000 --- a/content/en/docs/unit-testing.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: "Unit Testing with the AWS SDK for Go V2" -linkTitle: "Testing" -description: "How to mock the AWS SDK for Go V2 when unit testing your application." -weight: 9 ---- - -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. - -To 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. - -## Mocking Client Operations - -In this example, `S3GetObjectAPI` is an interface that defines the set of -{{% alias service=S3 %}} API operations required by the `GetObjectFromS3` -function. `S3GetObjectAPI` is satisfied by the {{% alias service=S3 %}} -client's [GetObject]({{< apiref "service/s3#Client.GetObject" >}}) method. - -```go -import "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, &s3.GetObjectInput{ - Bucket: &bucket, - Key: &key, - }) - 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. - -```go -import "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 string - 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 &s3.GetObjectOutput{ - Body: ioutil.NopCloser(bytes.NewReader([]byte("this is the body foo bar baz"))), - }, nil - }) - }, - bucket: "fooBucket", - key: "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. - -In the following example, `ListObjectsV2Pager` is an interface that defines the -behaviors for the {{% alias service=S3 %}} -[ListObjectsV2Paginator]({{< apiref "service/s3#ListObjectsV2Paginator" >}}). -required by `CountObjects` function. - -```go -import "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. - -```go -import "context" -import "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 < len(m.Pages) -} - -func (m *mockListObjectsV2Pager) NextPage(ctx context.Context, f ...func(*s3.Options)) (output *s3.ListObjectsV2Output, err error) { - if m.PageNum >= 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 := &mockListObjectsV2Pager{ - 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) - } -} -``` - diff --git a/data/aliases.toml b/data/aliases.toml deleted file mode 100644 index 48b870e7f12..00000000000 --- a/data/aliases.toml +++ /dev/null @@ -1,386 +0,0 @@ -sdk-go = "AWS SDK for Go V2" -sdk-api = "AWS SDK for Go V2 API Reference" -min-go-version = "1.20" - -[service] -AASlong = "Amazon AppStream" -AAS = "Amazon AppStream" -AAS2long = "Amazon AppStream 2.0" -AAS2 = "AppStream 2.0" -ABlong = "AWS Billing and Cost Management" -AB = "Billing and Cost Management" -ABPlong = "Amazon API Gateway" -ABP = "API Gateway" -ABUSlong = "Alexa for Business" -ABUS = "Alexa for Business" -AC9long = "AWS Cloud9" -AC9 = "AWS Cloud9" -ACBlong = "AWS CodeBuild" -ACB = "CodeBuild" -ACClong = "AWS CodeCommit" -ACC = "CodeCommit" -ACDlong = "AWS CodeDeploy" -ACD = "CodeDeploy" -ACMlong = "AWS Certificate Manager" -ACM = "ACM" -ACPlong = "AWS CodePipeline" -ACP = "CodePipeline" -ACSlong = "AWS CodeStar" -ADSlong = "AWS Directory Service" -ADS = "AWS Directory Service" -AEBlong = "AWS Elastic Beanstalk" -AEB = "Elastic Beanstalk" -AGSlong = "Amazon GameLift" -AGS = "Amazon GameLift" -AKAlong = "Amazon Kinesis Data Analytics" -AKA = "Kinesis Data Analytics" -AKFlong = "Amazon Kinesis Data Firehose" -AKF = "Kinesis Data Firehose" -AKSlong = "Amazon Kinesis Data Streams" -AKS = "Kinesis Data Streams" -AKlong = "Amazon Kinesis" -AK = "Kinesis" -AKVSlong = "Amazon Kinesis Video Streams" -AKVS = "Kinesis Video Streams" -ALYlong = "Amazon Lumberyard" -ALY = "Lumberyard" -AMBlong = "Amazon Managed Blockchain" -AMB = "Managed Blockchain" -AMHlong = "AWS Mobile Hub" -AMH = "Mobile Hub" -AMPClong = "AWS Connector for vCenter" -AMPC = "connector" -AMPlong = "AWS Management Portal for vCenter" -AMP = "management portal" -AMPLIFYlong = "AWS Amplify" -AMPLIFY = "Amplify" -AMQlong = "Amazon MQ" -AMQ = "Amazon MQ" -AOlong = "AWS Organizations" -AO = "Organizations" -APPAlong = "AWS Application Auto Scaling" -APPA = "Application Auto Scaling" -APPDlong = "AWS Application Discovery Service" -APPD = "Application Discovery Service" -APSYlong = "AWS AppSync" -APSY = "AWS AppSync" -ARGlong = "AWS Resource Groups" -ARG = "Resource Groups" -ARTlong = "AWS Artifact" -ART = "AWS Artifact" -ASlong = "AWS Auto Scaling" -AS = "AWS Auto Scaling" -ASHlong = "AWS Security Hub" -ASH = "Security Hub" -ASMlong = "AWS Secrets Manager" -ASM = "Secrets Manager" -ATElong = "Amazon Athena" -ATE = "Athena" -ATPlong = "AWS Device Farm" -ATP = "Device Farm" -ATSlong = "Alexa Top Sites" -ATS = "Alexa Top Sites" -AURlong = "Amazon Aurora" -AUR = "Aurora" -AWISlong = "Alexa Web Information Service" -AWIS = "Alexa Web Information Service" -AWSDClong = "AWS Direct Connect" -AWSDC = "Direct Connect" -AWSDPlong = "AWS Data Pipeline" -AWSDP = "Data Pipeline" -awshealthlong = "AWS Health" -awshealth = "AWS Health" -AWSSGlong = "AWS Storage Gateway" -AWSSG = "Storage Gateway" -AWSTAlong = "AWS Trusted Advisor" -AWSTA = "Trusted Advisor" -BATCHlong = "AWS Batch" -BATCH = "AWS Batch" -BKPlong = "AWS Backup" -BKP = "AWS Backup" -CClong = "AWS Config" -CC = "AWS Config" -CDlong = "AWS CodeDeploy" -CD = "AWS CodeDeploy" -CDSlong = "Amazon Cloud Directory" -CDS = "Cloud Directory" -CFNlong = "AWS CloudFormation" -CFN = "AWS CloudFormation" -CFlong = "Amazon CloudFront" -CF = "CloudFront" -CHMlong = "Amazon Chime" -CLIlong = "AWS Command Line Interface" -CLI = "AWS CLI" -COGID = "Amazon Cognito Identity" -COGSYNClong = "Amazon Cognito Sync" -COGSYNC = "Amazon Cognito Sync" -COGlong = "Amazon Cognito" -COG = "Amazon Cognito" -CMAPlong = "AWS Cloud Map" -CMAP = "AWS Cloud Map" -CMPlong = "Amazon Comprehend" -CMP = "Amazon Comprehend" -CON = "Amazon Connect" -CSlong = "Amazon CloudSearch" -CS = "CloudSearch" -CTlong = "AWS CloudTrail" -CT = "CloudTrail" -CWElong = "Amazon CloudWatch Events" -CWE = "CloudWatch Events" -CWLlong = "Amazon CloudWatch Logs" -CWL = "CloudWatch Logs" -CWlong = "Amazon CloudWatch" -CW = "CloudWatch" -DDBlong = "Amazon DynamoDB" -DDB = "DynamoDB" -DLlong = "AWS DeepLens" -DL = "AWS DeepLens" -DMSlong = "AWS Database Migration Service" -DMS = "AWS DMS" -DocDBlong = "Amazon DocumentDB (with MongoDB compatibility)" -DocDB = "Amazon DocumentDB" -DPlong = "Amazon DevPay" -DP = "DevPay" -DRlong = "AWS DeepRacer" -DR = "AWS DeepRacer" -DSlong = "Amazon DynamoDB Streams" -DS = "DynamoDB Streams" -DSYlong = "AWS DataSync" -DSY = "DataSync" -Disklong = "AWS Import/Export Disk" -EBSencryptlong = "Amazon EBS encryption" -EBSencrypt = "Amazon EBS encryption" -EBSlong = "Amazon Elastic Block Store" -EBS = "Amazon EBS" -EBlong = "AWS Elastic Beanstalk" -EB = "Elastic Beanstalk" -EC2long = "Amazon Elastic Compute Cloud" -EC2 = "Amazon EC2" -ECRlong = "Amazon Elastic Container Registry (Amazon ECR)" -ECR = "Amazon ECR" -ECSlong = "Amazon Elastic Container Service (Amazon ECS)" -ECS = "Amazon ECS" -EFSlong = "Amazon Elastic File System" -EFS = "Amazon EFS" -EIAlong = "Amazon Elastic Inference" -EIA = "Elastic Inference" -EKSlong = "Amazon Elastic Kubernetes Service" -EKS = "Amazon EKS" -ELBlong = "Elastic Load Balancing" -ELB = "ELB" -ELClong = "Amazon ElastiCache" -ELC = "ElastiCache" -EMClong = "AWS Elemental MediaConvert" -EMC = "MediaConvert" -EMLlong = "AWS Elemental MediaLive" -EML = "MediaLive" -EMPlong = "AWS Elemental MediaPackage" -EMP = "MediaPackage" -EMRlong = "Amazon EMR" -EMR = "Amazon EMR" -EMSlong = "AWS Elemental MediaStore" -EMS = "MediaStore" -EMTlong = "AWS Elemental MediaTailor" -EMT = "MediaTailor" -EMXlong = "AWS Elemental MediaConnect" -EMX = "MediaConnect" -ESlong = "Amazon Elasticsearch Service" -ES = "Amazon ES" -ETlong = "Amazon Elastic Transcoder" -ET = "Elastic Transcoder" -FFlong = "AWS Flow Framework" -FF = "the framework" -FMSlong = "AWS Firewall Manager" -FMS = "AWS Firewall Manager" -FORlong = "Amazon Forecast" -FOR = "Amazon Forecast" -FPSlong = "Amazon Flexible Payments Service" -FPS = "Amazon FPS" -Frozenlong = "AWS Snowball" -Frozen = "Snowball" -FSXlong = "Amazon FSx" -FSX = "Amazon FSx" -FWSlong = "Amazon Fulfillment Web Service" -FWS = "Amazon FWS" -GAXlong = "Amazon Global Accelerator" -GAX = "Global Accelerator" -GDUlong = "Amazon GuardDuty" -GDU = "GuardDuty" -GGlong = "AWS IoT Greengrass" -GG = "AWS IoT Greengrass" -GLlong = "Amazon S3 Glacier" -GL = "S3 Glacier" -GLUlong = "AWS Glue" -GLU = "AWS Glue" -GOVCLOUD-US = "AWS GovCloud (US)" -GRSlong = "AWS Ground Station" -GRS = "AWS Ground Station" -GSG = "Getting Started with AWS" -HSMlong = "AWS CloudHSM" -HSM = "AWS CloudHSM" -IAMlong = "AWS Identity and Access Management" -IAM = "IAM" -IElong = "AWS Import/Export" -IE = "Import/Export" -INS = "Amazon Inspector" -IoTC = "AWS IoT Device SDK for C" -IoTJS = "AWS IoT Device SDK for Node.js" -IoTlong = "AWS IoT Core" -IoT = "AWS IoT Core" -ITOClong = "AWS IoT 1-Click" -ITOC = "AWS IoT 1-Click" -ITAlong = "AWS IoT Analytics" -ITA = "AWS IoT Analytics" -ITDDlong = "AWS IoT Device Defender" -ITDD = "AWS IoT Device Defender" -ITDMlong = "AWS IoT Device Management" -ITDM = "AWS IoT Device Management" -ITE = "AWS IoT Events" -ITElong = "AWS IoT Events" -ITSW = "AWS IoT SiteWise" -ITSWlong = "AWS IoT SiteWise" -ITTGlong = "AWS IoT Things Graph" -ITTG = "AWS IoT Things Graph" -JSBlong = "AWS SDK for JavaScript" -JSB = "SDK for JavaScript" -KMSlong = "AWS Key Management Service" -KMS = "AWS KMS" -LAMlong = "AWS Lambda" -LAM = "Lambda" -LIClong = "AWS License Manager" -LIC = "License Manager" -LEXlong = "Amazon Lex" -lightsaillong = "Amazon Lightsail" -lightsail = "Lightsail" -MAlong = "Amazon Mobile Analytics" -MA = "Mobile Analytics" -MCElong = "Amazon Macie" -MCE = "Macie" -MESHlong = "AWS App Mesh" -MESH = "App Mesh" -MHBlong = "AWS Migration Hub" -MHB = "Migration Hub" -MKTlong = "AWS Marketplace" -MKT = "Marketplace" -MLlong = "Amazon Machine Learning" -ML = "Amazon ML" -MMPlong = "AWS Marketplace Management Portal" -MMlong = "AWS Molecular Modeling" -MM = "Molecular Modeling" -MSKlong = "Amazon Managed Streaming for Kafka (Amazon MSK) (public preview)" -MSK = "Amazon MSK" -MTlong = "Amazon Mechanical Turk" -MT = "Mechanical Turk" -neptunelong = "Amazon Neptune" -neptune = "Neptune" -OPSlong = "AWS OpsWorks" -OPS = "OpsWorks" -OPSStacklong = "AWS OpsWorks Stacks" -OPSStack = "OpsWorks Stacks" -OPSCAlong = "AWS OpsWorks for Chef Automate" -OPSCA = "OpsWorks for Chef Automate" -PAAPIlong = "Product Advertising API" -PAAPI = "PA API" -PCAlong = "AWS Certificate Manager Private Certificate Authority" -PCA = "ACM Private CA" -PERSlong = "Amazon Personalize" -PERS = "Amazon Personalize" -PINlong = "Amazon Pinpoint" -POLlong = "Amazon Polly" -PSlong = "IAM Policy Simulator" -PS = "Policy Simulator" -QSlong = "Amazon QuickSight" -R53long = "Amazon Route 53" -R53 = "Route 53" -RAMlong = "AWS Resource Access Manager" -RAM = "AWS RAM" -RDS-pricing = "Amazon RDS Pricing" -RDSlong = "Amazon Relational Database Service" -RDS = "Amazon RDS" -REKlong = "Amazon Rekognition" -REK = "Amazon Rekognition" -RMlong = "AWS RoboMaker" -RM = "AWS RoboMaker" -RSlong = "Amazon Redshift" -RS = "Amazon Redshift" -RTOSlong = "Amazon FreeRTOS" -RTOS = "Amazon FreeRTOS" -S3long = "Amazon Simple Storage Service" -S3 = "Amazon S3" -SARlong = "AWS Serverless Application Repository" -SAR = "AWS Serverless Application Repository" -SClong = "AWS Service Catalog" -SC = "AWS Service Catalog" -SCTlong = "AWS Schema Conversion Tool" -SCT = "AWS SCT" -SDBlong = "Amazon SimpleDB" -SDB = "SimpleDB" -SESlong = "Amazon Simple Email Service" -SES = "Amazon SES" -SFNlong = "AWS Step Functions" -SFN = "Step Functions" -SFTPlong = "AWS Transfer for SFTP" -SFTP = "AWS SFTP" -SHDlong = "AWS Shield" -SHD = "Shield" -SLKlong = "Amazon Silk" -SLK = "Silk" -SMlong = "Amazon SageMaker" -SM = "SageMaker" -SMSlong = "AWS Server Migration Service" -SMS = "AWS SMS" -Snowball = "Snowball" -Snowlong = "Snowball appliance" -SNSlong = "Amazon Simple Notification Service" -SNS = "Amazon SNS" -SPlong = "Amazon Simple Pay" -SP = "Amazon Simple Pay" -SPK = "AWS Elemental SPEKE" -SPKlong = "AWS Elemental Secure Packager and Encoder Key Exchange" -SQSlong = "Amazon Simple Queue Service" -SQS = "Amazon SQS" -SSMlong = "Amazon EC2 Simple Systems Manager" -SSM = "SSM" -SSOlong = "AWS IAM Identity Center (successor to AWS Single Sign-On)" -SSO = "IAM Identity Center" -STSlong = "AWS Security Token Service" -STS = "AWS STS" -sumerianlong = "Amazon Sumerian" -sumerian = "Sumerian" -SUPlong = "AWS Support" -SUP = "Support" -SWFlong = "Amazon Simple Workflow Service" -SWF = "Amazon SWF" -TFW = "AWS Tools for Windows" -TGWlong = "AWS Transit Gateway" -TGW = "AWS Transit Gateway" -TPC = "Tools for PowerShell Core" -TPClong = "AWS Tools for PowerShell Core" -TSClong = "Amazon Transcribe" -TSC = "Amazon Transcribe" -TSLlong = "Amazon Translate" -TSL = "Amazon Translate" -TWPALL = "Tools for PowerShell" -TWPALLlong = "AWS Tools for PowerShell" -TWPlong = "AWS Tools for Windows PowerShell" -TWP = "Tools for Windows PowerShell" -VMIElong = "VM Import/Export" -VMIE = "VM Import/Export" -VPClong = "Amazon Virtual Private Cloud" -VPC = "Amazon VPC" -WAFlong = "AWS WAF" -WAF = "AWS WAF" -WAMlong = "Amazon WorkSpaces Application Manager" -WAM = "Amazon WAM" -WATlong = "AWS Well-Architected Tool" -WAT = "AWS WA Tool" -WDlong = "Amazon WorkDocs" -WD = "WorkDocs" -WLKlong = "Amazon WorkLink" -WLK = "Amazon WorkLink" -WMlong = "Amazon WorkMail" -WM = "WorkMail" -WSPlong = "Amazon WorkSpaces" -WSP = "Amazon WorkSpaces" -xraylong = "AWS X-Ray" -xray = "X-Ray" diff --git a/diagrams/middleware.graffle b/diagrams/middleware.graffle deleted file mode 100644 index 7fe69632148..00000000000 Binary files a/diagrams/middleware.graffle and /dev/null differ diff --git a/docs/docs/cloud9-go/index.html b/docs/docs/cloud9-go/index.html index 7d94d880d61..e5824454e8d 100644 --- a/docs/docs/cloud9-go/index.html +++ b/docs/docs/cloud9-go/index.html @@ -1,677 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Using AWS Cloud9 with the AWS SDK for Go V2 | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Using AWS Cloud9 with the AWS SDK for Go V2

- -
- - - - - - - - - - - - - -
-

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.

-

Follow the instructions below to set up AWS Cloud9 with the AWS SDK for Go V2:

-

Set 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.

-

Review 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.

-

Set 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.

-

See Creating an Environment in AWS Cloud9 -in the AWS Cloud9 User Guide for details.

- - -
-

As 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.

- -
- -

Set 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.

-
    -
  1. -

    If the terminal isn’t already open in the IDE, open it. On the menu bar in the IDE, choose Window, New Terminal.

    -
    2. -
  2. -

    Validate the AWS Cloud9 available Go version.

    -
    go 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.

    -
    3. -
  3. -

    Follow the Getting Started guide to set up a Go project under ~/environment, -or follow the steps to Download Example Code

    -
    4. -
-

Download 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.

-

To 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.

-
git 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.

-

Run Example Code

-

To run code in your AWS Cloud9 development environment, see -Run Your Code in the -AWS Cloud9 User Guide.

-

Installing/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.)

-
wget 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.

-
 PATH=$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.)

-
. ~/.bashrc
-
- - -
- Last modified April 23, 2021: Fixing broken links, correcting typos (#1236) (6c3cbc2a76) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/code-examples/cloudwatch/createcustommetric/index.html b/docs/docs/code-examples/cloudwatch/createcustommetric/index.html index bfeb04c2aa1..e5824454e8d 100644 --- a/docs/docs/code-examples/cloudwatch/createcustommetric/index.html +++ b/docs/docs/code-examples/cloudwatch/createcustommetric/index.html @@ -1,14 +1,15 @@ - - - - - - CreateCustomMetricv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/cloudwatch/createenablemetricalarm/index.html b/docs/docs/code-examples/cloudwatch/createenablemetricalarm/index.html index 4964bf46d01..e5824454e8d 100644 --- a/docs/docs/code-examples/cloudwatch/createenablemetricalarm/index.html +++ b/docs/docs/code-examples/cloudwatch/createenablemetricalarm/index.html @@ -1,14 +1,15 @@ - - - - - - CreateEnableMetricAlarmv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/cloudwatch/describealarms/index.html b/docs/docs/code-examples/cloudwatch/describealarms/index.html index 64de8d7e7d8..e5824454e8d 100644 --- a/docs/docs/code-examples/cloudwatch/describealarms/index.html +++ b/docs/docs/code-examples/cloudwatch/describealarms/index.html @@ -1,14 +1,15 @@ - - - - - - DescribeAlarmsv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/cloudwatch/disablealarm/index.html b/docs/docs/code-examples/cloudwatch/disablealarm/index.html index 119f538b746..e5824454e8d 100644 --- a/docs/docs/code-examples/cloudwatch/disablealarm/index.html +++ b/docs/docs/code-examples/cloudwatch/disablealarm/index.html @@ -1,14 +1,15 @@ - - - - - - DisableAlarmv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/cloudwatch/index.html b/docs/docs/code-examples/cloudwatch/index.html index a02f94af541..e5824454e8d 100644 --- a/docs/docs/code-examples/cloudwatch/index.html +++ b/docs/docs/code-examples/cloudwatch/index.html @@ -1,649 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -Amazon CloudWatch Examples | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Amazon CloudWatch Examples

- -
- - - - - - - - - - - - - -
-

This section contains code examples for Amazon CloudWatch using version 2 of the AWS SDK for Go.

- -
- - - - - - - - -
- - -
-
- CreateCustomMetricv2 -
-

-
- - -
-
- CreateEnableMetricAlarmv2 -
-

-
- - -
-
- DescribeAlarmsv2 -
-

-
- - -
-
- DisableAlarmv2 -
-

-
- - -
-
- ListMetricsv2 -
-

-
- - -
-
- PutEventv2 -
-

-
- - -
- - - -
- Last modified January 14, 2021: Added code examples from AWS SDK docs repo (#1015) (6b77d0a0af) -
- -
- -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/code-examples/cloudwatch/listmetrics/index.html b/docs/docs/code-examples/cloudwatch/listmetrics/index.html index 46a160c4c64..e5824454e8d 100644 --- a/docs/docs/code-examples/cloudwatch/listmetrics/index.html +++ b/docs/docs/code-examples/cloudwatch/listmetrics/index.html @@ -1,14 +1,15 @@ - - - - - - ListMetricsv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/cloudwatch/putevent/index.html b/docs/docs/code-examples/cloudwatch/putevent/index.html index ced613ad531..e5824454e8d 100644 --- a/docs/docs/code-examples/cloudwatch/putevent/index.html +++ b/docs/docs/code-examples/cloudwatch/putevent/index.html @@ -1,14 +1,15 @@ - - - - - - PutEventv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/dynamodb/describetable/index.html b/docs/docs/code-examples/dynamodb/describetable/index.html index 7f3f31f4361..e5824454e8d 100644 --- a/docs/docs/code-examples/dynamodb/describetable/index.html +++ b/docs/docs/code-examples/dynamodb/describetable/index.html @@ -1,14 +1,15 @@ - - - - - - DescribeTablev2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/dynamodb/index.html b/docs/docs/code-examples/dynamodb/index.html index a15b6da1971..e5824454e8d 100644 --- a/docs/docs/code-examples/dynamodb/index.html +++ b/docs/docs/code-examples/dynamodb/index.html @@ -1,617 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -Amazon DynamoDB Examples | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Amazon DynamoDB Examples

- -
- - - - - - - - - - - - - -
-

This section contains code examples for Amazon DynamoDB using version 2 of the AWS SDK for Go.

- -
- - - - - - - - -
- - -
-
- DescribeTablev2 -
-

-
- - -
-
- ScanItemsv2 -
-

-
- - -
- - - -
- Last modified January 14, 2021: Added code examples from AWS SDK docs repo (#1015) (6b77d0a0af) -
- -
- -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/code-examples/dynamodb/scanitems/index.html b/docs/docs/code-examples/dynamodb/scanitems/index.html index 3c75a19f164..e5824454e8d 100644 --- a/docs/docs/code-examples/dynamodb/scanitems/index.html +++ b/docs/docs/code-examples/dynamodb/scanitems/index.html @@ -1,14 +1,15 @@ - - - - - - ScanItemsv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/ec2/createimage/index.html b/docs/docs/code-examples/ec2/createimage/index.html index 03433a5a5c1..e5824454e8d 100644 --- a/docs/docs/code-examples/ec2/createimage/index.html +++ b/docs/docs/code-examples/ec2/createimage/index.html @@ -1,14 +1,15 @@ - - - - - - CreateImagev2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/ec2/createinstance/index.html b/docs/docs/code-examples/ec2/createinstance/index.html index a048a27de41..e5824454e8d 100644 --- a/docs/docs/code-examples/ec2/createinstance/index.html +++ b/docs/docs/code-examples/ec2/createinstance/index.html @@ -1,14 +1,15 @@ - - - - - - CreateInstancev2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/ec2/describeinstances/index.html b/docs/docs/code-examples/ec2/describeinstances/index.html index 0b4ab2e131b..e5824454e8d 100644 --- a/docs/docs/code-examples/ec2/describeinstances/index.html +++ b/docs/docs/code-examples/ec2/describeinstances/index.html @@ -1,14 +1,15 @@ - - - - - - DescribeInstancesv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/ec2/describevpcendpoints/index.html b/docs/docs/code-examples/ec2/describevpcendpoints/index.html index 8bbdeaaa375..e5824454e8d 100644 --- a/docs/docs/code-examples/ec2/describevpcendpoints/index.html +++ b/docs/docs/code-examples/ec2/describevpcendpoints/index.html @@ -1,14 +1,15 @@ - - - - - - DescribeVpcEndpointsv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/ec2/index.html b/docs/docs/code-examples/ec2/index.html index 66b8a7518b7..e5824454e8d 100644 --- a/docs/docs/code-examples/ec2/index.html +++ b/docs/docs/code-examples/ec2/index.html @@ -1,665 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -Amazon EC2 Examples | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Amazon EC2 Examples

- -
- - - - - - - - - - - - - -
-

This section contains code examples for Amazon EC2 using version 2 of the AWS SDK for Go.

- -
- - - - - - - - -
- - -
-
- CreateImagev2 -
-

-
- - -
-
- CreateInstancev2 -
-

-
- - -
-
- DescribeInstancesv2 -
-

-
- - -
-
- DescribeVpcEndpointsv2 -
-

-
- - -
-
- MonitorInstancesv2 -
-

-
- - -
-
- RebootInstancesv2 -
-

-
- - -
-
- StartInstancesv2 -
-

-
- - -
-
- StopInstancesv2 -
-

-
- - -
- - - -
- Last modified January 14, 2021: Added code examples from AWS SDK docs repo (#1015) (6b77d0a0af) -
- -
- -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/code-examples/ec2/monitorinstances/index.html b/docs/docs/code-examples/ec2/monitorinstances/index.html index d90742ef5a1..e5824454e8d 100644 --- a/docs/docs/code-examples/ec2/monitorinstances/index.html +++ b/docs/docs/code-examples/ec2/monitorinstances/index.html @@ -1,14 +1,15 @@ - - - - - - MonitorInstancesv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/ec2/rebootinstances/index.html b/docs/docs/code-examples/ec2/rebootinstances/index.html index 9514c5a2a5e..e5824454e8d 100644 --- a/docs/docs/code-examples/ec2/rebootinstances/index.html +++ b/docs/docs/code-examples/ec2/rebootinstances/index.html @@ -1,14 +1,15 @@ - - - - - - RebootInstancesv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/ec2/startinstances/index.html b/docs/docs/code-examples/ec2/startinstances/index.html index 0fe1213de20..e5824454e8d 100644 --- a/docs/docs/code-examples/ec2/startinstances/index.html +++ b/docs/docs/code-examples/ec2/startinstances/index.html @@ -1,14 +1,15 @@ - - - - - - StartInstancesv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/ec2/stopinstances/index.html b/docs/docs/code-examples/ec2/stopinstances/index.html index 1101923cfb3..e5824454e8d 100644 --- a/docs/docs/code-examples/ec2/stopinstances/index.html +++ b/docs/docs/code-examples/ec2/stopinstances/index.html @@ -1,14 +1,15 @@ - - - - - - StopInstancesv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/accesskeylastused/index.html b/docs/docs/code-examples/iam/accesskeylastused/index.html index 462bf9f05fa..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/accesskeylastused/index.html +++ b/docs/docs/code-examples/iam/accesskeylastused/index.html @@ -1,14 +1,15 @@ - - - - - - AccessKeyLastUsedv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/attachuserpolicy/index.html b/docs/docs/code-examples/iam/attachuserpolicy/index.html index 91c80c03847..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/attachuserpolicy/index.html +++ b/docs/docs/code-examples/iam/attachuserpolicy/index.html @@ -1,14 +1,15 @@ - - - - - - AttachUserPolicyv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/createaccesskey/index.html b/docs/docs/code-examples/iam/createaccesskey/index.html index 5d14cfccbe4..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/createaccesskey/index.html +++ b/docs/docs/code-examples/iam/createaccesskey/index.html @@ -1,14 +1,15 @@ - - - - - - CreateAccessKeyv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/createaccountalias/index.html b/docs/docs/code-examples/iam/createaccountalias/index.html index 0a9201e1a1d..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/createaccountalias/index.html +++ b/docs/docs/code-examples/iam/createaccountalias/index.html @@ -1,14 +1,15 @@ - - - - - - CreateAccountAliasv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/createpolicy/index.html b/docs/docs/code-examples/iam/createpolicy/index.html index de3c1c1bc28..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/createpolicy/index.html +++ b/docs/docs/code-examples/iam/createpolicy/index.html @@ -1,14 +1,15 @@ - - - - - - CreatePolicyv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/createuser/index.html b/docs/docs/code-examples/iam/createuser/index.html index c040dfc2426..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/createuser/index.html +++ b/docs/docs/code-examples/iam/createuser/index.html @@ -1,14 +1,15 @@ - - - - - - CreateUserv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/deleteaccesskey/index.html b/docs/docs/code-examples/iam/deleteaccesskey/index.html index be9e663bd46..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/deleteaccesskey/index.html +++ b/docs/docs/code-examples/iam/deleteaccesskey/index.html @@ -1,14 +1,15 @@ - - - - - - DeleteAccessKeyv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/deleteaccountalias/index.html b/docs/docs/code-examples/iam/deleteaccountalias/index.html index 3a4fb12ae50..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/deleteaccountalias/index.html +++ b/docs/docs/code-examples/iam/deleteaccountalias/index.html @@ -1,14 +1,15 @@ - - - - - - DeleteAccountAliasv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/deleteservercert/index.html b/docs/docs/code-examples/iam/deleteservercert/index.html index b7081e8bac3..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/deleteservercert/index.html +++ b/docs/docs/code-examples/iam/deleteservercert/index.html @@ -1,14 +1,15 @@ - - - - - - DeleteServerCertv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/deleteuser/index.html b/docs/docs/code-examples/iam/deleteuser/index.html index 51a2781971c..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/deleteuser/index.html +++ b/docs/docs/code-examples/iam/deleteuser/index.html @@ -1,14 +1,15 @@ - - - - - - DeleteUserv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/detachuserpolicy/index.html b/docs/docs/code-examples/iam/detachuserpolicy/index.html index 9e31260046d..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/detachuserpolicy/index.html +++ b/docs/docs/code-examples/iam/detachuserpolicy/index.html @@ -1,14 +1,15 @@ - - - - - - DetachUserPolicyv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/getpolicy/index.html b/docs/docs/code-examples/iam/getpolicy/index.html index 1e60feb1bb0..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/getpolicy/index.html +++ b/docs/docs/code-examples/iam/getpolicy/index.html @@ -1,14 +1,15 @@ - - - - - - GetPolicyv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/getservercert/index.html b/docs/docs/code-examples/iam/getservercert/index.html index dc59e373a8f..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/getservercert/index.html +++ b/docs/docs/code-examples/iam/getservercert/index.html @@ -1,14 +1,15 @@ - - - - - - GetServerCertv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/index.html b/docs/docs/code-examples/iam/index.html index 019cb27e6a1..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/index.html +++ b/docs/docs/code-examples/iam/index.html @@ -1,769 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -IAM Examples | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

IAM Examples

- -
- - - - - - - - - - - - - -
-

This section contains code examples for IAM using version 2 of the AWS SDK for Go.

- -
- - - - - - - - -
- - -
-
- AccessKeyLastUsedv2 -
-

-
- - -
-
- AttachUserPolicyv2 -
-

-
- - -
-
- CreateAccessKeyv2 -
-

-
- - -
-
- CreateAccountAliasv2 -
-

-
- - -
-
- CreatePolicyv2 -
-

-
- - -
-
- CreateUserv2 -
-

-
- - -
-
- DeleteAccessKeyv2 -
-

-
- - -
-
- DeleteAccountAliasv2 -
-

-
- - -
-
- DeleteServerCertv2 -
-

-
- - -
-
- DeleteUserv2 -
-

-
- - -
-
- DetachUserPolicyv2 -
-

-
- - -
-
- GetPolicyv2 -
-

-
- - -
-
- GetServerCertv2 -
-

-
- - -
-
- ListAccessKeysv2 -
-

-
- - -
-
- ListAccountAliasesv2 -
-

-
- - -
-
- ListAdminsv2 -
-

-
- - -
-
- ListServerCertsv2 -
-

-
- - -
-
- ListUsersv2 -
-

-
- - -
-
- UpdateAccessKeyv2 -
-

-
- - -
-
- UpdateServerCertv2 -
-

-
- - -
-
- UpdateUserv2 -
-

-
- - -
- - - -
- Last modified January 14, 2021: Added code examples from AWS SDK docs repo (#1015) (6b77d0a0af) -
- -
- -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/code-examples/iam/listaccesskeys/index.html b/docs/docs/code-examples/iam/listaccesskeys/index.html index 8dac1f2a70a..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/listaccesskeys/index.html +++ b/docs/docs/code-examples/iam/listaccesskeys/index.html @@ -1,14 +1,15 @@ - - - - - - ListAccessKeysv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/listaccountaliases/index.html b/docs/docs/code-examples/iam/listaccountaliases/index.html index 0d4b5552d52..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/listaccountaliases/index.html +++ b/docs/docs/code-examples/iam/listaccountaliases/index.html @@ -1,14 +1,15 @@ - - - - - - ListAccountAliasesv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/listadmins/index.html b/docs/docs/code-examples/iam/listadmins/index.html index cccf630acd7..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/listadmins/index.html +++ b/docs/docs/code-examples/iam/listadmins/index.html @@ -1,14 +1,15 @@ - - - - - - ListAdminsv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/listservercerts/index.html b/docs/docs/code-examples/iam/listservercerts/index.html index c083600aa79..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/listservercerts/index.html +++ b/docs/docs/code-examples/iam/listservercerts/index.html @@ -1,14 +1,15 @@ - - - - - - ListServerCertsv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/listusers/index.html b/docs/docs/code-examples/iam/listusers/index.html index 3d869fbeca5..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/listusers/index.html +++ b/docs/docs/code-examples/iam/listusers/index.html @@ -1,14 +1,15 @@ - - - - - - ListUsersv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/updateaccesskey/index.html b/docs/docs/code-examples/iam/updateaccesskey/index.html index 4d48e532d28..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/updateaccesskey/index.html +++ b/docs/docs/code-examples/iam/updateaccesskey/index.html @@ -1,14 +1,15 @@ - - - - - - UpdateAccessKeyv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/updateservercert/index.html b/docs/docs/code-examples/iam/updateservercert/index.html index a56e406a529..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/updateservercert/index.html +++ b/docs/docs/code-examples/iam/updateservercert/index.html @@ -1,14 +1,15 @@ - - - - - - UpdateServerCertv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/iam/updateuser/index.html b/docs/docs/code-examples/iam/updateuser/index.html index 8f0e942ca5c..e5824454e8d 100644 --- a/docs/docs/code-examples/iam/updateuser/index.html +++ b/docs/docs/code-examples/iam/updateuser/index.html @@ -1,14 +1,15 @@ - - - - - - UpdateUserv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/index.html b/docs/docs/code-examples/index.html index 639c20b923d..e5824454e8d 100644 --- a/docs/docs/code-examples/index.html +++ b/docs/docs/code-examples/index.html @@ -1,687 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -Code Examples | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Code Examples

- -
- - - - - - - - - - - - - -
-

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.

-

Find 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.

- -
- - - - - - - - -
- - -
-
- Amazon CloudWatch Examples -
-

-
- - -
-
- Amazon DynamoDB Examples -
-

-
- - -
-
- Amazon EC2 Examples -
-

-
- - -
-
- Amazon S3 Examples -
-

-
- - -
-
- Amazon SNS Examples -
-

-
- - -
-
- Amazon SQS Examples -
-

-
- - -
-
- AWS KMS Examples -
-

-
- - -
-
- AWS STS Examples -
-

-
- - -
-
- AWS Systems Manager Examples -
-

-
- - -
-
- IAM Examples -
-

-
- - -
- - - -
- Last modified August 10, 2022: Developer Guide Updates (#1798) (36ceefc1bb) -
- -
- -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/code-examples/kms/createkey/index.html b/docs/docs/code-examples/kms/createkey/index.html index 7acc4d88e36..e5824454e8d 100644 --- a/docs/docs/code-examples/kms/createkey/index.html +++ b/docs/docs/code-examples/kms/createkey/index.html @@ -1,14 +1,15 @@ - - - - - - CreateKeyv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/kms/decryptdata/index.html b/docs/docs/code-examples/kms/decryptdata/index.html index c8c4c938619..e5824454e8d 100644 --- a/docs/docs/code-examples/kms/decryptdata/index.html +++ b/docs/docs/code-examples/kms/decryptdata/index.html @@ -1,14 +1,15 @@ - - - - - - DecryptDatav2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/kms/encryptdata/index.html b/docs/docs/code-examples/kms/encryptdata/index.html index 6ea43a120f0..e5824454e8d 100644 --- a/docs/docs/code-examples/kms/encryptdata/index.html +++ b/docs/docs/code-examples/kms/encryptdata/index.html @@ -1,14 +1,15 @@ - - - - - - EncryptDatav2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/kms/index.html b/docs/docs/code-examples/kms/index.html index 9b8e64cf02a..e5824454e8d 100644 --- a/docs/docs/code-examples/kms/index.html +++ b/docs/docs/code-examples/kms/index.html @@ -1,633 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -AWS KMS Examples | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

AWS KMS Examples

- -
- - - - - - - - - - - - - -
-

This section contains code examples for AWS KMS using version 2 of the AWS SDK for Go.

- -
- - - - - - - - -
- - -
-
- CreateKeyv2 -
-

-
- - -
-
- DecryptDatav2 -
-

-
- - -
-
- EncryptDatav2 -
-

-
- - -
-
- ReEncryptDatav2 -
-

-
- - -
- - - -
- Last modified January 14, 2021: Added code examples from AWS SDK docs repo (#1015) (6b77d0a0af) -
- -
- -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/code-examples/kms/reencryptdata/index.html b/docs/docs/code-examples/kms/reencryptdata/index.html index 19c8a2e8e04..e5824454e8d 100644 --- a/docs/docs/code-examples/kms/reencryptdata/index.html +++ b/docs/docs/code-examples/kms/reencryptdata/index.html @@ -1,14 +1,15 @@ - - - - - - ReEncryptDatav2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/s3/copyobject/index.html b/docs/docs/code-examples/s3/copyobject/index.html index 4e892aa6fc4..e5824454e8d 100644 --- a/docs/docs/code-examples/s3/copyobject/index.html +++ b/docs/docs/code-examples/s3/copyobject/index.html @@ -1,14 +1,15 @@ - - - - - - CopyObjectv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/s3/createbucket/index.html b/docs/docs/code-examples/s3/createbucket/index.html index 1c52d925408..e5824454e8d 100644 --- a/docs/docs/code-examples/s3/createbucket/index.html +++ b/docs/docs/code-examples/s3/createbucket/index.html @@ -1,14 +1,15 @@ - - - - - - CreateBucketv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/s3/deletebucket/index.html b/docs/docs/code-examples/s3/deletebucket/index.html index b899a8193ad..e5824454e8d 100644 --- a/docs/docs/code-examples/s3/deletebucket/index.html +++ b/docs/docs/code-examples/s3/deletebucket/index.html @@ -1,14 +1,15 @@ - - - - - - DeleteBucketv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/s3/deleteobject/index.html b/docs/docs/code-examples/s3/deleteobject/index.html index 3960939554c..e5824454e8d 100644 --- a/docs/docs/code-examples/s3/deleteobject/index.html +++ b/docs/docs/code-examples/s3/deleteobject/index.html @@ -1,14 +1,15 @@ - - - - - - DeleteObjectv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/s3/generatepresignedurl/index.html b/docs/docs/code-examples/s3/generatepresignedurl/index.html index 95b60d92100..e5824454e8d 100644 --- a/docs/docs/code-examples/s3/generatepresignedurl/index.html +++ b/docs/docs/code-examples/s3/generatepresignedurl/index.html @@ -1,14 +1,15 @@ - - - - - - GeneratePresignedURLv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/s3/getbucketacl/index.html b/docs/docs/code-examples/s3/getbucketacl/index.html index 3756dfc43ea..e5824454e8d 100644 --- a/docs/docs/code-examples/s3/getbucketacl/index.html +++ b/docs/docs/code-examples/s3/getbucketacl/index.html @@ -1,14 +1,15 @@ - - - - - - GetBucketAclv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/s3/getobjectacl/index.html b/docs/docs/code-examples/s3/getobjectacl/index.html index b6b5c7d5618..e5824454e8d 100644 --- a/docs/docs/code-examples/s3/getobjectacl/index.html +++ b/docs/docs/code-examples/s3/getobjectacl/index.html @@ -1,14 +1,15 @@ - - - - - - GetObjectAclv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/s3/index.html b/docs/docs/code-examples/s3/index.html index f1c0b0bec26..e5824454e8d 100644 --- a/docs/docs/code-examples/s3/index.html +++ b/docs/docs/code-examples/s3/index.html @@ -1,681 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -Amazon S3 Examples | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Amazon S3 Examples

- -
- - - - - - - - - - - - - -
-

This section contains code examples for Amazon S3 using version 2 of the AWS SDK for Go.

- -
- - - - - - - - -
- - -
-
- CopyObjectv2 -
-

-
- - -
-
- CreateBucketv2 -
-

-
- - -
-
- DeleteBucketv2 -
-

-
- - -
-
- DeleteObjectv2 -
-

-
- - -
-
- GeneratePresignedURLv2 -
-

-
- - -
-
- GetBucketAclv2 -
-

-
- - -
-
- GetObjectAclv2 -
-

-
- - -
-
- ListBucketsv2 -
-

-
- - -
-
- ListObjectsv2 -
-

-
- - -
-
- PutObjectv2 -
-

-
- - -
- - - -
- Last modified January 14, 2021: Added code examples from AWS SDK docs repo (#1015) (6b77d0a0af) -
- -
- -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/code-examples/s3/listbuckets/index.html b/docs/docs/code-examples/s3/listbuckets/index.html index 3ecfcbf0d47..e5824454e8d 100644 --- a/docs/docs/code-examples/s3/listbuckets/index.html +++ b/docs/docs/code-examples/s3/listbuckets/index.html @@ -1,14 +1,15 @@ - - - - - - ListBucketsv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/s3/listobjects/index.html b/docs/docs/code-examples/s3/listobjects/index.html index 59e0ce54919..e5824454e8d 100644 --- a/docs/docs/code-examples/s3/listobjects/index.html +++ b/docs/docs/code-examples/s3/listobjects/index.html @@ -1,14 +1,15 @@ - - - - - - ListObjectsv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/s3/putobject/index.html b/docs/docs/code-examples/s3/putobject/index.html index 8cf870dff15..e5824454e8d 100644 --- a/docs/docs/code-examples/s3/putobject/index.html +++ b/docs/docs/code-examples/s3/putobject/index.html @@ -1,14 +1,15 @@ - - - - - - PutObjectv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sns/createtopic/index.html b/docs/docs/code-examples/sns/createtopic/index.html index 18ce5b57fe6..e5824454e8d 100644 --- a/docs/docs/code-examples/sns/createtopic/index.html +++ b/docs/docs/code-examples/sns/createtopic/index.html @@ -1,14 +1,15 @@ - - - - - - CreateTopicv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sns/index.html b/docs/docs/code-examples/sns/index.html index 83810b2fb0e..e5824454e8d 100644 --- a/docs/docs/code-examples/sns/index.html +++ b/docs/docs/code-examples/sns/index.html @@ -1,641 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -Amazon SNS Examples | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Amazon SNS Examples

- -
- - - - - - - - - - - - - -
-

This section contains code examples for Amazon SNS using version 2 of the AWS SDK for Go.

- -
- - - - - - - - -
- - -
-
- CreateTopicv2 -
-

-
- - -
-
- ListSubscriptionsv2 -
-

-
- - -
-
- ListTopicsv2 -
-

-
- - -
-
- Publishv2 -
-

-
- - -
-
- Subscribev2 -
-

-
- - -
- - - -
- Last modified January 14, 2021: Added code examples from AWS SDK docs repo (#1015) (6b77d0a0af) -
- -
- -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/code-examples/sns/listsubscriptions/index.html b/docs/docs/code-examples/sns/listsubscriptions/index.html index dfc18b3d3c3..e5824454e8d 100644 --- a/docs/docs/code-examples/sns/listsubscriptions/index.html +++ b/docs/docs/code-examples/sns/listsubscriptions/index.html @@ -1,14 +1,15 @@ - - - - - - ListSubscriptionsv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sns/listtopics/index.html b/docs/docs/code-examples/sns/listtopics/index.html index 88b82643ca1..e5824454e8d 100644 --- a/docs/docs/code-examples/sns/listtopics/index.html +++ b/docs/docs/code-examples/sns/listtopics/index.html @@ -1,14 +1,15 @@ - - - - - - ListTopicsv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sns/publish/index.html b/docs/docs/code-examples/sns/publish/index.html index 98bfd21d04c..e5824454e8d 100644 --- a/docs/docs/code-examples/sns/publish/index.html +++ b/docs/docs/code-examples/sns/publish/index.html @@ -1,14 +1,15 @@ - - - - - - Publishv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sns/subscribe/index.html b/docs/docs/code-examples/sns/subscribe/index.html index 5ab023bd0ee..e5824454e8d 100644 --- a/docs/docs/code-examples/sns/subscribe/index.html +++ b/docs/docs/code-examples/sns/subscribe/index.html @@ -1,14 +1,15 @@ - - - - - - Subscribev2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sqs/changemsgvisibility/index.html b/docs/docs/code-examples/sqs/changemsgvisibility/index.html index 13f44397015..e5824454e8d 100644 --- a/docs/docs/code-examples/sqs/changemsgvisibility/index.html +++ b/docs/docs/code-examples/sqs/changemsgvisibility/index.html @@ -1,14 +1,15 @@ - - - - - - ChangeMsgVisibilityv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sqs/configurelpqueue/index.html b/docs/docs/code-examples/sqs/configurelpqueue/index.html index 60c595fae46..e5824454e8d 100644 --- a/docs/docs/code-examples/sqs/configurelpqueue/index.html +++ b/docs/docs/code-examples/sqs/configurelpqueue/index.html @@ -1,14 +1,15 @@ - - - - - - ConfigureLPQueuev2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sqs/createlpqueue/index.html b/docs/docs/code-examples/sqs/createlpqueue/index.html index e88500ccafa..e5824454e8d 100644 --- a/docs/docs/code-examples/sqs/createlpqueue/index.html +++ b/docs/docs/code-examples/sqs/createlpqueue/index.html @@ -1,14 +1,15 @@ - - - - - - CreateLPQueuev2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sqs/createqueue/index.html b/docs/docs/code-examples/sqs/createqueue/index.html index f5853b2e8ca..e5824454e8d 100644 --- a/docs/docs/code-examples/sqs/createqueue/index.html +++ b/docs/docs/code-examples/sqs/createqueue/index.html @@ -1,14 +1,15 @@ - - - - - - CreateQueuev2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sqs/deadletterqueue/index.html b/docs/docs/code-examples/sqs/deadletterqueue/index.html index 4b19b79c5c7..e5824454e8d 100644 --- a/docs/docs/code-examples/sqs/deadletterqueue/index.html +++ b/docs/docs/code-examples/sqs/deadletterqueue/index.html @@ -1,14 +1,15 @@ - - - - - - DeadLetterQueuev2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sqs/deletemessage/index.html b/docs/docs/code-examples/sqs/deletemessage/index.html index 5c7feaf2879..e5824454e8d 100644 --- a/docs/docs/code-examples/sqs/deletemessage/index.html +++ b/docs/docs/code-examples/sqs/deletemessage/index.html @@ -1,14 +1,15 @@ - - - - - - DeleteMessagev2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sqs/deletequeue/index.html b/docs/docs/code-examples/sqs/deletequeue/index.html index 1ee675d13d0..e5824454e8d 100644 --- a/docs/docs/code-examples/sqs/deletequeue/index.html +++ b/docs/docs/code-examples/sqs/deletequeue/index.html @@ -1,14 +1,15 @@ - - - - - - DeleteQueuev2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sqs/getqueueurl/index.html b/docs/docs/code-examples/sqs/getqueueurl/index.html index 6b92b724825..e5824454e8d 100644 --- a/docs/docs/code-examples/sqs/getqueueurl/index.html +++ b/docs/docs/code-examples/sqs/getqueueurl/index.html @@ -1,14 +1,15 @@ - - - - - - GetQueueURLv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sqs/index.html b/docs/docs/code-examples/sqs/index.html index c2f36a94995..e5824454e8d 100644 --- a/docs/docs/code-examples/sqs/index.html +++ b/docs/docs/code-examples/sqs/index.html @@ -1,697 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -Amazon SQS Examples | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Amazon SQS Examples

- -
- - - - - - - - - - - - - -
-

This section contains code examples for Amazon SQS using version 2 of the AWS SDK for Go.

- -
- - - - - - - - -
- - -
-
- ChangeMsgVisibilityv2 -
-

-
- - -
-
- ConfigureLPQueuev2 -
-

-
- - -
-
- CreateLPQueuev2 -
-

-
- - -
-
- CreateQueuev2 -
-

-
- - -
-
- DeadLetterQueuev2 -
-

-
- - -
-
- DeleteMessagev2 -
-

-
- - -
-
- DeleteQueuev2 -
-

-
- - -
-
- GetQueueURLv2 -
-

-
- - -
-
- ListQueuesv2 -
-

-
- - -
-
- ReceiveLPMessagev2 -
-

-
- - -
-
- ReceiveMessagev2 -
-

-
- - -
-
- SendMessagev2 -
-

-
- - -
- - - -
- Last modified January 14, 2021: Added code examples from AWS SDK docs repo (#1015) (6b77d0a0af) -
- -
- -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/code-examples/sqs/listqueues/index.html b/docs/docs/code-examples/sqs/listqueues/index.html index 7784517bc49..e5824454e8d 100644 --- a/docs/docs/code-examples/sqs/listqueues/index.html +++ b/docs/docs/code-examples/sqs/listqueues/index.html @@ -1,14 +1,15 @@ - - - - - - ListQueuesv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sqs/receivelpmessage/index.html b/docs/docs/code-examples/sqs/receivelpmessage/index.html index f4cf4d331ce..e5824454e8d 100644 --- a/docs/docs/code-examples/sqs/receivelpmessage/index.html +++ b/docs/docs/code-examples/sqs/receivelpmessage/index.html @@ -1,14 +1,15 @@ - - - - - - ReceiveLPMessagev2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sqs/receivemessage/index.html b/docs/docs/code-examples/sqs/receivemessage/index.html index 84347b79856..e5824454e8d 100644 --- a/docs/docs/code-examples/sqs/receivemessage/index.html +++ b/docs/docs/code-examples/sqs/receivemessage/index.html @@ -1,14 +1,15 @@ - - - - - - ReceiveMessagev2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sqs/sendmessage/index.html b/docs/docs/code-examples/sqs/sendmessage/index.html index 8733ad8185a..e5824454e8d 100644 --- a/docs/docs/code-examples/sqs/sendmessage/index.html +++ b/docs/docs/code-examples/sqs/sendmessage/index.html @@ -1,14 +1,15 @@ - - - - - - SendMessagev2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/ssm/deleteparameter/index.html b/docs/docs/code-examples/ssm/deleteparameter/index.html index c3516416166..e5824454e8d 100644 --- a/docs/docs/code-examples/ssm/deleteparameter/index.html +++ b/docs/docs/code-examples/ssm/deleteparameter/index.html @@ -1,14 +1,15 @@ - - - - - - DeleteParameterv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/ssm/getparameter/index.html b/docs/docs/code-examples/ssm/getparameter/index.html index cb2d8ff6631..e5824454e8d 100644 --- a/docs/docs/code-examples/ssm/getparameter/index.html +++ b/docs/docs/code-examples/ssm/getparameter/index.html @@ -1,14 +1,15 @@ - - - - - - GetParameterv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/ssm/index.html b/docs/docs/code-examples/ssm/index.html index d353bda0ecd..e5824454e8d 100644 --- a/docs/docs/code-examples/ssm/index.html +++ b/docs/docs/code-examples/ssm/index.html @@ -1,625 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -AWS Systems Manager Examples | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

AWS Systems Manager Examples

- -
- - - - - - - - - - - - - -
-

This section contains code examples for AWS Systems Manager using version 2 of the AWS SDK for Go.

- -
- - - - - - - - -
- - -
-
- DeleteParameterv2 -
-

-
- - -
-
- GetParameterv2 -
-

-
- - -
-
- PutParameterv2 -
-

-
- - -
- - - -
- Last modified January 14, 2021: Added code examples from AWS SDK docs repo (#1015) (6b77d0a0af) -
- -
- -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/code-examples/ssm/putparameter/index.html b/docs/docs/code-examples/ssm/putparameter/index.html index ceebbc05f3c..e5824454e8d 100644 --- a/docs/docs/code-examples/ssm/putparameter/index.html +++ b/docs/docs/code-examples/ssm/putparameter/index.html @@ -1,14 +1,15 @@ - - - - - - PutParameterv2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sts/assumerole/index.html b/docs/docs/code-examples/sts/assumerole/index.html index ee665938aa5..e5824454e8d 100644 --- a/docs/docs/code-examples/sts/assumerole/index.html +++ b/docs/docs/code-examples/sts/assumerole/index.html @@ -1,14 +1,15 @@ - - - - - - AssumeRolev2 - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ diff --git a/docs/docs/code-examples/sts/index.html b/docs/docs/code-examples/sts/index.html index 3037a9f61fb..e5824454e8d 100644 --- a/docs/docs/code-examples/sts/index.html +++ b/docs/docs/code-examples/sts/index.html @@ -1,609 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -AWS STS Examples | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

AWS STS Examples

- -
- - - - - - - - - - - - - -
-

This section contains code examples for AWS STS using version 2 of the AWS SDK for Go.

- -
- - - - - - - - -
- - -
-
- AssumeRolev2 -
-

-
- - -
- - - -
- Last modified January 14, 2021: Added code examples from AWS SDK docs repo (#1015) (6b77d0a0af) -
- -
- -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/configuring-sdk/auth/index.html b/docs/docs/configuring-sdk/auth/index.html index 53c1168f33c..e5824454e8d 100644 --- a/docs/docs/configuring-sdk/auth/index.html +++ b/docs/docs/configuring-sdk/auth/index.html @@ -1,863 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Configuring Authentication | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Configuring Authentication

-
Customizing service client authentication.
-
- - - - - - - - - - - - - -
-

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.

-

Definitions

-

This section provides a high-level description of authentication components in -the AWS SDK for Go V2.

-

AuthScheme

-

An AuthScheme is the -interface that defines the workflow through which the SDK retrieves a caller -identity and attaches it to an operation request.

-

An auth scheme uses the following components, described in detail further -below:

-
    -
  • A 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.

-

AuthSchemeResolver

-

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.

-

IMPORTANT: 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.

-

Option

-

Returned from a call to ResolverAuthSchemes, an Option represents a possible authentication option.

-

An option consists of three sets of information:

-
    -
  • An 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.

-

Identity

-

An Identity is an abstract -representation of who the SDK caller is.

-

The 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.

-

Note: 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.

-

IdentityResolver

-

IdentityResolver is the -interface through which an Identity is retrieved.

-

Concrete versions of IdentityResolver exist in the SDK in strongly-typed form -(e.g. aws.CredentialsProvider), the -SDK handles this mapping internally.

-

A caller will only need to directly implement the IdentityResolver interface -when defining an external auth scheme.

-

Signer

-

Signer is the interface -through which a request is supplemented with the retrieved caller Identity.

-

Concrete versions of Signer exist in the SDK in strongly-typed form -(e.g. v4.HTTPSigner), the SDK -handles this mapping internally.

-

A caller will only need to directly implement the Signer interface -when defining an external auth scheme.

-

AuthResolverParameters

-

Each service takes a specific set of inputs which are passed to its resolution -function, defined in each service package as AuthResolverParameters.

-

The base resolver parameters are as follows:

- - - - - - - - - - - - - - - - - - - - -
nametypedescription
OperationstringThe name of the operation being invoked.
RegionstringThe 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.

-

Auth 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:

-
    -
  1. The SDK calls the client’s AuthSchemeResolver.ResolveAuthSchemes() API, -sourcing the input parameters as necessary, to obtain a list of possible -Options for the operation.
    2. -
  2. 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)
      • -
    -
    3. -
  3. 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.
    4. -
  4. The SDK calls the identity resolver’s GetIdentity() (e.g. -aws.CredentialProvider.Retrieve() for SigV4).
    5. -
  5. 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).
    6. -
  6. 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.
    7. -
-

(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.

-

Natively-supported AuthSchemes

-

The following auth schemes are natively supported by AWS SDK for Go V2.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameScheme IDIdentity resolverSignerNotes
SigV4aws.auth#sigv4aws.CredentialsProviderv4.HTTPSignerThe current default for most AWS service operations.
SigV4Aaws.auth#sigv4aaws.CredentialsProvidern/aSigV4A usage is limited at this time, the signer implementation is internal.
SigV4Expresscom.amazonaws.s3#sigv4expresss3.ExpressCredentialsProviderv4.HTTPSignerUsed for Express One Zone.
HTTP Bearersmithy.api#httpBearerAuthsmithybearer.TokenProvidersmithybearer.SignerUsed by codecatalyst.
Anonymoussmithy.api#noAuthn/an/aNo 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.

-

Note: 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{}).

-

Signer 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.

-

Custom auth scheme

-

In order to define a custom auth scheme and configure it for use, the caller -must do the following:

-
    -
  1. Define an AuthScheme -implementation
    2. -
  2. Register the scheme on the SDK client’s AuthSchemes list
    3. -
  3. Instrument the SDK client’s AuthSchemeResolver to return an auth Option -with the scheme’s ID where applicable
    4. -
- - -
-

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:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ServiceNotes
S3Conditional use of SigV4A and SigV4Express depending on operation input.
EventBridgeConditional use of SigV4A depending on operation input.
CognitoCertain operations are anonymous-only.
SSOCertain operations are anonymous-only.
STSCertain operations are anonymous-only.
- -
- - - - -
- Last modified December 19, 2023: Add authentication config guide (#2426) (766cb48e53) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/configuring-sdk/custom-http/index.html b/docs/docs/configuring-sdk/custom-http/index.html index 844d74d3170..e5824454e8d 100644 --- a/docs/docs/configuring-sdk/custom-http/index.html +++ b/docs/docs/configuring-sdk/custom-http/index.html @@ -1,735 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Customizing the HTTP Client | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Customizing the HTTP Client

-
Create a custom HTTP client with the AWS SDK for Go V2 to specify custom timeout values.
-
- - - - - - - - - - - - - -
-

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. For more information, please refer to our FAQ as configuration recommendations vary based on specific workloads. -This section describes how to configure a custom HTTP client, and use that client to create AWS SDK for Go V2 calls.

-

To 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.

-

Let’s define what we want to customize.

-

Overriding 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:

-
cfg, 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:

-
import "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.

-
import 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.

-

Set to a negative value to disable keep-alives.

-

Set to 0 to enable keep-alives if supported by the protocol and operating system.

-

Network protocols or operating systems that do not support keep-alives ignore this field. By default, TCP enables keep -alive.

-

See https://golang.org/pkg/net/#Dialer.KeepAlive

-

Set KeepAlive as time.Duration.

-

Dialer.Timeout

-

This setting represents the maximum amount of time a dial waits for a connection to be created.

-

Default is 30 seconds.

-

See https://golang.org/pkg/net/#Dialer.Timeout

-

Set Timeout as time.Duration.

-

Transport

-

The BuildableHTTPClient provides a builder mechanics for constructing clients with modified -Transport options.

-

Configuring 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:

-
import 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:

-
import 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.

-

Default 1 second.

-

Set 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.

-

See https://golang.org/pkg/net/http/#Transport.ExpectContinueTimeout

-

Set ExpectContinue as time.Duration.

-

Transport.IdleConnTimeout

-

This setting represents the maximum amount of time to keep an idle network connection alive between HTTP requests.

-

Set to 0 for no limit.

-

See https://golang.org/pkg/net/http/#Transport.IdleConnTimeout

-

Set IdleConnTimeout as time.Duration.

-

Transport.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

-

0 means no limit.

-

See https://golang.org/pkg/net/http/#Transport.MaxIdleConns

-

SetMaxIdleConns as int.

-

Transport.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

-

Default is two idle connections per host.

-

Set to 0 to use DefaultMaxIdleConnsPerHost (2).

-

See https://golang.org/pkg/net/http/#Transport.MaxIdleConnsPerHost

-

Set MaxIdleConnsPerHost as int.

-

Transport.ResponseHeaderTimeout

-

This setting represents the maximum amount of time to wait for a client to read the response header.

-

If the client isn’t able to read the response’s header within this duration, the request fails with a timeout error.

-

Be 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.

-

Default is no timeout; wait forever.

-

See https://golang.org/pkg/net/http/#Transport.ResponseHeaderTimeout

-

Set ResponseHeaderTimeout as time.Duration.

-

Transport.TLSHandshakeTimeout

-

This setting represents the maximum amount of time waiting for a TLS handshake to be completed.

-

Default is 10 seconds.

-

Zero means no timeout.

-

See https://golang.org/pkg/net/http/#Transport.TLSHandshakeTimeout

-

Set TLSHandshakeTimeout as time.Duration.

- - - -
- Last modified September 11, 2024: fixing code example and adding clarifications to docs (#2781) (6ae12f1824) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/configuring-sdk/endpoints/index.html b/docs/docs/configuring-sdk/endpoints/index.html index 985639b2c31..e5824454e8d 100644 --- a/docs/docs/configuring-sdk/endpoints/index.html +++ b/docs/docs/configuring-sdk/endpoints/index.html @@ -1,1056 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Configuring Client Endpoints | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Configuring Client Endpoints

-
Customizing service client endpoints.
-
- - - - - - - - - - - - - -
- - -
-

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.

- -
- -

The 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.

-

Customization

-

There are two “versions” of endpoint resolution config within the SDK.

-
    -
  • v2, 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.

-

V2: 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).

-

Resolution 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.

-

For 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).

-

In practice, BaseEndpoint will most likely be used to point your client at a -development or preview instance of a service.

-

EndpointResolverV2 parameters

-

Each service takes a specific set of inputs which are passed to its resolution -function, defined in each service package as EndpointParameters.

-

Every service includes the following base parameters, which are used to -facilitate general endpoint resolution within AWS:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
nametypedescription
RegionstringThe client’s AWS region
EndpointstringThe value set for BaseEndpoint in client config
UseFipsboolWhether FIPS endpoints are enabled in client config
UseDualStackboolWhether 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.

-

If 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.

-

A 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.

-

Because 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).

-

Examples

-

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.

-
client := 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.

-
import (
-    "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 = &resolverV2{
-            // ...
-        }
-    })
-}
-

With both

-

The following sample program demonstrates the interaction between -BaseEndpoint and EndpointResolverV2. This is an advanced use case:

-
import (
-    "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 = &resolverV2{}
-    })
-
-    // ignore the output, this is just for demonstration
-    client.ListBuckets(context.Background(), nil)
-}
-

When run, the above program outputs the following:

-
The 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.

-

Use 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.

- -
- -

A 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.

-

A 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.

-

The 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.

-

An 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.

-

If your endpoint resolver implementation returns an error other than -EndpointNotFoundError, endpoint resolution will stop and the service -operation returns an error to your application.

-

Examples

-

With fallback

-

The following code snippet shows how a single service endpoint can be -overridden for DynamoDB with fallback behavior for other -endpoints:

-
customResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
-    if service == dynamodb.ServiceID && 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{}, &aws.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:

-
customResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
-    if service == dynamodb.ServiceID && 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.

- -
- -

Some 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:

-
customResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
-    if service == dynamodb.ServiceID && 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:

-
    -
  • Returning 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. -
      -
    • The primary exception is for operations with modeled endpoint prefixes. A -note on this is given further down.
      • -
    -
    • -
-

Examples for these cases are provided below.

- - -
-

V1 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.

- -
- -

Note on host prefixes

-

Some operations are modeled with host prefixes to be prepended to the resolved -endpoint. This behavior must work in tandem with the output of -ResolveEndpointV2 and therefore the host prefix will still be applied to that -result.

-

You can manually disable endpoint host prefixing by applying a middleware, see -the examples section.

-

Examples

-

Mutable endpoint

-

The following code sample demonstrates how to migrate a basic v1 endpoint -resolver that returns a modifiable endpoint:

-
// 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 = &staticResolver{}
-})
-

Disable host prefix

-
import (
-    "context"
-    "fmt"
-    "net/url"
-
-    "github.com/aws/aws-sdk-go-v2/aws"
-    "github.com/aws/aws-sdk-go-v2/config"
-    "github.com/aws/aws-sdk-go-v2/service/<service>"
-    smithyendpoints "github.com/aws/smithy-go/endpoints"
-    "github.com/aws/smithy-go/middleware"
-    smithyhttp "github.com/aws/smithy-go/transport/http"
-)
-
-// disableEndpointPrefix applies the flag that will prevent any
-// operation-specific host prefix from being applied
-type disableEndpointPrefix struct{}
-
-func (disableEndpointPrefix) ID() string { return "disableEndpointPrefix" }
-
-func (disableEndpointPrefix) HandleInitialize(
-    ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler,
-) (middleware.InitializeOutput, middleware.Metadata, error) {
-    ctx = smithyhttp.SetHostnameImmutable(ctx, true)
-    return next.HandleInitialize(ctx, in)
-}
-
-func addDisableEndpointPrefix(o *<service>.Options) {
-    o.APIOptions = append(o.APIOptions, (func(stack *middleware.Stack) error {
-        return stack.Initialize.Add(disableEndpointPrefix{}, middleware.After)
-    }))
-}
-
-type staticResolver struct{}
-
-func (staticResolver) ResolveEndpoint(ctx context.Context, params <service>.EndpointParameters) (
-    smithyendpoints.Endpoint, error,
-) {
-    u, err := url.Parse("https://custom.endpoint.api/")
-    if err != nil {
-        return smithyendpoints.Endpoint{}, err
-    }
-
-    return smithyendpoints.Endpoint{URI: *u}, nil
-}
-
-
-func main() {
-    cfg, err := config.LoadDefaultConfig(context.Background())
-    if err != nil {
-        panic(err)
-    }
-
-    svc := <service>.NewFromConfig(cfg, func(o *<service>.Options) {
-        o.EndpointResolverV2 = staticResolver{}
-    })
-
-    _, err = svc.<Operation>(context.Background(), &<service>.<OperationInput>{ /* ... */ },
-        addDisableEndpointPrefix)
-    if err != nil {
-        panic(err)
-    }
-}
-
- - -
- Last modified September 11, 2024: add blurb on disabling endpoint prefix (9b54222000) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/configuring-sdk/index.html b/docs/docs/configuring-sdk/index.html index 6d960ff5e31..e5824454e8d 100644 --- a/docs/docs/configuring-sdk/index.html +++ b/docs/docs/configuring-sdk/index.html @@ -1,1021 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -Configuring the AWS SDK for Go V2 | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Configuring the AWS SDK for Go V2

- -
- - - - - - - - - - - - - -
-

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.

-

Loading 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.

-

To configure the SDK to use the AWS shared configuration use the following code:

-
import (
-  "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.

-

For 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.

-

The SDK does not have a default Region. To specify a Region:

-
    -
  • -

    Set the AWS_REGION environment variable to the default Region

    -
    • -
  • -

    Set the region explicitly -using config.WithRegion -as an argument to config.LoadDefaultConfig when loading configuration.

    -
    • -
-

If you set a Region using all of these techniques, the SDK uses the Region you explicitly specified.

-
Configure 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.

-

When 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:

-
    -
  1. Environment variables. -
      -
    1. Static Credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
      2. -
    2. Web Identity Token (AWS_WEB_IDENTITY_TOKEN_FILE)
      3. -
    -
    2. -
  2. Shared configuration files. -
      -
    1. SDK defaults to credentials file under .aws folder that is placed in the home folder on your computer.
      2. -
    2. SDK defaults to config file under .aws folder that is placed in the home folder on your computer.
      3. -
    -
    3. -
  3. If your application uses an ECS task definition or RunTask API operation, -IAM role for tasks.
    4. -
  4. If your application is running on an Amazon EC2 instance, IAM role for Amazon EC2.
    5. -
-

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.

-

As a best practice, AWS recommends that you specify credentials in the -following order:

-
    -
  1. -

    Use IAM roles for tasks if your application uses an ECS task definition or RunTask API operation.

    -
    2. -
  2. -

    Use IAM roles for Amazon EC2 (if your application is running on an -Amazon EC2 instance).

    -

    IAM 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.

    -
    3. -
  3. -

    Use shared credentials or config files.

    -

    The 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.

    -
    4. -
  4. -

    Use environment variables.

    -

    Setting environment variables is useful if you’re doing development -work on a machine other than an Amazon EC2 instance.

    -
    5. -
-

IAM 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.

-

IAM 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.

-

If 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.

-

Shared 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.

-

You 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.

-
import (
-    "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"},
-    )	
-) 
-

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,

-
    -
  1. -

    If duplicate profiles are specified within a same credentials/config file, -the profile properties specified in the latter profile takes precedence.

    -
    2. -
  2. -

    If 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.

    -
    3. -
  3. -

    If a profile exists in both credentials file and config file, the credentials file -properties take precedence.

    -
    4. -
-

If need be, you can enable LogConfigurationWarnings on config.LoadOptions, and -log the profile resolution steps.

-

Creating 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 -<YOUR_ACCESS_KEY_ID> and <YOUR_SECRET_ACCESS_KEY> with your -credentials.

-
[default]
-aws_access_key_id = <YOUR_ACCESS_KEY_ID>
-aws_secret_access_key = <YOUR_SECRET_ACCESS_KEY>
-

The [default] heading defines credentials for the default profile, -which the SDK will use unless you configure it to use another profile.

-

You can also use temporary security credentials by adding the session -tokens to your profile, as shown in the following example:

-
[temp]
-aws_access_key_id = <YOUR_TEMP_ACCESS_KEY_ID>
-aws_secret_access_key = <YOUR_TEMP_SECRET_ACCESS_KEY>
-aws_session_token = <YOUR_SESSION_TOKEN>
-

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.

-

Creating 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 <REGION> with the -desired region.

-
[default]
-region = <REGION>
-

The [default] heading defines config for the default profile, -which the SDK will use unless you configure it to use another profile.

-

You use named profiles, as shown in the following example:

-
[profile named-profile]
-region = <REGION>
-

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.

-

Specifying 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.

-
[default]
-aws_access_key_id = <YOUR_DEFAULT_ACCESS_KEY_ID>
-aws_secret_access_key = <YOUR_DEFAULT_SECRET_ACCESS_KEY>
-
-[test-account]
-aws_access_key_id = <YOUR_TEST_ACCESS_KEY_ID>
-aws_secret_access_key = <YOUR_TEST_SECRET_ACCESS_KEY>
-
-[prod-account]
-; work profile
-aws_access_key_id = <YOUR_PROD_ACCESS_KEY_ID>
-aws_secret_access_key = <YOUR_PROD_SECRET_ACCESS_KEY>
-

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.

-

Sometimes, 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:

-
$ 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:

-
cfg, 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.

- -
- -

Environment 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.

-

The SDK looks for credentials in the following environment variables:

-
    -
  • AWS_ACCESS_KEY_ID
    • -
  • AWS_SECRET_ACCESS_KEY
    • -
  • AWS_SESSION_TOKEN (optional)
    • -
-

The following examples show how you configure the environment variables.

-

Linux, 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

-
> set AWS_ACCESS_KEY_ID=YOUR_AKID
-> set AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
-> 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 explicit 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:

-
cfg, err := config.LoadDefaultConfig(context.TODO(), 
-	config.WithCredentialsProvider(customProvider))
-

If you explicitly provide credentials, as in this example, the SDK uses only those credentials.

- - -
-

All credential providers passed to or returned by LoadDefaultConfig are wrapped in a -CredentialsCache automatically. This enables caching, and credential rotation that is concurrency safe. If you explicitly configure a provider on aws.Config directly you must also explicitly wrap the provider -with this type using NewCredentialsCache.

- -
- -

Static 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:

-
cfg, 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.

- -
- -

Single 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.

-

For example, you can create a profile, dev-profile, authenticate and authorize that profile using the -AWS CLI, and configure your application as shown below.

-
    -
  1. First create the profile and sso-session
    2. -
-
[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
-
    -
  1. Login using the AWS CLI to authenticate and authorize the SSO profile.
    2. -
-
$ 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
-
    -
  1. Next configure your application to use the SSO profile.
    2. -
-
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.

-

Other 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.

-

Available Credential Providers:

-
    -
  • -

    ec2rolecreds – Retrieve Credentials from Amazon EC2 -Instances Roles via Amazon EC2 IMDS.

    -
    • -
  • -

    endpointcreds – Retrieve Credentials from an arbitrary HTTP -endpoint.

    -
    • -
  • -

    processcreds – Retrieve Credentials from an external process that -will be invoked by the host environment’s shell.

    -
    • -
  • -

    stscreds – Retrieve Credentials from AWS STS

    -
    • -
- -
- - - - - - - - -
- - -
-
- Configuring Authentication -
-

Customizing service client authentication.

-
- - -
-
- Configuring Client Endpoints -
-

Customizing service client endpoints.

-
- - -
-
- Customizing the HTTP Client -
-

Create a custom HTTP client with the AWS SDK for Go V2 to specify custom timeout values.

-
- - -
-
- Logging -
-

Using Logging facilities for debugging SDK requests.

-
- - -
-
- Retries and Timeouts -
-

-
- - -
- - - -
- Last modified September 11, 2024: fixing code example and adding clarifications to docs (#2781) (6ae12f1824) -
- -
- -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/configuring-sdk/logging/index.html b/docs/docs/configuring-sdk/logging/index.html index 753ba80dc9e..e5824454e8d 100644 --- a/docs/docs/configuring-sdk/logging/index.html +++ b/docs/docs/configuring-sdk/logging/index.html @@ -1,636 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Logging | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Logging

-
Using Logging facilities for debugging SDK requests.
-
- - - - - - - - - - - - - -
-

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.

-

Logger

-

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.

-

For example to configure our clients to use our applicationLogger:

-
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithLogger(applicationLogger))
-

Now clients configured using the constructed aws.Config will send log messages to applicationLogger.

-

Context-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.

-

ClientLogMode

-

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:

-
    -
  • Signature Version 4 (SigV4) Signing
    • -
  • Request Retries
    • -
  • HTTP Requests
    • -
  • HTTP Responses
    • -
-

For example to enable logging of HTTP requests and retries:

-
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithClientLogMode(aws.LogRetries | aws.LogRequest))
-

See ClientLogMode for the different client log modes available.

- - - -
- Last modified January 15, 2021: Code Example Highlighting, Vairous Documentation Fixes (#1045) (495b900f9e) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/configuring-sdk/retries-timeouts/index.html b/docs/docs/configuring-sdk/retries-timeouts/index.html index 588badd2a51..e5824454e8d 100644 --- a/docs/docs/configuring-sdk/retries-timeouts/index.html +++ b/docs/docs/configuring-sdk/retries-timeouts/index.html @@ -1,827 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Retries and Timeouts | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Retries and Timeouts

- -
- - - - - - - - - - - - - -
-

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.

-

The 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.

-

Standard 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.

-

The following table defines the default values for this retryer:

- - - - - - - - - - - - - - - - - -
PropertyDefault
Max Number of Attempts3
Max Back Off Delay20 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.

-

See the retry package documentation for details on what errors are considered as -retryable by the standard retryer implementation.

-

NopRetryer

-

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.

-

Customizing 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.

- - - - -

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.

-

For example, you can the following code to wrap the standard client retryer with a maximum of five attempts:

-
import "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.

-

For example, you can the following code to wrap the standard client retryer with a desired max delay of five seconds:

-
import "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.

-

For example, you can the following code to wrap the standard client retryer to include the Amazon S3 -NoSuchBucketException exception as retryable.

-
import "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)
-

Client-side rate limiting

-

The AWS SDK for Go V2 introduces a new client-side rate-limiting mechanism -in the standard retry policy to align with the behavior of modern SDKs. This is -behavior is controlled by the RateLimiter -field on a retryer’s options.

-

A RateLimiter operates as a token bucket with a set capacity, where operation -attempt failures consume tokens. A retry that attempts to consume more tokens -than what’s available results in operation failure with a -QuotaExceededError.

-

The default implementation is parameterized as follows (how to modify each setting):

-
    -
  • a capacity of 500 (set the value of RateLimiter on StandardOptions using NewTokenRateLimit)
    • -
  • a retry caused by a timeout costs 10 tokens (set RetryTimeoutCost on StandardOptions)
    • -
  • a retry caused by other errors costs 5 tokens (set RetryCost on StandardOptions)
    • -
  • an operation that succeeds on the 1st attempt adds 1 token (set NoRetryIncrement on StandardOptions) -
      -
    • operations that succeed on the 2nd or later attempt do not add back any tokens
      • -
    -
    • -
-

If you find that the default behavior does not fit your application’s needs, -you can disable it with ratelimit.None.

-

Example: modified rate limiter

-
import (
-    "context"
-
-    "github.com/aws/aws-sdk-go-v2/aws"
-    "github.com/aws/aws-sdk-go-v2/aws/ratelimit"
-    "github.com/aws/aws-sdk-go-v2/aws/retry"
-    "github.com/aws/aws-sdk-go-v2/config"
-)
-
-// ...
-
-cfg, err := config.LoadDefaultConfig(context.Background(), config.WithRetryer(func() aws.Retryer {
-    return retry.NewStandard(func(o *retry.StandardOptions) {
-        // Makes the rate limiter more permissive in general. These values are
-        // arbitrary for demonstration and may not suit your specific
-        // application's needs.
-        o.RateLimiter = ratelimit.NewTokenRateLimit(1000)
-        o.RetryCost = 1
-        o.RetryTimeoutCost = 3
-        o.NoRetryIncrement = 10
-    })
-}))
-

Example: no rate limit using ratelimit.None

-
import (
-    "context"
-
-    "github.com/aws/aws-sdk-go-v2/aws"
-    "github.com/aws/aws-sdk-go-v2/aws/ratelimit"
-    "github.com/aws/aws-sdk-go-v2/aws/retry"
-    "github.com/aws/aws-sdk-go-v2/config"
-)
-
-// ...
-
-cfg, err := config.LoadDefaultConfig(context.Background(), config.WithRetryer(func() aws.Retryer {
-    return retry.NewStandard(func(o *retry.StandardOptions) {
-        o.RateLimiter = ratelimit.None
-    })
-}))
-

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.

-

Setting a timeout

-

The following example shows how to set a timeout for a service client operation.

-
import "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, &s3.GetObjectInput{
-	// input parameters
-})
-if err != nil {
-	// handle error
-}
-
- - -
- Last modified August 31, 2024: Fix typo (#2759) (264eff1b98) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/faq/index.html b/docs/docs/faq/index.html index 6702a5de8e6..e5824454e8d 100644 --- a/docs/docs/faq/index.html +++ b/docs/docs/faq/index.html @@ -1,701 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -Frequently Asked Questions | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Frequently Asked Questions

-
Answers to some commonly-asked questions about the AWS SDK for Go V2
-
- - - - - - - - - - - - - -
-

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:

-
    -
  • the 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:

-
    -
  • All 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.

-

Requests 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:

-
    -
  • Time 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.

-

How 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.

-

However, 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.

-

This 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.

-

This can occur for several reasons:

-
    -
  • You 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.

-

Why 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.

-

If 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.

- -
- - - - - - - - -
- - -
-
- Timing SDK operations -
-

How to perform basic instrumentation in the AWS SDK for Go V2 to time SDK operations

-
- - -
- - - -
- Last modified December 21, 2023: docs: add FAQ/troubleshooting and operation timing guide (#2434) (3f11379952) -
- -
- -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/faq/timing-operations/index.html b/docs/docs/faq/timing-operations/index.html index 3771658faf0..e5824454e8d 100644 --- a/docs/docs/faq/timing-operations/index.html +++ b/docs/docs/faq/timing-operations/index.html @@ -1,819 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Timing SDK operations | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Timing SDK operations

-
How to perform basic instrumentation in the AWS SDK for Go V2 to time SDK operations
-
- - - - - - - - - - - - - -
-

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.

-

The 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:

-
    -
  • AWS 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.

-

The 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.

-

The service used here is interchangeable - ALL service client options accept -APIOptions and an HTTPClient as configuration. For example, -WithOperationTiming could instead be declared as:

-
func 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.

-
import (
-    "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 = &timedHTTPClient{
-            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(&timeOperationMiddleware{msgHandler: mh}, middleware.Before); err != nil {
-            return fmt.Errorf("add time operation middleware: %v", err)
-        }
-        if err := s.Initialize.Add(&addInvokeIDMiddleware{msgHandler: mh}, middleware.Before); err != nil {
-            return fmt.Errorf("add invoke id middleware: %v", err)
-        }
-        if err := s.Initialize.Insert(&emitMetadataMiddleware{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 < 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:

-
[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
-
- - -
- Last modified December 21, 2023: docs: add FAQ/troubleshooting and operation timing guide (#2434) (3f11379952) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/getting-started/index.html b/docs/docs/getting-started/index.html index bfa1dd682db..e5824454e8d 100644 --- a/docs/docs/getting-started/index.html +++ b/docs/docs/getting-started/index.html @@ -1,721 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Getting Started with the AWS SDK for Go V2 | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Getting Started with the AWS SDK for Go V2

- -
- - - - - - - - - - - - - -
-

The AWS SDK for Go requires Go 1.20 or later. You can view your current version of Go by running the following command:

-
go version
-

For information about installing or upgrading your version of Go, see https://golang.org/doc/install.

-

Get 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.

-

Install 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.

-
go 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.

-

The following commands show how to retrieve the standard set of SDK modules to use in your application.

-
go 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.

-

Next 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.

-
go 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

- - -
-

To 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.

- -
- -

To get your access key ID and secret access key.

-
    -
  1. Open the IAM console
    2. -
  2. On the navigation menu, choose Users.
    3. -
  3. Choose your IAM user name (not the check box).
    4. -
  4. Open the Security credentials tab, and then choose Create access key.
    5. -
  5. To see the new access key, choose Show. Your credentials resemble the following: -
      -
    • Access key ID: AKIAIOSFODNN7EXAMPLE
      • -
    • Secret access key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
      • -
    -
    6. -
  6. To download the key pair, choose Download .csv file. Store the keys in a secure location.
    7. -
- - -
-

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.

- -
- - - -

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.

-
package 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(), &s3.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)
-	}
-}
-
- - -
- Last modified December 19, 2023: true up migration guide: iface, endpoints, auth, request customization, s3crypto (#2431) (33023c3b7f) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/handling-errors/index.html b/docs/docs/handling-errors/index.html index 4440bea63bf..e5824454e8d 100644 --- a/docs/docs/handling-errors/index.html +++ b/docs/docs/handling-errors/index.html @@ -1,717 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Handling Errors in the AWS SDK for Go V2 | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Handling Errors in the AWS SDK for Go V2

-
Use the Error interface to handle errors from the AWS SDK for Go V2 or AWS service.
-
- - - - - - - - - - - - - -
-

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.

-

It 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:

-
if 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:

-
import "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.

-

For example:

-
import "log"
-import "github.com/aws/smithy-go"
-
-// ...
-
-if err != nil {
-	var oe *smithy.OperationError
-	if errors.As(err, &oe) {
-		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.

-

For example, to check if an error was a BucketAlreadyExists error:

-
import "log"
-import "github.com/aws/aws-sdk-go-v2/service/s3/types"
-
-// ...
-
-if err != nil {
-	var bne *types.BucketAlreadyExists
-	if errors.As(err, &bne) {
-		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:

-
import "log"
-import "github.com/aws/smithy-go"
-
-// ...
-
-if err != nil {
-	var ae smithy.APIError
-	if errors.As(err, &ae) {
-		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.

-

For example:

-
import "log"
-import awshttp "github.com/aws/aws-sdk-go-v2/aws/transport/http"
-
-// ...
-
-if err != nil {
-	var re *awshttp.ResponseError
-	if errors.As(err, &re) {
-		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.

-

For example:

-
import "log"
-import "github.com/aws/aws-sdk-go-v2/service/s3"
-
-// ...
-
-if err != nil {
-	var re s3.ResponseError
-	if errors.As(err, &re) {
-		log.Printf("requestID: %s, hostID: %s request failure", re.ServiceRequestID(), re.ServiceHostID());
-	}
-	return
-}
-
- - -
- Last modified June 23, 2021: Reference `s3.ResponseError` in documentation (#1311) (71c774a758) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/index.html b/docs/docs/index.html index a29194b7819..e5824454e8d 100644 --- a/docs/docs/index.html +++ b/docs/docs/index.html @@ -1,716 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -Developer Guide | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Developer Guide

- -
- - - - - - - - - - - - - -
-

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).

-

The SDK removes the complexity of coding directly against a web service interface. It hides a lot of the lower-level -plumbing, such as authentication, request retries, and error handling.

-

The SDK also includes helpful utilities. For example, the Amazon S3 download and upload manager can automatically break -up large objects into multiple parts and transfer them in parallel.

-

Use 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.

-

Maintenance 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:

- - -
- - - - - - - - -
- - -
-
- Getting Started with the AWS SDK for Go V2 -
-

-
- - -
-
- Configuring the AWS SDK for Go V2 -
-

-
- - -
-
- Migrating to the AWS SDK for Go V2 -
-

How to migrate to the AWS SDK for Go V2 from AWS SDK for Go V1.

-
- - -
-
- Using the AWS SDK for Go V2 with AWS Services -
-

Construct service clients and make operation calls to send requests to AWS services.

-
- - -
-
- Handling Errors in the AWS SDK for Go V2 -
-

Use the Error interface to handle errors from the AWS SDK for Go V2 or AWS service.

-
- - -
-
- Using the AWS SDK for Go V2 Utilities -
-

Use the AWS SDK for Go V2 utilities to help use AWS services.

-
- - -
-
- Customizing the AWS SDK for Go V2 Client Requests -
-

How to use stack step middleware to customize AWS SDK for Go V2 client requests.

-
- - -
-
- Frequently Asked Questions -
-

Answers to some commonly-asked questions about the AWS SDK for Go V2

-
- - -
-
- Unit Testing with the AWS SDK for Go V2 -
-

How to mock the AWS SDK for Go V2 when unit testing your application.

-
- - -
-
- Using AWS Cloud9 with the AWS SDK for Go V2 -
-

-
- - -
-
- Security for this AWS Product or Service -
-

-
- - -
-
- Code Examples -
-

-
- - -
- - - -
- Last modified December 19, 2023: true up migration guide: iface, endpoints, auth, request customization, s3crypto (#2431) (33023c3b7f) -
- -
- -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/making-requests/index.html b/docs/docs/making-requests/index.html index 02838fbbcd4..e5824454e8d 100644 --- a/docs/docs/making-requests/index.html +++ b/docs/docs/making-requests/index.html @@ -1,1124 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Using the AWS SDK for Go V2 with AWS Services | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Using the AWS SDK for Go V2 with AWS Services

-
Construct service clients and make operation calls to send requests to AWS services.
-
- - - - - - - - - - - - - -
-

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.

-

When 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.

-

For the list of service clients, including their methods and parameters, see the AWS SDK for Go V2 API Reference

-

Constructing 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.

-

NewFromConfig

-

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:

-
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 {
-	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:

-
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 {
-	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.

-

New

- - -
-

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.

- -
- -

New 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:

-
import "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:

-
import "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.

-

Calling 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:

-
response, err := client.GetObject(context.TODO(), &s3.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.

-

Passing 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 -<OperationName>Input struct found in the service’s respective Go package. You pass in API input parameters using -the operation input struct.

-

Operation 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.

-

In 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 <Type> and From<Type> 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<Type> functions are helpful when handling service responses.

-

Let’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.<Type> helpers.

-
import "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(), &s3.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.

-

For example to override the client region from “us-west-2” to “us-east-1”:

-
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion("us-west-2"))
-if err != nil {
-	log.Printf("error: %v", err)
-	return
-}
-
-client := s3.NewFromConfig(cfg)
-
-params := &s3.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 <OperationName>Output. 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.

-

For example to log an operation error and prematurely return from the calling function:

-
response, 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.

-

Responses 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.

-

For example, Amazon S3 GetObject operation returns a response -whose Body member is an io.ReadCloser for accessing the object payload.

- - -
-

You 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.

- -
- -
resp, err := s3svc.GetObject(context.TODO(), &s3.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(&myStruct); 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:

-
import "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(), &s3.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.

-

In the following example, an service client is used in multiple goroutines. This example -concurrently uploads two objects to an Amazon S3 bucket.

-
import "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(), &s3.PutObjectInput{
-        Bucket: aws.String("my-bucket"),
-        Key:    aws.String("foo"),
-        Body:   strings.NewReader("foo body content"),
-    })
-    results <- result{Output: output, Err: err}
-}()
-
-go func() {
-    defer wg.Done()
-    output, err := client.PutObject(context.TODO(), &s3.PutObjectInput{
-        Bucket: aws.String("my-bucket"),
-        Key:    aws.String("bar"),
-        Body:   strings.NewReader("bar body content"),
-    })
-    results <- 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.

-

Paginator 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<OperationName>Paginator function. Paginator construct -functions take the service Client, the operation’s <OperationName>Input input parameters, and an optional set of -functional arguments allowing you to configure other optional paginator settings.

-

The 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

-

The 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.

-
import "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 := &s3.ListObjectsV2Input{
-	Bucket: aws.String("my-bucket"),
-}
-
-paginator := s3.NewListObjectsV2Paginator(client, params, func(o *s3.ListObjectsV2PaginatorOptions) {
-	o.Limit = 10
-})
-
-pageNum := 0
-for paginator.HasMorePages() && pageNum < 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

-

Using 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.

-

For 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.

-

Writing 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.

-

For example, you can use waiters to poll if a DynamoDB table -is created and ready for a write operation.

-
import "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 := &dynamodb.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.

-

For example, to override waiter configuration during waiter construction

-
import "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.
-Similar to the above example, you can override waiter configuration per Wait request.

-
// params is the input to api operation used by the waiter
-params := &dynamodb.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.

-

For example, to configure advanced waiter overrides.

-
import "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	
-        }
-    }
-}
-
-// 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
-})
-
- - -
- Last modified December 21, 2023: docs: add FAQ/troubleshooting and operation timing guide (#2434) (3f11379952) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/middleware/index.html b/docs/docs/middleware/index.html index d133f83524c..e5824454e8d 100644 --- a/docs/docs/middleware/index.html +++ b/docs/docs/middleware/index.html @@ -1,928 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Customizing the AWS SDK for Go V2 Client Requests | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Customizing the AWS SDK for Go V2 Client Requests

-
How to use stack step middleware to customize AWS SDK for Go V2 client requests.
-
- - - - - - - - - - - - - -
- - -
-

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.

- -
- -

You 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.

-

Middleware

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Stack StepDescription
InitializePrepares the input, and sets any default parameters as needed.
SerializeSerializes the input to a protocol format suitable for the target transport layer.
BuildAttach additional metadata to the serialized input, such as HTTP Content-Length.
FinalizeFinal message preparation, including retries and authentication (SigV4 signing).
DeserializeDeserialize 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.

-

You 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.

- - -
-

You 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.

- -
- -

Writing 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 <Step>MiddlewareFunc 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.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
StepInterfaceHelper Function
InitializeInitializeMiddlewareInitializeMiddlewareFunc
BuildBuildMiddlewareBuildMiddlewareFunc
SerializeSerializeMiddlewareSerializeMiddlewareFunc
FinalizeFinalizeMiddlewareFinalizeMiddlewareFunc
DeserializeDeserializeMiddlewareDeserializeMiddlewareFunc
-

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.

-
import "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:

-
import "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:

-
import "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(), &s3.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.

-
import "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:

- - - - - - - - - - - - - - - - - - - - - - - - - -
KeyRetrieverDescription
ServiceIDGetServiceIDRetrieve the service identifier for the executing stack. This can be compared to the service client package’s ServiceID constant.
OperationNameGetOperationNameRetrieve the operation name for the executing stack.
LoggerGetLoggerRetrieve 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.

-

The following examples shows how a custom middleware can add metadata that is returned as part of the operation output.

-
import "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(&metadata, "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(), &s3.GetObjectInput{
-	// input parameters
-})
-if err != nil {
-	// handle error
-}
-
-customValue := GetCustomKey(out.ResponseMetadata)
-
- - -
- Last modified January 31, 2024: Update middleware.md (#2471) (44139c8822) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/migrating/index.html b/docs/docs/migrating/index.html index 1afaa851be1..e5824454e8d 100644 --- a/docs/docs/migrating/index.html +++ b/docs/docs/migrating/index.html @@ -1,1997 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -Migrating to the AWS SDK for Go V2 | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Migrating to the AWS SDK for Go V2

-
How to migrate to the AWS SDK for Go V2 from AWS SDK for Go V1.
-
- - - - - - - - - - - - - -
-

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.

-

Modularization

-

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.

-

The following list are some Go modules provided by the SDK:

- - - - - - - - - - - - - - - - - - - - - - - - - -
ModuleDescription
github.com/aws/aws-sdk-go-v2The SDK core
github.com/aws/aws-sdk-go-v2/configShared Configuration Loading
github.com/aws/aws-sdk-go-v2/credentialsAWS Credential Providers
github.com/aws/aws-sdk-go-v2/feature/ec2/imdsAmazon EC2 Instance Metadata Service Client
-

The SDK’s service clients and higher level utilities modules are nested under the following import paths:

- - - - - - - - - - - - - - - - - -
Import RootDescription
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.

-
go get github.com/aws/aws-sdk-go-v2/config
-

The session.New, session.NewSession, -NewSessionWithOptions, and -session.Must must be migrated to -config.LoadDefaultConfig.

-

The 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.

-

For more information on loading shared configuration -see Configuring the AWS SDK for Go V2.

-

Examples

-
Migrating from NewSession to LoadDefaultConfig
-

The following example shows how usage of session.NewSession without additional argument parameters is migrated to -config.LoadDefaultConfig.

-
// 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.

-
// 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.

-
// 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.

-

Usage of *iface should be replaced by scoped caller-defined interfaces for -the service operations being used:

-
// 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(&s3.GetObjectInput{
-        Bucket: &bucket,
-        Key:    &key,
-    })
-    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 := client.GetObject(ctx, &s3.GetObjectInput{
-        Bucket: &bucket,
-        Key:    &key,
-    })
-    if err != nil {
-        return nil, err
-    }
-    defer object.Body.Close()
-
-    return io.ReadAll(object.Body)
-}
-

See the testing guide for more -information.

-

Credentials & 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.

-
go 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.

-

You 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.

-

The following table list the location changes of the AWS credential providers from AWS SDK for Go V1 to -AWS SDK for Go V2.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameV1 ImportV2 Import
Amazon EC2 IAM Role Credentialsgithub.com/aws/aws-sdk-go/aws/credentials/ec2rolecredsgithub.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds
Endpoint Credentialsgithub.com/aws/aws-sdk-go/aws/credentials/endpointcredsgithub.com/aws/aws-sdk-go-v2/credentials/endpointcreds
Process Credentialsgithub.com/aws/aws-sdk-go/aws/credentials/processcredsgithub.com/aws/aws-sdk-go-v2/credentials/processcreds
AWS Security Token Servicegithub.com/aws/aws-sdk-go/aws/credentials/stscredsgithub.com/aws/aws-sdk-go-v2/credentials/stscreds
-

Static Credentials

-

Applications that use credentials.NewStaticCredentials to -construct static credential programmatically must use -credentials.NewStaticCredentialsProvider.

-

Example

-
// 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.

-

The 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.

-

Example

-
// 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.

-

The 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.

-

Process Credentials

-

You must migrate usage of NewCredentials, -NewCredentialsCommand, and -NewCredentialsTimeout to use -NewProvider or -NewProviderCommand.

-

The 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.

-

NewProviderCommand 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.

-

Example

-
// 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.

-

The 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.

-
Example
-
// 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.

-

The 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.

-
Example
-
// 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.

- - - - - - - - - - - - - - - - - - - - - - - - - -
Service NameV1 Import PathV2 Import Path
Amazon S3github.com/aws/aws-sdk-go/service/s3github.com/aws/aws-sdk-go-v2/service/s3
Amazon DynamoDBgithub.com/aws/aws-sdk-go/service/dynamodbgithub.com/aws/aws-sdk-go-v2/service/dynamodb
Amazon CloudWatch Logsgithub.com/aws/aws-sdk-go/service/cloudwatchlogsgithub.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

-
go 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.

-
Example 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, &aws.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.

-

Additionally, 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.

-

By 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.

-

For more information on endpoints and implementing a custom resolver, see -Configuring Client Endpoints.

-

Authentication

-

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.

-

Invoking API Operations

-

The number of service client operation methods have been reduced significantly. The <OperationName>Request, -<OperationName>WithContext, and <OperationName> methods have all been consolidated into single operation method, <OperationName>.

-

Example

-

The following example shows how calls to the <nil> PutObject operation would be migrated from -AWS SDK for Go to AWS SDK for Go V2.

-
// V1
-
-import "context"
-import "github.com/aws/aws-sdk-go/service/s3"
-
-// ...
-
-client := s3.New(sess)
-
-// Pattern 1
-output, err := client.PutObject(&s3.PutObjectInput{
-	// input parameters
-})
-
-// Pattern 2
-output, err := client.PutObjectWithContext(context.TODO(), &s3.PutObjectInput{
-	// input parameters
-})
-
-// Pattern 3
-req, output := client.PutObjectRequest(context.TODO(), &s3.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(), &s3.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 <OperationName>Input and <OperationName>Output, 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.

-

All 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.

-

Enumeration 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 -{{& 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.

-

Pointer 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.

-

The 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.

-

Errors 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.

-

Example

-
// 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(&s3.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(), &s3.GetObjectInput{
-	// input parameters
-})
-if err != nil {
-	var nsk *types.NoSuchKey
-	if errors.As(err, &nsk) {
-		// handle NoSuchKey error
-		return
-	}
-	var apiErr smithy.APIError
-	if errors.As(err, &apiErr) {
-		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 -.

-

Let’s look at an example of how to migrate from a AWS SDK for Go paginator to the AWS SDK for Go V2 equivalent.

-

Example

-
// V1
-
-import "fmt"
-import "github.com/aws/aws-sdk-go/service/s3"
-
-// ...
-
-client := s3.New(sess)
-
-params := &s3.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 := &s3.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.

-

Presigned 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).

-

AWS SDK for Go V2 resolves this by exposing specific PresignClient -implementations in service packages with specific APIs for supported -presignable operations.

-

Note: 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.

-

Uses of Presign and -PresignRequest must -be converted to use service-specific presigning clients.

-

The following example shows how to migrate presigning of an S3 GetObject -request:

-
// 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(&s3.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(), &s3.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.

-

Operation 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:

-

Request handlers which reference Request.Params and Request.Data must be migrated to middleware.

-

migrating 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(&withPutObjectDefaultACL{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(&withReadPutObjectOutput{}, 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.

-

Request handlers which reference Request.HTTPRequest and -Request.HTTPResponse must be migrated to middleware.

-

migrating 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(&withHeader{
-                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.

-

The following table provides a rough mapping of v1 handler phases to their -equivalent location within the V2 middleware stack:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
v1 handler namev2 middleware phase
ValidateInitialize
BuildSerialize
SignFinalize
Sendn/a (1)
ValidateResponseDeserialize
UnmarshalDeserialize
UnmarshalMetadataDeserialize
UnmarshalErrorDeserialize
RetryFinalize, after "Retry" middleware (2)
AfterRetryFinalize, before "Retry" middleware, post-next.HandleFinalize() (2,3)
CompleteAttemptFinalize, end of step
CompleteInitialize, 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.

-

(2) Any middleware after the "Retry" middleware in the Finalize step will be -part of the retry loop.

-

(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.

-

For 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:

-
// 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

-
go 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.

-

Example

-
// 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.

-

s3.NewUploader and -s3.NewUploaderWithClient have been replaced with the -constructor method manager.NewUploader for creating an Upload manager client.

-

s3.NewDownloader and -s3.NewDownloaderWithClient have been replaced with a -single constructor method manager.NewDownloader for creating a -Download manager client.

-

Amazon 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.

-
go 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:

-
go 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.

-

Like other service clients in AWS SDK for Go V2, the operation APIs have -been condensed:

-
    -
  • The 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.

-

Service Customizations Changes

-

S3

-

When migrating from AWS SDK for Go v1 to v2, an important change to be aware of involves the handling of the SSECustomerKey used for server-side encryption with customer-provided keys (SSE-C). In Go SDK v1, the encoding of the SSECustomerKey to Base64 was handled internally by the SDK. In SDK v2, this automatic encoding has been removed, and it is now required to manually encode the SSECustomerKey to Base64 before passing it to the SDK.

-

Example Adjustment:

-
// V1
-
-import (
-  "context"
-  "encoding/base64"
-  "github.com/aws/aws-sdk-go-v2/config"
-  "github.com/aws/aws-sdk-go-v2/service/s3"
-)
-// ... more code
-
-plainTextKey := "12345678901234567890123456789012" // 32 bytes in length
-
-// calculate md5..
-
-_, err = client.PutObjectWithContext(context.Background(), &s3.PutObjectInput{
-    Bucket: aws.String("your-bucket-name"),
-    Key:    aws.String("your-object-key"),
-    Body:                 strings.NewReader("hello-world"),
-    SSECustomerKey:       &plainTextKey,
-    SSECustomerKeyMD5:    &base64Md5,
-    SSECustomerAlgorithm: aws.String("AES256"),
-})
-
-// ... more code
-
// V2
-
-import (
-  "github.com/aws/aws-sdk-go/aws"
-  "github.com/aws/aws-sdk-go/aws/session"
-  "github.com/aws/aws-sdk-go/service/s3"
-)
-
-// ... more code
-
-plainTextKey := "12345678901234567890123456789012" // 32 bytes in length
-base64EncodedKey := base64.StdEncoding.EncodeToString([]byte(plainTextKey))
-
-// calculate md5..
-
-_, err = client.PutObject(context.Background(), &s3.PutObjectInput{
-    Bucket: aws.String("your-bucket-name"),
-    Key:    aws.String("your-object-key"),
-    Body:                 strings.NewReader("hello-world"),
-    SSECustomerKey:       &base64EncodedKey,
-    SSECustomerKeyMD5:    &base64Md5,
-    SSECustomerAlgorithm: aws.String("AES256"),
-})
-
-// ... more code
-
-
- - - - - - - - - -
- - - -
- Last modified September 11, 2024: fixing code example and adding clarifications to docs (#2781) (6ae12f1824) -
- -
- -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/sdk-utilities/cloudfront/index.html b/docs/docs/sdk-utilities/cloudfront/index.html index d65241a5f14..e5824454e8d 100644 --- a/docs/docs/sdk-utilities/cloudfront/index.html +++ b/docs/docs/sdk-utilities/cloudfront/index.html @@ -1,618 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Amazon CloudFront Utilities | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Amazon CloudFront Utilities

-
Using the AWS SDK for Go V2 Amazon CloudFront Utilities
-
- - - - - - - - - - - - - -
-

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).

-

To 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.

-

The following example creates a signed URL that’s valid for one hour -after it is created.

-
import "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.

- - - -
- Last modified November 24, 2020: Developer Guide: SDK Utilities (#924) (cdec04c06f) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/sdk-utilities/ec2-imds/index.html b/docs/docs/sdk-utilities/ec2-imds/index.html index 4519faea1e5..e5824454e8d 100644 --- a/docs/docs/sdk-utilities/ec2-imds/index.html +++ b/docs/docs/sdk-utilities/ec2-imds/index.html @@ -1,629 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Amazon EC2 Instance Metadata Service | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Amazon EC2 Instance Metadata Service

-
Using the AWS SDK for Go V2 Amazon EC2 Instance Metadata Service Client
-
- - - - - - - - - - - - - -
-

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.

-

The 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.

-

For example to construct a client:

-
import "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).

-
localIp, err := client.GetMetadata(context.TODO(), &imds.GetMetadataInput{
-    Path: "local-ipv4",
-})
-if err != nil {
-    log.Printf("Unable to retrieve the private IP address from the EC2 instance: %s\n", err)
-    return
-}
-content, _ := io.ReadAll(localIp.Content)
-fmt.Printf("local-ip: %v\n", string(content))
-

For a list of all metadata categories, see -Instance Metadata Categories -in the Amazon EC2 User Guide.

- - - -
- Last modified September 11, 2024: fixing code example and adding clarifications to docs (#2781) (6ae12f1824) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/sdk-utilities/index.html b/docs/docs/sdk-utilities/index.html index c0469043598..e5824454e8d 100644 --- a/docs/docs/sdk-utilities/index.html +++ b/docs/docs/sdk-utilities/index.html @@ -1,631 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -Using the AWS SDK for Go V2 Utilities | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Using the AWS SDK for Go V2 Utilities

-
Use the AWS SDK for Go V2 utilities to help use AWS services.
-
- - - - - - - - - - - - - -
-

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.

- -
- - - - - - - - -
- - -
-
- Amazon RDS Utilities -
-

Using the AWS SDK for Go V2 Amazon RDS Utilities

-
- - -
-
- Amazon CloudFront Utilities -
-

Using the AWS SDK for Go V2 Amazon CloudFront Utilities

-
- - -
-
- Amazon EC2 Instance Metadata Service -
-

Using the AWS SDK for Go V2 Amazon EC2 Instance Metadata Service Client

-
- - -
-
- Amazon S3 Utilities -
-

-
- - -
- - - -
- Last modified December 23, 2020: Content Updates and Theming (#1001) (b911073c54) -
- -
- -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/sdk-utilities/rds/index.html b/docs/docs/sdk-utilities/rds/index.html index 19018f8da4d..e5824454e8d 100644 --- a/docs/docs/sdk-utilities/rds/index.html +++ b/docs/docs/sdk-utilities/rds/index.html @@ -1,625 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Amazon RDS Utilities | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Amazon RDS Utilities

-
Using the AWS SDK for Go V2 Amazon RDS Utilities
-
- - - - - - - - - - - - - -
-

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:

- -

The following examples shows how to generate an authentication token to connect to an Amazon RDS -database:

-
import "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())
-}
-
- - -
- Last modified February 14, 2023: Update grammar, spelling in rds.md (#1970) (93c2cd9dca) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/sdk-utilities/s3/index.html b/docs/docs/sdk-utilities/s3/index.html index 6bae10d5171..e5824454e8d 100644 --- a/docs/docs/sdk-utilities/s3/index.html +++ b/docs/docs/sdk-utilities/s3/index.html @@ -1,1007 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Amazon S3 Utilities | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Amazon S3 Utilities

- -
- - - - - - - - - - - - - -
-

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.

-

Upload 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.

-

The following example uses the Amazon S3 Uploader to upload a file. -Using Uploader is similar to the s3.PutObject() operation.

-
import "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(), &s3.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:

-
    -
  • PartSize – 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.

-

For 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).

- - -
-

Your application is expected to limit the concurrent calls to Upload to prevent application resource exhaustion.

- -
- -

Below is an example to set the default part size during Uploader creation:

-
uploader := 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.

-

PutObjectInput 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:

-
type 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.

-

Because 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.

-

For 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.

-

Handling 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.

-

You 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.

-
result, err := uploader.Upload(context.TODO(), &s3.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, &mu) {
-		// 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:

-
params := &s3.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.

-
package 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], "<local path> <bucket> <prefix>")
-	}
-	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(), &s3.PutObjectInput{
-			Bucket: &bucket,
-			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 <- 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.

-

Example: Download a File

-

The following example uses the Amazon S3 Downloader to download a file. Using Downloader is similar -to the s3.GetObject operation.

-
import "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, &s3.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.

-

Configuration Options

-

When you instantiate a Downloader instance, you can specify configuration options to customize how objects are -downloaded:

-
    -
  • PartSize – 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.

-

For 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).

- - -
-

Your application is expected to limit the concurrent calls to Download to prevent application resource exhaustion.

- -
- -

For more information about Downloader and its other configuration options, see -manager.Downloader in the AWS SDK for Go V2 API Reference.

-

Overriding 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:

-
params := &s3.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.

-
package 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, &s3.ListObjectsV2Input{
-		Bucket: &Bucket,
-		Prefix: &Prefix,
-	})
-
-	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, &s3.GetObjectInput{Bucket: &bucket, Key: &key})
-
-	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.

-

For example to find the Region for the Bucket my-bucket:

-
cfg, 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, &bnf) {
-		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.

-

Unseekable 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.

-
operation 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.

-
resp, err := client.PutObject(context.TODO(), &s3.PutObjectInput{
-    Bucket: &bucketName,
-    Key: &objectName,
-    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.

-

Use the SDK’s Amazon S3 Upload Manager for uploads that are not seekable, and do not have a known length.

- -
- - - - -
- Last modified February 16, 2023: doc: fix incorrectly link url (#2024) (01cae8c31e) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/security/compliance-validation/index.html b/docs/docs/security/compliance-validation/index.html index f8e2418ce87..e5824454e8d 100644 --- a/docs/docs/security/compliance-validation/index.html +++ b/docs/docs/security/compliance-validation/index.html @@ -1,627 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Compliance Validation for this AWS Product or Service | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Compliance Validation for this AWS Product or Service

- -
- - - - - - - - - - - - - -
-

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.

-

The 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.

-

Third-party audit reports are available for you to download using AWS Artifact. For more information, -see Downloading Reports in AWS Artifact.

-

For more information about AWS compliance programs, -see AWS Compliance Programs.

-

Your 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:

-
    -
  • Security 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.
    • -
- - - -
- Last modified November 17, 2020: Developer Guide: Configuring the SDK (#899) (1077c2349c) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/security/data-protection/index.html b/docs/docs/security/data-protection/index.html index 694b2940a8b..e5824454e8d 100644 --- a/docs/docs/security/data-protection/index.html +++ b/docs/docs/security/data-protection/index.html @@ -1,619 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Data Protection in this AWS Product or Service | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Data Protection in this AWS Product or Service

- -
- - - - - - - - - - - - - -
-

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.

-

For 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:

-
    -
  • Use 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.

- - - -
- Last modified April 23, 2021: Fixing broken links, correcting typos (#1236) (6c3cbc2a76) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/security/disaster-recovery-resiliency/index.html b/docs/docs/security/disaster-recovery-resiliency/index.html index 41f9b086121..e5824454e8d 100644 --- a/docs/docs/security/disaster-recovery-resiliency/index.html +++ b/docs/docs/security/disaster-recovery-resiliency/index.html @@ -1,611 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Resilience for this AWS Product or Service | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Resilience for this AWS Product or Service

- -
- - - - - - - - - - - - - -
-

The Amazon Web Services (AWS) global infrastructure is built around AWS Regions and Availability Zones.

-

AWS Regions provide multiple physically separated and isolated Availability Zones, which are connected with low-latency, -high-throughput, and highly redundant networking.

-

With 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.

-

For more information about AWS Regions and Availability Zones, -see AWS Global Infrastructure.

-

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.

- - - -
- Last modified November 17, 2020: Developer Guide: Configuring the SDK (#899) (1077c2349c) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/security/iam/index.html b/docs/docs/security/iam/index.html index 2a8356c6dcf..e5824454e8d 100644 --- a/docs/docs/security/iam/index.html +++ b/docs/docs/security/iam/index.html @@ -1,611 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Identity and Access Management for this AWS Product or Service | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Identity and Access Management for this AWS Product or Service

- -
- - - - - - - - - - - - - -
-

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.

-

To 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.

-

For details about working with IAM, see IAM.

-

For 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.

-

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.

- - - -
- Last modified November 17, 2020: Developer Guide: Configuring the SDK (#899) (1077c2349c) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/security/index.html b/docs/docs/security/index.html index db780ea0527..e5824454e8d 100644 --- a/docs/docs/security/index.html +++ b/docs/docs/security/index.html @@ -1,658 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -Security for this AWS Product or Service | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Security for this AWS Product or Service

- -
- - - - - - - - - - - - - -
-

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.

-

Security 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.

-

Security 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.

- -
- - - - - - - - -
- - -
-
- Compliance Validation for this AWS Product or Service -
-

-
- - -
-
- Identity and Access Management for this AWS Product or Service -
-

-
- - -
-
- Infrastructure Security for this AWS Product or Service -
-

-
- - -
-
- Resilience for this AWS Product or Service -
-

-
- - -
-
- Data Protection in this AWS Product or Service -
-

-
- - -
-
- TLS Version in AWS SDK for Go V2 -
-

-
- - -
- - - -
- Last modified December 23, 2020: Content Updates and Theming (#1001) (b911073c54) -
- -
- -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/security/infrastructure-security/index.html b/docs/docs/security/infrastructure-security/index.html index 3d1168810ec..e5824454e8d 100644 --- a/docs/docs/security/infrastructure-security/index.html +++ b/docs/docs/security/infrastructure-security/index.html @@ -1,606 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Infrastructure Security for this AWS Product or Service | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Infrastructure Security for this AWS Product or Service

- -
- - - - - - - - - - - - - -
-

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 -.

-

For information about AWS security processes, see -the AWS: Overview of Security Processes -whitepaper.

- - - -
- Last modified November 17, 2020: Developer Guide: Configuring the SDK (#899) (1077c2349c) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/security/tls/index.html b/docs/docs/security/tls/index.html index a4e7a3dbe91..e5824454e8d 100644 --- a/docs/docs/security/tls/index.html +++ b/docs/docs/security/tls/index.html @@ -1,648 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -TLS Version in AWS SDK for Go V2 | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

TLS Version in AWS SDK for Go V2

- -
- - - - - - - - - - - - - -
-

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.

- - -
-

If 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.

- -
- -

Enforcing 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.

- - -
-

Some 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.

- -
- -
package 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 = &tls.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).
-    // ...
-}
-
- - -
- Last modified April 18, 2022: Update SDK's TLS minimum version documentation for TLS 1.2 vs 1.3 (#1672) (f0118b21fe) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/docs/unit-testing/index.html b/docs/docs/unit-testing/index.html index 907bea557f1..e5824454e8d 100644 --- a/docs/docs/unit-testing/index.html +++ b/docs/docs/unit-testing/index.html @@ -1,773 +1,15 @@ - - - - - - - - - - - - - - - - - - - - -Unit Testing with the AWS SDK for Go V2 | AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
-
- - -
- - - - - -
-

Unit Testing with the AWS SDK for Go V2

-
How to mock the AWS SDK for Go V2 when unit testing your application.
-
- - - - - - - - - - - - - -
-

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.

-

To 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.

-

Mocking 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.

-
import "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, &s3.GetObjectInput{
-		Bucket: &bucket,
-		Key:    &key,
-	})
-	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.

-
import "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	string
-		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 &s3.GetObjectOutput{
-						Body: ioutil.NopCloser(bytes.NewReader([]byte("this is the body foo bar baz"))),
-					}, nil
-				})
-			},
-			bucket: "fooBucket",
-			key:	"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.

-

In the following example, ListObjectsV2Pager is an interface that defines the -behaviors for the Amazon S3 -ListObjectsV2Paginator. -required by CountObjects function.

-
import "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.

-
import "context"
-import	"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 < len(m.Pages)
-}
-
-func (m *mockListObjectsV2Pager) NextPage(ctx context.Context, f ...func(*s3.Options)) (output *s3.ListObjectsV2Output, err error) {
-	if m.PageNum >= 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 := &mockListObjectsV2Pager{
-		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)
-	}
-}
-
- - -
- Last modified January 5, 2022: docs(testing): Fix paginator example (#1544) (55d4daf3cd) -
- -
- - -
-
-
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/docs/index.html b/docs/index.html index 556146738f6..e5824454e8d 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,356 +1,15 @@ - - - - - - - - - - - - - - - - - - - - - -AWS SDK for Go V2 - - - - - - - - - - - - - - - - - - - - - -
- - - -
-
-
- - - - - - - - - - - - - - -
-
-
-
-
-

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.

- -
- -
- - -
-
- -
-

Paginators

-
-

Easily iterate over API results that span multiple pages.

- -
- -
- - -
-
- -
-

Waiters

-
-

Validate AWS resources states before performing additional actions.

- -
- -
- - -
-
- -
-

Utilities

-
-

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.

- -
- -
- - -
-
- -
-

Extensible

-
-

Middleware allows you to extend or customize the transport request pipeline to fit your applications requirements.

- -
- -
- - - - -
-
-
- - - - -
- -
-
-
-
- - - - - - - -
-
- - - - - - - -
-
- © 2024 Amazon Web Services, Inc. or its affiliates. All Rights Reserved - - - - -
-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + +

The aws-sdk-go-v2 developer guide is now hosted on the main AWS documentation site. You will be redirected in 5 seconds...

+

If you are not redirected, click here.

+ + diff --git a/go.mod b/go.mod deleted file mode 100644 index a1e97a6779b..00000000000 --- a/go.mod +++ /dev/null @@ -1,8 +0,0 @@ -module github.com/aws/aws-sdk-go-v2/internal/developerguide - -go 1.19 - -require ( - github.com/google/docsy v0.4.0 // indirect - github.com/google/docsy/dependencies v0.4.0 // indirect -) diff --git a/go.sum b/go.sum deleted file mode 100644 index 66d71013c18..00000000000 --- a/go.sum +++ /dev/null @@ -1,9 +0,0 @@ -github.com/FortAwesome/Font-Awesome v0.0.0-20210804190922-7d3d774145ac/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo= -github.com/google/docsy v0.2.0 h1:DN6wfyyp2rXsjdV1K3wioxOBTRvG6Gg48wLPDso2lc4= -github.com/google/docsy v0.2.0/go.mod h1:shlabwAQakGX6qpXU6Iv/b/SilpHRd7d+xqtZQd3v+8= -github.com/google/docsy v0.4.0 h1:Eyt2aiDC1fnw/Qq/9xnIqUU5n5Yyk4c8gX3nBDdTv/4= -github.com/google/docsy v0.4.0/go.mod h1:vJjGkHNaw9bO42gpFTWwAUzHZWZEVlK46Kx7ikY5c7Y= -github.com/google/docsy/dependencies v0.2.0/go.mod h1:2zZxHF+2qvkyXhLZtsbnqMotxMukJXLaf8fAZER48oo= -github.com/google/docsy/dependencies v0.4.0 h1:FXwyjtuFfPIPBauU2t7uIAgS6VYfJf+OD5pzxGvkQsQ= -github.com/google/docsy/dependencies v0.4.0/go.mod h1:2zZxHF+2qvkyXhLZtsbnqMotxMukJXLaf8fAZER48oo= -github.com/twbs/bootstrap v4.6.1+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0= diff --git a/layouts/redirect/examples.html b/layouts/redirect/examples.html deleted file mode 100644 index dca7a82e616..00000000000 --- a/layouts/redirect/examples.html +++ /dev/null @@ -1,14 +0,0 @@ - - - - - - - {{ .Title }} - - -

- This example has been migrated. Click the link if you are not automatically redirected. -

- - diff --git a/layouts/shortcodes/alias.html b/layouts/shortcodes/alias.html deleted file mode 100644 index 8873b19e86d..00000000000 --- a/layouts/shortcodes/alias.html +++ /dev/null @@ -1,7 +0,0 @@ -{{- $resolved := "" -}} -{{- if .Get "service" -}} - {{- $resolved = (index .Site.Data.aliases.service (.Get "service")) -}} -{{- else if .Get 0 -}} - {{- $resolved = (index .Site.Data.aliases (.Get 0)) -}} -{{- end -}} -{{- print $resolved -}} diff --git a/layouts/shortcodes/apiref.html b/layouts/shortcodes/apiref.html deleted file mode 100644 index 7c10d58443b..00000000000 --- a/layouts/shortcodes/apiref.html +++ /dev/null @@ -1,8 +0,0 @@ -{{- $pkgGoDev := "https://pkg.go.dev/" -}} -{{- if (.Get 0) -}} - {{- print $pkgGoDev "github.com/aws/aws-sdk-go-v2/" (.Get 0) -}} -{{- else if (.Get "smithy") -}} - {{- print $pkgGoDev "github.com/aws/smithy-go/" (.Get "smithy") -}} -{{- else if (.Get "v1") -}} - {{- print "https://docs.aws.amazon.com/sdk-for-go/api/" (.Get "v1") -}} -{{- end -}} diff --git a/package-lock.json b/package-lock.json deleted file mode 100644 index 0c8b5b4ebff..00000000000 --- a/package-lock.json +++ /dev/null @@ -1,1566 +0,0 @@ -{ - "name": "aws-sdk-go-v2-docs", - "version": "1.0.0", - "lockfileVersion": 2, - "requires": true, - "packages": { - "": { - "name": "aws-sdk-go-v2-docs", - "version": "1.0.0", - "license": "Apache-2.0", - "devDependencies": { - "autoprefixer": "^10.0.2", - "postcss": "^8.4.5", - "postcss-cli": "^10.0.0" - } - }, - "node_modules/@nodelib/fs.scandir": { - "version": "2.1.5", - "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", - "integrity": "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==", - "dev": true, - "dependencies": { - "@nodelib/fs.stat": "2.0.5", - "run-parallel": "^1.1.9" - }, - "engines": { - "node": ">= 8" - } - }, - "node_modules/@nodelib/fs.stat": { - "version": "2.0.5", - "resolved": "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz", - "integrity": "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==", - "dev": true, - "engines": { - "node": ">= 8" - } - }, - "node_modules/@nodelib/fs.walk": { - "version": "1.2.8", - "resolved": "https://registry.npmjs.org/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz", - "integrity": "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==", - "dev": true, - "dependencies": { - "@nodelib/fs.scandir": "2.1.5", - "fastq": "^1.6.0" - }, - "engines": { - "node": ">= 8" - } - }, - "node_modules/ansi-regex": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", - "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", - "dev": true, - "engines": { - "node": ">=8" - } - }, - "node_modules/ansi-styles": { - "version": "4.3.0", - "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", - "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", - "dev": true, - "dependencies": { - "color-convert": "^2.0.1" - }, - "engines": { - "node": ">=8" - }, - "funding": { - "url": "https://github.com/chalk/ansi-styles?sponsor=1" - } - }, - "node_modules/anymatch": { - "version": "3.1.2", - "resolved": "https://registry.npmjs.org/anymatch/-/anymatch-3.1.2.tgz", - "integrity": "sha512-P43ePfOAIupkguHUycrc4qJ9kz8ZiuOUijaETwX7THt0Y/GNK7v0aa8rY816xWjZ7rJdA5XdMcpVFTKMq+RvWg==", - "dev": true, - "dependencies": { - "normalize-path": "^3.0.0", - "picomatch": "^2.0.4" - }, - "engines": { - "node": ">= 8" - } - }, - "node_modules/autoprefixer": { - "version": "10.4.8", - "resolved": "https://registry.npmjs.org/autoprefixer/-/autoprefixer-10.4.8.tgz", - "integrity": "sha512-75Jr6Q/XpTqEf6D2ltS5uMewJIx5irCU1oBYJrWjFenq/m12WRRrz6g15L1EIoYvPLXTbEry7rDOwrcYNj77xw==", - "dev": true, - "funding": [ - { - "type": "opencollective", - "url": "https://opencollective.com/postcss/" - }, - { - "type": "tidelift", - "url": "https://tidelift.com/funding/github/npm/autoprefixer" - } - ], - "dependencies": { - "browserslist": "^4.21.3", - "caniuse-lite": "^1.0.30001373", - "fraction.js": "^4.2.0", - "normalize-range": "^0.1.2", - "picocolors": "^1.0.0", - "postcss-value-parser": "^4.2.0" - }, - "bin": { - "autoprefixer": "bin/autoprefixer" - }, - "engines": { - "node": "^10 || ^12 || >=14" - }, - "peerDependencies": { - "postcss": "^8.1.0" - } - }, - "node_modules/binary-extensions": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.2.0.tgz", - "integrity": "sha512-jDctJ/IVQbZoJykoeHbhXpOlNBqGNcwXJKJog42E5HDPUwQTSdjCHdihjj0DlnheQ7blbT6dHOafNAiS8ooQKA==", - "dev": true, - "engines": { - "node": ">=8" - } - }, - "node_modules/braces": { - "version": "3.0.2", - "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.2.tgz", - "integrity": "sha512-b8um+L1RzM3WDSzvhm6gIz1yfTbBt6YTlcEKAvsmqCZZFw46z626lVj9j1yEPW33H5H+lBQpZMP1k8l+78Ha0A==", - "dev": true, - "dependencies": { - "fill-range": "^7.0.1" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/browserslist": { - "version": "4.21.3", - "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.21.3.tgz", - "integrity": "sha512-898rgRXLAyRkM1GryrrBHGkqA5hlpkV5MhtZwg9QXeiyLUYs2k00Un05aX5l2/yJIOObYKOpS2JNo8nJDE7fWQ==", - "dev": true, - "funding": [ - { - "type": "opencollective", - "url": "https://opencollective.com/browserslist" - }, - { - "type": "tidelift", - "url": "https://tidelift.com/funding/github/npm/browserslist" - } - ], - "dependencies": { - "caniuse-lite": "^1.0.30001370", - "electron-to-chromium": "^1.4.202", - "node-releases": "^2.0.6", - "update-browserslist-db": "^1.0.5" - }, - "bin": { - "browserslist": "cli.js" - }, - "engines": { - "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7" - } - }, - "node_modules/caniuse-lite": { - "version": "1.0.30001375", - "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001375.tgz", - "integrity": "sha512-kWIMkNzLYxSvnjy0hL8w1NOaWNr2rn39RTAVyIwcw8juu60bZDWiF1/loOYANzjtJmy6qPgNmn38ro5Pygagdw==", - "dev": true, - "funding": [ - { - "type": "opencollective", - "url": "https://opencollective.com/browserslist" - }, - { - "type": "tidelift", - "url": "https://tidelift.com/funding/github/npm/caniuse-lite" - } - ] - }, - "node_modules/chokidar": { - "version": "3.5.3", - "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.5.3.tgz", - "integrity": "sha512-Dr3sfKRP6oTcjf2JmUmFJfeVMvXBdegxB0iVQ5eb2V10uFJUCAS8OByZdVAyVb8xXNz3GjjTgj9kLWsZTqE6kw==", - "dev": true, - "funding": [ - { - "type": "individual", - "url": "https://paulmillr.com/funding/" - } - ], - "dependencies": { - "anymatch": "~3.1.2", - "braces": "~3.0.2", - "glob-parent": "~5.1.2", - "is-binary-path": "~2.1.0", - "is-glob": "~4.0.1", - "normalize-path": "~3.0.0", - "readdirp": "~3.6.0" - }, - "engines": { - "node": ">= 8.10.0" - }, - "optionalDependencies": { - "fsevents": "~2.3.2" - } - }, - "node_modules/cliui": { - "version": "7.0.4", - "resolved": "https://registry.npmjs.org/cliui/-/cliui-7.0.4.tgz", - "integrity": "sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ==", - "dev": true, - "dependencies": { - "string-width": "^4.2.0", - "strip-ansi": "^6.0.0", - "wrap-ansi": "^7.0.0" - } - }, - "node_modules/color-convert": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", - "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", - "dev": true, - "dependencies": { - "color-name": "~1.1.4" - }, - "engines": { - "node": ">=7.0.0" - } - }, - "node_modules/color-name": { - "version": "1.1.4", - "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", - "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", - "dev": true - }, - "node_modules/dependency-graph": { - "version": "0.11.0", - "resolved": "https://registry.npmjs.org/dependency-graph/-/dependency-graph-0.11.0.tgz", - "integrity": "sha512-JeMq7fEshyepOWDfcfHK06N3MhyPhz++vtqWhMT5O9A3K42rdsEDpfdVqjaqaAhsw6a+ZqeDvQVtD0hFHQWrzg==", - "dev": true, - "engines": { - "node": ">= 0.6.0" - } - }, - "node_modules/dir-glob": { - "version": "3.0.1", - "resolved": "https://registry.npmjs.org/dir-glob/-/dir-glob-3.0.1.tgz", - "integrity": "sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==", - "dev": true, - "dependencies": { - "path-type": "^4.0.0" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/electron-to-chromium": { - "version": "1.4.213", - "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.213.tgz", - "integrity": "sha512-+3DbGHGOCHTVB/Ms63bGqbyC1b8y7Fk86+7ltssB8NQrZtSCvZG6eooSl9U2Q0yw++fL2DpHKOdTU0NVEkFObg==", - "dev": true - }, - "node_modules/emoji-regex": { - "version": "8.0.0", - "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", - "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", - "dev": true - }, - "node_modules/escalade": { - "version": "3.1.1", - "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.1.1.tgz", - "integrity": "sha512-k0er2gUkLf8O0zKJiAhmkTnJlTvINGv7ygDNPbeIsX/TJjGJZHuh9B2UxbsaEkmlEo9MfhrSzmhIlhRlI2GXnw==", - "dev": true, - "engines": { - "node": ">=6" - } - }, - "node_modules/fast-glob": { - "version": "3.2.11", - "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.2.11.tgz", - "integrity": "sha512-xrO3+1bxSo3ZVHAnqzyuewYT6aMFHRAd4Kcs92MAonjwQZLsK9d0SF1IyQ3k5PoirxTW0Oe/RqFgMQ6TcNE5Ew==", - "dev": true, - "dependencies": { - "@nodelib/fs.stat": "^2.0.2", - "@nodelib/fs.walk": "^1.2.3", - "glob-parent": "^5.1.2", - "merge2": "^1.3.0", - "micromatch": "^4.0.4" - }, - "engines": { - "node": ">=8.6.0" - } - }, - "node_modules/fastq": { - "version": "1.13.0", - "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.13.0.tgz", - "integrity": "sha512-YpkpUnK8od0o1hmeSc7UUs/eB/vIPWJYjKck2QKIzAf71Vm1AAQ3EbuZB3g2JIy+pg+ERD0vqI79KyZiB2e2Nw==", - "dev": true, - "dependencies": { - "reusify": "^1.0.4" - } - }, - "node_modules/fill-range": { - "version": "7.0.1", - "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.0.1.tgz", - "integrity": "sha512-qOo9F+dMUmC2Lcb4BbVvnKJxTPjCm+RRpe4gDuGrzkL7mEVl/djYSu2OdQ2Pa302N4oqkSg9ir6jaLWJ2USVpQ==", - "dev": true, - "dependencies": { - "to-regex-range": "^5.0.1" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/fraction.js": { - "version": "4.2.0", - "resolved": "https://registry.npmjs.org/fraction.js/-/fraction.js-4.2.0.tgz", - "integrity": "sha512-MhLuK+2gUcnZe8ZHlaaINnQLl0xRIGRfcGk2yl8xoQAfHrSsL3rYu6FCmBdkdbhc9EPlwyGHewaRsvwRMJtAlA==", - "dev": true, - "engines": { - "node": "*" - }, - "funding": { - "type": "patreon", - "url": "https://www.patreon.com/infusion" - } - }, - "node_modules/fs-extra": { - "version": "10.1.0", - "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-10.1.0.tgz", - "integrity": "sha512-oRXApq54ETRj4eMiFzGnHWGy+zo5raudjuxN0b8H7s/RU2oW0Wvsx9O0ACRN/kRq9E8Vu/ReskGB5o3ji+FzHQ==", - "dev": true, - "dependencies": { - "graceful-fs": "^4.2.0", - "jsonfile": "^6.0.1", - "universalify": "^2.0.0" - }, - "engines": { - "node": ">=12" - } - }, - "node_modules/fsevents": { - "version": "2.3.2", - "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz", - "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==", - "dev": true, - "hasInstallScript": true, - "optional": true, - "os": [ - "darwin" - ], - "engines": { - "node": "^8.16.0 || ^10.6.0 || >=11.0.0" - } - }, - "node_modules/get-caller-file": { - "version": "2.0.5", - "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz", - "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==", - "dev": true, - "engines": { - "node": "6.* || 8.* || >= 10.*" - } - }, - "node_modules/get-stdin": { - "version": "9.0.0", - "resolved": "https://registry.npmjs.org/get-stdin/-/get-stdin-9.0.0.tgz", - "integrity": "sha512-dVKBjfWisLAicarI2Sf+JuBE/DghV4UzNAVe9yhEJuzeREd3JhOTE9cUaJTeSa77fsbQUK3pcOpJfM59+VKZaA==", - "dev": true, - "engines": { - "node": ">=12" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, - "node_modules/glob-parent": { - "version": "5.1.2", - "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz", - "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==", - "dev": true, - "dependencies": { - "is-glob": "^4.0.1" - }, - "engines": { - "node": ">= 6" - } - }, - "node_modules/globby": { - "version": "13.1.2", - "resolved": "https://registry.npmjs.org/globby/-/globby-13.1.2.tgz", - "integrity": "sha512-LKSDZXToac40u8Q1PQtZihbNdTYSNMuWe+K5l+oa6KgDzSvVrHXlJy40hUP522RjAIoNLJYBJi7ow+rbFpIhHQ==", - "dev": true, - "dependencies": { - "dir-glob": "^3.0.1", - "fast-glob": "^3.2.11", - "ignore": "^5.2.0", - "merge2": "^1.4.1", - "slash": "^4.0.0" - }, - "engines": { - "node": "^12.20.0 || ^14.13.1 || >=16.0.0" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, - "node_modules/graceful-fs": { - "version": "4.2.10", - "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.10.tgz", - "integrity": "sha512-9ByhssR2fPVsNZj478qUUbKfmL0+t5BDVyjShtyZZLiK7ZDAArFFfopyOTj0M05wE2tJPisA4iTnnXl2YoPvOA==", - "dev": true - }, - "node_modules/ignore": { - "version": "5.2.0", - "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.2.0.tgz", - "integrity": "sha512-CmxgYGiEPCLhfLnpPp1MoRmifwEIOgjcHXxOBjv7mY96c+eWScsOP9c112ZyLdWHi0FxHjI+4uVhKYp/gcdRmQ==", - "dev": true, - "engines": { - "node": ">= 4" - } - }, - "node_modules/is-binary-path": { - "version": "2.1.0", - "resolved": "https://registry.npmjs.org/is-binary-path/-/is-binary-path-2.1.0.tgz", - "integrity": "sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw==", - "dev": true, - "dependencies": { - "binary-extensions": "^2.0.0" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/is-extglob": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz", - "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==", - "dev": true, - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/is-fullwidth-code-point": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", - "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", - "dev": true, - "engines": { - "node": ">=8" - } - }, - "node_modules/is-glob": { - "version": "4.0.3", - "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz", - "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==", - "dev": true, - "dependencies": { - "is-extglob": "^2.1.1" - }, - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/is-number": { - "version": "7.0.0", - "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz", - "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==", - "dev": true, - "engines": { - "node": ">=0.12.0" - } - }, - "node_modules/jsonfile": { - "version": "6.1.0", - "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz", - "integrity": "sha512-5dgndWOriYSm5cnYaJNhalLNDKOqFwyDB/rr1E9ZsGciGvKPs8R2xYGCacuf3z6K1YKDz182fd+fY3cn3pMqXQ==", - "dev": true, - "dependencies": { - "universalify": "^2.0.0" - }, - "optionalDependencies": { - "graceful-fs": "^4.1.6" - } - }, - "node_modules/lilconfig": { - "version": "2.0.6", - "resolved": "https://registry.npmjs.org/lilconfig/-/lilconfig-2.0.6.tgz", - "integrity": "sha512-9JROoBW7pobfsx+Sq2JsASvCo6Pfo6WWoUW79HuB1BCoBXD4PLWJPqDF6fNj67pqBYTbAHkE57M1kS/+L1neOg==", - "dev": true, - "engines": { - "node": ">=10" - } - }, - "node_modules/merge2": { - "version": "1.4.1", - "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz", - "integrity": "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==", - "dev": true, - "engines": { - "node": ">= 8" - } - }, - "node_modules/micromatch": { - "version": "4.0.5", - "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.5.tgz", - "integrity": "sha512-DMy+ERcEW2q8Z2Po+WNXuw3c5YaUSFjAO5GsJqfEl7UjvtIuFKO6ZrKvcItdy98dwFI2N1tg3zNIdKaQT+aNdA==", - "dev": true, - "dependencies": { - "braces": "^3.0.2", - "picomatch": "^2.3.1" - }, - "engines": { - "node": ">=8.6" - } - }, - "node_modules/nanoid": { - "version": "3.3.4", - "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.4.tgz", - "integrity": "sha512-MqBkQh/OHTS2egovRtLk45wEyNXwF+cokD+1YPf9u5VfJiRdAiRwB2froX5Co9Rh20xs4siNPm8naNotSD6RBw==", - "dev": true, - "bin": { - "nanoid": "bin/nanoid.cjs" - }, - "engines": { - "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1" - } - }, - "node_modules/node-releases": { - "version": "2.0.6", - "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.6.tgz", - "integrity": "sha512-PiVXnNuFm5+iYkLBNeq5211hvO38y63T0i2KKh2KnUs3RpzJ+JtODFjkD8yjLwnDkTYF1eKXheUwdssR+NRZdg==", - "dev": true - }, - "node_modules/normalize-path": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz", - "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==", - "dev": true, - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/normalize-range": { - "version": "0.1.2", - "resolved": "https://registry.npmjs.org/normalize-range/-/normalize-range-0.1.2.tgz", - "integrity": "sha512-bdok/XvKII3nUpklnV6P2hxtMNrCboOjAcyBuQnWEhO665FwrSNRxU+AqpsyvO6LgGYPspN+lu5CLtw4jPRKNA==", - "dev": true, - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/path-type": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz", - "integrity": "sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==", - "dev": true, - "engines": { - "node": ">=8" - } - }, - "node_modules/picocolors": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.0.0.tgz", - "integrity": "sha512-1fygroTLlHu66zi26VoTDv8yRgm0Fccecssto+MhsZ0D/DGW2sm8E8AjW7NU5VVTRt5GxbeZ5qBuJr+HyLYkjQ==", - "dev": true - }, - "node_modules/picomatch": { - "version": "2.3.1", - "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", - "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", - "dev": true, - "engines": { - "node": ">=8.6" - }, - "funding": { - "url": "https://github.com/sponsors/jonschlinkert" - } - }, - "node_modules/pify": { - "version": "2.3.0", - "resolved": "https://registry.npmjs.org/pify/-/pify-2.3.0.tgz", - "integrity": "sha512-udgsAY+fTnvv7kI7aaxbqwWNb0AHiB0qBO89PZKPkoTmGOgdbrHDKD+0B2X4uTfJ/FT1R09r9gTsjUjNJotuog==", - "dev": true, - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/postcss": { - "version": "8.4.16", - "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.16.tgz", - "integrity": "sha512-ipHE1XBvKzm5xI7hiHCZJCSugxvsdq2mPnsq5+UF+VHCjiBvtDrlxJfMBToWaP9D5XlgNmcFGqoHmUn0EYEaRQ==", - "dev": true, - "funding": [ - { - "type": "opencollective", - "url": "https://opencollective.com/postcss/" - }, - { - "type": "tidelift", - "url": "https://tidelift.com/funding/github/npm/postcss" - } - ], - "dependencies": { - "nanoid": "^3.3.4", - "picocolors": "^1.0.0", - "source-map-js": "^1.0.2" - }, - "engines": { - "node": "^10 || ^12 || >=14" - } - }, - "node_modules/postcss-cli": { - "version": "10.0.0", - "resolved": "https://registry.npmjs.org/postcss-cli/-/postcss-cli-10.0.0.tgz", - "integrity": "sha512-Wjy/00wBBEgQqnSToznxLWDnATznokFGXsHtF/3G8glRZpz5KYlfHcBW/VMJmWAeF2x49zjgy4izjM3/Wx1dKA==", - "dev": true, - "dependencies": { - "chokidar": "^3.3.0", - "dependency-graph": "^0.11.0", - "fs-extra": "^10.0.0", - "get-stdin": "^9.0.0", - "globby": "^13.0.0", - "picocolors": "^1.0.0", - "postcss-load-config": "^4.0.0", - "postcss-reporter": "^7.0.0", - "pretty-hrtime": "^1.0.3", - "read-cache": "^1.0.0", - "slash": "^4.0.0", - "yargs": "^17.0.0" - }, - "bin": { - "postcss": "index.js" - }, - "engines": { - "node": ">=14" - }, - "peerDependencies": { - "postcss": "^8.0.0" - } - }, - "node_modules/postcss-load-config": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/postcss-load-config/-/postcss-load-config-4.0.1.tgz", - "integrity": "sha512-vEJIc8RdiBRu3oRAI0ymerOn+7rPuMvRXslTvZUKZonDHFIczxztIyJ1urxM1x9JXEikvpWWTUUqal5j/8QgvA==", - "dev": true, - "dependencies": { - "lilconfig": "^2.0.5", - "yaml": "^2.1.1" - }, - "engines": { - "node": ">= 14" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/postcss/" - }, - "peerDependencies": { - "postcss": ">=8.0.9", - "ts-node": ">=9.0.0" - }, - "peerDependenciesMeta": { - "postcss": { - "optional": true - }, - "ts-node": { - "optional": true - } - } - }, - "node_modules/postcss-reporter": { - "version": "7.0.5", - "resolved": "https://registry.npmjs.org/postcss-reporter/-/postcss-reporter-7.0.5.tgz", - "integrity": "sha512-glWg7VZBilooZGOFPhN9msJ3FQs19Hie7l5a/eE6WglzYqVeH3ong3ShFcp9kDWJT1g2Y/wd59cocf9XxBtkWA==", - "dev": true, - "dependencies": { - "picocolors": "^1.0.0", - "thenby": "^1.3.4" - }, - "engines": { - "node": ">=10" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/postcss/" - }, - "peerDependencies": { - "postcss": "^8.1.0" - } - }, - "node_modules/postcss-value-parser": { - "version": "4.2.0", - "resolved": "https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz", - "integrity": "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==", - "dev": true - }, - "node_modules/pretty-hrtime": { - "version": "1.0.3", - "resolved": "https://registry.npmjs.org/pretty-hrtime/-/pretty-hrtime-1.0.3.tgz", - "integrity": "sha512-66hKPCr+72mlfiSjlEB1+45IjXSqvVAIy6mocupoww4tBFE9R9IhwwUGoI4G++Tc9Aq+2rxOt0RFU6gPcrte0A==", - "dev": true, - "engines": { - "node": ">= 0.8" - } - }, - "node_modules/queue-microtask": { - "version": "1.2.3", - "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz", - "integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==", - "dev": true, - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/feross" - }, - { - "type": "patreon", - "url": "https://www.patreon.com/feross" - }, - { - "type": "consulting", - "url": "https://feross.org/support" - } - ] - }, - "node_modules/read-cache": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/read-cache/-/read-cache-1.0.0.tgz", - "integrity": "sha512-Owdv/Ft7IjOgm/i0xvNDZ1LrRANRfew4b2prF3OWMQLxLfu3bS8FVhCsrSCMK4lR56Y9ya+AThoTpDCTxCmpRA==", - "dev": true, - "dependencies": { - "pify": "^2.3.0" - } - }, - "node_modules/readdirp": { - "version": "3.6.0", - "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.6.0.tgz", - "integrity": "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==", - "dev": true, - "dependencies": { - "picomatch": "^2.2.1" - }, - "engines": { - "node": ">=8.10.0" - } - }, - "node_modules/require-directory": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", - "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==", - "dev": true, - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/reusify": { - "version": "1.0.4", - "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.0.4.tgz", - "integrity": "sha512-U9nH88a3fc/ekCF1l0/UP1IosiuIjyTh7hBvXVMHYgVcfGvt897Xguj2UOLDeI5BG2m7/uwyaLVT6fbtCwTyzw==", - "dev": true, - "engines": { - "iojs": ">=1.0.0", - "node": ">=0.10.0" - } - }, - "node_modules/run-parallel": { - "version": "1.2.0", - "resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz", - "integrity": "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==", - "dev": true, - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/feross" - }, - { - "type": "patreon", - "url": "https://www.patreon.com/feross" - }, - { - "type": "consulting", - "url": "https://feross.org/support" - } - ], - "dependencies": { - "queue-microtask": "^1.2.2" - } - }, - "node_modules/slash": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/slash/-/slash-4.0.0.tgz", - "integrity": "sha512-3dOsAHXXUkQTpOYcoAxLIorMTp4gIQr5IW3iVb7A7lFIp0VHhnynm9izx6TssdrIcVIESAlVjtnO2K8bg+Coew==", - "dev": true, - "engines": { - "node": ">=12" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, - "node_modules/source-map-js": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.0.2.tgz", - "integrity": "sha512-R0XvVJ9WusLiqTCEiGCmICCMplcCkIwwR11mOSD9CR5u+IXYdiseeEuXCVAjS54zqwkLcPNnmU4OeJ6tUrWhDw==", - "dev": true, - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/string-width": { - "version": "4.2.3", - "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", - "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", - "dev": true, - "dependencies": { - "emoji-regex": "^8.0.0", - "is-fullwidth-code-point": "^3.0.0", - "strip-ansi": "^6.0.1" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/strip-ansi": { - "version": "6.0.1", - "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", - "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", - "dev": true, - "dependencies": { - "ansi-regex": "^5.0.1" - }, - "engines": { - "node": ">=8" - } - }, - "node_modules/thenby": { - "version": "1.3.4", - "resolved": "https://registry.npmjs.org/thenby/-/thenby-1.3.4.tgz", - "integrity": "sha512-89Gi5raiWA3QZ4b2ePcEwswC3me9JIg+ToSgtE0JWeCynLnLxNr/f9G+xfo9K+Oj4AFdom8YNJjibIARTJmapQ==", - "dev": true - }, - "node_modules/to-regex-range": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz", - "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==", - "dev": true, - "dependencies": { - "is-number": "^7.0.0" - }, - "engines": { - "node": ">=8.0" - } - }, - "node_modules/universalify": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.0.tgz", - "integrity": "sha512-hAZsKq7Yy11Zu1DE0OzWjw7nnLZmJZYTDZZyEFHZdUhV8FkH5MCfoU1XMaxXovpyW5nq5scPqq0ZDP9Zyl04oQ==", - "dev": true, - "engines": { - "node": ">= 10.0.0" - } - }, - "node_modules/update-browserslist-db": { - "version": "1.0.5", - "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.0.5.tgz", - "integrity": "sha512-dteFFpCyvuDdr9S/ff1ISkKt/9YZxKjI9WlRR99c180GaztJtRa/fn18FdxGVKVsnPY7/a/FDN68mcvUmP4U7Q==", - "dev": true, - "funding": [ - { - "type": "opencollective", - "url": "https://opencollective.com/browserslist" - }, - { - "type": "tidelift", - "url": "https://tidelift.com/funding/github/npm/browserslist" - } - ], - "dependencies": { - "escalade": "^3.1.1", - "picocolors": "^1.0.0" - }, - "bin": { - "browserslist-lint": "cli.js" - }, - "peerDependencies": { - "browserslist": ">= 4.21.0" - } - }, - "node_modules/wrap-ansi": { - "version": "7.0.0", - "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", - "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", - "dev": true, - "dependencies": { - "ansi-styles": "^4.0.0", - "string-width": "^4.1.0", - "strip-ansi": "^6.0.0" - }, - "engines": { - "node": ">=10" - }, - "funding": { - "url": "https://github.com/chalk/wrap-ansi?sponsor=1" - } - }, - "node_modules/y18n": { - "version": "5.0.8", - "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz", - "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==", - "dev": true, - "engines": { - "node": ">=10" - } - }, - "node_modules/yaml": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.1.1.tgz", - "integrity": "sha512-o96x3OPo8GjWeSLF+wOAbrPfhFOGY0W00GNaxCDv+9hkcDJEnev1yh8S7pgHF0ik6zc8sQLuL8hjHjJULZp8bw==", - "dev": true, - "engines": { - "node": ">= 14" - } - }, - "node_modules/yargs": { - "version": "17.5.1", - "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.5.1.tgz", - "integrity": "sha512-t6YAJcxDkNX7NFYiVtKvWUz8l+PaKTLiL63mJYWR2GnHq2gjEWISzsLp9wg3aY36dY1j+gfIEL3pIF+XlJJfbA==", - "dev": true, - "dependencies": { - "cliui": "^7.0.2", - "escalade": "^3.1.1", - "get-caller-file": "^2.0.5", - "require-directory": "^2.1.1", - "string-width": "^4.2.3", - "y18n": "^5.0.5", - "yargs-parser": "^21.0.0" - }, - "engines": { - "node": ">=12" - } - }, - "node_modules/yargs-parser": { - "version": "21.1.1", - "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz", - "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==", - "dev": true, - "engines": { - "node": ">=12" - } - } - }, - "dependencies": { - "@nodelib/fs.scandir": { - "version": "2.1.5", - "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", - "integrity": "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==", - "dev": true, - "requires": { - "@nodelib/fs.stat": "2.0.5", - "run-parallel": "^1.1.9" - } - }, - "@nodelib/fs.stat": { - "version": "2.0.5", - "resolved": "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz", - "integrity": "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==", - "dev": true - }, - "@nodelib/fs.walk": { - "version": "1.2.8", - "resolved": "https://registry.npmjs.org/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz", - "integrity": "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==", - "dev": true, - "requires": { - "@nodelib/fs.scandir": "2.1.5", - "fastq": "^1.6.0" - } - }, - "ansi-regex": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", - "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", - "dev": true - }, - "ansi-styles": { - "version": "4.3.0", - "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", - "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", - "dev": true, - "requires": { - "color-convert": "^2.0.1" - } - }, - "anymatch": { - "version": "3.1.2", - "resolved": "https://registry.npmjs.org/anymatch/-/anymatch-3.1.2.tgz", - "integrity": "sha512-P43ePfOAIupkguHUycrc4qJ9kz8ZiuOUijaETwX7THt0Y/GNK7v0aa8rY816xWjZ7rJdA5XdMcpVFTKMq+RvWg==", - "dev": true, - "requires": { - "normalize-path": "^3.0.0", - "picomatch": "^2.0.4" - } - }, - "autoprefixer": { - "version": "10.4.8", - "resolved": "https://registry.npmjs.org/autoprefixer/-/autoprefixer-10.4.8.tgz", - "integrity": "sha512-75Jr6Q/XpTqEf6D2ltS5uMewJIx5irCU1oBYJrWjFenq/m12WRRrz6g15L1EIoYvPLXTbEry7rDOwrcYNj77xw==", - "dev": true, - "requires": { - "browserslist": "^4.21.3", - "caniuse-lite": "^1.0.30001373", - "fraction.js": "^4.2.0", - "normalize-range": "^0.1.2", - "picocolors": "^1.0.0", - "postcss-value-parser": "^4.2.0" - } - }, - "binary-extensions": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.2.0.tgz", - "integrity": "sha512-jDctJ/IVQbZoJykoeHbhXpOlNBqGNcwXJKJog42E5HDPUwQTSdjCHdihjj0DlnheQ7blbT6dHOafNAiS8ooQKA==", - "dev": true - }, - "braces": { - "version": "3.0.2", - "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.2.tgz", - "integrity": "sha512-b8um+L1RzM3WDSzvhm6gIz1yfTbBt6YTlcEKAvsmqCZZFw46z626lVj9j1yEPW33H5H+lBQpZMP1k8l+78Ha0A==", - "dev": true, - "requires": { - "fill-range": "^7.0.1" - } - }, - "browserslist": { - "version": "4.21.3", - "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.21.3.tgz", - "integrity": "sha512-898rgRXLAyRkM1GryrrBHGkqA5hlpkV5MhtZwg9QXeiyLUYs2k00Un05aX5l2/yJIOObYKOpS2JNo8nJDE7fWQ==", - "dev": true, - "requires": { - "caniuse-lite": "^1.0.30001370", - "electron-to-chromium": "^1.4.202", - "node-releases": "^2.0.6", - "update-browserslist-db": "^1.0.5" - } - }, - "caniuse-lite": { - "version": "1.0.30001375", - "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001375.tgz", - "integrity": "sha512-kWIMkNzLYxSvnjy0hL8w1NOaWNr2rn39RTAVyIwcw8juu60bZDWiF1/loOYANzjtJmy6qPgNmn38ro5Pygagdw==", - "dev": true - }, - "chokidar": { - "version": "3.5.3", - "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.5.3.tgz", - "integrity": "sha512-Dr3sfKRP6oTcjf2JmUmFJfeVMvXBdegxB0iVQ5eb2V10uFJUCAS8OByZdVAyVb8xXNz3GjjTgj9kLWsZTqE6kw==", - "dev": true, - "requires": { - "anymatch": "~3.1.2", - "braces": "~3.0.2", - "fsevents": "~2.3.2", - "glob-parent": "~5.1.2", - "is-binary-path": "~2.1.0", - "is-glob": "~4.0.1", - "normalize-path": "~3.0.0", - "readdirp": "~3.6.0" - } - }, - "cliui": { - "version": "7.0.4", - "resolved": "https://registry.npmjs.org/cliui/-/cliui-7.0.4.tgz", - "integrity": "sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ==", - "dev": true, - "requires": { - "string-width": "^4.2.0", - "strip-ansi": "^6.0.0", - "wrap-ansi": "^7.0.0" - } - }, - "color-convert": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", - "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", - "dev": true, - "requires": { - "color-name": "~1.1.4" - } - }, - "color-name": { - "version": "1.1.4", - "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", - "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", - "dev": true - }, - "dependency-graph": { - "version": "0.11.0", - "resolved": "https://registry.npmjs.org/dependency-graph/-/dependency-graph-0.11.0.tgz", - "integrity": "sha512-JeMq7fEshyepOWDfcfHK06N3MhyPhz++vtqWhMT5O9A3K42rdsEDpfdVqjaqaAhsw6a+ZqeDvQVtD0hFHQWrzg==", - "dev": true - }, - "dir-glob": { - "version": "3.0.1", - "resolved": "https://registry.npmjs.org/dir-glob/-/dir-glob-3.0.1.tgz", - "integrity": "sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==", - "dev": true, - "requires": { - "path-type": "^4.0.0" - } - }, - "electron-to-chromium": { - "version": "1.4.213", - "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.213.tgz", - "integrity": "sha512-+3DbGHGOCHTVB/Ms63bGqbyC1b8y7Fk86+7ltssB8NQrZtSCvZG6eooSl9U2Q0yw++fL2DpHKOdTU0NVEkFObg==", - "dev": true - }, - "emoji-regex": { - "version": "8.0.0", - "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", - "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", - "dev": true - }, - "escalade": { - "version": "3.1.1", - "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.1.1.tgz", - "integrity": "sha512-k0er2gUkLf8O0zKJiAhmkTnJlTvINGv7ygDNPbeIsX/TJjGJZHuh9B2UxbsaEkmlEo9MfhrSzmhIlhRlI2GXnw==", - "dev": true - }, - "fast-glob": { - "version": "3.2.11", - "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.2.11.tgz", - "integrity": "sha512-xrO3+1bxSo3ZVHAnqzyuewYT6aMFHRAd4Kcs92MAonjwQZLsK9d0SF1IyQ3k5PoirxTW0Oe/RqFgMQ6TcNE5Ew==", - "dev": true, - "requires": { - "@nodelib/fs.stat": "^2.0.2", - "@nodelib/fs.walk": "^1.2.3", - "glob-parent": "^5.1.2", - "merge2": "^1.3.0", - "micromatch": "^4.0.4" - } - }, - "fastq": { - "version": "1.13.0", - "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.13.0.tgz", - "integrity": "sha512-YpkpUnK8od0o1hmeSc7UUs/eB/vIPWJYjKck2QKIzAf71Vm1AAQ3EbuZB3g2JIy+pg+ERD0vqI79KyZiB2e2Nw==", - "dev": true, - "requires": { - "reusify": "^1.0.4" - } - }, - "fill-range": { - "version": "7.0.1", - "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.0.1.tgz", - "integrity": "sha512-qOo9F+dMUmC2Lcb4BbVvnKJxTPjCm+RRpe4gDuGrzkL7mEVl/djYSu2OdQ2Pa302N4oqkSg9ir6jaLWJ2USVpQ==", - "dev": true, - "requires": { - "to-regex-range": "^5.0.1" - } - }, - "fraction.js": { - "version": "4.2.0", - "resolved": "https://registry.npmjs.org/fraction.js/-/fraction.js-4.2.0.tgz", - "integrity": "sha512-MhLuK+2gUcnZe8ZHlaaINnQLl0xRIGRfcGk2yl8xoQAfHrSsL3rYu6FCmBdkdbhc9EPlwyGHewaRsvwRMJtAlA==", - "dev": true - }, - "fs-extra": { - "version": "10.1.0", - "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-10.1.0.tgz", - "integrity": "sha512-oRXApq54ETRj4eMiFzGnHWGy+zo5raudjuxN0b8H7s/RU2oW0Wvsx9O0ACRN/kRq9E8Vu/ReskGB5o3ji+FzHQ==", - "dev": true, - "requires": { - "graceful-fs": "^4.2.0", - "jsonfile": "^6.0.1", - "universalify": "^2.0.0" - } - }, - "fsevents": { - "version": "2.3.2", - "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz", - "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==", - "dev": true, - "optional": true - }, - "get-caller-file": { - "version": "2.0.5", - "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz", - "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==", - "dev": true - }, - "get-stdin": { - "version": "9.0.0", - "resolved": "https://registry.npmjs.org/get-stdin/-/get-stdin-9.0.0.tgz", - "integrity": "sha512-dVKBjfWisLAicarI2Sf+JuBE/DghV4UzNAVe9yhEJuzeREd3JhOTE9cUaJTeSa77fsbQUK3pcOpJfM59+VKZaA==", - "dev": true - }, - "glob-parent": { - "version": "5.1.2", - "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz", - "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==", - "dev": true, - "requires": { - "is-glob": "^4.0.1" - } - }, - "globby": { - "version": "13.1.2", - "resolved": "https://registry.npmjs.org/globby/-/globby-13.1.2.tgz", - "integrity": "sha512-LKSDZXToac40u8Q1PQtZihbNdTYSNMuWe+K5l+oa6KgDzSvVrHXlJy40hUP522RjAIoNLJYBJi7ow+rbFpIhHQ==", - "dev": true, - "requires": { - "dir-glob": "^3.0.1", - "fast-glob": "^3.2.11", - "ignore": "^5.2.0", - "merge2": "^1.4.1", - "slash": "^4.0.0" - } - }, - "graceful-fs": { - "version": "4.2.10", - "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.10.tgz", - "integrity": "sha512-9ByhssR2fPVsNZj478qUUbKfmL0+t5BDVyjShtyZZLiK7ZDAArFFfopyOTj0M05wE2tJPisA4iTnnXl2YoPvOA==", - "dev": true - }, - "ignore": { - "version": "5.2.0", - "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.2.0.tgz", - "integrity": "sha512-CmxgYGiEPCLhfLnpPp1MoRmifwEIOgjcHXxOBjv7mY96c+eWScsOP9c112ZyLdWHi0FxHjI+4uVhKYp/gcdRmQ==", - "dev": true - }, - "is-binary-path": { - "version": "2.1.0", - "resolved": "https://registry.npmjs.org/is-binary-path/-/is-binary-path-2.1.0.tgz", - "integrity": "sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw==", - "dev": true, - "requires": { - "binary-extensions": "^2.0.0" - } - }, - "is-extglob": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz", - "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==", - "dev": true - }, - "is-fullwidth-code-point": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", - "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", - "dev": true - }, - "is-glob": { - "version": "4.0.3", - "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz", - "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==", - "dev": true, - "requires": { - "is-extglob": "^2.1.1" - } - }, - "is-number": { - "version": "7.0.0", - "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz", - "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==", - "dev": true - }, - "jsonfile": { - "version": "6.1.0", - "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz", - "integrity": "sha512-5dgndWOriYSm5cnYaJNhalLNDKOqFwyDB/rr1E9ZsGciGvKPs8R2xYGCacuf3z6K1YKDz182fd+fY3cn3pMqXQ==", - "dev": true, - "requires": { - "graceful-fs": "^4.1.6", - "universalify": "^2.0.0" - } - }, - "lilconfig": { - "version": "2.0.6", - "resolved": "https://registry.npmjs.org/lilconfig/-/lilconfig-2.0.6.tgz", - "integrity": "sha512-9JROoBW7pobfsx+Sq2JsASvCo6Pfo6WWoUW79HuB1BCoBXD4PLWJPqDF6fNj67pqBYTbAHkE57M1kS/+L1neOg==", - "dev": true - }, - "merge2": { - "version": "1.4.1", - "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz", - "integrity": "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==", - "dev": true - }, - "micromatch": { - "version": "4.0.5", - "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.5.tgz", - "integrity": "sha512-DMy+ERcEW2q8Z2Po+WNXuw3c5YaUSFjAO5GsJqfEl7UjvtIuFKO6ZrKvcItdy98dwFI2N1tg3zNIdKaQT+aNdA==", - "dev": true, - "requires": { - "braces": "^3.0.2", - "picomatch": "^2.3.1" - } - }, - "nanoid": { - "version": "3.3.4", - "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.4.tgz", - "integrity": "sha512-MqBkQh/OHTS2egovRtLk45wEyNXwF+cokD+1YPf9u5VfJiRdAiRwB2froX5Co9Rh20xs4siNPm8naNotSD6RBw==", - "dev": true - }, - "node-releases": { - "version": "2.0.6", - "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.6.tgz", - "integrity": "sha512-PiVXnNuFm5+iYkLBNeq5211hvO38y63T0i2KKh2KnUs3RpzJ+JtODFjkD8yjLwnDkTYF1eKXheUwdssR+NRZdg==", - "dev": true - }, - "normalize-path": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz", - "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==", - "dev": true - }, - "normalize-range": { - "version": "0.1.2", - "resolved": "https://registry.npmjs.org/normalize-range/-/normalize-range-0.1.2.tgz", - "integrity": "sha512-bdok/XvKII3nUpklnV6P2hxtMNrCboOjAcyBuQnWEhO665FwrSNRxU+AqpsyvO6LgGYPspN+lu5CLtw4jPRKNA==", - "dev": true - }, - "path-type": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz", - "integrity": "sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==", - "dev": true - }, - "picocolors": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.0.0.tgz", - "integrity": "sha512-1fygroTLlHu66zi26VoTDv8yRgm0Fccecssto+MhsZ0D/DGW2sm8E8AjW7NU5VVTRt5GxbeZ5qBuJr+HyLYkjQ==", - "dev": true - }, - "picomatch": { - "version": "2.3.1", - "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", - "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", - "dev": true - }, - "pify": { - "version": "2.3.0", - "resolved": "https://registry.npmjs.org/pify/-/pify-2.3.0.tgz", - "integrity": "sha512-udgsAY+fTnvv7kI7aaxbqwWNb0AHiB0qBO89PZKPkoTmGOgdbrHDKD+0B2X4uTfJ/FT1R09r9gTsjUjNJotuog==", - "dev": true - }, - "postcss": { - "version": "8.4.16", - "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.16.tgz", - "integrity": "sha512-ipHE1XBvKzm5xI7hiHCZJCSugxvsdq2mPnsq5+UF+VHCjiBvtDrlxJfMBToWaP9D5XlgNmcFGqoHmUn0EYEaRQ==", - "dev": true, - "requires": { - "nanoid": "^3.3.4", - "picocolors": "^1.0.0", - "source-map-js": "^1.0.2" - } - }, - "postcss-cli": { - "version": "10.0.0", - "resolved": "https://registry.npmjs.org/postcss-cli/-/postcss-cli-10.0.0.tgz", - "integrity": "sha512-Wjy/00wBBEgQqnSToznxLWDnATznokFGXsHtF/3G8glRZpz5KYlfHcBW/VMJmWAeF2x49zjgy4izjM3/Wx1dKA==", - "dev": true, - "requires": { - "chokidar": "^3.3.0", - "dependency-graph": "^0.11.0", - "fs-extra": "^10.0.0", - "get-stdin": "^9.0.0", - "globby": "^13.0.0", - "picocolors": "^1.0.0", - "postcss-load-config": "^4.0.0", - "postcss-reporter": "^7.0.0", - "pretty-hrtime": "^1.0.3", - "read-cache": "^1.0.0", - "slash": "^4.0.0", - "yargs": "^17.0.0" - } - }, - "postcss-load-config": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/postcss-load-config/-/postcss-load-config-4.0.1.tgz", - "integrity": "sha512-vEJIc8RdiBRu3oRAI0ymerOn+7rPuMvRXslTvZUKZonDHFIczxztIyJ1urxM1x9JXEikvpWWTUUqal5j/8QgvA==", - "dev": true, - "requires": { - "lilconfig": "^2.0.5", - "yaml": "^2.1.1" - } - }, - "postcss-reporter": { - "version": "7.0.5", - "resolved": "https://registry.npmjs.org/postcss-reporter/-/postcss-reporter-7.0.5.tgz", - "integrity": "sha512-glWg7VZBilooZGOFPhN9msJ3FQs19Hie7l5a/eE6WglzYqVeH3ong3ShFcp9kDWJT1g2Y/wd59cocf9XxBtkWA==", - "dev": true, - "requires": { - "picocolors": "^1.0.0", - "thenby": "^1.3.4" - } - }, - "postcss-value-parser": { - "version": "4.2.0", - "resolved": "https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz", - "integrity": "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==", - "dev": true - }, - "pretty-hrtime": { - "version": "1.0.3", - "resolved": "https://registry.npmjs.org/pretty-hrtime/-/pretty-hrtime-1.0.3.tgz", - "integrity": "sha512-66hKPCr+72mlfiSjlEB1+45IjXSqvVAIy6mocupoww4tBFE9R9IhwwUGoI4G++Tc9Aq+2rxOt0RFU6gPcrte0A==", - "dev": true - }, - "queue-microtask": { - "version": "1.2.3", - "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz", - "integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==", - "dev": true - }, - "read-cache": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/read-cache/-/read-cache-1.0.0.tgz", - "integrity": "sha512-Owdv/Ft7IjOgm/i0xvNDZ1LrRANRfew4b2prF3OWMQLxLfu3bS8FVhCsrSCMK4lR56Y9ya+AThoTpDCTxCmpRA==", - "dev": true, - "requires": { - "pify": "^2.3.0" - } - }, - "readdirp": { - "version": "3.6.0", - "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.6.0.tgz", - "integrity": "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==", - "dev": true, - "requires": { - "picomatch": "^2.2.1" - } - }, - "require-directory": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", - "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==", - "dev": true - }, - "reusify": { - "version": "1.0.4", - "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.0.4.tgz", - "integrity": "sha512-U9nH88a3fc/ekCF1l0/UP1IosiuIjyTh7hBvXVMHYgVcfGvt897Xguj2UOLDeI5BG2m7/uwyaLVT6fbtCwTyzw==", - "dev": true - }, - "run-parallel": { - "version": "1.2.0", - "resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz", - "integrity": "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==", - "dev": true, - "requires": { - "queue-microtask": "^1.2.2" - } - }, - "slash": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/slash/-/slash-4.0.0.tgz", - "integrity": "sha512-3dOsAHXXUkQTpOYcoAxLIorMTp4gIQr5IW3iVb7A7lFIp0VHhnynm9izx6TssdrIcVIESAlVjtnO2K8bg+Coew==", - "dev": true - }, - "source-map-js": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.0.2.tgz", - "integrity": "sha512-R0XvVJ9WusLiqTCEiGCmICCMplcCkIwwR11mOSD9CR5u+IXYdiseeEuXCVAjS54zqwkLcPNnmU4OeJ6tUrWhDw==", - "dev": true - }, - "string-width": { - "version": "4.2.3", - "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", - "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", - "dev": true, - "requires": { - "emoji-regex": "^8.0.0", - "is-fullwidth-code-point": "^3.0.0", - "strip-ansi": "^6.0.1" - } - }, - "strip-ansi": { - "version": "6.0.1", - "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", - "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", - "dev": true, - "requires": { - "ansi-regex": "^5.0.1" - } - }, - "thenby": { - "version": "1.3.4", - "resolved": "https://registry.npmjs.org/thenby/-/thenby-1.3.4.tgz", - "integrity": "sha512-89Gi5raiWA3QZ4b2ePcEwswC3me9JIg+ToSgtE0JWeCynLnLxNr/f9G+xfo9K+Oj4AFdom8YNJjibIARTJmapQ==", - "dev": true - }, - "to-regex-range": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz", - "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==", - "dev": true, - "requires": { - "is-number": "^7.0.0" - } - }, - "universalify": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.0.tgz", - "integrity": "sha512-hAZsKq7Yy11Zu1DE0OzWjw7nnLZmJZYTDZZyEFHZdUhV8FkH5MCfoU1XMaxXovpyW5nq5scPqq0ZDP9Zyl04oQ==", - "dev": true - }, - "update-browserslist-db": { - "version": "1.0.5", - "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.0.5.tgz", - "integrity": "sha512-dteFFpCyvuDdr9S/ff1ISkKt/9YZxKjI9WlRR99c180GaztJtRa/fn18FdxGVKVsnPY7/a/FDN68mcvUmP4U7Q==", - "dev": true, - "requires": { - "escalade": "^3.1.1", - "picocolors": "^1.0.0" - } - }, - "wrap-ansi": { - "version": "7.0.0", - "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", - "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", - "dev": true, - "requires": { - "ansi-styles": "^4.0.0", - "string-width": "^4.1.0", - "strip-ansi": "^6.0.0" - } - }, - "y18n": { - "version": "5.0.8", - "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz", - "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==", - "dev": true - }, - "yaml": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.1.1.tgz", - "integrity": "sha512-o96x3OPo8GjWeSLF+wOAbrPfhFOGY0W00GNaxCDv+9hkcDJEnev1yh8S7pgHF0ik6zc8sQLuL8hjHjJULZp8bw==", - "dev": true - }, - "yargs": { - "version": "17.5.1", - "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.5.1.tgz", - "integrity": "sha512-t6YAJcxDkNX7NFYiVtKvWUz8l+PaKTLiL63mJYWR2GnHq2gjEWISzsLp9wg3aY36dY1j+gfIEL3pIF+XlJJfbA==", - "dev": true, - "requires": { - "cliui": "^7.0.2", - "escalade": "^3.1.1", - "get-caller-file": "^2.0.5", - "require-directory": "^2.1.1", - "string-width": "^4.2.3", - "y18n": "^5.0.5", - "yargs-parser": "^21.0.0" - } - }, - "yargs-parser": { - "version": "21.1.1", - "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz", - "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==", - "dev": true - } - } -} diff --git a/package.json b/package.json deleted file mode 100644 index 59e47242eb8..00000000000 --- a/package.json +++ /dev/null @@ -1,27 +0,0 @@ -{ - "name": "aws-sdk-go-v2-docs", - "version": "1.0.0", - "description": "This source tree contains the AWS SDK for Go V2 developer and migration guides.", - "main": "index.js", - "directories": { - "doc": "docs" - }, - "devDependencies": { - "autoprefixer": "^10.0.2", - "postcss": "^8.4.5", - "postcss-cli": "^10.0.0" - }, - "scripts": { - "test": "echo \"Error: no test specified\" && exit 1" - }, - "repository": { - "type": "git", - "url": "git+https://github.com/aws/aws-sdk-go-v2.git#documentation" - }, - "author": "", - "license": "Apache-2.0", - "bugs": { - "url": "https://github.com/skmcgrail/aws-sdk-go-v2/issues" - }, - "homepage": "https://github.com/skmcgrail/aws-sdk-go-v2#readme" -} diff --git a/static/diagrams/middleware.png b/static/diagrams/middleware.png deleted file mode 100644 index 94ccd9f1031..00000000000 Binary files a/static/diagrams/middleware.png and /dev/null differ diff --git a/utilities/README.md b/utilities/README.md deleted file mode 100644 index cb8b9fa6ea1..00000000000 --- a/utilities/README.md +++ /dev/null @@ -1,8 +0,0 @@ -## Setup - -1. Install [Pandoc](https://pandoc.org/) and ensure it is in your `PATH`. -2. Execute -``` -cd ./scripts -./UpdateGoExamples.sh -p $REPO_ROOT/content/en/docs/code-examples -u $GITHUB_USERNAME -l go -k md -t index -``` diff --git a/utilities/cmd/patch-zonbook-files/config.json b/utilities/cmd/patch-zonbook-files/config.json deleted file mode 100644 index 7ad52d8d5b0..00000000000 --- a/utilities/cmd/patch-zonbook-files/config.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "PathComment": "Path defines where the XLM/Zonbook files are found", - "Path": "", - "LanguageComment": "Language defines the name of the entity file in shared", - "Language": "go" -} diff --git a/utilities/cmd/patch-zonbook-files/main.go b/utilities/cmd/patch-zonbook-files/main.go deleted file mode 100644 index 4baf021cc3b..00000000000 --- a/utilities/cmd/patch-zonbook-files/main.go +++ /dev/null @@ -1,524 +0,0 @@ -package main - -import ( - "bufio" - "encoding/json" - "errors" - "flag" - "fmt" - "io/ioutil" - "os" - "path/filepath" - "strconv" - "strings" -) - -// Config defines the configuration values from config.json -type Config struct { - Path string `json:"Path"` - Language string `json:"Language"` - DebugString string `json:"Debug"` - Debug bool -} - -var configFileName = "config.json" - -var globalConfig Config - -func populateConfiguration() error { - content, err := ioutil.ReadFile(configFileName) - if err != nil { - return err - } - - text := string(content) - - err = json.Unmarshal([]byte(text), &globalConfig) - if err != nil { - return err - } - - globalConfig.Debug = globalConfig.DebugString == "true" - - return nil -} - -func debugPrint(debug bool, s string) { - if debug { - fmt.Println(s) - } -} - -// Utility functions to get the first and last N chars from a string -func getFirstN(s string, n int) string { - if len(s) < n { - return "" - - } - - return s[0:n] -} - -func getLastN(s string, n int) string { - if len(s) < n { - return "" - - } - - return s[len(s)-n:] -} - -func stripFirstN(s string, n int) string { - if len(s) < n { - return "" - - } - - return getLastN(s, len(s)-n) -} - -func stripLastN(s string, n int) string { - if len(s) < n { - return "" - - } - - return getFirstN(s, len(s)-n) -} - -/* - Returns an empty string if text does not match: - - -*/ -func patchEntRef(debug bool, text string, lang string, depth int) string { - entString := "" - - text = strings.Trim(text, " \t") - - if text != entString { - return "" - } - - // Split string by " - // The string we want to change has the following parts: - // "" - // so make sure there are three parts - parts := strings.Split(text, "\"") - - if len(parts) != 3 { - return "" - } - - // Now build up the tag - tag := "" -} - -// Determines whether text ends with: -// -func isFullTitle(debug bool, text string) bool { - // Trim off any leading or trailing white space - text = strings.Trim(text, " \t") - endChars := "" - - // Is the string long enough? - minLen := len("." + endChars) - - if len(text) < minLen { - debugPrint(debug, "Text is not long enough to be a full title tag") - return false - } - - lastCharsLength := len(endChars) - - // Does it end with </info - lastChars := getLastN(text, lastCharsLength) - - if lastChars != endChars { - debugPrint(debug, "Text does not end with "+endChars) - return false - } - - return true -} - -/* - Returns "" if it's not a title tag; - i.e, does NOT start with: - - - Returns string, where string is: - <info><title id="SECTION-ID.title">... - if we have part of a title, such as: - <info><title>... - OR - <info><title id="SECTION-ID.title"...</info> - if we have an entire title. -*/ -func getTitle(debug bool, text string, sectionID string) string { - // Trim off any leading white space - text = strings.TrimLeft(text, " \t") - - // It's not a title tag if the line isn't at least as long as: - preamble := "" - minLen := len(preamble) - - if len(text) < minLen { - return "" - } - - firstTags := getFirstN(text, minLen) - - if firstTags != preamble { - // It's not at least <info><title> - return "" - } - - debugPrint(debug, "Original title tag:") - debugPrint(debug, " "+text) - - /* text that has a title tag is something like: - <info><title>AssumeRolev2.go - TEXT - so check for the first case by calling isFullTitle(). - */ - - fullTitle := isFullTitle(debug, text) - if fullTitle { - debugPrint(debug, "Full title") - } else { - debugPrint(debug, "NOT a full title") - } - - // Strip off leading tags - titleText := stripFirstN(text, len(preamble)) - - /* Should now be something like: - TEXT</info> - OR - TEXT - so strip off traling "" - (we'll restore them when we return if fullTitle) - */ - if fullTitle { - titleText = stripLastN(titleText, len("")) - } - - debugPrint(debug, "Title text before removing suffix:") - debugPrint(debug, titleText) - - // If we have a full title - if fullTitle { - return "" + titleText + "" - } - - // titleText did NOT end with "" - return "" + titleText -} - -// If text is a section tag, such as: -// <section id="anythingv2.go"> -// and lang == "go" -// return "anythingv2" -func getSectionID(debug bool, text string, lang string) string { - // Trim off any potential leading or trailing white space - text = strings.Trim(text, " \t") - - // Split by quotes, so we should get something like: - // <section id= - // anythingv2.go - // > - parts := strings.Split(text, "\"") - - if len(parts) != 3 { - return "" - } - - if parts[0] != "<section id=" { - return "" - } - - if lang != "" { - // Lop off .LANG if it exists - lastPart := "." + lang - lastLen := len(lastPart) - tail := getLastN(parts[1], lastLen) - - if tail == lastPart { - text = stripLastN(parts[1], lastLen) - } else { - text = parts[1] - } - } - - // Do something similar if the section ID ends with a period - lastPart := "." - lastLen := len(lastPart) - tail := getLastN(parts[1], lastLen) - - if tail == lastPart { - text = stripLastN(parts[1], lastLen) - } - - return text -} - -func patchFiles(debug bool, sourcePath string, lang string) error { - srcParts := strings.Split(sourcePath, "\\") - srcLength := len(srcParts) // Should be 3 for C:\test\test - debugPrint(debug, "Depth is "+strconv.Itoa(srcLength)+" for "+sourcePath) - - // srcParts := strings.Split(sourcePath, "/") - // srcLength := len(srcParts) - // Get list of files and directories - // and call patchFile for every file. - err := filepath.Walk(sourcePath, - func(path string, info os.FileInfo, err error) error { - if err != nil { - return err - } - - // Skip directories - if info.IsDir() { - return nil - } - - // Only parse XML files - // First get filename from path - fileParts := strings.Split(path, "\\") - // we get: {D:, src, aws-cdk-examples, file.xml} - // Should be 5 for C:\test\test\Dynamodb\README.xml - // and 6 for C:\test\test\dynamodb\DescribeTable\DescribeTablev2.xml - length := len(fileParts) - - debugPrint(debug, "Depth is "+strconv.Itoa(length)+" for "+path) - depth := length - srcLength - 3 - - fileName := fileParts[length-1] // Now we have file.ext, so does ext == xml? - - parts := strings.Split(fileName, ".") // gives us file and xml - - if len(parts) < 2 || parts[1] != "xml" { - return nil - } - - // If it's an xml file, call patchFile - err = patchFile(debug, path, depth, lang) - - return err - }) - if err != nil { - return err - } - - return nil -} - -func myWrite(debug bool, w bufio.Writer, s string) { - _, err := w.WriteString(s + "\n") - if err != nil { - panic(err) - } - - w.Flush() -} - -// Patches the section ID and creates the associated title ID in an XML (Zonbook) file -// Name is going to be something like: -// CopyObject.xml - -// Patches the section ID and creates the associated title ID in an XML (Zonbook) file -// Name is going to be something like: -// CopyObject.xml - -// Returns true if we created patch file name.lmx -func patchFile(debug bool, name string, depth int, lang string) error { - fmt.Println("Parsing " + name) - - parts := strings.Split(name, ".") // gives us filename and xml - // make sure it has two parts - if len(parts) != 2 { - msg := "The filename " + name + " did not match NAME.EXTENSION" - return errors.New(msg) - } - - // Get contents of file - inFile, err := os.Open(name) - if err != nil { - msg := "Got error opening " + name - return errors.New(msg) - } - - defer inFile.Close() - - // Create topic file in that directory - fmt.Println("Creating new file " + parts[0] + ".lmx") - f, err := os.Create(parts[0] + ".lmx") - if err != nil { - return err - } - - defer f.Close() - - w := bufio.NewWriter(f) - - lineNumber := 0 - - // If not empty, we have found a section tag - // (from call to getSectionID) - sectionID := "" - rootSectionID := "" - - // If not empty, we have at least part of a title - // (from call to getTitle) - patchedTitle := "" - - scanner := bufio.NewScanner(inFile) - - for scanner.Scan() { - text := scanner.Text() - lineNumber++ - - debugPrint(debug, strconv.Itoa(lineNumber)+": "+text) - - // Skip empty lines - if len(text) == 0 { - myWrite(debug, *w, text) - continue - } - - // Do we already have part of a title? - if patchedTitle != "" { - // Just append the next line - patchedTitle = strings.TrimRight(patchedTitle, " ") - text = strings.TrimLeft(text, " ") - debugPrint(debug, "") - debugPrint(debug, "Created new title from two lines: ") - debugPrint(debug, " "+patchedTitle+" "+text) - debugPrint(debug, "") - - myWrite(debug, *w, patchedTitle+" "+text) - - sectionID = "" - patchedTitle = "" - continue - } - - // If we aren't in a section, try to find one so we can get its ID and save it for the title ID - if sectionID == "" { - // If input line contains a reference to the enitity file, - // fix that reference. - fixedEntRef := patchEntRef(debug, text, lang, depth) - - if fixedEntRef != "" { - myWrite(debug, *w, fixedEntRef) - continue - } - - sectionID = getSectionID(debug, text, lang) - - // If section ID == "", it's not a section, so just pass it through - if sectionID == "" { - myWrite(debug, *w, text) - continue - } - - // Stash first section ID as we need it for later section IDs - if rootSectionID == "" { - rootSectionID = sectionID - } else { - // Do we want to do this for all subsequent section IDs? - sectionID = rootSectionID + "-" + sectionID - } - - sectionTag := "<section id=\"" + sectionID + "\">" - - debugPrint(debug, "Original section tag:") - debugPrint(debug, " "+text) - - // We have a section ID, so barf out the section tag with that ID - debugPrint(debug, "New section tag: ") - debugPrint(debug, " "+sectionTag) - - myWrite(debug, *w, sectionTag) - - continue - } - - // We are in a section, so look for a title tag - patchedTitle = getTitle(debug, text, sectionID) - - // We just pass it through as it's not a title if patchedTitle == "" - if patchedTitle == "" { - myWrite(debug, *w, text) - continue - } - - fullTitle := isFullTitle(debug, patchedTitle) - - if fullTitle { - // We have a complete title, so no need to look for another until we hit a new section tag - debugPrint(debug, "New title with ID: ") - debugPrint(debug, " "+patchedTitle) - - myWrite(debug, *w, patchedTitle) - - sectionID = "" - patchedTitle = "" - continue - } - } - if err := scanner.Err(); err != nil { - msg := "Got error scanning " + name - return errors.New(msg) - } - - w.Flush() - return nil -} - -// Updates a Zonbook XML file so the title has an ID (section ID + ".title") -// If a -l flag is supplied, lops off the .lang from the section ID and title value -func main() { - err := populateConfiguration() - if err != nil { - globalConfig.Path = "" - globalConfig.Language = "" - globalConfig.Debug = false - } - // Process command line args - pathPtr := flag.String("p", globalConfig.Path, "Fully-qualified path to XML files") - langPtr := flag.String("l", globalConfig.Language, "The language for the entity filename.") - debugPtr := flag.Bool("d", globalConfig.Debug, "Whether to show debug output") - - flag.Parse() - - // Validate args - path := *pathPtr - lang := *langPtr - debug := *debugPtr - - if path == "" { - fmt.Println("You must specify where to start looking for XML/Zonbook files (-p PATH)") - return - } - - err = patchFiles(debug, path, lang) - if err != nil { - fmt.Println("Got an error patching files in " + path + ":") - fmt.Println(err.Error()) - } else { - fmt.Println("Patched XML files in " + path) - } -} diff --git a/utilities/cmd/traverse-repo-files/config.json b/utilities/cmd/traverse-repo-files/config.json deleted file mode 100644 index 9c0ddd543cb..00000000000 --- a/utilities/cmd/traverse-repo-files/config.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "UserNameComment": "UserName defines who is using GitHub API", - "UserName": "", - "LanguagesComment": "Languages is the list of programming languages for which we create code example topics", - "Languages": ["aws-cli", "c", "cloudformation", "cpp", "dotnet3.5", "gov2", "iam_policies", "javascriptv3", "javav2", "lambda_functions", "multi-language-examples", "php", "python", "ruby", "scripts", "typescript"], - "LanguageComment": "Language defines the specific programming language for which we create code example topics from the GitHub repo. Only gov2 is supported.", - "Language": "gov2", - "OutDirComment": "OutDir is the local directory where we place the constructed topic .MD files, based on the .GO source file name", - "Outdir": "", - "TranslationComment": "Option to translate source filename -> destination filename; valid values are none (just use existing filename), index (tranlate everything to _index.md), or metadata (use name from metadata.yaml)", - "Translation": "index" -} diff --git a/utilities/cmd/traverse-repo-files/main.go b/utilities/cmd/traverse-repo-files/main.go deleted file mode 100644 index 18d9fa4b61e..00000000000 --- a/utilities/cmd/traverse-repo-files/main.go +++ /dev/null @@ -1,627 +0,0 @@ -package main - -import ( - "bufio" - "bytes" - "encoding/json" - "errors" - "flag" - "fmt" - "io/ioutil" - "net/http" - "os" - "strings" - - "gopkg.in/yaml.v2" -) - -// Data represents the entries in metadata.yaml -type Data struct { - Files []struct { - Path string `yaml:"path"` - Description string `yaml:"description"` - Services []string `yaml:"services"` - Operations []string `yaml:"operations"` - } `yaml:"files"` -} - -// Global struct to hold metadata for gov2 and gov2/<service> folders -var files Data - -func populateFiles(debug bool, path string) error { - filePrefix := "https://raw.githubusercontent.com/awsdocs/aws-doc-sdk-examples/master/" - debugPrint(debug, "Getting metadata from "+filePrefix+path) - results, err := http.Get(filePrefix + path) - if err != nil { - return err - } - - buf := new(bytes.Buffer) - buf.ReadFrom(results.Body) - text := buf.String() - - err = yaml.Unmarshal([]byte(text), &files) - if err != nil { - fmt.Println("Got an error unmarshalling " + filePrefix + path) - return err - } - - return nil -} - -// RepoTree represents the files in a repo -// See https://docs.github.com/en/free-pro-team@latest/rest/reference/git#trees -type RepoTree struct { - Sha string `json:"sha"` // Like a checksum for the request - URL string `json:"url"` // The API URL for the request - Tree []struct { - Path string `json:"path"` // The path to the directory/file after https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/ - Mode string `json:"mode"` // The file permissions. Most folders are ; files 100644 - Type string `json:"type"` // "blob" for files; "tree" for directories - Sha string `json:"sha"` // Like a checksum for the directory/file - Size int `json:"size"` // The size, in bytes, of files - URL string `json:"url"` // The API URL for the file - } `json:"tree"` - Truncated bool `json:"truncated"` // Whether the request was truncated (more to come) -} - -func debugPrint(debug bool, s string) { - if debug { - fmt.Println(s) - } -} - -func isValueLanguage(debug bool, lang string) bool { - for _, l := range globalConfig.Languages { - if lang == l { - return true - } - } - - return false -} - -// This only works for Go currently -func getNameForSvcDir(debug bool, dir string) string { - switch dir { - case "cloudwatch": - return "Amazon CloudWatch" - case "dynamodb": - return "Amazon DynamoDB" - case "ec2": - return "Amazon EC2" - case "iam": - return "IAM" - case "kms": - return "AWS KMS" - case "s3": - return "Amazon S3" - case "sns": - return "Amazon SNS" - case "sqs": - return "Amazon SQS" - case "ssm": - return "AWS Systems Manager" - case "sts": - return "AWS STS" - default: - return "" - } -} - -func createSvcDir(debug bool, language string, dir string, outDir string, translation string) error { - name := getNameForSvcDir(debug, dir) - if name == "" { - msg := dir + " is not recognized as a valid service directory" - return errors.New(msg) - } - - outputDir := outDir + "/" + dir - outputFile := outputDir + "/" - - // Create directory for service - debugPrint(debug, "Creating service directory "+outputDir) - err := os.Mkdir(outDir+"/"+dir, 0755) - if err != nil { - return err - } - - switch translation { - case "index": - // Create _index.md files for top-level service topics - outputFile += "_index.md" - break - default: - // Otherwise, create <service>_index.md - outputFile += dir + "_index.md" - } - - // Create topic file in that directory - f, err := os.Create(outputFile) - if err != nil { - return err - } - - defer f.Close() - - w := bufio.NewWriter(f) - - content := "" - - switch translation { - case "index": - // Here's what we write to [<service>]_index.md - content = "---\n" + - "title: \"" + name + " Examples\"\n" + - "linkTitle: \"" + name + "\"\n" + - "weight: 3\n" + - "---\n" + - "\n" + - "This section contains code examples for " + name + " using version 2 of the AWS SDK for Go.\n" - - break - default: - content = "This section contains code examples for " + name + " using version 2 of the AWS SDK for Go.\n" - // Add after updating metadata.yaml with description, operations: - // 1. Get all paths that don't end in _test.go -> ## path - // 2. Get description for that entry -> Description - break - } - - _, err = w.WriteString(content) - if err != nil { - fmt.Println("Got an error writing to " + outputFile) - return err - } - - /* If we ever want to add the contents of the README.md file in that folder: - filePrefix := "https://raw.githubusercontent.com/awsdocs/aws-doc-sdk-examples/master/" - path := filePrefix + language + "/" + dir + "/" + "README.md" - results, err := http.Get(path) - if err != nil { - return err - } - - buf := new(bytes.Buffer) - buf.ReadFrom(results.Body) - text := buf.String() - - _, err = w.WriteString(text) - if err != nil { - fmt.Println("Got an error writing README.md to " + outputFile) - return err - } - */ - - w.Flush() - - return nil -} - -func createOperationDir(debug bool, dir string, subdir string, outDir string) error { - outputDir := outDir + "/" + dir + "/" + subdir - - // Create directory - debugPrint(debug, "Creating operation directory "+outputDir) - err := os.Mkdir(outputDir, 0755) - - return err -} - -func getNameFromMetadata(debug bool, subdir string, file string) (string, error) { - // Wade through files - // If subdir/file == path, return operation[0], if it exists - for _, f := range files.Files { - debugPrint(debug, "Looking at metadata path: "+f.Path) - - // Until we get operations for all Go v2 service metadata files - if f.Path == subdir+"/"+file { - if nil != f.Operations && f.Operations[0] != "" { - return f.Operations[0], nil - } - } - - debugPrint(debug, "No operations for "+subdir+"/"+file) - // Just return the filename, with .go replace by .md - file = strings.Replace(file, ".go", ".md", 1) - return file, nil - } - - return "", nil -} - -func createFile(debug bool, dir string, subdir string, fileName string, path string, outDir string, translation string) error { - filePrefix := "https://raw.githubusercontent.com/awsdocs/aws-doc-sdk-examples/master/" - linkPrefix := "https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/gov2/" - linkFile := linkPrefix + dir + "/" + subdir + "/" + fileName - - filePath := filePrefix + path - - // Is there a README.md file in the same directory? - // filePath is something like: - // https://raw.githubusercontent.com/awsdocs/aws-doc-sdk-examples/master/gov2/cloudwatch/DescribeAlarms/DescribeAlarmsv2.go - // So split the string by '/', get the last part, and replace it with README.md. - mdFilePath := strings.Replace(filePath, fileName, "README.md", 1) - - // Snarf README.md and use it to start building the local file - results, err := http.Get(mdFilePath) - if err != nil { - return err - } - - outFileName := outDir + "/" + dir + "/" + subdir - - // The file to create - switch translation { - case "index": - outFileName += "/_index.md" - break - case "metadata": - name, err := getNameFromMetadata(debug, subdir, fileName) - if err != nil { - return err - } - - debugPrint(debug, "Name from metadata: "+name) - - outFileName += "/" + name - break - default: // none - fileName = strings.Replace(fileName, ".go", ".md", 1) - outFileName += "/" + fileName - } - - debugPrint(debug, "Creating output file: "+outFileName) - - // Read each line of readme file from repo - scanner := bufio.NewScanner(results.Body) - - f, err := os.OpenFile(outFileName, os.O_RDWR|os.O_CREATE, 0644) - if err != nil { - fmt.Println("Got an error opening " + outFileName) - return err - } - - _, err = f.Write([]byte(fmt.Sprintf(`--- -title: "%s" ---- -`, strings.TrimSuffix(fileName, ".go")))) - if err != nil { - fmt.Println("Got an error writing to " + outFileName) - return err - } - - defer f.Close() - - // Dump contents of readme into new MD file - for scanner.Scan() { - // Convert third-level heading to top-level heading - text := strings.Replace(scanner.Text(), "##", "#", 1) - _, err = f.Write([]byte(text + "\n")) - if err != nil { - fmt.Println("Got an error writing to " + outFileName) - return err - } - } - - // Add heading for code - _, err = f.Write([]byte("\n## Source code\n\n")) - if err != nil { - fmt.Println("Got an error writing to " + outFileName) - return err - } - - // Get contents of repo file - resp, err := http.Get(filePath) - if err != nil { - return err - } - - scanner = bufio.NewScanner(resp.Body) - - // Start of code - _, err = f.Write([]byte("```go\n")) - if err != nil { - fmt.Println("Got an error writing to " + outFileName) - return err - } - - for scanner.Scan() { - // Strip out any snippet tags - if !strings.Contains(scanner.Text(), "snippet-") { - _, err = f.Write([]byte(scanner.Text() + "\n")) - if err != nil { - fmt.Println("Got an error writing to " + outFileName) - return err - } - } - } - - coda := "```\n" + - "\n" + - "See the [complete example in GitHub](" + linkFile + ")." - - // End of code - _, err = f.Write([]byte(coda)) - if err != nil { - fmt.Println("Got an error writing to " + outFileName) - return err - } - - return nil -} - -func processFiles(debug bool, language string, input string, outDir string, translation string) error { - // We're only looking at gov2 paths for now - if language != "gov2" { - return errors.New("Sorry, only gov2 is currently supported as a language") - } - - // Unmarshal string into tree - var repoTree RepoTree - - json.Unmarshal([]byte(input), &repoTree) - - svcDir := "" - subDir := "" - - for _, leaf := range repoTree.Tree { - // leaf.Path for a file looks like: - // gov2/cloudwatch/CreateCustomMetric/CreateCustomMetricv2.go - - if leaf.Path == language { - debugPrint(debug, "Processing "+language+" root path: "+leaf.Path) - if translation == "metadata" { - // Read metadata so we can name output files correctly - debugPrint(debug, "Processing "+leaf.Path+"/metadata.yaml") - err := populateFiles(debug, leaf.Path+"/metadata.yaml") - if err != nil { - return err - } - } - } - - // Split up the path '/' - parts := strings.Split(leaf.Path, "/") - // parts[0] == gov2 - // parts[1] == cloudwatch - // parts[2] == CreateCustomeMetric - // parts[3] == CreateCustomMetricv2.go - - if parts[0] != language { - continue - } - - switch len(parts) { - case 2: - // We have something like: - // gov2/cloudwatch or gov2/.gitignore - // so skip files - if leaf.Type == "blob" { - break - } - - if svcDir != parts[1] { - debugPrint(debug, "Found new service directory: "+parts[1]) - - if translation == "metadata" { - // Read metadata so we can: - // * name operation topic files correctly when metadata-based naming scheme is specified - // * create list of code examples for service-level topic - debugPrint(debug, "Processing "+parts[0]+"/"+parts[1]+"/metadata.yaml") - err := populateFiles(debug, parts[0]+"/"+parts[1]+"/metadata.yaml") - if err != nil { - return err - } - } - - err := createSvcDir(debug, language, parts[1], outDir, translation) - if err != nil { - return err - } - - svcDir = parts[1] - } - - break - case 3: - // Now we have entries like: - // gov2/cloudwatch/CreateCustomMetric - // Make sure we trap any files at this level - // Files are of type "blob" - if leaf.Type == "blob" { - break - } - - if subDir != parts[2] { - debugPrint(debug, "Found new operation directory: "+parts[2]) - - err := createOperationDir(debug, svcDir, parts[2], outDir) - if err != nil { - return err - } - - subDir = parts[2] - } - - break - case 4: - // Now we have entries like: - // gov2/cloudwatch/CreateCustomMetric/CreateCustomMetricv2.go - // parts[0] == gov2 - // parts[1] == cloudwatch - // parts[2] == CreateCustomeMetric - // parts[3] == CreateCustomMetricv2.go - // gov2/cloudwatch/CreateCustomMetric/CreateCustomMetricv2_test.go - // gov2/cloudwatch/CreateCustomMetric/config.json - // We only care about *.go, but not _test.go - if strings.Contains(parts[3], "_test.go") { - break - } - - if strings.Contains(parts[3], ".go") { - // For paths like: - // gov2/cloudwatch/CreateCustomMetric/CreateCustomMetricv2.go - err := createFile(debug, svcDir, subDir, parts[3], leaf.Path, outDir, translation) - if err != nil { - return err - } - } - - break - - default: - break - } - } - - return nil -} - -// Config defines the configuration values from config.json -type Config struct { - UserName string `json:"UserName"` - Languages []string `json:"Languages"` - Language string `json:"Language"` - OutDir string `json:"OutDir"` - Translation string `json:"Translation"` -} - -var configFileName = "config.json" - -var globalConfig Config - -func populateConfiguration() error { - content, err := ioutil.ReadFile(configFileName) - if err != nil { - return err - } - - text := string(content) - - err = json.Unmarshal([]byte(text), &globalConfig) - if err != nil { - return err - } - - return nil -} - -func usage() { - fmt.Println("Usage:") - fmt.Println(" go run TraverseRepoFiles.go -u NAME -l Language -o OUTPUT-DIR [-t none | index (default) | metadata] [-d] [-h] [-f]") - fmt.Println(" where:") - fmt.Println(" NAME is the name of the GitHub user used to the GitHub API") - fmt.Println(" the default is the value of UserName in config.json") - fmt.Println(" LANGUAGE is the programming language directory in our GitHub repo, such as gov2") - fmt.Println(" the default is the value of Language in config.json") - fmt.Println(" OUT-DIR specifies where the code example topics are saved") - fmt.Println(" the default is the value of OutDir in config.json") - fmt.Println(" -d (debug) displays additional debugging information") - fmt.Println(" -h (help) displays this error message and quits") - fmt.Println(" -f (fake it) displays the response as JSON and quits") - fmt.Println("") -} - -func main() { - err := populateConfiguration() - if err != nil { - globalConfig.UserName = "" - globalConfig.Language = "" - globalConfig.OutDir = "" - globalConfig.Translation = "index" - } - - userName := flag.String("u", globalConfig.UserName, "Your GitHub user name") - language := flag.String("l", globalConfig.Language, "The language in the GitHub repo") - outDir := flag.String("o", globalConfig.OutDir, "Root directory where the output files are created") - translation := flag.String("t", globalConfig.Translation, "Whether to translate source filename -> destination filename; valid values are none (just use existing filename), index (default, translate everything to _index.md), or metadata (use name from metadata.yaml)") - debug := flag.Bool("d", false, "Whether to barf out more info. False by default.") - fakeIt := flag.Bool("f", false, "Whether to just barf out the response") - help := flag.Bool("h", false, "Displays usage and quits") - flag.Parse() - - if *help { - usage() - return - } - - if *userName == "" || *language == "" || *outDir == "" { - usage() - return - } - - if *debug { - fmt.Println("Debugging enabled") - fmt.Println("User: " + *userName) - fmt.Println("Language: " + *language) - fmt.Println("Output dir: " + *outDir) - fmt.Println("Translation: " + globalConfig.Translation) - } - - // We overload language in the toolchain - if *language == "go" { - *language = "gov2" - } - - if !isValueLanguage(*debug, *language) { - fmt.Println("The language directory " + *language + " is not present in the repo") - return - } - - if !(*translation == "none" || *translation == "index" || *translation == "metadata") { - fmt.Println("The translation value " + *translation + " is neither none, index, nor metadata") - return - } - - gitHubURL := "https://api.github.com" - query := gitHubURL + "/repos/awsdocs/aws-doc-sdk-examples/git/trees/master?recursive=1" - - debugPrint(*debug, "Querying: ") - debugPrint(*debug, query) - - jsonData := "" - jsonValue, _ := json.Marshal(jsonData) - - request, err := http.NewRequest("GET", query, bytes.NewBuffer(jsonValue)) - if err != nil { - fmt.Println("Got an error creating HTTP request:") - fmt.Println(err) - return - } - - request.Header.Set("Content-Type", "application/json") - request.Header.Set("Accept", "application/vnd.github.v3+json") - - request.SetBasicAuth(*userName, "") - - client := &http.Client{} - - response, err := client.Do(request) - if err != nil { - fmt.Printf("The HTTP request failed with error %s\n", err) - return - } - - data, _ := ioutil.ReadAll(response.Body) - - var prettyJSON bytes.Buffer - error := json.Indent(&prettyJSON, data, "", "\t") - if error != nil { - fmt.Println("Got an error indenting JSON bytes:") - fmt.Println(err) - return - } - - // If tryit set, just barf out response - if *fakeIt { - fmt.Println(string(prettyJSON.Bytes())) - return - } - - err = processFiles(*debug, *language, string(prettyJSON.Bytes()), *outDir, *translation) - if err != nil { - fmt.Println("Got an error processing files:") - fmt.Println(err) - } -} diff --git a/utilities/go.mod b/utilities/go.mod deleted file mode 100644 index 480b2f90125..00000000000 --- a/utilities/go.mod +++ /dev/null @@ -1,8 +0,0 @@ -module aws-sdk-go-v2-doc-utils - -go 1.15 - -require ( - github.com/davecgh/go-spew v1.1.1 - gopkg.in/yaml.v2 v2.4.0 -) diff --git a/utilities/go.sum b/utilities/go.sum deleted file mode 100644 index b7b8cbb104f..00000000000 --- a/utilities/go.sum +++ /dev/null @@ -1,6 +0,0 @@ -github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= -github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= -gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= -gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= -gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY= -gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ= diff --git a/utilities/scripts/FixZonbookTags.sh b/utilities/scripts/FixZonbookTags.sh deleted file mode 100755 index fba196886c1..00000000000 --- a/utilities/scripts/FixZonbookTags.sh +++ /dev/null @@ -1,69 +0,0 @@ -#!/usr/bin/env bash - -make_list () { - masterList=./list.txt - # Delete existing list - rm $masterList > /dev/nul 2>&1 - find . -type f -name *.$1 -print > $masterList - tmp=$$.txt - cat $masterList | sed s/' '/'\\ '/g > $tmp - mv $tmp $masterList -} - -# Convert tags in XML files in current folder to XML/Zonbook tags -# It takes two args, $1 is the folder where to start looking for XML files -# and $2 is the default programming language for programlisting tags -# If we don't have an arg, we just leave the language tag out of programlisting tags - -pushd $1 -make_list xml - -# <title> -> <info><title> -# -> -# -> -# -> -# href/uling url -# -> - -for i in `cat $masterList` -do - tmpfile=$$.tmp - - echo "> $tmpfile - echo "[" >> $tmpfile - echo " " >> $tmpfile - echo " %xinclude;" >> $tmpfile - echo " " >> $tmpfile - echo " %phrases-shared;" >> $tmpfile - - if [ "$2" != "" ] - then - echo " " >> $tmpfile - echo " %phrases-${2};" >> $tmpfile - fi - - echo "]>" >> $tmpfile - - cat $i >> $tmpfile - rm $i - - cat $tmpfile | - sed "s/xml:id/id/g" | \ - sed "s//\<info\>\<title\>/g" | \ - sed "s/<\/title>/\<\/title\>\<\/info>/g" | \ - sed "s/<literal>/<code>/g" | \ - sed "s/<\/literal>/<\/code>/g" | \ - sed "s/link xlink:href/ulink url/g" | \ - sed "s/<\/link>/<\/ulink>/g" > $i - - if [ "$2" != "" ] - then - rm $tmpfile - cat $i | sed "s/<programlisting>/<programlisting language=\"$2\">/g" > $tmpfile - mv $tmpfile $i - else - rm $tmpfile - fi -done - -rm $masterList > /dev/nul 2>&1 diff --git a/utilities/scripts/UpdateGoExamples.sh b/utilities/scripts/UpdateGoExamples.sh deleted file mode 100755 index 5d58697f640..00000000000 --- a/utilities/scripts/UpdateGoExamples.sh +++ /dev/null @@ -1,101 +0,0 @@ -#!/usr/bin/env bash - -usage() { echo "Usage: $0 -p OUTPUT-PATH -u GITHUB-USERNAME [-l LANGUAGE] (but only go is supported) -k md | xml -t index | metadata | none" 1>&2; exit 1; } - -while getopts ":d:p:u:l:k:t:" o; do - case "${o}" in - p) - p=${OPTARG} - ;; - u) - u=${OPTARG} - ;; - l) - l=${OPTARG} - ;; - k) - k=${OPTARG} - ((k == md || k == xml)) || usage - ;; - t) - t=${OPTARG} - ((t == index || t == metadata || t == none)) || usage - ;; - *) - usage - ;; - esac -done -shift $((OPTIND-1)) - -if [ -z "${p}" ]; then - echo "You must specify a path (-p PATH)" - usage -fi - -if [ -z "${u}" ]; then - echo "You must specify a GitHub user name (-u NAME)" - usage -fi - -if [ -z "${k}" ]; then - echo "You must specify a file extension to keep (-k md | xml)" - usage -fi - -if [ -z "${t}" ]; then - echo "You must specify a type of outout name (-t index | metadata | none)" - usage -fi - -echo "path = ${p}" -echo "user = ${u}" -echo "keep = ${k}" -echo "type = ${t}" - -if [ "$l" != "" ] -then - echo "lang = ${l}" - echo - echo "Creating empty ${p}/shared/${l}.ent" - mkdir $p/shared - touch $p/shared/$l.ent -fi - -echo -echo "Calling: traverse-repo-file -u $u -l $l -o $p -t $t" -echo "To Create MD files from GitHub repo" -pushd ../cmd/traverse-repo-files > /dev/null 2>&1 -go run . -u $u -l $l -o $p -t $t -popd > /dev/null 2>&1 - -if [ "$k" == "md" ] -then - echo "Finished with MD files" - exit -fi - -echo -echo "Calling: ./cnvReadmes2Zonbook.sh $p" -echo "To convert MD files in ${p} to XML/DocBook" -./cnvReadmes2Zonbook.sh $p - -echo -echo "Calling ./FixZonbookTags.sh $p $l" -echo "To convert DocBook tags -> Zonbook tags" -./FixZonbookTags.sh $p $l - -echo -echo "Calling patch-zonebook-files -p $p -l $l" -echo "To create LMX files in ${p} so the title has an ID (section ID + .title)" -pushd ../cmd/patch-zonebook-file > /dev/null 2>&1 -go run . -p $p -l $l -popd > /dev/null 2>&1 - -echo -echo "Calling ./fixXmlFiles.sh $p" -echo "To rename LMX files to XML AND deleting any MD files" -./fixXmlFiles.sh $p - -echo -echo Done diff --git a/utilities/scripts/cnvReadmes2Zonbook.sh b/utilities/scripts/cnvReadmes2Zonbook.sh deleted file mode 100755 index dac893ee5b0..00000000000 --- a/utilities/scripts/cnvReadmes2Zonbook.sh +++ /dev/null @@ -1,42 +0,0 @@ -#!/usr/bin/env bash - -make_list () { - masterList=./list.txt - # Delete existing list - rm $masterList > /dev/nul 2>&1 - find . -type f -name *.$1 -print > $masterList - tmp=$$.txt - cat $masterList | sed s/' '/'\\ '/g > $tmp - mv $tmp $masterList -} - -# Searches $1 for *.md files -# and converts them to XML/DocBook files. -# e.g. myFile.md -> myFile.xml - -# If we don't have an arg, bail with error message -if [ "$1" == "" ] -then - echo "You must tell me where to find the .MD files" - exit -fi - -# Navigate to $1 -pushd $1 > /dev/nul 2>&1 - -# Create list of markdown files -make_list md - -# For each markdown file -for i in `cat $masterList` -do -# echo "Converting $i" - # Convert it to XML - basename=`basename $i .md` - dirname=`dirname $i` - pandoc -f markdown -t docbook $1/$i > $1/$dirname/$basename.xml -done - -rm $masterList -popd > /dev/nul 2>&1 -echo Done diff --git a/utilities/scripts/fixXmlFiles.sh b/utilities/scripts/fixXmlFiles.sh deleted file mode 100755 index 9c56dafbde2..00000000000 --- a/utilities/scripts/fixXmlFiles.sh +++ /dev/null @@ -1,60 +0,0 @@ -#!/usr/bin/env bash - -make_list () { - masterList=./list.txt - # Delete existing list - rm $masterList > /dev/nul 2>&1 - find . -type f -name *.$1 -print > $masterList - tmp=$$.txt - cat $masterList | sed s/' '/'\\ '/g > $tmp - mv $tmp $masterList -} - -# Searches $1 for *.lmx files -# and renames them to *.xml. -# e.g. myFile.lmx -> myFile.xml - -# If we don't have an arg, bail with error message -if [ "$1" == "" ] -then - echo "You must tell me where to find the .MD files" - exit -fi - -# Navigate to $1 -pushd $1 > /dev/nul 2>&1 - -# If list of lmx or md files exists, delete them -rm lmx_masterList.txt > /dev/nul 2>&1 -rm md_masterList.txt > /dev/nul 2>&1 - -# Create list of lmx files -make_list lmx - -# For each lmx file -echo "Converting LMX files to XML" -for i in `cat $masterList` -do -# echo "Converting $i" - # Convert it to XML - basename=`basename $i .lmx` - dirname=`dirname $i` - mv $1/$i $1/$dirname/$basename.xml -done - -# Create list of md files -make_list md - -# For each md file -echo "Deleting MD files" -for i in `cat $masterList` -do -# echo "Deleting $i" - rm $i -done - -# Delete list -rm $masterList > /dev/nul 2>&1 - -popd > /dev/nul 2>&1 -echo Done