翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS SDK for Rust でのサービスクライアントの設定
プログラムを使用して AWS のサービスにアクセスするために、AWS SDK for Rust は各 AWS のサービスにクライアント構造体を使用します。例えば、アプリケーションが Amazon EC2 にアクセスする必要がある場合、アプリケーションはそのサービスとインターフェイスをとる Amazon EC2 クライアント構造体を作成します。次に、サービスクライアントを使用して、その AWS のサービス に対してリクエストを実行します。
AWS のサービス にリクエストを行うには、まずサービスクライアントを作成する必要があります。コードが使用する各 AWS のサービス には、専用のクレートと、やり取りを行うための専用の型があります。クライアントは、サービスが提供する各 API オペレーションに対応するメソッドをそれぞれ公開しています。
SDK の動作を設定する方法は多岐にわたりますが、最終的にはすべてサービスクライアントの動作に関係しています。どのような設定も、それに基づいて作成されたサービスクライアントが使用されるまでは効果がありません。
AWS のサービスを使用して開発する際には、AWS によりコードがどのように認証するかを確立する必要があります。使用する AWS リージョン を設定する必要があります。
[AWS SDK とツールのリファレンスガイド](https://docs.aws.amazon.com/sdkref/latest/guide/)には、AWS SDK の多くに共通する設定、機能、その他の基本概念も含まれています。
**Topics**
+ [クライアントの外部設定](config-external.md)
+ [コードでのクライアント設定](config-code.md)
+ [AWS リージョン](region.md)
+ [認証情報プロバイダー](credproviders.md)
+ [動作バージョン](behavior-versions.md)
+ [再試行](retries.md)
+ [タイムアウト](timeouts.md)
+ [オブザーバビリティ](observability.md)
+ [クライアントエンドポイント](endpoints.md)
+ [オペレーション設定をオーバーライドする](peroperation.md)
+ [HTTP](http.md)
+ [インターセプター](interceptors.md)
# 外部で AWS SDK for Rust サービスクライアントを設定する
多くの設定はコードの外部で管理できます。設定が外部で管理されている場合、その設定はすべてのアプリケーションに適用されます。ほとんどの設定は、環境変数または個別の共有 AWS `config` ファイルを使用して行うことができます。共有 `config` ファイルでは「プロファイル」と呼ばれる異なる設定セットを保持して、環境やテストごとに異なる設定を提供できます。
環境変数と共有 `config` ファイルの設定は標準化されており、AWS SDK やツール全体で共有されて、異なる言語やアプリケーション間でも一貫した機能をサポートします。
SDK 設定の詳細については、「*AWS SDK とツールのリファレンスガイド*」を参照してください。SDK が環境変数または設定ファイルから解決できるすべての設定を確認するには、「*AWS SDK とツールのリファレンスガイド*」の「[設定リファレンス](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html)」を参照してください。
AWS のサービス にリクエストを行うには、まずそのサービスのクライアントをインスタンス化します。タイムアウトや HTTP クライアント、再試行設定など、サービスクライアントの共通設定を行うことができます。
各サービスクライアントには AWS リージョン と認証情報プロバイダーが必要です。SDK はこれらの値を使用して、リソースの正しいリージョンにリクエストを送信し、正しい認証情報でリクエストに署名します。これらの値はコード内でプログラムによって指定することも、環境から自動的にロードされるようにすることもできます。
SDK には、設定の値を見つけるために順番に確認する一連の場所 (またはソース) があります。
1. コードまたはサービスクライアント自体に設定されている明示的な設定は、他の設定よりも優先されます。
1. 環境変数
+ 環境変数の設定の詳細については、「*AWS SDK とツールのリファレンスガイド*」の「[環境変数](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html)」を参照してください。
+ シェルの環境変数は、システム全体、ユーザー全体、特定のターミナルセッションなど、さまざまなスコープレベルで設定できることに注意してください。
1. 共有 `config` および `credentials` ファイル
+ これらのファイルの設定については、「*AWS SDK とツールのリファレンスガイド*」の「[共有 `config` ファイルと `credentials` ファイル](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)」を参照してください。
1. SDK ソースコード自体が提供するデフォルト値が最後に使用されます。
+ Region などの一部のプロパティにはデフォルトがありません。これらのプロパティは、コード、環境設定、または共有 `config` ファイルのいずれかで明示的に指定する必要があります。SDK が必要な設定を解決できない場合、API リクエストは実行時に失敗する可能性があります。
# コードでの AWS SDK for Rust サービスクライアントの設定
設定がコード内で直接処理される場合、設定のスコープは、そのコードを使用するアプリケーションに限定されます。そのアプリケーション内には、すべてのサービスクライアントに対するグローバル設定、特定の AWS のサービス タイプのすべてのクライアントに対する設定、特定のサービスクライアントインスタンスに対する設定のオプションがあります。
にリクエストを行うには AWS のサービス、まずそのサービスのクライアントをインスタンス化します。タイムアウトや HTTP クライアント、再試行設定など、サービスクライアントの共通設定を行うことができます。
各サービスクライアントには、 AWS リージョン と認証情報プロバイダーが必要です。SDK はこれらの値を使用して、リソースの正しいリージョンにリクエストを送信し、正しい認証情報でリクエストに署名します。これらの値はコード内でプログラムによって指定することも、環境から自動的にロードされるようにすることもできます。
**注記**
サービスクライアントはコンストラクトにコストがかかることが多く、一般的に共有されることを想定しています。これを容易にするため、すべての `Client` 構造体は `Clone` を実装します。
## 環境からクライアントを設定する
環境ソース設定でクライアントを作成するには、`aws-config` クレートの静的メソッドを使用します。
```
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
```
この方法でクライアントを作成することは、Amazon Elastic Compute Cloud で実行する場合 AWS Lambdaや、サービスクライアントの設定が環境から直接利用できるその他のコンテキストで実行する場合に便利です。これにより、コードが実行中の環境から切り離され、コードを変更 AWS リージョン せずにアプリケーションを複数の にデプロイすることが容易になります。
特定のプロパティを明示的にオーバーライドできます。明示的な設定は、実行環境から解決される設定よりも優先されます。次の例では、環境から設定を読み込みますが、明示的に AWS リージョンをオーバーライドしています。
```
let config = aws_config::defaults(BehaviorVersion::latest())
.region("us-east-1")
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
```
**注記**
すべての設定値がクライアントの作成時に読み込まれるわけではありません。クライアントがリクエストを行う際に、一時的なアクセスキーや IAM Identity Center の設定などの認証情報関連の設定は、認証情報プロバイダーレイヤーによってアクセスされます。
前の例に示すコード `BehaviorVersion::latest()` は、デフォルトに使用する SDK のバージョンを示しています。`BehaviorVersion::latest()` は、ほとんどのケースで適しています。詳細については、「[での動作バージョンの使用 AWS SDK for Rust](behavior-versions.md)」を参照してください。
## サービス固有の設定にビルダーパターンを使用する
オプションの中には、特定のサービスクライアントタイプでのみ設定できるものがあります。ただし、ほとんどの場合、設定の大部分は環境から読み込み、その後に追加のオプションを特に指定して追加する場合が多いです。ビルダーパターンは、 AWS SDK for Rust クレート内の一般的なパターンです。まず `aws_config::defaults` を使用して一般的な設定を読み込み、次に `from` メソッドを使用して、その設定を作業中のサービスのビルダーに読み込みます。その後、そのサービスの一意の設定値を設定し、`build` を呼び出すことができます。最後に、この変更後の設定からクライアントが作成されます。
```
// Call a static method on aws-config that sources default config values.
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
// Use the Builder for S3 to create service-specific config from the default config.
let s3_config = aws_sdk_s3::config::Builder::from(&config)
.accelerate(true) // Set an S3-only configuration option
.build();
// Create the client.
let s3 = aws_sdk_s3::Client::from_conf(s3_config);
```
特定のタイプのサービスクライアントで使用できる追加メソッドを検出する方法の 1 つは、[https://docs.rs/aws-sdk-s3/latest/aws_sdk_s3/config/struct.Builder.html](https://docs.rs/aws-sdk-s3/latest/aws_sdk_s3/config/struct.Builder.html) などの API ドキュメントを使用することです。
## 高度な明示的なクライアント設定
環境から設定をロードする代わりに、特定の値でサービスクライアントを設定するには、次に示すように、クライアント `Config` ビルダーで指定できます。
```
let conf = aws_sdk_s3::Config::builder()
.region("us-east-1")
.endpoint_resolver(my_endpoint_resolver)
.build();
let s3 = aws_sdk_s3::Client::from_conf(conf);
```
`aws_sdk_s3::Config::builder()` を使用してサービス設定を作成した場合、*デフォルト設定は読み込まれません*。デフォルトは、`aws_config::defaults` に基づいて設定を作成する場合にのみ読み込まれます。
オプションの中には、特定のサービスクライアントタイプでのみ設定できるものがあります。前の例は、Amazon S3 クライアントで `endpoint_resolver` 関数を使用する例を示しています。
# AWS リージョン の の設定 AWS SDK for Rust
を使用して、特定の地域 AWS のサービス で動作する にアクセスできます AWS リージョン。これは、冗長性を確保するためや、ユーザーがアクセスする場所の近くでのデータとアプリケーションの実行を維持するために有効です。リージョンの使用の詳細については、「*AWS SDK とツールのリファレンスガイド*」の「[AWS リージョン](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html)」を参照してください。
**重要**
ほとんどのリソースは特定の に存在し AWS リージョン 、SDK を使用するときにリソースに正しいリージョンを指定する必要があります。
AWS リクエストに使用する SDK for Rust AWS リージョン のデフォルトを設定する必要があります。このデフォルトは、リージョンが指定されていないすべての SDK サービスメソッドの呼び出しに使用されます。
共有 AWS `config`ファイルまたは環境変数を使用してデフォルトのリージョンを設定する方法の例については、 [AWS リージョン](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html) *AWS SDKs*「」を参照してください。
## AWS リージョン プロバイダーチェーン
サービスクライアントの設定を実行環境から読み込む場合は、次の検索プロセスが使用されます。SDK が最初に設定されている値が検出されると、その値がクライアントの設定に使用されます。サービスクライアントの作成の詳細については、「[環境からクライアントを設定する](config-code.md#configure-a-client-from-the-environment)」を参照してください。
1. プログラムによって設定された明示的なリージョン。
1. `AWS_REGION` 環境変数が確認されます。
+ AWS Lambda サービスを使用している場合、この環境変数は AWS Lambda コンテナによって自動的に設定されます。
1. 共有 AWS `config`ファイルの `region`プロパティがチェックされます。
+ `AWS_CONFIG_FILE` 環境変数を使用すると、共有 `config` ファイルの場所を変更できます。このファイルの保存場所の詳細については、「*AWS SDK とツールのリファレンスガイド*」の「[共有 `config` と `credentials` ファイルの場所](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html)」を参照してください。
+ `AWS_PROFILE` 環境変数を使用すると、デフォルトの代わりに名前付きプロファイルを選択できます。名前付きプロファイルの設定の詳細については、「*AWS SDK とツールのリファレンスガイド*」の「[共有 `config` と `credentials` ファイル](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)」を参照してください。
1. SDK は、Amazon EC2 インスタンスメタデータサービスを使用して、現在実行中の Amazon EC2 インスタンスのリージョンを決定しようとします。
+ は IMDSv2 AWS SDK for Rust のみをサポートします。
`RegionProviderChain` は、サービスクライアントで使用する基本設定を作成する際に、追加のコードなしで自動的に使用されます。
```
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
```
## コード AWS リージョン での の設定
### コードでリージョンを明示的に設定する
リージョンを明示的に設定する場合は、設定で `Region::new()` を直接使用します。
リージョンプロバイダーチェーンは、環境、共有 `config` ファイル、Amazon EC2 インスタンスメタデータサービスをチェックしないため使用しません。
```
use aws_config::{defaults, BehaviorVersion};
use aws_sdk_s3::config::Region;
#[tokio::main]
async fn main() {
let config = defaults(BehaviorVersion::latest())
.region(Region::new("us-west-2"))
.load()
.await;
println!("Using Region: {}", config.region().unwrap());
}
```
に有効な文字列を入力していることを確認してください AWS リージョン。指定された値は検証されません。
### `RegionProviderChain` のカスタマイズ
リージョンを条件付きで挿入したり、上書きしたり、解決チェーンをカスタマイズしたりする場合は、[AWS リージョン プロバイダーチェーン](#region-provider-chain) を使用します。
```
use aws_config::{defaults, BehaviorVersion};
use aws_config::meta::region::RegionProviderChain;
use aws_sdk_s3::config::Region;
use std::env;
#[tokio::main]
async fn main() {
let region_provider = RegionProviderChain::first_try(env::var("CUSTOM_REGION").ok().map(Region::new))
.or_default_provider()
.or_else(Region::new("us-east-2"));
let config = aws_config::defaults(BehaviorVersion::latest())
.region(region_provider)
.load()
.await;
println!("Using Region: {}", config.region().unwrap());
}
```
前の設定では、以下のようになります。
1. まず、`CUSTOM_REGION` 環境変数に文字列が設定されているかどうかを確認します。
1. 利用できない場合は、デフォルトのリージョンプロバイダーチェーンにフォールバックします。
1. 失敗した場合は、最終的なフォールバックとして「us-east-2」を使用します。
# AWS SDK for Rust 認証情報プロバイダーの使用
へのすべてのリクエストは、 によって発行された認証情報を使用して暗号化して署名 AWS する必要があります AWS。実行時、SDK は複数の場所を確認して認証情報の設定値を取得します。
取得した設定に[AWS IAM アイデンティティセンター シングルサインオンアクセス設定](credentials.md)が含まれている場合、SDK は IAM Identity Center と連携して、 AWS のサービスへのリクエストに使用する一時的な認証情報を取得します。
取得した設定に[一時的な認証情報](https://docs.aws.amazon.com/sdkref/latest/guide/access-temp-idc.html)が含まれている場合、SDK はそれらを使用して AWS のサービス 呼び出しを行います。一次的な認証情報は、アクセスキーおよびセッショントークンで構成されています。
を使用した認証は AWS 、コードベース外で処理できます。多くの認証方法は、認証情報プロバイダーチェーンを使用して、SDK によって自動的に検出、使用、更新されます。
プロジェクトの AWS 認証を開始するためのガイド付きオプションについては、 SDK およびツールリファレンスガイドの[「認証とアクセス](https://docs.aws.amazon.com/sdkref/latest/guide/access.html)」を参照してください。 *AWS SDKs *
## 認証情報プロバイダーチェーン
クライアントのコンストラクト時に認証情報プロバイダーを明示的に指定しない場合、SDK for Rust は認証情報プロバイダーチェーンを使用して、認証情報を提供できる一連の場所を確認します。SDK がこれらの場所のいずれかで認証情報を見つけると、検索は停止します。クライアントの構築の詳細については、「[コードでの AWS SDK for Rust サービスクライアントの設定](config-code.md)」を参照してください。
次の例では、コードに認証情報プロバイダーを指定していません。SDK は、認証情報プロバイダーチェーンを使用して、ホスティング環境で設定された認証を検出し、その認証を AWS のサービスへの呼び出しに使用します。
```
let config = aws_config::defaults(BehaviorVersion::latest()).load().await;
let s3 = aws_sdk_s3::Client::new(&config);
```
### 認証情報の取得順序
認証情報プロバイダーチェーンは、以下の事前定義されたシーケンスで認証情報を検索します。
1. **アクセスキー環境変数**
SDK は `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`、および `AWS_SESSION_TOKEN` 環境変数から認証情報をロードしようとします。
1. **共有 AWS `config` ファイルと `credentials` ファイル**
SDK は、共有 AWS `config` および `credentials` ファイル内の`[default]`プロファイルから認証情報をロードしようとします。`AWS_PROFILE` 環境変数を使用することで、SDK がロードする名前付きプロファイルを選択できます。これにより、`[default]` の代わりに任意のプロファイルを使用できます。`config` および `credentials`ファイルは、さまざまな AWS SDKsとツールによって共有されます。これらのファイルの詳細については、「*AWS SDK とツールのリファレンスガイド*」の「[共有 `config` および `credentials` ファイル](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)」を参照してください。プロファイルで指定できる標準化されたプロバイダーの詳細については、[AWS SDKs](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html)」を参照してください。
1. **AWS STS ウェブ ID**
アクセスを必要とするモバイルアプリケーションまたはクライアントベースのウェブアプリケーションを作成すると AWS、 AWS Security Token Service (AWS STS) は、パブリック ID プロバイダー (IdP) を介して認証されたフェデレーティッドユーザーの一時的なセキュリティ認証情報のセットを返します。
+ プロファイルでこれを指定すると、SDK またはツールは API メソッドを使用して AWS STS `AssumeRoleWithWebIdentity`一時的な認証情報の取得を試みます。この方法の詳細については、「*AWS Security Token Service API リファレンス*」の「[AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)」を参照してください。
+ このプロバイダーの設定に関するガイダンスについては、「*AWS SDK とツールのリファレンスガイド*」の「[ウェブアイデンティティまたは OpenID Connect とのフェデレーション](https://docs.aws.amazon.com/sdkref/latest/guide/access-assume-role.html#webidentity)」を参照してください。
+ このプロバイダーの SDK 設定プロパティの詳細については、「*AWS SDK とツールのリファレンスガイド*」の「[ロール認証情報プロバイダーを引き受ける](https://docs.aws.amazon.com/sdkref/latest/guide/feature-assume-role-credentials.html)」を参照してください。
1. **Amazon ECS および Amazon EKS コンテナ認証情報**
Amazon Elastic Container Service のタスクと Kubernetes サービスアカウントには IAM ロールを関連付けることができます。IAM ロールで付与されたアクセス許可は、タスクで実行されているコンテナまたはポッドのコンテナによって引き受けられます。このロールにより、(コンテナ上の) SDK for Rust アプリケーションコードが他の AWS のサービスを使用できるようになります。
SDK は、Amazon ECS と Amazon EKS によって自動的に設定される `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` または `AWS_CONTAINER_CREDENTIALS_FULL_URI` の環境変数から認証情報を取得しようとします。
+ Amazon ECS 用にこのロールを設定する方法の詳細については、「*Amazon Elastic Container Service デベロッパーガイド*」の「[Amazon ECS タスクの IAM ロール](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)」を参照してください。
+ Amazon EKS の設定情報については、「**Amazon EKS ユーザーガイド**」の「[Amazon EKS Pod Identity Agent の設定](https://docs.aws.amazon.com/eks/latest/userguide/pod-id-agent-setup.html)」を参照してください。
+ このプロバイダーの SDK 設定プロパティの詳細については、「*AWS SDK とツールのリファレンスガイド*」の「[コンテナ認証情報プロバイダー](https://docs.aws.amazon.com/sdkref/latest/guide/feature-container-credentials.html)」を参照してください。
1. **Amazon EC2 インスタンスメタデータサービス**
IAM ロールを作成し、インスタンスにアタッチします。インスタンス上の SDK for Rust アプリケーションは、ロールによって提供された認証情報をインスタンスメタデータから取得しようとします。
+ SDK for Rust は [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html) のみをサポートします。
+ このロールの設定とメタデータの使用の詳細については、「*Amazon EC2 ユーザーガイド*」の「[Amazon EC2 の IAM ロール](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)」および「[インスタンスメタデータの操作](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)」を参照してください。
+ このプロバイダーの SDK 設定プロパティの詳細については、「*AWS SDK とツールのリファレンスガイド*」の「[IMDS 認証情報プロバイダー](https://docs.aws.amazon.com/sdkref/latest/guide/feature-imds-credentials.html)」を参照してください。
1. この時点で認証情報が引き続き解決されていない場合は、panics オペレーションでエラーが発生します。
AWS 認証情報プロバイダーの設定の詳細については、「 SDK およびツール*リファレンスガイド」の「設定*リファレンス」の[「標準化された認証情報プロバイダー](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html)」を参照してください。 *AWS SDKs *
## 明示的な認証情報プロバイダー
SDK による認証方法の検出のために認証情報プロバイダーチェーンに依存するのではなく、特定の認証情報プロバイダーを指定できます。`aws_config::defaults` を使用して一般的な設定をロードする場合、以下に示すように、カスタム認証情報プロバイダーを指定できます。
```
let config = aws_config::defaults(BehaviorVersion::latest())
.credentials_provider(MyCredentialsProvider::new())
.load()
.await;
```
[https://docs.rs/aws-credential-types/latest/aws_credential_types/provider/trait.ProvideCredentials.html](https://docs.rs/aws-credential-types/latest/aws_credential_types/provider/trait.ProvideCredentials.html) トレイトを実装することにより、独自の認証情報プロバイダーを実装できます。
## アイデンティティのキャッシュ
SDK は、認証情報や SSO トークンなど他のアイデンティティタイプをキャッシュします。デフォルトでは、SDK は遅延キャッシュ方式を使用します。この方式では、認証情報は最初のリクエスト時にロードされ、キャッシュされて、有効期限が近づいたら、次のリクエスト時に自動的に更新が試みられます。同じ `SdkConfig` から作成されたクライアントは [https://docs.rs/aws-smithy-runtime/latest/aws_smithy_runtime/client/identity/struct.IdentityCache.html](https://docs.rs/aws-smithy-runtime/latest/aws_smithy_runtime/client/identity/struct.IdentityCache.html) を共有します。
# での動作バージョンの使用 AWS SDK for Rust
AWS SDK for Rust 開発者は、言語とその主要なライブラリが提供する堅牢で予測可能な動作を期待し、それに依存します。SDK for Rust を使用するデベロッパーが期待する動作が得られるように、クライアント設定に `BehaviorVersion` を含める必要があります。`BehaviorVersion` は、デフォルトが想定される SDK のバージョンを指定します。これにより、SDK は時間の経過に従って進化し、アプリケーションの動作に予期しない悪影響を与えることなく、新しい標準に適合させるためのベストプラクティスの変更や新機能のサポートを行えるようになります。
**警告**
`BehaviorVersion` を明示的に指定せずに SDK を設定したり、クライアントを作成したりしようとすると、コンストラクタは panic になります。
例えば、新しいデフォルトのリトライポリシーを備えた SDK の新しいバージョンがリリースされたとします。アプリケーションが SDK の以前のバージョンと一致する `BehaviorVersion` を使用している場合、その以前の設定が新しいデフォルト設定の代わりに使用されます。
SDK for Rust の新しい動作バージョンがリリースされるたびに、以前の `BehaviorVersion` は SDK for Rust の `deprecated` 属性でマークされ、新しいバージョンが追加されます。これにより、コンパイル時に警告が発生しますが、それ以外は通常どおりビルドが継続します。`BehaviorVersion::latest()` も更新され、新しいバージョンのデフォルト動作が示されます。
**注記**
コードが非常に特殊な動作特性に依存していない場合は、コードで `BehaviorVersion::latest()` を使用するか、`Cargo.toml` ファイルで機能フラグ `behavior-version-latest` を使用する必要があります。レイテンシーの影響を受けやすいコードや Rust SDK の動作を調整するコードを記述する場合は、`BehaviorVersion` を特定のメジャーバージョンに固定することを検討してください。
## `Cargo.toml` で動作バージョンを設定する
SDK や個々のモジュールの動作バージョン (`aws-sdk-s3` または `aws-sdk-iam` など) は、`Cargo.toml` ファイルに適切な機能フラグを含めることにより指定できます。現時点では、SDK の `latest` バージョンのみが `Cargo.toml` でサポートされています。
```
[dependencies]
aws-config = { version = "1", features = ["behavior-version-latest"] }
aws-sdk-s3 = { version = "1", features = ["behavior-version-latest"] }
```
## コードで動作バージョンを設定する
SDK またはクライアントを設定するときにコードを指定することにより、必要に応じて動作バージョンを変更できます。
```
let config = aws_config::load_defaults(BehaviorVersion::v2023_11_09()).await;
```
この例では、環境を使用して SDK を設定する設定を作成しますが、`BehaviorVersion` は `v2023_11_09()` に設定します。
# AWS SDK for Rust での再試行の設定
AWS SDK for Rust は、サービスリクエストのデフォルトの再試行動作とカスタマイズ可能な設定オプションを提供します。を呼び出すと、予期しない例外が返される AWS のサービス ことがあります。スロットリングや一時的なエラーなど、特定のタイプのエラーは、呼び出しを再試行すれば成功する場合があります。
再試行動作は、共有 AWS `config`ファイルの環境変数または設定を使用してグローバルに設定できます。この方法の詳細については、「*AWS SDK とツールのリファレンスガイド*」の「[再試行動作](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html)」を参照してください。再試行戦略の実装についての詳細と、それらの中からどれを選択すべきかについても説明しています。
代わりに、以下のセクションに示すように、これらのオプションをコードで設定することもできます。
## デフォルトの再試行設定
すべてのサービスクライアントはデフォルトで、[https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html) 構造体を通じて提供される `standard` 再試行戦略設定を使用します。デフォルトでは、呼び出しは 3 回試行されます (*最初の試行と 2 回の再試行*)。さらに、再試行ストームを避けるために、各再試行はランダムな短時間の間隔で遅延します。この規則は、ほとんどのユースケースに適していますが、高スループットシステムなどの特定の状況では不適切な場合があります。
SDK では、一部のタイプのエラーのみが再試行可能とみなされます。再試行可能なエラーの例を以下に示します。
+ ソケットタイムアウト
+ サービス側のスロットリング
+ HTTP 5XX レスポンスなどの一時的なサービスエラー
以下の例は、再試行可能とは**みなされません**。
+ パラメータなしまたは無効
+ 認証/セキュリティエラー
+ 誤設定の例外
最大試行回数、遅延回数、バックオフ回数を設定して、`standard` 再試行戦略をカスタマイズできます。
## 最大試行回数
変更された [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html) を `aws_config::defaults` に提供することにより、コードの最大試行回数をカスタマイズできます。
```
const CUSTOM_MAX_ATTEMPTS: u32 = 5;
let retry_config = RetryConfig::standard()
// Set max attempts. When max_attempts is 1, there are no retries.
// This value MUST be greater than zero.
// Defaults to 3.
.with_max_attempts(CUSTOM_MAX_ATTEMPTS);
let config = aws_config::defaults(BehaviorVersion::latest())
.retry_config(retry_config)
.load()
.await;
```
## 遅延とバックオフ
再試行が必要な場合、デフォルトの再試行戦略は次の試行の前に待機します。最初の再試行の遅延は小さいですが、それ以降の再試行の遅延は指数関数的に増加します。最大遅延量は、大きくなりすぎないように上限が設定されます。
すべての試行間の遅延には、ランダムなジッタが適用されます。ジッタは、再試行ストームを引き起こす可能性のある大規模なフリートの影響を緩和するのに役立ちます。エクスポネンシャルバックオフとジッタの詳細については、「*AWS アーキテクチャブログ*」の「[Exponential Backoff And Jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)」を参照してください。
変更された [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html) を `aws_config::defaults` に提供することにより、コードの遅延設定をカスタマイズできます。次のコードは、最初の再試行を最大 100 ミリ秒遅延させ、再試行間の最大時間は 5 秒に設定しています。
```
let retry_config = RetryConfig::standard()
// Defaults to 1 second.
.with_initial_backoff(Duration::from_millis(100))
// Defaults to 20 seconds.
.with_max_backoff(Duration::from_secs(5));
let config = aws_config::defaults(BehaviorVersion::latest())
.retry_config(retry_config)
.load()
.await;
```
## アダプティブ再試行モード
`adaptive` モード再試行戦略は、`standard` モード再試行戦略の代替としてスロットリングエラーを最小限に抑えるための理想的なリクエストレートを求める高度な手法です。
**注記**
アダプティブ再試行は高度な再試行モードです。この手法を使用することは通常お勧めしません。「*AWS SDK とツールのリファレンスガイド*」の「[再試行動作](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html#standardvsadaptive)」を参照してください。
アダプティブ再試行には、標準的な再試行のすべての機能が含まれます。クライアント側のレートリミッターを追加し、スロットリングされたリクエストのレートを、スロットリングされていないリクエストと比較して測定します。また、トラフィックが安全な帯域幅内に収まるように制限し、理想的にはスロットリングエラーをゼロに抑えます。
レートは、サービス条件やトラフィックパターンの変化にリアルタイムで適応し、それに応じてトラフィックのレートが増減する場合があります。重要な点として、レートリミッターはトラフィックが集中するシナリオでは初期の試行を遅延させる可能性があります。
コードで `adaptive` 再試行戦略を選択するには、次のような変更された [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html) を入力します。
```
let config = aws_config::defaults(BehaviorVersion::latest())
.retry_config(RetryConfig::adaptive())
.load()
.await;
```
# AWS SDK for Rust でのタイムアウトの設定
AWS SDK for Rust には、 AWS のサービス リクエストのタイムアウトと停止したデータストリームを管理するためのいくつかの設定が用意されています。これらは、ネットワークで予期しない遅延や障害が発生した場合に、アプリケーションが最適に動作するのに役立ちます。
## API タイムアウト
一時的な問題により、リクエストの試行に時間がかかる、または完全に失敗する可能性がある場合、アプリケーションがフェイルファストによって最適に動作できるように、タイムアウトを確認して設定することが重要です。失敗したリクエストは、SDK によって自動的に再試行できます。個々の試行とリクエスト全体の両方にタイムアウトを設定するのがグッドプラクティスです。
SDK for Rust は、リクエストの接続を確立するためにデフォルトでタイムアウトが設定されています。SDK には、リクエストの試行やリクエスト全体のレスポンスを受信するための最大待機時間は、デフォルトでは設定されていません。利用可能なタイムアウトオプションは以下のとおりです。
| パラメータ | デフォルトの値 | 説明 |
| --- | --- | --- |
| 接続タイムアウト | 3.1 秒 | 接続を確立する前に待機する最大時間 (再試行を中止するまでの時間)。 |
| オペレーションタイムアウト | なし | SDK for Rust からレスポンスを受信するまでの最大待機時間で、すべての再試行が含まれます。 |
| オペレーション試行タイムアウト | なし | 1 回の HTTP 試行にかかる最大待機時間で、この時間が経過すると API コールを再試行できます。 |
| 読み取りタイムアウト | なし | リクエストが開始されてから、レスポンスの最初のバイトを読み取るまで待機する最大時間。 |
次の例は、カスタムタイムアウト値を使用する Amazon S3 クライアントの設定を示しています。
```
let config = aws_config::defaults(BehaviorVersion::latest())
.timeout_config(
TimeoutConfig::builder()
.operation_timeout(Duration::from_secs(5))
.operation_attempt_timeout(Duration::from_millis(1500))
.build()
)
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
```
オペレーションタイムアウトと試行タイプアウトを一緒に使用すると、すべての再試行に費やされる合計時間にハードリミットを設定します。また、低速なリクエストに対して、フェイルファストするよう、個々の HTTP リクエストを設定することもできます。
すべてのオペレーションに対してサービスクライアントでこれらのタイムアウト値を設定する代わりに、[1 つのリクエストに対して設定またはオーバーライドできます](peroperation.md)。
**重要**
オペレーションタイムアウトと試行タイムアウトは、SDK for Rust がレスポンスを返した後に消費されるストリーミングデータには適用されません。例えば、レスポンスの `ByteStream` メンバーからデータを消費しても、オペレーションタイムアウトの対象にはなりません。
## ストリーム保護の停止
SDK for Rust は、停止したストリームの検出に関連する別の形式のタイムアウトを利用できます。停止ストリームは、設定された猶予期間を超えてもデータを生成しないアップロードまたはダウンロードストリームです。これにより、アプリケーションが無期限に停止したまま進行しない状態を防止できます。
ストリーム保護が停止すると、ストリームが許容期間を超えてアイドル状態になるとエラーを返します。
デフォルトでは、SDK for Rust はアップロードとダウンロードの両方でストリームの保護の停止を有効化し、20 秒という長めの猶予期間を設け、少なくとも 1 バイト/秒のアクティビティを検出します。
次の例は、アップロード保護を無効化し、アクティビティがない状態の猶予期間を 10 秒に変更するカスタマイズされた `StalledStreamProtectionConfig` を示しています。
```
let config = aws_config::defaults(BehaviorVersion::latest())
.stalled_stream_protection(
StalledStreamProtectionConfig::enabled()
.upload_enabled(false)
.grace_period(Duration::from_secs(10))
.build()
)
.load()
.await;
```
**警告**
ストリーム保護の停止は、高度な設定オプションです。これらの値は、アプリケーションのパフォーマンスの強化が必要な場合や、他の問題を引き起こしている場合にのみ変更することをお勧めします。
### 停止したストリーム保護を無効にする
次の例は、停止したストリーム保護を完全に無効化する方法を示しています。
```
let config = aws_config::defaults(BehaviorVersion::latest())
.stalled_stream_protection(StalledStreamProtectionConfig::disabled())
.load()
.await;
```
# AWS SDK for Rust のオブザーバビリティ機能の設定
オブザーバビリティは、システムが出力するデータから現在の状態をどの程度推論できるかを示します。出力されるデータは、一般的にテレメトリと呼ばれます。
**Topics**
+ [ログ記録](logging.md)
# AWS SDK for Rust でのログ記録の設定と使用
AWS SDK for Rust は、ログ記録に[トレース](http://tracing.rs/)フレームワークを使用しています。ログ記録を有効にするには、Rust アプリケーションで `tracing-subscriber` クレートを追加して初期化します。ログにはタイムスタンプ、ログレベル、モジュールパスが含まれており、API リクエストと SDK の動作のデバッグに役立ちます。`RUST_LOG` 環境変数を使用してログの詳細度を制御し、必要に応じてモジュールごとにフィルタリングします。
## AWS SDK for Rust でログ記録を有効にする方法
1. プロジェクトディレクトリのコマンドプロンプトで、[tracing-subscriber](https://crates.io/crates/tracing-subscriber) クレートを次の依存関係として追加します。
```
$ cargo add tracing-subscriber --features tracing-subscriber/env-filter
```
これにより、`[dependencies]` ファイルの `Cargo.toml` セクションにクレートが追加されます。
1. サブスクライバーを初期化します。通常、これは SDK for Rust オペレーションを呼び出す前に、`main` 関数の早い段階で行われます。
```
use aws_config::BehaviorVersion;
type BoxError = Box;
#[tokio::main]
async fn main() -> Result<(), BoxError> {
tracing_subscriber::fmt::init(); // Initialize the subscriber.
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
let _resp = s3.list_buckets()
.send()
.await?;
Ok(())
}
```
1. `RUST_LOG` 環境変数を使用して、ログ記録を有効化します。ログ情報の表示を有効化するには、コマンドプロンプトで、`RUST_LOG` 環境変数をログ記録しようとするレベルに設定します。次の例では、ログ記録のレベルを `debug` に設定します。
------
#### [ Linux/macOS ]
```
$ RUST_LOG=debug
```
------
#### [ Windows ]
VSCode を使用している場合、ターミナルウィンドウのデフォルトは PowerShell です。使用しているプロンプトのタイプを確認します。
```
C:\> set RUST_LOG=debug
```
------
#### [ PowerShell ]
```
PS C:\> $ENV:RUST_LOG="debug"
```
------
1. 以下のプログラムを実行します。
```
$ cargo run
```
コンソールまたはターミナルウィンドウに追加の出力が表示されます。
詳細については、`tracing-subscriber` ドキュメントの「[環境変数を使用したイベントのフィルタリング](https://docs.rs/tracing-subscriber/0.3.18/tracing_subscriber/fmt/index.html#filtering-events-with-environment-variables)」を参照してください。
## ログ出力の解釈
前のセクションの手順に従ってログ記録を有効化すると、デフォルトで追加のログ情報が標準出力に表示されます。
デフォルトのログ出力形式 (トレースモジュールでは「full」と呼ばれます) を使用している場合、ログ出力に表示される情報は次のようになります。
```
2024-06-25T16:10:12.367482Z DEBUG invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt:lazy_load_identity: aws_smithy_runtime::client::identity::cache::lazy: identity cache miss occurred; added new identity (took 480.892ms) new_expiration=2024-06-25T23:07:59Z valid_for=25066.632521s partition=IdentityCachePartition(7)
2024-06-25T16:10:12.367602Z DEBUG invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::identity::cache::lazy: loaded identity
2024-06-25T16:10:12.367643Z TRACE invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::orchestrator::auth: resolved identity identity=Identity { data: Credentials {... }, expiration: Some(SystemTime { tv_sec: 1719356879, tv_nsec: 0 }) }
2024-06-25T16:10:12.367695Z TRACE invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::orchestrator::auth: signing request
```
各エントリには、以下の内容が含まれています。
+ ログエントリのタイムスタンプ。
+ エントリのログレベル。これは、`INFO`、`DEBUG`、または `TRACE` のような単語です。
+ ログエントリが生成された[スパン](https://docs.rs/tracing/latest/tracing/span/index.html)がネストされた集合で、コロン (":") で区切られています。これにより、ログエントリのソースを識別できます。
+ ログエントリを生成したコードを含む Rust モジュールパス。
+ ログメッセージテキスト。
トレースモジュールの標準出力形式は、ANSI エスケープコードを使用して出力を色分けします。出力のフィルタリングや検索を行う場合は、これらのエスケープシーケンスに注意してください。
**注記**
ネストされたスパンの集合内に表示される `sdk_invocation_id` は、SDK によってクライアント側で生成される一意の ID で、ログメッセージを関連付けしやすくします。これは、AWS のサービス からのレスポンスで確認されたリクエスト ID とは無関係です。
## ログ記録レベルのファインチューニング
`tracing_subscriber` などの環境フィルタリングをサポートするクレートを使用する場合は、モジュールごとにログの詳細度を制御できます。
すべてのモジュールに対して同じログレベルを有効化できます。以下は、各モジュールのログ記録レベルを `trace` に設定しています。
```
$ RUST_LOG=trace cargo run
```
特定のモジュールのトレースレベルのログ記録を有効化できます。次の例では、`aws_smithy_runtime` からのログのみが `trace` レベルで入力されています。
```
$ RUST_LOG=aws_smithy_runtime=trace
```
複数のモジュールに異なるログレベルを指定するには、カンマで区切ります。次の例では、`aws_config` モジュールを `trace` レベルのログ記録に設定し、`aws_smithy_runtime` モジュールを `debug` レベルのログ記録に設定しています。
```
$ RUST_LOG=aws_config=trace,aws_smithy_runtime=debug cargo run
```
次の表は、ログメッセージのフィルタリングに使用できるモジュールの一部を示しています。
| プレフィックス | 説明 |
| --- | --- |
| `aws_smithy_runtime` | リクエストとレスポンスのワイヤログ記録 |
| `aws_config` | 認証情報の読み込み |
| `aws_sigv4` | リクエスト署名と正規リクエスト |
ログ出力に含める必要があるモジュールを特定する 1 つの方法は、最初にすべてをログに記録し、次に必要な情報をログ出力で該当するクレート名を見つけることです。その後、対応する環境変数を設定することにより、プログラムを再度実行できます。
# でのクライアントエンドポイントの設定 AWS SDK for Rust
が を AWS SDK for Rust 呼び出すとき AWS のサービスの最初のステップの 1 つは、リクエストをルーティングする場所を決定することです。このプロセスは、エンドポイント解決と呼ばれます。
サービスクライアントを作成する際に、SDK のエンドポイント解決を設定できます。デフォルトのエンドポイント解決の設定で通常は問題ありませんが、デフォルト設定を変更する理由はいくつかあります。これには以下のように 2 つの理由があります。
+ サービスのプレリリースバージョンまたはローカルデプロイにリクエストするには
+ SDK でモデル化が完了していない特定のサービス機能にアクセスするには
**警告**
エンドポイント解決は、高度な SDK トピックです。デフォルト設定を変更すると、コードが機能しなくなるリスクがあります。デフォルト設定は、本番環境のほとんどのユーザーに適用されます。
カスタムエンドポイントは、すべてのサービスリクエストに使用されるようにグローバルに設定することも、特定の のカスタムエンドポイントを設定することもできます AWS のサービス。
カスタムエンドポイントは、共有 AWS `config`ファイルの環境変数または設定を使用して設定できます。この手法の詳細については、「*AWS SDK とツールのリファレンスガイド*」の「[サービス固有のエンドポイント](https://docs.aws.amazon.com/sdkref/latest/guide/feature-ss-endpoints.html)」を参照してください。すべての共有`config`ファイル設定と環境変数の完全なリストについては AWS のサービス、[「サービス固有のエンドポイントの識別子](https://docs.aws.amazon.com/sdkref/latest/guide/ss-endpoints-table.html)」を参照してください。
代わりに、以下のセクションに示すように、このカスタマイズをコードで設定することもできます。
## カスタム設定
サービスクライアントのエンドポイント解決は、クライアントの構築時に使用できる 2 つの方法でカスタマイズできます。
1. `endpoint_url(url: Into)`
1. `endpoint_resolver(resolver: impl crate::config::endpoint::ResolveEndpoint + `static)`
両方のプロパティを設定できます。ただし、ほとんどの場合、設定するのは 1 つのみです。一般的な用途では、`endpoint_url` は最も頻繁にカスタマイズされます。
### エンドポイント URL の設定
`endpoint_url` の値を設定して、サービスの「ベース」ホスト名を指定できます。ただし、この値はクライアントの `ResolveEndpoint` インスタンスにパラメータとして渡されるため、最終値ではありません。その後、`ResolveEndpoint` 実装はその値を検査し、場合によっては変更して、最終的なエンドポイントを決定できます。
### エンドポイントリゾルバーの設定
サービスクライアントの `ResolveEndpoint` 実装によって、SDK が特定のリクエストに使用する最終的に解決されたエンドポイントが決まります。サービスクライアントは、すべてのリクエストに対して `resolve_endpoint` メソッドを呼び出し、リゾルバーから返される [https://docs.rs/aws-smithy-runtime-api/latest/aws_smithy_runtime_api/client/endpoint/struct.EndpointFuture.html](https://docs.rs/aws-smithy-runtime-api/latest/aws_smithy_runtime_api/client/endpoint/struct.EndpointFuture.html) 値をそのまま使用します。
次の例では、Amazon S3 クライアント向けにカスタムエンドポイント解決の実装を提供し、ステージングや本番稼働など、ステージごとに異なるエンドポイントを解決する方法を示しています。
```
use aws_sdk_s3::config::endpoint::{ResolveEndpoint, EndpointFuture, Params, Endpoint};
#[derive(Debug)]
struct StageResolver { stage: String }
impl ResolveEndpoint for StageResolver {
fn resolve_endpoint(&self, params: &Params) -> EndpointFuture<'_> {
let stage = &self.stage;
EndpointFuture::ready(Ok(Endpoint::builder().url(format!("{stage}.myservice.com")).build()))
}
}
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
let resolver = StageResolver { stage: std::env::var("STAGE").unwrap() };
let s3_config = aws_sdk_s3::config::Builder::from(&config)
.endpoint_resolver(resolver)
.build();
let s3 = aws_sdk_s3::Client::from_conf(s3_config);
```
**注記**
エンドポイントリゾルバー、および拡張により `ResolveEndpoint` トレイトは各サービスに固有であるため、サービスクライアント設定でのみ設定できます。一方、エンドポイント URL は、共有設定 (そこから派生するすべてのサービスに適用されます) 使用して設定することも、特定のサービスに対して設定することもできます。
#### ResolveEndpoint パラメータ
`resolve_endpoint` メソッドは、エンドポイント解決で使用されるプロパティを含む、サービス固有のパラメータを受け入れます。
サービスごとに、以下のベースプロパティが含まれます。
| 名前 | 型 | 説明 |
| --- | --- | --- |
| region | 文字列 | クライアントの AWS リージョン |
| endpoint | String | endpointUrl の値セットの文字列表現 |
| use\$1fips | ブール値 | クライアントの設定で FIPS エンドポイントが有効かどうか |
| use\$1dual\$1stack | ブール値 | クライアントの設定でデュアルスタックエンドポイントが有効かどうか |
AWS のサービス は、解決に必要な追加のプロパティを指定できます。例えば、Amazon S3 [エンドポイントパラメータ](https://docs.rs/aws-sdk-s3/latest/aws_sdk_s3/config/endpoint/struct.Params.html)には、バケット名と複数の Amazon S3 固有の機能設定が含まれます。例えば、`force_path_style` プロパティは仮想ホストアドレス指定を使用できるかどうかを決定します。
独自のプロバイダーを実装する場合、エンドポイントパラメータの独自のインスタンスをコンストラクトする必要はありません。SDK は、各リクエストのプロパティを提供し、`resolve_endpoint` の実装に渡します。
### `endpoint_url` の使用と `endpoint_resolver` の使用の比較
次の 2 つの設定 (`endpoint_url` を使用する設定と `endpoint_resolver` を使用する設定) は、クライアントエンドポイント解決動作が同じではないことを理解することが重要です。
```
use aws_sdk_s3::config::endpoint::{ResolveEndpoint, EndpointFuture, Params, Endpoint};
#[derive(Debug, Default)]
struct CustomResolver;
impl ResolveEndpoint for CustomResolver {
fn resolve_endpoint(&self, _params: &Params) -> EndpointFuture<'_> {
EndpointFuture::ready(Ok(Endpoint::builder().url("https://endpoint.example").build()))
}
}
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
// use endpoint url
aws_sdk_s3::config::Builder::from(&config)
.endpoint_url("https://endpoint.example")
.build();
// Use endpoint resolver
aws_sdk_s3::config::Builder::from(&config)
.endpoint_resolver(CustomResolver::default())
.build();
```
`endpoint_url` を設定するクライアントは、エンドポイント解決の一部として変更できる (デフォルト) プロバイダーに渡される*ベース* URL を指定します。
`endpoint_resolver` を設定するクライアントは、Amazon S3 クライアントが使用する*最終的な* URL を指定します。
## 例
カスタムエンドポイントはテストによく使用されます。クラウドベースのサービスを呼び出す代わりに、呼び出しはローカルにホストされたシミュレートされたサービスにルーティングされます。以下のような 2 種類のオプションがあります。
+ [DynamoDB local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html) – Amazon DynamoDB サービスのローカルバージョンです。
+ [LocalStack](https://github.com/localstack/localstack) – ローカルマシンのコンテナで実行されるクラウドサービスエミュレータです。
次の例では、これら 2 つのテストオプションを使用するために、カスタムエンドポイントを指定する 2 種類の方法を示しています。
### DynamoDB local をコードで直接使用する
前のセクションで説明したように、`endpoint_url` をコードで直接設定して、ローカル DynamoDB サーバーを指すようにベースエンドポイントをオーバーライドできます。コード:
```
let config = aws_config::defaults(aws_config::BehaviorVersion::latest())
.test_credentials()
// DynamoDB run locally uses port 8000 by default.
.endpoint_url("http://localhost:8000")
.load()
.await;
let dynamodb_local_config = aws_sdk_dynamodb::config::Builder::from(&config).build();
let client = aws_sdk_dynamodb::Client::from_conf(dynamodb_local_config);
```
[完全な例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/dynamodb/src/bin/list-tables-local.rs)は GitHub で入手できます。
### `config` ファイルを使用して LocalStack を使用する
共有 AWS `config`ファイルで[サービス固有のエンドポイント](https://docs.aws.amazon.com/sdkref/latest/guide/feature-ss-endpoints.html)を設定できます。次の設定プロファイルは、ポート `4566` で `localhost` に接続するように `endpoint_url` を設定します。LocalStack 設定の詳細については、*LocalStack ドキュメント*ウェブサイトの「[エンドポイント URL 経由の LocalStack へのアクセス](https://docs.localstack.cloud/references/network-troubleshooting/endpoint-url/)」を参照してください。
```
[profile localstack]
region=us-east-1
endpoint_url = http://localhost:4566
```
SDK は、共有 `config` ファイルの変更を検出し、`localstack` プロファイルを使用する際に SDK クライアントに適用します。この手法を使用すると、コードにエンドポイントへの参照を含める必要がなく、次のようになります。
```
// set the environment variable `AWS_PROFILE=localstack` when running
// the application to source `endpoint_url` and point the SDK at the
// localstack instance
let config = aws_config::defaults(BehaviorVersion::latest()).load().await;
let s3_config = aws_sdk_s3::config::Builder::from(&config)
.force_path_style(true)
.build();
let s3 = aws_sdk_s3::Client::from_conf(s3_config);
```
[完全な例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/localstack)は GitHub で入手できます。
# AWS SDK for Rust でのクライアントの 1 つのオペレーション設定の上書き
[サービスクライアントを作成](config-code.md)すると、設定は変更不可能になり、以降のすべてのオペレーションに適用されます。この時点で設定は変更できませんが、オペレーションごとにオーバーライドできます。
各オペレーションビルダーには、既存の設定の個別のコピーをオーバーライドできるように、`CustomizableOperation` を作成するための `customize` メソッドがあります。元のクライアント設定は変更されません。
次は、2 つのオペレーションを呼び出す Amazon S3 クライアントの作成例を示しています。2 番目のオペレーションは、別の AWS リージョンに送信するようにオーバーライドされます。Amazon S3 のオブジェクト呼び出しはすべて `us-east-1` リージョンを使用します。ただし、API コールが明示的にオーバーライドされ、変更された `us-west-2` を使用する場合を除きます。
```
use aws_config::{BehaviorVersion, Region};
let config = aws_config::defaults(BehaviorVersion::latest())
.region("us-east-1")
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
// Request will be sent to "us-east-1"
s3.list_buckets()
.send()
.await?;
// Unset fields default to using the original config value
let modified = aws_sdk_s3::Config::builder()
.region(Region::from_static("us-west-2"));
// Request will be sent to "us-west-2"
s3.list_buckets()
// Creates a CustomizableOperation
.customize()
.config_override(modified)
.send()
.await?;
```
**注記**
前の例は Amazon S3 向けですが、概念はすべてのオペレーションで同じです。一部のオペレーションでは、`CustomizeableOperation` で追加のメソッドがある場合があります。
1 回のオペレーションで `customize` を使用してインターセプターを追加する例については、「[特定のオペレーションのみのインターセプター](interceptors.md#interceptors-registration-specific)」を参照してください。
# AWS SDK for Rust 内での HTTP レベルの設定の構成
AWS SDK for Rust には、コードで作成するクライアントで使用される AWS のサービス 組み込み HTTP 機能が用意されています。
デフォルトでは、SDK for Rust は `hyper`、`rustls`、および `aws-lc-rs` に基づく HTTPS クライアントを使用します。このクライアントは、追加の設定なしでほとんどのユースケースで問題なく機能します。
+ [https://docs.rs/hyper/latest/hyper/](https://docs.rs/hyper/latest/hyper/) は Rust 用の低レベルの HTTP ライブラリで、 で API サービスコール AWS SDK for Rust を行うことができます。
+ [https://github.com/rustls/rustls](https://github.com/rustls/rustls) は、Rust で記述された最新の TLS ライブラリで、暗号化プロバイダー用のオプションが組み込まれています。
+ [https://github.com/aws/aws-lc](https://github.com/aws/aws-lc) は、TLS および一般的なアプリケーションに必要なアルゴリズムを含む汎用暗号化ライブラリです。
+ [https://github.com/aws/aws-lc-rs](https://github.com/aws/aws-lc-rs) は、Rust の `aws-lc` ライブラリに対する慣用的なラッパーです。
別の TLS または暗号化プロバイダーを選択する場合、`aws-smithy-http-client` クレートには追加オプションと設定が複数用意されています。より高度なユースケースでは、独自の HTTP クライアントの実装を導入するか、検討のために機能リクエストを提出することをお勧めします。
## 代替 TLS プロバイダーの選択
`aws-smithy-http-client` クレートには、複数の代替 TLS プロバイダーが用意されています。
以下のプロバイダーが利用可能です。
**`rustls` に `aws-lc` を使用する**
[https://github.com/rustls/rustls](https://github.com/rustls/rustls) に基づく TLS プロバイダーで、暗号化に [https://github.com/aws/aws-lc-rs](https://github.com/aws/aws-lc-rs) を使用します。
これは、SDK for Rust のデフォルトの HTTP 動作です。このオプションを使用する場合、コードで追加のアクションを実行する必要はありません。
**`s2n-tls`**
[https://github.com/aws/s2n-tls](https://github.com/aws/s2n-tls) に基づく TLS プロバイダー。
**`rustls` に `aws-lc-fips` を使用する**
[https://github.com/rustls/rustls](https://github.com/rustls/rustls) に基づく TLS プロバイダーで、暗号化に [https://github.com/aws/aws-lc-rs](https://github.com/aws/aws-lc-rs) の FIPS 準拠バージョンを使用します
**`rustls` に `ring` を使用する**
[https://github.com/rustls/rustls](https://github.com/rustls/rustls) に基づく TLS プロバイダーで、暗号化に [https://github.com/briansmith/ring](https://github.com/briansmith/ring) を使用します。
### 前提条件
`aws-lc-rs` または `s2n-tls` を使用するには、C コンパイラ (Clang または GCC) を構築する必要があります。一部のプラットフォームでは、ビルドに CMake が必要な場合があります。任意のプラットフォームで「fips」機能を使用して構築するには、CMake と Go が必要です。詳細については、「[Rust 向け AWS Libcrypto (`aws-lc-rs`)](https://github.com/aws/aws-lc-rs/blob/main/aws-lc-rs/README.md)」のリポジトリとビルド手順を参照してください。
### 代替 TLS プロバイダーの使用方法
`aws-smithy-http-client` クレートには、追加の TLS オプションが用意されています。 AWS のサービス クライアントが別の TLS プロバイダーを使用するには、`aws_config` クレートからローダーを使用して `http_client` をオーバーライドします。HTTP クライアントは、 AWS のサービス および認証情報プロバイダーの両方に使用されます。
以下の例は、`s2n-tls` TLS プロバイダーの使用方法を示しています。ただし、同様の手法は他のプロバイダーに対しても有効です。
サンプルコードをコンパイルするには、以下のコマンドを実行して依存関係をプロジェクトに追加します。
```
cargo add aws-smithy-http-client -F s2n-tls
```
コード例:
```
use aws_smithy_http_client::{tls, Builder};
#[tokio::main]
async fn main() {
let http_client = Builder::new()
.tls_provider(tls::Provider::S2nTls)
.build_https();
let sdk_config = aws_config::defaults(
aws_config::BehaviorVersion::latest()
)
.http_client(http_client)
.load()
.await;
// create client(s) using sdk_config
// e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```
## FIPS サポートの有効化
`aws-smithy-http-client` クレートには、FIPS 準拠の暗号化実装を有効化するオプションがあります。 AWS のサービス クライアントが FIPS 準拠プロバイダーを使用するには、クレートのローダー`http_client`を使用して `aws_config` を上書きします。HTTP クライアントは、 AWS のサービス および 認証情報プロバイダーの両方に使用されます。
**注記**
FIPS サポートには、ビルド環境で追加の依存関係が必要です。`aws-lc` クレートの「[ビルド](https://github.com/aws/aws-lc/blob/main/BUILDING.md)」手順を参照してください。
サンプルコードをコンパイルするには、以下のコマンドを実行して依存関係をプロジェクトに追加します。
```
cargo add aws-smithy-http-client -F rustls-aws-lc-fips
```
次のコード例では、FIPS のサポートを有効化しています。
```
// file: main.rs
use aws_smithy_http_client::{
tls::{self, rustls_provider::CryptoMode},
Builder,
};
#[tokio::main]
async fn main() {
let http_client = Builder::new()
.tls_provider(tls::Provider::Rustls(CryptoMode::AwsLcFips))
.build_https();
let sdk_config = aws_config::defaults(
aws_config::BehaviorVersion::latest()
)
.http_client(http_client)
.load()
.await;
// create client(s) using sdk_config
// e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```
## ポスト量子キー交換の優先順位付け
デフォルトの TLS プロバイダーは、`X25519MLKEM768` ポスト量子キー交換アルゴリズムをサポートする `aws-lc-rs` を使用する `rustls` に基づいています。最も優先度の高いアルゴリズムとして `X25519MLKEM768` を作成するには、`rustls` パッケージをクレートに追加し、`prefer-post-quantum` 機能フラグを有効にする必要があります。それ以外の場合、使用はできますが、最優先ではありません。詳細については、`rustls` の「[ドキュメント](https://docs.rs/rustls/0.23.23/rustls/manual/_05_defaults/index.html#about-the-post-quantum-secure-key-exchange-x25519mlkem768)」を参照してください。
**注記**
これは、今後のリリースではデフォルトになります。
## DNS リゾルバーのオーバーライド
デフォルトの DNS リゾルバーは、HTTP クライアントを手動で設定することによりオーバーライドできます。
サンプルコードをコンパイルするには、以下のコマンドを実行して依存関係をプロジェクトに追加します。
```
cargo add aws-smithy-http-client -F rustls-aws-lc
cargo add aws-smithy-runtime-api -F client
```
次のコード例では、DNS リゾルバーをオーバーライドしています。
```
use aws_smithy_http_client::{
tls::{self, rustls_provider::CryptoMode},
Builder
};
use aws_smithy_runtime_api::client::dns::{DnsFuture, ResolveDns};
use std::net::{IpAddr, Ipv4Addr};
/// A DNS resolver that returns a static IP address (127.0.0.1)
#[derive(Debug, Clone)]
struct StaticResolver;
impl ResolveDns for StaticResolver {
fn resolve_dns<'a>(&'a self, _name: &'a str) -> DnsFuture<'a> {
DnsFuture::ready(Ok(vec![IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1))]))
}
}
#[tokio::main]
async fn main() {
let http_client = Builder::new()
.tls_provider(tls::Provider::Rustls(CryptoMode::AwsLc))
.build_with_resolver(StaticResolver);
let sdk_config = aws_config::defaults(
aws_config::BehaviorVersion::latest()
)
.http_client(http_client)
.load()
.await;
// create client(s) using sdk_config
// e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```
**注記**
デフォルトでは、Amazon Linux 2023 (AL2023) はオペレーティングシステムレベルで DNS キャッシュを行いません。
## ルート CA 証明書のカスタマイズ
デフォルトでは、TLS プロバイダーは指定されたプラットフォームのシステムネイティブルート証明書を読み込みます。この動作をカスタマイズしてカスタム CA バンドルを読み込むには、独自の `TlsContext` を使用して `TrustStore` を設定できます。
サンプルコードをコンパイルするには、以下のコマンドを実行して依存関係をプロジェクトに追加します。
```
cargo add aws-smithy-http-client -F rustls-aws-lc
```
次の例では、`rustls` で `aws-lc` を使用しますが、サポートされているすべての TLS プロバイダーで機能します。
```
use aws_smithy_http_client::{
tls::{self, rustls_provider::CryptoMode},
Builder
};
use std::fs;
/// read the PEM encoded root CA (bundle) and return a custom TLS context
fn tls_context_from_pem(filename: &str) -> tls::TlsContext {
let pem_contents = fs::read(filename).unwrap();
// Create a new empty trust store (this will not load platform native certificates)
let trust_store = tls::TrustStore::empty()
.with_pem_certificate(pem_contents.as_slice());
tls::TlsContext::builder()
.with_trust_store(trust_store)
.build()
.expect("valid TLS config")
}
#[tokio::main]
async fn main() {
let http_client = Builder::new()
.tls_provider(tls::Provider::Rustls(CryptoMode::AwsLc))
.tls_context(tls_context_from_pem("my-custom-ca.pem"))
.build_https();
let sdk_config = aws_config::defaults(
aws_config::BehaviorVersion::latest()
)
.http_client(http_client)
.load()
.await;
// create client(s) using sdk_config
// e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```
# AWS SDK for Rust でのインターセプターの設定
インターセプターを使用して、API リクエストおよびレスポンスの実行フローにフックを挿入できます。インターセプターは、SDK がユーザー定義のコードを呼び出して、リクエスト/レスポンスのライフサイクルに処理を挿入できるようにする、柔軟な仕組みです。これにより、進行中のリクエストの変更、リクエスト処理のデバッグ、エラーの確認などを行うことができます。
次の例は、再試行ループに入る前にすべての送信リクエストにヘッダーを追加するシンプルなインターセプターを示しています。
```
use std::borrow::Cow;
use aws_smithy_runtime_api::client::interceptors::{
Intercept,
context::BeforeTransmitInterceptorContextMut,
};
use aws_smithy_runtime_api::client::runtime_components::RuntimeComponents;
use aws_smithy_types::config_bag::ConfigBag;
use aws_smithy_runtime_api::box_error::BoxError;
#[derive(Debug)]
struct AddHeaderInterceptor {
key: Cow<'static, str>,
value: Cow<'static, str>,
}
impl AddHeaderInterceptor {
fn new(key: &'static str, value: &'static str) -> Self {
Self {
key: Cow::Borrowed(key),
value: Cow::Borrowed(value),
}
}
}
impl Intercept for AddHeaderInterceptor {
fn name(&self) -> &'static str {
"AddHeader"
}
fn modify_before_retry_loop(
&self,
context: &mut BeforeTransmitInterceptorContextMut<'_>,
_runtime_components: &RuntimeComponents,
_cfg: &mut ConfigBag,
) -> Result<(), BoxError> {
let headers = context.request_mut().headers_mut();
headers.insert(self.key.clone(), self.value.clone());
Ok(())
}
}
```
詳細と使用可能なインターセプターフックについては、「[インターセプト](https://docs.rs/aws-smithy-runtime-api/latest/aws_smithy_runtime_api/client/interceptors/trait.Intercept.html)」トレイトを参照してください。
## インターセプターの登録
インターセプターは、サービスクライアントをコンストラクトするときや、特定のオペレーションの設定をオーバーライドするときに登録します。登録方法は、インターセプターをクライアントのすべてのオペレーションに適用するか、特定のオペレーションのみに適用するかによって異なります。
### サービスクライアントに対するすべてのオペレーションのインターセプター
クライアント全体のインターセプターを登録するには、`Builder` パターンを使用してインターセプターを追加します。
```
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
// All service operations invoked using 's3' will have the header added.
let s3_conf = aws_sdk_s3::config::Builder::from(&config)
.interceptor(AddHeaderInterceptor::new("x-foo-version", "2.7"))
.build();
let s3 = aws_sdk_s3::Client::from_conf(s3_conf);
```
### 特定のオペレーションのみのインターセプター
1 回のオペレーションのみにインターセプターを登録するには、`customize` 拡張機能を使用します。このメソッドを使用すると、サービスクライアントの設定をオペレーション単位でオーバーライドできます。これらのカスタマイズ可能なオペレーションの詳細については、「[AWS SDK for Rust でのクライアントの 1 つのオペレーション設定の上書き](peroperation.md)」を参照してください。
```
// Only the list_buckets operation will have the header added.
s3.list_buckets()
.customize()
.interceptor(AddHeaderInterceptor::new("x-bar-version", "3.7"))
.send()
.await?;
```