翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# SDK を設定
AWS SDK for Go V2 では、ロガー、ログレベル、再試行設定など、サービスクライアントの一般的な設定を行うことができます。ほとんどの設定はオプションです。ただし、サービスクライアントごとに、 AWS リージョンと認証情報を指定する必要があります。SDK はこれらの値を使用して、正しいリージョンにリクエストを送信し、正しい認証情報でリクエストに署名します。これらの値は、コード内でプログラムで指定することも、実行環境から取得することもできます。
## AWS 共有設定ファイルのロード
サービス API クライアントを初期化する方法はいくつかありますが、次に示すのはユーザーに推奨される最も一般的なパターンです。
AWS 共有設定ファイルを使用するように SDK を設定するには、次のコードを使用します。
```
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())` は、 AWS 共有設定ソースを使用して [aws.Config](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Config) を構築します。これには、認証情報プロバイダーの設定、 AWS リージョンの設定、サービス固有の設定のロードが含まれます。ロードされた `aws.Config` を使用してサービスクライアントを作成することで、クライアントの作成方法に一貫性を持たせることができます。
AWS 共有設定ファイルの詳細については、「SDK およびツールリファレンスガイド」の[「設定](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html)」を参照してください。 AWS SDKs
## AWS リージョンの指定
リージョンを指定するときは、`us-west-2` や `us-east-2` など、リクエストの送信先を指定します。各サービスのリージョンのリストについては、「 Amazon Web Services 全般のリファレンス」の「[サービスエンドポイントとクォータ](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html)」を参照してください。
SDK にはデフォルトのリージョンはありません。リージョンを指定するには:
+ `AWS_REGION` 環境変数を設定して、デフォルトのリージョンを指定します。
+ 設定のロード時に `config.LoadDefaultConfig` に [config.WithRegion](https://github.com/aws/aws-sdk-go-v2/blob/config/v0.2.2/config/provider.go#L127) を引数として渡して、明示的にリージョンを設定します。
注: これらすべての方法でリージョンを設定した場合、SDK は明示的に指定したリージョンを使用します。
### 環境変数を使用してリージョンを設定する
#### Linux、macOS、または Unix
```
export AWS_REGION=us-west-2
```
#### Server
```
set AWS_REGION=us-west-2
```
### リージョンをプログラムで指定する
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion("us-west-2"))
```
## 認証情報の指定
には、リクエストに署名するための認証情報 (アクセスキーとシークレットアクセスキー) AWS SDK for Go が必要です AWS。特定のユースケースに応じて、認証情報をいくつかの場所で指定できます。認証情報の取得については、「[AWS SDK for Go の開始方法](getting-started.md)」を参照してください。
を使用して`aws.Config`インスタンスを初期化すると`config.LoadDefaultConfig`、SDK はデフォルトの認証情報チェーンを使用して AWS 認証情報を検索します。このデフォルトの認証情報チェーンは、次の順序で認証情報を検索します。
1. 環境変数。
1. 静的な認証情報 (`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`、`AWS_SESSION_TOKEN`)
1. ウェブ ID トークン (`AWS_WEB_IDENTITY_TOKEN_FILE`)
1. 共有設定ファイル。
1. SDK は、ユーザーのコンピュータのホームフォルダ内にある `.aws` フォルダ下の `credentials` ファイルを共有設定ファイルのデフォルトとして使用します。
1. SDK は、ユーザーのコンピュータのホームフォルダ内にある `.aws` フォルダ下の `config` ファイルを共有設定ファイルのデフォルトとして使用します。
1. アプリケーションが Amazon ECS タスク定義または RunTask API オペレーションを使用している場合は、タスクの IAM ロール。
1. アプリケーションが Amazon EC2 インスタンスで動作している場合は、Amazon EC2 の IAM ロール。
SDK は、これらの組み込みプロバイダーを自動的に検出して使用するため、手動での設定は不要です。例えば、Amazon EC2 インスタンスの IAM ロールを使用している場合、アプリケーションは自動的にそのインスタンスの認証情報を使用します。アプリケーション側で認証情報を手動で設定する必要はありません。
ベストプラクティスとして、 では、次の順序で認証情報を指定 AWS することをお勧めします。
1. アプリケーションが Amazon ECS のタスク定義または RunTask API オペレーションを使用している場合は、タスクの IAM ロールを使用します。
1. アプリケーションが Amazon EC2 インスタンスで動作している場合は、Amazon EC2 の IAM ロールを使用します。
IAM ロールは、 AWS 呼び出しを行うための一時的なセキュリティ認証情報をインスタンスでアプリケーションに提供します。また IAM ロールは、複数の Amazon EC2 インスタンスに認証情報を分散して管理するための簡単な方法を提供します。
1. 共有認証情報または設定ファイルを使用します。
これらの認証情報と設定ファイルは、他の AWS SDK や AWS CLIと共有されます。セキュリティのベストプラクティスとして、アクセスキー ID やシークレットキーなどの機密情報は認証情報ファイルで設定することをお勧めします。これらの各ファイルの[フォーマット要件](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)は次のとおりです。
1. 環境変数を使用します。
Amazon EC2 インスタンス以外のマシンで開発作業を行う場合は、環境変数を設定すると便利です。
### タスク用の IAM ロール
アプリケーションが Amazon ECS タスク定義または `RunTask` オペレーションを使用している場合は、[タスクの IAM ロール](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)を使用して、タスクのコンテナで使用できる IAM ロールを指定します。
### Amazon EC2 インスタンスの IAM ロール
Amazon EC2 インスタンスでアプリケーションを実行している場合は、そのインスタンスの [IAM ロール](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)を利用して、 AWSへの呼び出しに使用する一時的なセキュリティ認証情報を取得します。
IAM ロールを使用するようにインスタンスを設定している場合、SDK はその認証情報を自動的に使用してアプリケーションを認証します。これらの認証情報を手動で指定する必要はありません。
### 共有認証情報と設定
共有認証情報と設定ファイルは、 AWS SDKs やその他のツール間で共通の設定を共有するために使用できます。ツールやアプリケーションごとに異なる認証情報を使用している場合は、*プロファイル*を使用して複数のアクセスキーを同じ設定ファイル内に設定できます。
`config.LoadOptions` を使用して複数の認証情報ファイルや設定ファイルの場所を指定できますが、SDK はデフォルトで、「[認証情報の指定](#specifying-credentials)」に記載されている既定の場所に保存されたファイルをロードします。
```
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"},
)
)
```
共有認証情報ファイルと設定ファイルを使用する場合、同じプロファイルが複数定義されていると、それらはマージされてプロファイルが解決されます。マージの競合が発生した場合:
1. 同じ認証情報/設定ファイル内でプロファイルが重複している場合は、後に記述されたプロファイルのプロパティが優先されます。
1. 複数の認証情報ファイルまたは複数の設定ファイル間でプロファイルが重複している場合は、`config.LoadOptions` に渡されたファイルの順序に基づいて、後のファイルのプロパティが優先されます。後のファイルのプロパティが優先されます。
1. 認証情報ファイルと設定ファイルの両方に同じプロファイルが存在する場合は、認証情報ファイルのプロパティが優先されます。
必要に応じて、`config.LoadOptions` で `LogConfigurationWarnings` を有効にして、プロファイル解決の手順をログに記録することもできます。
#### 認証情報ファイルの作成
共有認証情報ファイル (`.aws/credentials`) がない場合は、任意のテキストエディタを使用してホームディレクトリ内に作成できます。認証情報ファイルに次の内容を追加し、** と ** を実際の認証情報に置き換えます。
```
[default]
aws_access_key_id =
aws_secret_access_key =
```
`[default]` 見出しは、デフォルトプロファイルの認証情報を定義します。別のプロファイルを使用するように設定していない限り、SDK はこのデフォルトプロファイルを使用します。
次の例のように、セッショントークンをプロファイルに追加することで、一時的なセキュリティ認証情報を使用することもできます。
```
[temp]
aws_access_key_id =
aws_secret_access_key =
aws_session_token =
```
認証情報ファイル内のデフォルト以外のプロファイルのセクション名は、`profile` という単語で始めることはできません。詳細については、「[AWS SDK とツールのリファレンスガイド](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds)」を参照してください。
#### 設定ファイルの作成
共有認証情報ファイル (`.aws/config`) がない場合は、任意のテキストエディタを使用してホームディレクトリ内に作成できます。次の内容を設定ファイルに追加し、** を必要なリージョンに置き換えます。
```
[default]
region =
```
`[default]` 見出しは、デフォルトプロファイルの設定を定義します。別のプロファイルを使用するように設定していない限り、SDK はこのデフォルトプロファイルを使用します。
次の例のように、名前付きプロファイルを使用することもできます。
```
[profile named-profile]
region =
```
設定ファイル内のデフォルト以外のプロファイルのセクション名は、必ず `profile` という単語で始まり、その後に目的のプロファイル名が続く必要があります。詳細については、「[AWS SDK とツールのリファレンスガイド](https://docs.aws.amazon.com/credref/latest/refdocs/file-format.html#file-format-config)」を参照してください。
#### プロファイルの指定
アクセスキーの各セットをプロファイルに関連付けることで、同じ設定ファイルに複数のアクセスキーを含めることができます。例えば、認証情報ファイルでは、次のように複数のプロファイルを宣言できます。
```
[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 =
```
デフォルトでは、SDK は `AWS_PROFILE` 環境変数を確認して、使用するプロファイルを決定します。`AWS_PROFILE` 変数が設定されていない場合、SDK は `default`プロファイルを使用します。
アプリケーションで別のプロファイルを使用する場合もあります。例えば、`test-account` アプリケーションで `myapp` 認証情報を使用する場合です。このようなプロファイルを使用するには、次のコマンドを実行します。
```
$ AWS_PROFILE=test-account myapp
```
また、SDK がプロファイルを選択するようにするには、`config.LoadDefaultConfig` を呼び出す前に `os.Setenv("AWS_PROFILE", "test-account")` を呼び出すか、次の例のように明示的にプロファイルを引数として渡します。
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithSharedConfigProfile("test-account"))
```
**注記**
環境変数で認証情報を指定している場合は、どのプロファイルを指定していても、SDK は常にその環境変数の認証情報を使用します。
### 環境可変
デフォルトでは、SDK は環境で設定された AWS 認証情報を検出し、それらを使用してリクエストに署名します AWS。この方法では、アプリケーションで認証情報を管理する必要はありません。
SDK は次の環境変数から認証情報を検索します。
+ `AWS_ACCESS_KEY_ID`
+ `AWS_SECRET_ACCESS_KEY`
+ `AWS_SESSION_TOKEN` (オプション)
次の例では、環境変数の設定方法を示しています。
#### Linux、OS X、Unix
```
$ export AWS_ACCESS_KEY_ID=YOUR_AKID
$ export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
$ export AWS_SESSION_TOKEN=TOKEN
```
#### Server
```
> set AWS_ACCESS_KEY_ID=YOUR_AKID
> set AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
> set AWS_SESSION_TOKEN=TOKEN
```
### 認証情報をプログラムで指定する
`config.LoadDefaultConfig` では、共有設定ソースをロードするときに、明示的な [aws.CredentialProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsProvider) を指定できます。共有設定をロードするときに明示的な認証情報プロバイダーを渡すには、[config.WithCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithCredentialsProvider) を使用します。例えば、`customProvider` が `aws.CredentialProvider` 実装のインスタンスを参照している場合、次のように設定のロード時に渡すことができます。
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithCredentialsProvider(customProvider))
```
この例のように、明示的に認証情報を指定した場合、SDK はその認証情報のみを使用します。
**注記**
`LoadDefaultConfig` との間で受け渡しされるすべての認証情報プロバイダーは [CredentialsCache](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsCache) に自動的にラップされます。これにより、スレッドセーフなキャッシュと認証情報のローテーションが可能になります。`aws.Config` でプロバイダーを直接明示的に設定する場合は、[NewCredentialsCache](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NewCredentialsCache) を使用してそのプロバイダーをこの型で明示的にラップする必要があります。
#### 静的な認証情報
[credentials.NewStaticCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials#NewStaticCredentialsProvider) 認証プロバイダーを利用して、使用するアクセスキーを明示的に設定することで、アプリケーションに認証情報をハードコードすることもできます。例えば、次のようになります。
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("AKID", "SECRET_KEY", "TOKEN")),
)
```
**警告**
ただし、アプリケーション内に認証情報を埋め込まないでください。この方法はテスト目的にのみ使用してください。
#### シングルサインオン認証情報
SDK は、 を使用して一時的な認証情報を取得するための AWS 認証情報プロバイダーを提供します AWS IAM アイデンティティセンター。を使用して AWS CLI、 AWS アクセスポータルで認証し、一時的な AWS 認証情報へのアクセスを許可します。次に、シングルサインオン (SSO) プロファイルをロードするようにアプリケーションを設定します。SDK は SSO 認証情報を使用して一時的な AWS 認証情報を取得し、有効期限が切れると自動的に更新されます。SSO 認証情報の有効期限が切れた場合は、 を使用して IAM Identity Center アカウントに再度ログインして、明示的に更新する必要があります AWS CLI。
たとえば、プロファイルを作成し、 `dev-profile`を使用してそのプロファイルを認証および認可し AWS CLI、以下に示すようにアプリケーションを設定できます。
1. まず、`profile` と `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
```
1. を使用してログイン AWS CLI し、SSO プロファイルを認証および認可します。
```
$ 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. その後、SSO プロファイルを使用するようにアプリケーションを設定します。
```
import "github.com/aws/aws-sdk-go-v2/config"
// ...
cfg, err := config.LoadDefaultConfig(
context.Background(),
config.WithSharedConfigProfile("dev-profile"),
)
if err != nil {
return err
}
```
SSO プロファイルの設定と を使用した認証の詳細については、 ユーザーガイドの「 [を使用する AWS CLI ように AWS IAM アイデンティティセンター](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html)を設定する AWS CLI 」を参照してください。 AWS CLI SSO 認証情報プロバイダーをプログラムで作成する方法の詳細については、「[ssocreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/ssocreds) API リファレンスドキュメント」を参照してください。
#### ログイン認証情報
既存の AWS マネジメントコンソールのサインイン認証情報を使用して、 AWS サービスにプログラムでアクセスできます。ブラウザベースの認証フローの後、 は CLI AWS Tools for PowerShell や AWS SDKs AWS などのローカル開発ツールで動作する一時的な認証情報 AWS を生成します。この機能は、特に長期的なアクセスキーの管理よりもインタラクティブな認証を希望する場合に、CLI AWS 認証情報の設定と管理のプロセスを簡素化します。
1. AWS CLI を使用してログインフローを開始し、ブラウザのプロンプトに従います。この例では、ログインセッションを新しいプロファイル に保存しますが**dev-profile**、これはオプションです。
```
$ aws --profile dev-profile login
```
1. (オプション) AWS 共有設定ファイルを調べて、セッションが確立されたことを確認します。
```
[profile dev-profile]
login_session = arn:aws:sts::account id>:role
```
1. 次に、ログインプロファイルを使用するようにアプリケーションを設定します。
```
import "github.com/aws/aws-sdk-go-v2/config"
// ...
cfg, err := config.LoadDefaultConfig(
context.Background(),
// only necessary if login session is saved to a non-default profile
config.WithSharedConfigProfile("dev-profile"),
)
if err != nil {
return err
}
```
ログインプロファイルの設定と CLI AWS を使用した認証の詳細については、[「コンソール認証情報を使用した AWS ローカル開発のログイン](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html)」を参照してください。
#### その他の認証情報プロバイダー
SDK には、[credentials](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials) モジュール内で他にもさまざまな認証情報取得方法が提供されています。たとえば、 から一時的なセキュリティ認証情報を取得 AWS Security Token Service したり、暗号化されたストレージから認証情報を取得したりできます。
**使用可能な認証情報プロバイダー**:
+ [ec2rolecreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds) – Amazon EC2 IMDS 経由で、Amazon EC2 インスタンスロールから認証情報を取得します。
+ [endpointcreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/endpointcreds) – 任意の HTTP エンドポイントから認証情報を取得します。
+ [processcreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/processcreds) – ホスト環境のシェルで実行される外部プロセスから認証情報を取得します。
+ [stscreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/stscreds) – から認証情報を取得する AWS STS
# 認証を設定する
AWS SDK for Go には、認証動作サービスを設定する機能が用意されています。ほとんどの場合、デフォルト設定で十分ですが、カスタム認証を設定すると、プレリリースサービス機能の使用など追加の動作が可能になります。
## 定義
このセクションでは、AWS SDK for Go での認証ロジックの構成要素の概要を示します。
### AuthScheme
[AuthScheme](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#AuthScheme) は、オペレーションリクエストに呼び出し元の ID をアタッチするワークフローを、SDK 内で定義するインターフェイスです。
認証スキームでは、次の構成要素を使用します (詳細は後述)。
+ スキームを識別する一意の ID
+ 署名プロセスで使用される呼び出し元 ID (AWS 認証情報など) を返す ID リゾルバー
+ 署名ロジック。呼び出し元の ID をオペレーションのトランスポートリクエストに実際に挿入します (例: `Authorization` HTTP ヘッダー)
各サービスクライアントのオプションには `AuthSchemes` フィールドが含まれており、デフォルトではそのサービスでサポートされている認証スキームのリストが入力されています。
### AuthSchemeResolver
各サービスクライアントのオプションには `AuthSchemeResolver` フィールドが含まれています。このインターフェイスはサービスごとに定義され、各オペレーションで使用可能な認証オプションを決定するために SDK によって呼び出される API です。
**重要**
認証スキームリゾルバーは、使用する認証スキームを決定するものではありません。代わりに、*使用可能な*スキームのリスト (「Options」) を返し、最終的なスキームは[こちら](#auth-scheme-resolution-workflow)で説明している固定アルゴリズムによって選択されます。
### オプション
`ResolverAuthSchemes` を呼び出した結果として返される [Option](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option) は、認証の候補オプションを表します。
Option は 3 つの情報セットで構成されます。
+ 使用可能なスキームを表す ID
+ スキームの ID リゾルバーに渡される不透明なプロパティの集合
+ スキームの署名ロジックに渡される不透明なプロパティの集合
#### プロパティに関する注意事項
ほとんど (99%) のユースケースでは、呼び出し元は ID 解決および署名のための不透明なプロパティを意識する必要はありません。SDK は各スキームに必要なプロパティを自動的に抽出し、SDK で公開している厳密に型付けされたインターフェイスに渡します。例えば、サービスごとのデフォルトの認証リゾルバーは、SigV4 オプションに「署名名」と「リージョン」の情報を含む署名ロジックプロパティをエンコードします。これらの値は、SigV4 が選択されたときに、クライアントに設定された [v4.HTTPSigner](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option) 実装に渡されます。
### ID
[Identity](https://pkg.go.dev/github.com/aws/smithy-go/auth#Identity) は、SDK の呼び出し元を抽象的に表すものです。
SDK で最も一般的に使用される Identity の型は `aws.Credentials` です。ほとんどのユースケースでは、呼び出し元は `Identity` という抽象型を意識せず、具体的な型をそのまま扱うことができます。
**注記**
下位互換性の維持と API の混乱防止のため、AWS SDK 固有の Identity の型 `aws.Credentials` は、`Identity` インターフェイスを直接実装していません。このマッピングは内部で処理されます。
### IdentityResolver
[IdentityResolver](https://pkg.go.dev/github.com/aws/smithy-go/auth#IdentityResolver) は、`Identity` を取得するためのインターフェイスです。
`IdentityResolver` の具体的な実装は、SDK に厳密な型付き形式で含まれており ([aws.CredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsProvider) など)、これらのマッピングは SDK が内部で処理します。
呼び出し元は、外部の認証スキームを定義する場合にのみ、`IdentityResolver` インターフェイスを直接実装する必要があります。
### Signer
[Signer](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#Signer) は、取得された呼び出し元の `Identity` をリクエストに追加するためのインターフェイスです。
`Signer` の具体的な実装は、SDK に厳密な型付き形式で含まれており ([v4.HTTPSigner](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/signer/v4#HTTPSigner) など)、これらのマッピングは SDK が内部で処理します。
呼び出し元は、外部の認証スキームを定義する場合にのみ、`Signer` インターフェイスを直接実装する必要があります。
### AuthResolverParameters
各サービスは、それぞれ専用の入力値セットを受け取り、それを `AuthResolverParameters` としてサービスパッケージ内で定義された解決関数に渡します。
基本的なリゾルバーパラメータは次のとおりです。
| 名前 | type | description |
| --- | --- | --- |
| Operation | string | 呼び出されるオペレーションの名前。 |
| Region | string | クライアントの AWS リージョン。SigV4[A] を使用するサービスでのみ存在します。 |
独自のリゾルバーを実装する場合でも、これらのパラメータのインスタンスを自分で作成する必要はありません。SDK がリクエストごとにこれらの値を取得し、カスタム実装に渡します。
## 認証スキームの解決ワークフロー
SDK 経由で AWS サービスのオペレーションを呼び出すと、リクエストのシリアル化後に次の一連のアクションが実行されます。
1. SDK はクライアントの `AuthSchemeResolver.ResolveAuthSchemes()` API を呼び出して必要な入力パラメータを取得して、そのオペレーションで使用可能な [Options](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option) のリストを取得します。
1. SDK はそのリストを反復処理し、次の条件を満たす最初のスキームを選択します。
+ ID が一致するスキームがクライアント自身の `AuthSchemes` リストに存在する
+ スキームの ID リゾルバーがクライアントのオプション内に存在する (`nil` でない) (このチェックはスキームの `GetIdentityResolver` メソッドを通じて行われ、前述の具体的な ID リゾルバー型へのマッピングは内部で処理されます) (1)
1. 有効なスキームが選択されると、SDK はその `GetIdentityResolver()` API を呼び出して呼び出し元の ID を取得します。例えば、組み込みの SigV4 認証スキームは、クライアントの `Credentials` プロバイダーに内部でマッピングされます。
1. SDK は ID リゾルバーの `GetIdentity()` (例: SigV4 の場合は `aws.CredentialProvider.Retrieve()`) を呼び出します。
1. SDK はエンドポイントリゾルバーの `ResolveEndpoint()` を呼び出して、リクエストのエンドポイントを見つけます。このエンドポイントには、署名プロセスに影響する追加のメタデータ (S3 Object Lambda 用の一意の署名名など) が含まれている場合があります。
1. SDK は認証スキームの `Signer()` API を呼び出して署名ロジックを取得し、その `SignRequest()` API を使用して、取得済みの呼び出し元の ID でリクエストに署名します。
(1) SDK がリスト内で匿名オプション (ID `smithy.api#noAuth`) を検出した場合、対応する ID リゾルバーがないため、自動的にそのオプションが選択されます。
## ネイティブでサポートされている `AuthScheme`
次の認証スキームは AWS SDK for Go でネイティブにサポートされています。
| 名前 | スキーム ID | ID リゾルバー | Signer | メモ |
| --- | --- | --- | --- | --- |
| [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) | aws.auth\$1sigv4 | [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) | 現時点でほとんどの AWS サービスオペレーションで使用されるデフォルトです。 |
| SigV4A | aws.auth\$1sigv4a | aws.CredentialsProvider | 該当なし | SigV4A の使用は現時点では限定的であり、署名ロジックの実装は内部的なものです。HTTP リクエストに署名するための汎用 API を公開する新しいオプトインモジュール aws-http-auth については、こちらの[お知らせ](https://github.com/aws/aws-sdk-go-v2/discussions/2812)を参照してください。 |
| SigV4Express | com.amazonaws.s3\$1sigv4express | [s3.ExpressCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#ExpressCredentialsProvider) | v4.HTTPSigner | [Express One Zone](https://aws.amazon.com/s3/storage-classes/express-one-zone/) に使用されます。 |
| HTTP Bearer | smithy.api\$1httpBearerAuth | [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) | [codecatalyst](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/codecatalyst) によって使用されます。 |
| Anonymous | smithy.api\$1noAuth | 該当なし | 該当なし | 認証なし - ID は不要で、リクエストは署名も認証もされません。 |
### ID の設定
AWS SDK for Go では、認証スキームの ID 構成要素は SDK クライアントの `Options` で設定されます。SDK は、オペレーションが呼び出されたときに選択したスキームに対して、これらの構成要素の値を自動的に取得して使用します。
**注記**
下位互換性の理由から、ID リゾルバーが設定されていない場合、SDK は匿名認証スキームの使用を暗黙的に許可します。これは、クライアントの `Options` にあるすべての ID リゾルバーを `nil` に設定することで手動でも可能です (sigv4 の ID リゾルバーを `aws.AnonymousCredentials{}` に設定することもできます)。
### Signer の設定
AWS SDK for Go では、認証スキームの署名ロジック構成要素は SDK クライアントの `Options` で設定されます。SDK は、オペレーションが呼び出されたときに選択したスキームに対して、これらの構成要素の値を自動的に取得して使用します。追加の設定は不要です。
#### カスタム認証スキーム
カスタム認証スキームを定義して使用するには、呼び出し元で以下を行う必要があります。
1. [AuthScheme](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#AuthScheme) 実装を定義する
1. そのスキームを SDK クライアントの `AuthSchemes` リストに登録する
1. SDK クライアントの `AuthSchemeResolver` を調整して、必要に応じてスキーム ID を含む auth `Option` を返すようにします。
**警告**
次のサービスでは、独自またはカスタムの認証動作が実装されています。カスタム認証動作が必要な場合は、まずはデフォルト実装に処理を委譲し、その上で適切にラップしてカスタマイズすることをお勧めします。
| サービス | メモ |
| --- | --- |
| S3 | オペレーションの入力に応じて SigV4A および SigV4Express を条件付きで使用。 |
| EventBridge | オペレーションの入力に応じて SigV4A を条件付きで使用。 |
| Cognito | 一部のオペレーションは匿名専用。 |
| SSO | 一部のオペレーションは匿名専用。 |
| STS | 一部のオペレーションは匿名専用。 |
# クライアントエンドポイントを設定する
**警告**
エンドポイントの解決は上級者向けの SDK トピックです。これらの設定を変更すると、コードが動作しなくなる可能性があります。デフォルト設定は、本番環境のほとんどのユーザーに適しています。
AWS SDK for Go は、サービスに使用するカスタムエンドポイントを設定する機能を提供します。ほとんどの場合、デフォルトの設定で十分です。カスタムエンドポイントを設定することで、サービスのプレリリースバージョンとの連携など、追加の動作が可能になります。
## カスタマイズ
SDK では、エンドポイント解決の設定に 2 つの「バージョン」があります。
+ v2。2023 年第 3 四半期にリリース。以下で設定:
+ `EndpointResolverV2`
+ `BaseEndpoint`
+ v1。SDK と同時にリリース。以下で設定:
+ `EndpointResolver`
新しいエンドポイント関連のサービス機能にアクセスできるようにするため、v1 エンドポイント解決のユーザーは v2 に移行することをお勧めします。
## V2: `EndpointResolverV2` \$1 `BaseEndpoint`
エンドポイント解決 v2 では、`EndpointResolverV2` がエンドポイント解決の決定的なメカニズムです。リゾルバーの `ResolveEndpoint` メソッドは、SDK で行うすべてのリクエストのワークフローの一部として呼び出されます。リゾルバーが返す `Endpoint` のホスト名はリクエスト時に**そのまま**使用されます (ただし、オペレーションシリアライザが HTTP パスに追記することはできます)。
エンドポイント解決 v2 では、クライアントレベルの追加設定 `BaseEndpoint` が含まれており、サービスインスタンスの「ベース」ホスト名を指定するために使用されます。ここで設定された値は決定的なものではなく、最終的にはクライアントの `EndpointResolverV2` にパラメータとして渡され、最終解決に使用されます (`EndpointResolverV2` パラメータの詳細については後述)。その後、リゾルバーの実装により、この値が検査 (場合によっては変更) されて、最終的なエンドポイントが決定されます。
例えば、`BaseEndpoint` を指定したクライアントで、特定のバケットに対して S3 `GetObject` リクエストを実行する場合、デフォルトのリゾルバーは、バケットが仮想ホスト対応であればホスト名にバケット名を挿入します (クライアント設定で仮想ホスティングを無効にしていない場合)。
実際には、`BaseEndpoint` はほとんどの場合、クライアントの接続先を開発インスタンスやプレビューインスタンスに指定するために使用されます。
### `EndpointResolverV2` 個のパラメータ
各サービスは、それぞれ専用の入力値セットを受け取り、それを `EndpointParameters` としてサービスパッケージ内で定義された解決関数に渡します。
すべてのサービスには、 AWS内での一般的なエンドポイント解決を容易にする次の基本パラメータが含まれています。
| 名前 | 型 | 説明 |
| --- | --- | --- |
| Region | string | クライアントの AWS リージョン |
| Endpoint | string | クライアント設定での BaseEndpoint の値 |
| UseFips | bool | クライアント設定で FIPS エンドポイントが有効かどうか |
| UseDualStack | bool | クライアント設定でデュアルスタックエンドポイントが有効かどうか |
サービスは、エンドポイント解決に必要な追加のパラメータを指定できます。例えば、S3 の `EndpointParameters` にはバケット名や、仮想ホストアドレッシングが有効かどうかなど、S3 固有の機能設定が含まれます。
独自の `EndpointResolverV2` を実装する場合でも、`EndpointParameters` のインスタンスを自分で作成する必要はありません。SDK がリクエストごとにそれらの値を取得し、カスタム実装に渡します。
### Amazon S3 に関する注意事項
Amazon S3 は、バケットの仮想ホスティングや S3 MRAP など、複雑なエンドポイントのカスタマイズによって多くの機能が設計されている高度なサービスです。
このため、S3 クライアントの `EndpointResolverV2` 実装を置き換えないことをお勧めします。エンドポイントの追加設定を行ったローカル開発スタックにリクエストを送信するなど、解決動作を拡張する場合は、デフォルトの実装をラップし、その中で必要に応じて元の実装に処理を委譲 (フォールバック) することをお勧めします (以下の例を参照)。
### 例
#### `BaseEndpoint` の場合
次のコードスニペットでは、S3 クライアントの接続先をローカルのサービスインスタンス (この例ではループバックデバイスのポート 8080) に指定する方法を示しています。
```
client := s3.NewFromConfig(cfg, func (o *svc.Options) {
o.BaseEndpoint = aws.String("https://localhost:8080/")
})
```
#### `EndpointResolverV2` の場合
次のコードスニペットでは、`EndpointResolverV2` を使用して S3 のエンドポイント解決にカスタム動作を挿入する方法を示しています。
```
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{
// ...
}
})
}
```
#### 両方を使用
次のサンプルプログラムでは、`BaseEndpoint` と `EndpointResolverV2` の相互動作を示しています。**これは、高度なユースケースです。**
```
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)
}
```
このプログラムを実行すると、次の出力が得られます。
```
The endpoint provided in config is https://endpoint.dev/
```
## V1: `EndpointResolver`
**警告**
エンドポイント解決 v1 は下位互換性のために保持されており、v2 の最新の動作とは分離されています。呼び出し元が `EndpointResolver` フィールドを設定した場合にのみ使用されます。
v1 を使用すると、v2 リリース以降に導入されたエンドポイント関連のサービス機能にアクセスできなくなる可能性が高くなります。アップグレード方法の手順については、「移行」を参照してください。
[EndpointResolver](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointResolver) を設定することで、サービスクライアントにカスタムエンドポイント解決ロジックを提供できます。カスタムエンドポイントリゾルバーを使用して、すべてのエンドポイント、または特定のリージョンエンドポイントに対して、サービスのエンドポイント解決ロジックをオーバーライドできます。カスタムエンドポイントリゾルバーが、あるエンドポイントの解決を行わない場合 (意図的にスキップする場合など)、サービスのエンドポイント解決ロジックにフォールバックさせることができます。[EndpointResolverWithOptionsFunc](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointResolverWithOptionsFunc) を使用すると、関数を簡単にラップして `EndpointResolverWithOptions` インターフェイスを実装できます。
`EndpointResolver` は、[WithEndpointResolverWithOptions](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithEndpointResolverWithOptions) でラップされたリゾルバーを [LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig) に渡すことで簡単に設定でき、認証情報のロード時にエンドポイントをオーバーライドしたり、結果として得られる `aws.Config` にカスタムエンドポイントリゾルバーを設定したりできます。
エンドポイントリゾルバーにはサービス名とリージョンが文字列として渡されるため、リゾルバーはその動作を動的に制御できます。各サービスクライアントパッケージには、どのサービスクライアントがエンドポイントリゾルバーを呼び出しているかを特定するための `ServiceID` 定数がエクスポートされています。
エンドポイントリゾルバーは、[EndpointNotFoundError](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointNotFoundError) のセンチネルエラー値を使用して、サービスクライアントのデフォルト解決ロジックにフォールバックさせます。これにより、フォールバックロジックを個別に扱うことなく、1 つ以上のエンドポイントを選択的にシームレスにオーバーライドできます。
エンドポイントリゾルバーが `EndpointNotFoundError` 以外のエラーを返した場合、エンドポイント解決は停止し、サービスオペレーションはアプリケーションにエラーを返します。
### 例
#### フォールバックあり
DynamoDB の 1 つのサービスエンドポイントをオーバーライドし、他のエンドポイントにはフォールバック動作を適用する方法を示すコードスニペットです。
```
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))
```
#### フォールバックなし
DynamoDB の 1 つのサービスエンドポイントをオーバーライドし、他のエンドポイントにはフォールバック動作を適用しない方法を示すコードスニペットです。
```
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))
```
### 変更不可のエンドポイント
**警告**
エンドポイントを変更不可として設定すると、一部のサービスクライアント機能が正しく動作しなくなり、未定義の動作が発生する可能性があります。エンドポイントを変更不可として定義する際は注意が必要です。
Amazon S3 などの一部のサービスクライアントでは、特定のサービスオペレーションに対してリゾルバーが返すエンドポイントを変更する場合があります。例えば Amazon S3 では、[仮想バケットアドレス指定](https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html)を自動的に処理するために、解決されたエンドポイントを変更します。[HostnameImmutable](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint.HostnameImmutable) を `true` に設定することで、SDK がカスタムエンドポイントを変更しないようにできます。例えば、次のようになります。
```
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))
```
## 移行
エンドポイント解決を v1 から v2 に移行する際は、次の一般的な原則が適用されます。
+ [HostnameImmutable](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint.HostnameImmutable) を `false` に設定した [Endpoint](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint) を返すことは、`BaseEndpoint` を v1 から元々返された URL に設定し、`EndpointResolverV2` をデフォルトのままにすることとほぼ同等です。
+ HostnameImmutable を `true` に設定した Endpoint を返すことは、v1 から元々返された URL を返す `EndpointResolverV2` を実装することとほぼ同等です。
+ 主な例外は、エンドポイントのプレフィックスがモデルとして定義されているオペレーションに該当する場合です。これに関する注意点は後述します。
これらのケースの例を次に示します。
**警告**
v1 の変更不可エンドポイントと v2 の解決ロジックは、動作上は同等ではありません。例えば、S3 Object Lambda などのカスタム機能に対する署名のオーバーライドは、v1 コードで返された変更不可エンドポイントには適用されますが、v2 では適用されません。
### ホストプレフィックスに関する注意事項
一部のオペレーションでは、解決されたエンドポイントの前にホストプレフィックスが付加されます。この動作は ResolveEndpointV2 の出力と連携して機能する必要があるため、ホストプレフィックスはその結果に引き続き適用されます。
ミドルウェアを適用することで、エンドポイントホストのプレフィックスを手動で無効にできます (例のセクションを参照)。
### 例
#### 変更可能なエンドポイント
次のコードサンプルは、変更可能なエンドポイントを返す基本的な v1 エンドポイントリゾルバーをどのように移行するかを示しています。
```
// 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/")
})
```
#### 変更不可のエンドポイント
```
// 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{}
})
```
#### ホストプレフィックスを無効にする
```
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)
}
}
```
# HTTP クライアントをカスタマイズする
AWS SDK for Go は、デフォルトの設定値を持つ標準の HTTP クライアントを使用します。一部の設定値は変更できますが、高スループットかつ低レイテンシーを要件とする環境で AWS SDK for Go を使用する顧客にとって、標準の HTTP クライアントとトランスポート設定では十分でありません。設定の推奨事項はワークロードによって異なるため、詳細については「[よくある質問](faq-gosdk.md)」を参照してください。このセクションでは、カスタム HTTP クライアントを設定し、そのクライアントを使用して AWS SDK for Go 呼び出しを作成する方法について説明します。
カスタム HTTP クライアントの作成に役立つように、このセクションでは [NewBuildableClient](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/transport/http#NewBuildableClient) を使用してカスタム設定を行い、そのクライアントを AWS SDK for Go サービスクライアントで使用する方法について説明します。
カスタマイズする内容を定義しましょう。
## 設定ロード時のオーバーライド
カスタム HTTP クライアントは、[LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig) を呼び出す際に、[WithHTTPClient](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithHTTP) でラップして `LoadDefaultConfig` に渡すことで提供できます。例えば、`customClient` をクライアントとして渡すには次のようにします。
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithHTTPClient(customClient))
```
## タイムアウト
`BuildableHTTPClient` には、リクエストのタイムアウト制限を設定できます。このタイムアウトには、接続時間、リダイレクトの処理時間、レスポンス本文全体の読み取り時間が含まれます。例えば、クライアントのタイムアウトを変更するには次のようにします。
```
import "github.com/aws/aws-sdk-go-v2/aws/transport/http"
// ...
httpClient := http.NewBuildableClient().WithTimeout(time.Second*5)
```
## Dialer
`BuildableHTTPClient` では、[Dialer](https://golang.org/pkg/net/#Dialer) オプションを変更してクライアントを作成するためのビルダー構造が提供されています。次の例では、クライアントの `Dialer` 設定を行う方法を示しています。
```
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
})
```
### 設定
#### Dialer.KeepAlive
この設定は、アクティブなネットワーク接続のキープアライブ期間を表します。
キープアライブを無効にするには、負の値に設定します。
プロトコルとオペレーティングシステムがサポートしている場合、キープアライブを有効にするには、**0** に設定します。
キープアライブをサポートしていないネットワークプロトコルやオペレーティングシステムでは、このフィールドは無視されます。TCP では、デフォルトでキープアライブが有効になっています。
[https://golang.org/pkg/net/\$1Dialer.KeepAlive](https://golang.org/pkg/net/#Dialer.KeepAlive) を参照してください。
`KeepAlive` は **time.Duration** 型で設定してください。
#### Dialer.Timeout
この設定は、ダイヤルが接続を確立するまでの最大待機時間を表します。
デフォルトは 30 秒です。
[https://golang.org/pkg/net/\$1Dialer.Timeout](https://golang.org/pkg/net/#Dialer.Timeout) を参照してください。
`Timeout` は **time.Duration** 型で設定してください。
## トランスポート
`BuildableHTTPClient` では、[Transport](https://golang.org/pkg/net/http#Transport) オプションを変更してクライアントを作成するためのビルダー構造が提供されています。
### プロキシの設定
インターネットに直接接続できない場合は、Go がサポートする環境変数 (`HTTP_PROXY`/`HTTPS_PROXY`) を使用するか、カスタム HTTP クライアントを作成してプロキシを設定できます。次の例では、クライアントがプロキシエンドポイントとして `PROXY_URL` を使用するように設定しています。
```
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)
})
```
### その他の設定
次に示しているのは、HTTP クライアントのチューニングに使用できるその他の `Transport` 設定です。ここで説明されていない追加の設定については、[Transport](https://golang.org/pkg/net/http/#Transport) 型に関するドキュメントを参照してください。これらの設定は次の例に示すように適用できます。
```
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
リクエストに [Expect: 100-continue] ヘッダーが含まれている場合、この設定はリクエストヘッダーの送信完了後にサーバーから最初のレスポンスヘッダーを受信するまでの最大待機時間を表します。この時間にはリクエストヘッダーの送信時間は含まれません。このタイムアウトが経過すると、HTTP クライアントはペイロードの送信を開始します。
デフォルトは 1 秒です。
**0** に設定するとタイムアウトは無効になり、待機せずにペイロードが送信されます。この設定のユースケースの 1 つは、Amazon S3 を使用する関数のように (後述)、プロキシやサードパーティのサービスでセッション処理に関する問題が発生する場合です。
[https://golang.org/pkg/net/http/\$1Transport.ExpectContinueTimeout](https://golang.org/pkg/net/http/#Transport.ExpectContinueTimeout) を参照してください。
`ExpectContinue` は **time.Duration** 型で設定してください。
#### Transport.IdleConnTimeout
この設定は、HTTP リクエスト間でアイドル状態のネットワーク接続を維持する最大時間を表します。
制限なしにするには **0** に設定します。
[https://golang.org/pkg/net/http/\$1Transport.IdleConnTimeout](https://golang.org/pkg/net/http/#Transport.IdleConnTimeout) を参照してください。
`IdleConnTimeout` は **time.Duration** 型で設定してください。
#### Transport.MaxIdleConns
この設定は、すべてのホストにわたって保持されるアイドル (キープアライブ) 接続の最大数を表します。この値を増やすユースケースの 1 つは、同じクライアントから短期間に多数の接続が行われる場合です。
**0** に設定すると無制限になります。
[https://golang.org/pkg/net/http/\$1Transport.MaxIdleConns](https://golang.org/pkg/net/http/#Transport.MaxIdleConns) を参照してください。
`MaxIdleConns` は **int** 型で設定してください。
#### Transport.MaxIdleConnsPerHost
この設定は、ホストごとに保持するアイドル (キープアライブ) 接続の最大数を表します。この値を増やすユースケースの 1 つは、同じクライアントから短期間に多数の接続が行われる場合です。
デフォルトでは、ホストごとに 2 つのアイドル接続が保持されます。
**0** に設定すると、DefaultMaxIdleConnsPerHost (2) が使用されます。
[https://golang.org/pkg/net/http/\$1Transport.MaxIdleConnsPerHost](https://golang.org/pkg/net/http/#Transport.MaxIdleConnsPerHost) を参照してください。
`MaxIdleConnsPerHost` は **int** 型で設定してください。
#### Transport.ResponseHeaderTimeout
この設定は、クライアントがレスポンスヘッダーを読み取るまでに待機する最大時間を表します。
クライアントがこの時間内にレスポンスヘッダーを読み取れない場合、リクエストはタイムアウトエラーで失敗します。
長時間実行される Lambda 関数を使用する場合、この値の設定には注意が必要です。Lambda 関数が終了するかタイムアウトするまで、レスポンスヘッダーが返されないためです。ただし、\$1\$1InvokeAsync\$1\$1 API オペレーションではこのオプションを使用できます。
デフォルトではタイムアウトはなく、無期限に待機します。
[https://golang.org/pkg/net/http/\$1Transport.ResponseHeaderTimeout](https://golang.org/pkg/net/http/#Transport.ResponseHeaderTimeout) を参照してください。
`ResponseHeaderTimeout` は **time.Duration** 型で設定してください。
#### Transport.TLSHandshakeTimeout
この設定は、TLS ハンドシェイクが完了するまでの最大待機時間を表します。
デフォルトは 10 秒です。
0 に設定すると、タイムアウトは無効になります。
[https://golang.org/pkg/net/http/\$1Transport.TLSHandshakeTimeout](https://golang.org/pkg/net/http/#Transport.TLSHandshakeTimeout) を参照してください。
`TLSHandshakeTimeout` は **time.Duration** 型で設定してください。
# HTTP インターセプター
インターセプターを使用して、API リクエストおよびレスポンスの実行フローにフックを挿入できます。インターセプターは、SDK がユーザー定義のコードを呼び出して、リクエスト/レスポンスのライフサイクルに処理を挿入できるようにする、柔軟な仕組みです。これにより、進行中のリクエストの変更、リクエスト処理のデバッグ、例外の確認などを行うことができます。
## インターセプターとミドルウェアの比較
AWS SDK for Go v2 では、リクエスト処理をカスタマイズする手段として、インターセプターとミドルウェアの両方を提供しています。いずれも同様の目的に使用できますが、対象ユーザーやユースケースが異なります。
+ **インターセプター**は、HTTP 処理に特化したシンプルな API を使用してリクエスト/レスポンス処理をカスタマイズする SDK ユーザー向けに設計されています。インターセプターはリクエストライフサイクルの特定の段階にフックを挿入でき、HTTP リクエストおよびレスポンスを直接操作します。
+ **ミドルウェア**はより高度なシステムであり、トランスポートに依存しない設計となっており、主に SDK 内部で使用されます。ミドルウェアは強力な反面、SDK の内部構造に関する深い知識や、より複雑なインターフェイスの扱いが求められます。
一般的なユースケースにおいて、インターセプターがミドルウェアより優れている主な点は次のとおりです。
+ **HTTP に特化**: インターセプターは HTTP リクエストおよびレスポンスを直接扱うため、ミドルウェアに必要なトランスポート型の判定が不要です。
+ **インターフェイスがシンプル**: 各インターセプターフックは、特定の用途に特化したシンプルなインターフェイスを備えており、汎用的なミドルウェアとは異なる設計になっています。
+ **実行モデルが明確**: インターセプターは、リクエストのライフサイクル中の明確に定義されたポイントで実行され、ミドルウェアスタックの順序を理解する必要がありません。
**注記**
インターセプターは既存のミドルウェアシステムの上に構築されており、両者は同じアプリケーション内で共存できます。ミドルウェアは、トランスポートに依存しない動作や複雑なスタック操作が必要な高度なユースケースに引き続き使用できます。
## 使用可能なインターセプターフック
AWS SDK for Go v2 では、リクエストライフサイクルのさまざまなステージで使用できるインターセプターフックを提供しています。各フックは、実装できる特定のインターフェイスに対応しています。
+ `BeforeExecution` - オペレーション実行時に最初に呼び出されるフック
+ `BeforeSerialization` - 入力メッセージがトランスポートリクエストにシリアル化される前
+ `AfterSerialization` - 入力メッセージがトランスポートリクエストにシリアル化された後
+ `BeforeRetryLoop` - 再試行ループに入る前
+ `BeforeAttempt` - 再試行ループ内で最初に呼び出されるフック
+ `BeforeSigning` - トランスポートリクエストが署名される前
+ `AfterSigning` - トランスポートリクエストが署名された後
+ `BeforeTransmit` - トランスポートリクエストが送信される前
+ `AfterTransmit` - トランスポートレスポンスを受信した後
+ `BeforeDeserialization` - トランスポートレスポンスが逆シリアル化される前
+ `AfterDeserialization` - トランスポートレスポンスがアンマーシャルされた後
+ `AfterAttempt` - 再試行ループ内で最後に呼び出されるフック
+ `AfterExecution` - オペレーション実行中に最後に呼び出されるフック
1 つのインターセプターで複数のインターフェイスを実装して、リクエストライフサイクルの複数のステージにフックを挿入できます。
## インターセプターの登録
インターセプターは、サービスクライアントを作成するときや、特定のオペレーションの設定をオーバーライドするときに登録します。登録方法は、インターセプターをクライアントのすべてのオペレーションに適用するか、特定のオペレーションのみに適用するかによって異なります。
インターセプターは、追加および削除メソッドを備えた登録オブジェクトを通じて管理されます。次の例では、署名処理の前に送信リクエストに AWS X-Ray トレース ID ヘッダーを追加するシンプルなインターセプターを示しています。
```
type recursionDetection struct{}
func (recursionDetection) BeforeSigning(ctx context.Context, in *smithyhttp.InterceptorContext) error {
if traceID := os.Getenv("_X_AMZN_TRACE_ID"); traceID != "" {
in.Request.Header.Set("X-Amzn-Trace-Id", traceID)
}
return nil
}
// use it on the client
svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
o.Interceptors.AddBeforeSigning(recursionDetection{})
})
```
インターセプターの登録オブジェクトはクライアントの Options に追加されて、オペレーションごとのインターセプター設定が可能になります。
```
// ... or use it per-operation
s3.ListBuckets(context.Background(), &s3.ListBucketsInput{
}, func(o *s3.Options) {
o.Interceptors.AddBeforeSigning(recursionDetection{})
})
```
## グローバルなインターセプター設定
また、各インターセプター型に対応する適切な `config.LoadDefaultConfig` オプションを指定して `With*` 関数を使用することで、インターセプターをグローバルに登録することもできます。これにより、その設定から作成されるすべての AWS サービスクライアントにインターセプターが適用されます。
```
type myExecutionInterceptor struct{}
func (*myExecutionInterceptor) AfterExecution(ctx context.Context, in *smithyhttp.InterceptorContext) error {
// Add your custom logic here
return nil
}
cfg, err := config.LoadDefaultConfig(context.Background(),
config.WithAfterExecution(&myExecutionInterceptor{}))
if err != nil {
panic(err)
}
// every service client created from the above config
// will include this interceptor
svc := s3.NewFromConfig(cfg)
```
# ログ記録
AWS SDK for Go には、リクエストの問題や失敗をデバッグ・診断するために、アプリケーションでデバッグ情報を有効にできるログ記録機能があります。[Logger](https://pkg.go.dev/github.com/aws/smithy-go/logging#Logger) インターフェイスと [ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode) は、クライアントがログに記録する方法と内容を決定するための主要な構成要素です。
## ロガー
[LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Config) を使用して [Config](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig) を作成すると、デフォルトで `Logger` はログメッセージを標準エラー出力 (stderr) に送信するように設定されます。[Logger](https://pkg.go.dev/github.com/aws/smithy-go/logging#Logger) インターフェイスを実装するカスタムロガーは、[config.WithLogger](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithLogger) でラップして `LoadDefaultConfig` に引数として渡すことができます。
例えば、クライアントが `applicationLogger` を使用するように設定するには、次のようにします。
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithLogger(applicationLogger))
```
このように作成された `aws.Config` を使用するクライアントは、`applicationLogger` にログメッセージを送信します。
### コンテキスト対応ロガー
ロガーの実装では、オプションの [ContextLogger](https://pkg.go.dev/github.com/aws/smithy-go/logging#ContextLogger) インターフェイスを実装できます。このインターフェイスを実装したロガーは、現在のコンテキストで `WithContext` メソッドを呼び出します。これにより、ログ記録の実装で、コンテキスト内の値に基づいて追加のログメタデータを書き込める新しい `Logger` を返すことができます。
## ClientLogMode
デフォルトでは、サービスクライアントはログメッセージを出力しません。クライアントがデバッグ目的でログメッセージを出力するように設定するには、`Config` の [ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode) メンバーを使用します。`ClientLogMode` を設定することにより、デバッグ目的で次のログ記録を有効にできます。
+ Signature Version 4 (SigV4) 署名処理
+ リクエストの再試行
+ HTTP リクエスト
+ HTTP レスポンス
例えば、HTTP リクエストおよび再試行処理のログ記録を有効にするには、次のようにします。
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithClientLogMode(aws.LogRetries | aws.LogRequest))
```
使用可能なさまざまなクライアントログモードについては、「[ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode)」を参照してください。
# トレースとメトリクス
AWS SDK for Go は、SDK オペレーションのトレーススパンとクライアント側のメトリクスを記録するように計測されます。デフォルトでは、クライアントはトレースとメトリクスの両方に no-op 実装を使用します。つまり、プロバイダーを設定しない限り、データは収集されません。
サービスクライアントには、オブザーバビリティのための 2 つの設定オプションがあります。
+ [TracerProvider](https://pkg.go.dev/github.com/aws/smithy-go/tracing#TracerProvider) – トレーサーを作成し、クライアントトレーススパンを記録するためのエントリポイント。
+ [MeterProvider](https://pkg.go.dev/github.com/aws/smithy-go/metrics#MeterProvider) – メーターを作成し、クライアント側のメトリクスを記録するためのエントリポイント。
OpenTelemetry (OTel) 仕様に着想を得ながら、これらの APIsは で個別に定義されています`smithy-go`。SDK には、具体的な OTel SDK 実装を SDK のプロバイダーインターフェイスに接続するためのアダプターモジュールが用意されています。
## トレース
[Smithyoteltracing](https://pkg.go.dev/github.com/aws/smithy-go/tracing/smithyoteltracing) アダプターモジュールを使用して、OTel `trace.TracerProvider`をサービスクライアントに接続します。
次の例は、Amazon S3 クライアントのトレースを設定する方法を示しています。
```
import (
"github.com/aws/aws-sdk-go-v2/service/s3"
"github.com/aws/smithy-go/tracing/smithyoteltracing"
"go.opentelemetry.io/otel/trace"
)
// provider is an OTel trace.TracerProvider that you have configured.
var provider trace.TracerProvider
svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
o.TracerProvider = smithyoteltracing.Adapt(provider)
})
```
SDK オペレーションは、リクエストのシリアル化、署名、再試行ループなど、オペレーションライフサイクルの高レベルのコンポーネントをカバーするスパン階層で計測されます。
## メトリクス
[Smithyotelmetrics](https://pkg.go.dev/github.com/aws/smithy-go/metrics/smithyotelmetrics) アダプターモジュールを使用して、OTel `metric.MeterProvider`をサービスクライアントに接続します。
次の例は、Amazon S3 クライアントのメトリクスを設定する方法を示しています。
```
import (
"github.com/aws/aws-sdk-go-v2/service/s3"
"github.com/aws/smithy-go/metrics/smithyotelmetrics"
"go.opentelemetry.io/otel/metric"
)
// provider is an OTel metric.MeterProvider that you have configured.
var provider metric.MeterProvider
svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
o.MeterProvider = smithyotelmetrics.Adapt(provider)
})
```
### サポートされるメトリクス
SDK クライアントは、次のメトリクスを収集します。
| メトリクス名 | Unit | 型 | 説明 |
| --- | --- | --- | --- |
| client.call.duration | s | ヒストグラム | 再試行、リクエストとレスポンス本文の送受信時間を含む全体的な通話時間。 |
| client.call.attempts | \$1attempt\$1 | MonotonicCounter | 個々のオペレーションの試行回数。 |
| client.call.errors | \$1error\$1 | MonotonicCounter | オペレーションのエラーの数。 |
| client.call.attempt\$1duration | s | ヒストグラム | サービスに接続してリクエストを送信し、HTTP ステータスコードとヘッダーを返す時間 (キューに入れられた送信待機時間を含む）。 |
| client.call.resolve\$1endpoint\$1duration | s | ヒストグラム | リクエストのエンドポイント (DNS ではなくエンドポイントリゾルバー) を解決する時間。 |
| client.call.deserialization\$1duration | s | ヒストグラム | メッセージ本文を逆シリアル化する時間。 |
| client.call.auth.signing\$1duration | s | ヒストグラム | リクエストに署名する時間。 |
| client.call.auth.resolve\$1identity\$1duration | s | ヒストグラム | ID プロバイダーから ID (AWS 認証情報、ベアラートークンなど) を取得する時間。 |
該当する場合は、各メトリクスに次の属性 (ディメンション) が含まれます。
+ `rpc.service` – サービス名。
+ `rpc.method` – オペレーション名。
+ `exception.type` – エラータイプ ( に付属`client.call.errors`)。
+ `auth.scheme_id` – 認証スキーム (認証関連のメトリクスに付属）。
### HTTP クライアントメトリクス
SDK の HTTP クライアントは、基盤となる HTTP 接続ライフサイクルに関連する以下の追加のメトリクスを収集します。
| メトリクス名 | Unit | 型 | 説明 |
| --- | --- | --- | --- |
| client.http.connections.acquire\$1duration | s | ヒストグラム | 接続の取得リクエストにかかる時間。 |
| client.http.connections.dns\$1lookup\$1duration | s | ヒストグラム | DNS ルックアップの実行にかかる時間。 |
| client.http.connections.tls\$1handshake\$1duration | s | ヒストグラム | TLS ハンドシェイクの実行にかかる時間。 |
| client.http.connections.usage | \$1接続\$1 | UpDownCounter | プール内の接続の現在の状態。idle または の値を持つstateディメンションを使用しますacquired。 |
| client.http.do\$1request\$1duration | s | ヒストグラム | HTTP リクエストの実行にかかった合計時間。 |
| client.http.time\$1to\$1first\$1byte | s | ヒストグラム | リクエストの送信から最初のレスポンスバイトの受信までの時間。 |
# 再試行とタイムアウト
AWS SDK for Go を使用すると、HTTP サービスへのリクエストの再試行動作を設定できます。デフォルトでは、サービスクライアントは [retry.Standard](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) をデフォルトのリトライヤとして使用します。デフォルトの設定や動作がアプリケーションの要件を満たさない場合は、リトライヤの設定を調整するか、独自のリトライヤ実装を提供できます。
AWS SDK for Go は、実装する再試行実装に必要なメソッドのセットを定義する [aws.Retryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Retryer) インターフェイスを提供します。SDK には、再試行用に [retry.Standard](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) と [aws.NoOpRetryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NoOpRetryer) の 2 つの実装が用意されています。
## 標準リトライヤ
[retry.Standard](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) リトライヤは、SDK クライアントが使用するデフォルトの `aws.Retryer` 実装です。標準リトライヤは、レート制限付きの再試行方式を採用しており、最大試行回数を設定できるほか、リクエストのバックオフポリシーも調整できます。
次の表では、このリトライヤのデフォルト値を示しています。
| プロパティ | デフォルト |
| --- | --- |
| 最大試行回数 | 3 |
| 最大バックオフ遅延 | 20 秒 |
リクエストの呼び出し時に再試行可能なエラーが発生すると、標準リトライヤは指定された設定に基づいてリクエストを遅延させた後、再試行します。再試行により、リクエストの全体的なレイテンシーが長くなります。そのため、デフォルトの設定がアプリケーションの要件に合わない場合は、リトライヤを設定する必要があります。
標準リトライヤ実装で再試行可能と判断されるエラーの詳細については、[retry](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry) パッケージのドキュメントを参照してください。
## NopRetryer
[aws.NopRetryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NopRetryer) は、すべての再試行を無効にするために用意されている `aws.Retryer` 実装です。このリトライヤを使用すると、サービスクライアントのオペレーションは 1 回だけ試行され、エラーが発生した場合は呼び出し元のアプリケーションにそのまま返されます。
## 動作のカスタマイズ
SDK は `aws.Retryer` 実装をラップするためのヘルパーユーティリティ群を提供しており、必要な再試行動作を適用したリトライヤを返します。デフォルトのリトライヤは、アプリケーションの要件に応じて、すべてのクライアント、個別のクライアント、またはオペレーション単位でオーバーライドできます。これを行う方法を示すその他の例については、[retry](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry) パッケージのドキュメントの例を参照してください。
**警告**
`config.WithRetryer` を使用してグローバルな `aws.Retryer` 実装を指定する場合は、呼び出しごとに新しい `aws.Retryer` インスタンスを返すようにする必要があります。これにより、すべてのサービスクライアント間でグローバルな再試行トークンバケットが作成されなくなります。
### 最大試行回数の制限
[retry.AddWithMaxAttempts](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithMaxAttempts) を使用して `aws.Retryer` 実装をラップし、最大試行回数を必要な値に設定します。
**警告**
`retry.AddWithMaxAttempts` に 0 を指定すると、SDK はリクエストが成功するか、再試行不能なエラーが返されるまで、すべての再試行可能なエラーに対してリクエストを再試行できます。**SDK に無限の再試行を許可すると、ワークロードが暴走し、請求サイクルが増大する可能性があります。**
```
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"
// ...
// MaxAttempts will be infinite (will retry indefinitely)
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRetryer(func() aws.Retryer {
return retry.AddWithMaxAttempts(retry.NewStandard(), 0)
}))
if err != nil {
return err
}
client := s3.NewFromConfig(cfg)
```
関数型オプションを使用して MaxAttempts を直接設定してリトライヤをインスタンス化する場合、動作はわずかに異なります。具体的には、0 以下の値を設定すると、無限の再試行ではなく、デフォルトの最大 3 回の再試行が使用されます。
```
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"
// ...
// MaxAttempts will default to 3
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRetryer(func() aws.Retryer {
return retry.NewStandard(func(o *retry.StandardOptions) {
o.MaxAttempts = 0
})
}))
if err != nil {
return err
}
client := s3.NewFromConfig(cfg)
```
### 最大バックオフ遅延の制限
[retry.AddWithMaxBackoffDelay](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithMaxBackoffDelay) を使用して `aws.Retryer` 実装をラップし、失敗したリクエストの再試行間に発生する最大バックオフ遅延を制限できます。
例えば、次のコードを使用して、標準クライアントのリトライヤに 5 秒の最大遅延を設定できます。
```
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)
```
### 追加の API エラーコードを再試行する
[retry.AddWithErrorCodes](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithErrorCodes) を使用すると、`aws.Retryer` 実装をラップして、再試行可能と見なす追加の API エラーコードを指定できます。
例えば、次のコードを使用して、標準クライアントリトライヤをラップし、Amazon S3 の `NoSuchBucketException` 例外を再試行可能として含めることができます。
```
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)
```
### クライアント側のレート制限
では、最新の SDK の動作に合わせて、標準の再試行ポリシーに新しいクライアント側のレート制限メカニズム AWS SDK for Go が導入されています。 SDKs この動作は、リトライヤの [options](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#StandardOptions) にある [RateLimiter](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#RateLimiter) フィールドによって制御されます。
RateLimiter は、容量を設定されたトークンバケットとして動作し、オペレーションの試行失敗によりトークンを消費します。トークンが不足している状態で再試行を試みると、そのオペレーションは [QuotaExceededError](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#QuotaExceededError) により失敗します。
デフォルトの実装では、次のようにパラメータ化されています (各設定値の変更方法を示す例も示しています)。
+ 容量は 500 ([NewTokenRateLimit](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#NewTokenRateLimit) を使用して StandardOptions の RateLimiter の値を設定)
+ タイムアウトによる再試行は 10 トークンを消費 (StandardOptions の RetryTimeoutCost を設定)
+ その他のエラーによる再試行は 5 トークンを消費 (StandardOptions の RetryCost を設定)
+ 最初の試行で成功したオペレーションは 1 トークンを追加 (StandardOptions の NoRetryIncrement を設定)
+ 2 回目以降の試行で成功したオペレーションはトークンを追加しない
デフォルトの動作がアプリケーションの要件に合わない場合は、[ratelimit.None](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#pkg-variables) を使用してレート制限を無効にできます。
#### 例: レート制限を変更
```
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
})
}))
```
#### 例: 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
})
}))
```
## タイムアウト
サービスクライアントのオペレーションを呼び出す際には、[context](https://golang.org/pkg/context/) パッケージを使用してタイムアウトやデッドラインを設定します。[context.WithDeadline](https://golang.org/pkg/context/#WithDeadline) を使用してアプリケーションのコンテキストをラップし、呼び出したオペレーションを完了する必要がある特定の時間に期限を設定します。一定時間 `time.Duration` 後にタイムアウトを設定するには、[context.WithTimeout](https://golang.org/pkg/context/#WithTimeout) を使用します。SDK は、渡された `context.Context` をサービス API の呼び出し時に HTTP トランスポートクライアントに渡します。SDK に渡したコンテキストが既にキャンセルされている、または呼び出し中にキャンセルされた場合、SDK はそれ以上リクエストを再試行せず、呼び出し元アプリケーションに制御を戻します。そのため、SDK に渡すコンテキストがキャンセルされた場合に備えて、アプリケーション側で適切なキャンセル処理を実装する必要があります。
### タイムアウトの設定
次の例では、サービスクライアントのオペレーションにタイムアウトを設定する方法を示しています。
```
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
}
```