翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AWS SDK for Rust でのクライアントエンドポイントの設定

AWS SDK for Rust によって AWS のサービス を呼び出す際の最初のステップの 1 つは、リクエストをルーティングする場所を決定することです。このプロセスは、エンドポイント解決と呼ばれます。

サービスクライアントを作成する際に、SDK のエンドポイント解決を設定できます。デフォルトのエンドポイント解決の設定で通常は問題ありませんが、デフォルト設定を変更する理由はいくつかあります。これには以下のように 2 つの理由があります。

カスタムエンドポイントは、すべてのサービスリクエストに使用されるようにグローバルに設定することも、特定の AWS のサービス にカスタムエンドポイントを設定することもできます。

カスタムエンドポイントは、共有 AWS config ファイルの環境変数または設定を使用して設定できます。この手法の詳細については、「AWS SDK とツールのリファレンスガイド」の「サービス固有のエンドポイント」を参照してください。すべての AWS のサービスの共有 config ファイル設定と環境変数の完全なリストについては、「サービス固有のエンドポイントの識別子」を参照してください。

代わりに、以下のセクションに示すように、このカスタマイズをコードで設定することもできます。

カスタム設定

サービスクライアントのエンドポイント解決は、クライアントの構築時に使用できる 2 つの方法でカスタマイズできます。

両方のプロパティを設定できます。ただし、ほとんどの場合、設定するのは 1 つのみです。一般的な用途では、endpoint_url は最も頻繁にカスタマイズされます。

エンドポイント URL の設定

endpoint_url の値を設定して、サービスの「ベース」ホスト名を指定できます。ただし、この値はクライアントの ResolveEndpoint インスタンスにパラメータとして渡されるため、最終値ではありません。その後、ResolveEndpoint 実装はその値を検査し、場合によっては変更して、最終的なエンドポイントを決定できます。

エンドポイントリゾルバーの設定

サービスクライアントの ResolveEndpoint 実装によって、SDK が特定のリクエストに使用する最終的に解決されたエンドポイントが決まります。サービスクライアントは、すべてのリクエストに対して resolve_endpoint メソッドを呼び出し、リゾルバーから返される EndpointFuture 値をそのまま使用します。

次の例では、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 パラメータ

resolve_endpoint メソッドは、エンドポイント解決で使用されるプロパティを含む、サービス固有のパラメータを受け入れます。

サービスごとに、以下のベースプロパティが含まれます。

AWS のサービスでは、解決に必要なプロパティを追加で指定できます。例えば、Amazon S3 エンドポイントパラメータには、バケット名と複数の 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 種類のオプションがあります。

次の例では、これら 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);

完全な例は GitHub で入手できます。

config ファイルを使用して LocalStack を使用する

共有 AWS config ファイルでサービス固有のエンドポイントを設定できます。次の設定プロファイルは、ポート 4566 で localhost に接続するように endpoint_url を設定します。LocalStack 設定の詳細については、LocalStack ドキュメントウェブサイトの「エンドポイント URL 経由の LocalStack へのアクセス」を参照してください。

[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);

完全な例は GitHub で入手できます。