AWS SDK for Java 1.x は 2025 年 12 月 31 日にend-of-supportしました。新しい機能、可用性の向上、セキュリティ更新のために、[AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/home.html) に移行することをお勧めします。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# の使用 AWS SDK for Java
このセクションでは、 SDK で使用するすべてのサービスに適用される AWS SDK for Java を使用したプログラミングに関する重要な一般情報を提供します。
サービス固有のプログラミング情報と例 ( など) については Amazon EC2 Amazon S3 Amazon SWF、[AWS SDK for Java 「コード例](prog-services.md)」を参照してください。
**Topics**
+ [を使用した AWS 開発のベストプラクティス AWS SDK for Java](best-practices.md)
+ [サービスクライアントの作成](creating-clients.md)
+ [一時的な認証情報の提供](credentials.md)
+ [AWS リージョン 選択](java-dg-region-selection.md)
+ [例外処理](java-dg-exceptions.md)
+ [非同期プログラミング](basics-async.md)
+ [AWS SDK for Java 通話のログ記録](java-dg-logging.md)
+ [クライアント設定](section-client-configuration.md)
+ [アクセスコントロールポリシー](java-dg-access-control.md)
+ [DNS 名参照用の JVM TTL を設定する](jvm-ttl-dns.md)
+ [のメトリクスの有効化 AWS SDK for Java](generating-sdk-metrics.md)
# を使用した AWS 開発のベストプラクティス AWS SDK for Java
以下のベストプラクティスは、 を使用して AWS アプリケーションを開発する際の問題や問題を回避するのに役立ちます AWS SDK for Java。ベストプラクティスはサービスごとに整理してあります。
## S3
### ResetExceptions の回避
ストリーム Amazon S3 を使用して ( `AmazonS3`クライアントまたは を介して`TransferManager`) オブジェクトを にアップロードすると、ネットワーク接続またはタイムアウトの問題が発生する可能性があります。デフォルトでは、 は転送の開始前に入力ストリームをマークし、再試行する前にリセットすることで、 AWS SDK for Java 失敗した転送を再試行しようとします。
ストリームが mark と reset をサポートしていない場合、一時的なエラーが発生して再試行が有効になると、SDK は [ResetException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/ResetException.html) をスローします。
**ベストプラクティス**
mark オペレーションと reset オペレーションをサポートするストリームを使用することをお勧めします。
[ResetException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/ResetException.html) を回避する最も信頼性の高い方法は、[File](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html) または [FileInputStream](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/FileInputStream.html) を使用してデータを提供することです。これは、 がマークとリセットの制限に制約されることなく処理 AWS SDK for Java できます。
ストリームが [FileInputStream](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/FileInputStream.html) でないものの mark と reset をサポートしている場合は、[RequestClientOptions](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/RequestClientOptions.html) の `setReadLimit` メソッドを使用して mark の制限を設定できます。デフォルト値は 128 KB です。読み取り制限値を*ストリームのサイズより 1 バイト大きく*設定すると、信頼できる方法で [ResetException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/ResetException.html) を回避できます。
たとえば、ストリームの最大予想サイズが 100,000 バイトである場合、読み取り制限を 100,001 (100,000 \$1 1) バイトに設定します。mark と reset は常に 100,000 バイト以下で動作します。これにより、一部のストリームではそのバイト数がメモリにバッファされる場合があることに注意してください。
# サービスクライアントの作成
にリクエストを行うには Amazon Web Services、まずサービスクライアントオブジェクトを作成します。推奨される方法は、サービスクライアントビルダーを使用することです。
各 AWS のサービス には、サービス API の各アクションのメソッドを含むサービスインターフェイスがあります。たとえば、DynamoDB のサービスインターフェイスは、[AmazonDynamoDBClient](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/AmazonDynamoDBClient.html) という名前です。各サービスインターフェイスに対応するクライアントビルダーがあり、サービスインターフェイスの実装を構築する際に使用できます。のクライアントビルダークラス DynamoDB は、[AmazonDynamoDBClientBuilder](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/AmazonDynamoDBClientBuilder.html) という名前です。
## クライアントビルダーの取得
クライアントビルダーのインスタンスを取得するには、次の例に示す静的ファクトリメソッド `standard` を使用します。
```
AmazonDynamoDBClientBuilder builder = AmazonDynamoDBClientBuilder.standard();
```
ビルダーを取得すると、ビルダー API で多数の fluent setter を使用して、クライアントのプロパティをカスタマイズできます。たとえば、カスタムリージョンおよびカスタム認証情報プロバイダーは以下のように設定できます。
```
AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.standard()
.withRegion(Regions.US_WEST_2)
.withCredentials(new ProfileCredentialsProvider("myProfile"))
.build();
```
**注記**
fluent `withXXX` メソッドは `builder` オブジェクトを返し、メソッドの呼び出しを連鎖させて利便性とコードの可読性を向上させることができます。必要なプロパティを設定後、`build` メソッドを呼び出してクライアントを作成することができます。作成後のクライアントはイミュータブルで、`setRegion` または `setEndpoint` の呼び出しはすべて失敗します。
ビルダーでは、同じ構成で複数のクライアントを作成できます。アプリケーションを記述している場合、ビルダーがミュータブルであり、スレッドセーフでないことに注意してください。
次のコードでは、クライアントインスタンスのファクトリとしてビルダーが使用されます。
```
public class DynamoDBClientFactory {
private final AmazonDynamoDBClientBuilder builder =
AmazonDynamoDBClientBuilder.standard()
.withRegion(Regions.US_WEST_2)
.withCredentials(new ProfileCredentialsProvider("myProfile"));
public AmazonDynamoDB createClient() {
return builder.build();
}
}
```
ビルダーは、[ClientConfiguration](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/ClientConfiguration.html) および [RequestMetricCollector](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/metrics/RequestMetricCollector.html) の fluent setter、および [RequestHandler2](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/handlers/RequestHandler2.html) のカスタムリストも公開します。
すべての設定可能なプロパティをオーバーライドする完全な例を次に示します。
```
AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.standard()
.withRegion(Regions.US_WEST_2)
.withCredentials(new ProfileCredentialsProvider("myProfile"))
.withClientConfiguration(new ClientConfiguration().withRequestTimeout(5000))
.withMetricsCollector(new MyCustomMetricsCollector())
.withRequestHandlers(new MyCustomRequestHandler(), new MyOtherCustomRequestHandler)
.build();
```
## 非同期クライアントの作成
AWS SDK for Java には、すべてのサービス ( を除く) に非同期 (または非同期 Amazon S3) クライアントがあり、すべてのサービスに対応する非同期クライアントビルダーがあります。
### 非同期 DynamoDB クライアントをデフォルトの ExecutorService で作成するには
```
AmazonDynamoDBAsync ddbAsync = AmazonDynamoDBAsyncClientBuilder.standard()
.withRegion(Regions.US_WEST_2)
.withCredentials(new ProfileCredentialsProvider("myProfile"))
.build();
```
同期クライアントビルダーがサポートする構成オプションに加え、非同期クライアントでは、カスタム [ExecutorFactory](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/client/builder/ExecutorFactory.html) を設定して、非同期クライアントが使用する `ExecutorService` を変更することができます。`ExecutorFactory` は関数型インターフェイスであり、Java 8 ラムダ式表現およびメソッド参照とともに使用することができます。
### 非同期クライアントをカスタムエグゼキューターで作成するには
```
AmazonDynamoDBAsync ddbAsync = AmazonDynamoDBAsyncClientBuilder.standard()
.withExecutorFactory(() -> Executors.newFixedThreadPool(10))
.build();
```
## DefaultClient の使用
同期クライアントビルダーと非同期クライアントビルダーの両方に、`defaultClient` という名前の別のファクトリメソッドがあります。このメソッドは、デフォルトプロバイダチェーンを使用して認証情報と AWS リージョンをロードすることで、デフォルト構成を持つサービスクライアントを作成します。アプリケーションを実行している環境から認証情報またはリージョンが決定できない場合、`defaultClient` の呼び出しは失敗します。[AWS 認証情報とリージョンの決定方法の詳細については、「認証情報の使用](credentials.md)と[AWS リージョン 選択](java-dg-region-selection.md)」を参照してください。
### デフォルトサービスクライアントを作成するには
```
AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient();
```
## クライアントのライフサイクル
SDK のサービスクライアントはスレッドセーフであり、最大のパフォーマンスを得るには、存続期間の長いオブジェクトとしてこれらを処理する必要があります。各クライアントは独自の接続プールリソースを備えています。リソースリークを回避するために、不要になったときは明示的にクライアントをシャットダウンしてください。
明示的にクライアントをシャットダウンする場合は、`shutdown` メソッドを呼び出します。`shutdown` の呼び出し後は、すべてのクライアントリソースが解放され、クライアントが使用できなくなります。
### クライアントをシャットダウンするには
```
AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient();
ddb.shutdown();
// Client is now unusable
```
# に一時的な認証情報を提供する AWS SDK for Java
にリクエストを行うには Amazon Web Services、 が サービスを呼び出すときに AWS SDK for Java 使用する AWS 一時的な認証情報を指定する必要があります。これは以下の方法で対応できます。
+ デフォルトの認証情報プロバイダーチェーンを使用する *(推奨)*。
+ 特定の認証情報プロバイダーまたはプロバイダーチェーンを使用する (または独自のものを作成する)。
+ 一時的な認証情報はご自分でコードに入力してください。
## デフォルトの認証情報プロバイダチェーンの使用
引数を指定せずに新しいサービスクライアントを初期化すると、 は [DefaultAWSCredentialsProviderChain](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/DefaultAWSCredentialsProviderChain.html) クラスによって実装された*デフォルトの認証情報プロバイダーチェーンを使用して一時的な認証情報*を検索 AWS SDK for Java しようとします。デフォルトの認証情報プロバイダーチェーンは、次の順序で認証情報を検索します。
1. **環境変数** - `AWS_ACCESS_KEY_ID` `AWS_SECRET_KEY`、または`AWS_SECRET_ACCESS_KEY` および `AWS_SESSION_TOKEN`。 AWS SDK for Java は [EnvironmentVariableCredentialsProvider](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/EnvironmentVariableCredentialsProvider.html) クラスを使用してこれらの認証情報をロードします。
1. **Java システムプロパティ** - `aws.accessKeyId`、 `aws.secretKey` (ただし、 `aws.secretAccessKey` ではありません)、および `aws.sessionToken`。 AWS SDK for Java は [SystemPropertiesCredentialsProvider](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/SystemPropertiesCredentialsProvider.html) を使用してこれらの認証情報を読み込みます。
1. 環境またはコンテナからの**ウェブアイデンティティトークンの認証情報**。
1. **デフォルトの認証情報プロファイルファイル **- 通常、 に配置され `~/.aws/credentials` (場所はプラットフォームによって異なります）、多くの AWS SDKs と によって共有されます AWS CLI。 AWS SDK for Java は [ProfileCredentialsProvider](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/profile/ProfileCredentialsProvider.html) を使用してこれらの認証情報をロードします。
が提供する `aws configure` コマンドを使用して認証情報ファイルを作成することも AWS CLI、テキストエディタでファイルを編集して作成することもできます。認証情報ファイル形式に関する情報については、「[AWS Credentials File Format](#credentials-file-format)」を参照してください。
1. **Amazon ECS コンテナの認証情報** - 環境変数 `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` が設定されている場合に、Amazon ECS からロードされます。 AWS SDK for Java は [ContainerCredentialsProvider](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/ContainerCredentialsProvider.html) を使用してこれらの認証情報をロードします。この値の IP アドレスを指定できます。
1. **インスタンスプロファイル認証情報** - EC2 インスタンスで使用され、 Amazon EC2 メタデータサービスを介して配信されます。 AWS SDK for Java は [InstanceProfileCredentialsProvider](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/InstanceProfileCredentialsProvider.html) を使用してこれらの認証情報をロードします。この値の IP アドレスを指定できます。
**注記**
インスタンスプロファイル認証情報は、`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` が設定されていない場合にのみ使用されます。詳細については、「[EC2ContainerCredentialsProviderWrapper](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/EC2ContainerCredentialsProviderWrapper.html)」を参照してください。
### 一時的な認証情報の設定
AWS 一時的な認証情報を使用するには、前述の場所*の少なくとも 1* つに設定する必要があります。認証情報の設定の詳細については、以下のトピックを参照してください。
+ *環境*またはデフォルトの*認証情報プロファイルファイル*での認証情報の指定については、「[一時的な認証情報の設定](setup-credentials.md#setup-credentials-setting)」を参照してください。
+ Java *システムプロパティ*の設定については、公式の [Java Tutorials](http://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html) ウェブサイトにある「*System Properties*」チュートリアルを参照してください。
+ EC2 *インスタンスでインスタンスプロファイル認証情報*をセットアップして使用するには、[「IAM ロールを使用して の AWS リソースへのアクセスを許可する Amazon EC2](java-dg-roles.md)」を参照してください。
### 別の認証情報プロファイルの設定
はデフォルトで*デフォルトの*プロファイル AWS SDK for Java を使用しますが、認証情報ファイルから取得されるプロファイルをカスタマイズする方法があります。
AWS プロファイル環境変数を使用して、SDK によってロードされたプロファイルを変更できます。
例えば、Linux、macOS、または Unix の場合は、次のコマンドを実行してプロファイルを *myProfile* に変更します。
```
export AWS_PROFILE="myProfile"
```
Windows の場合は次のコマンドを使用します。
```
set AWS_PROFILE="myProfile"
```
`AWS_PROFILE` 環境変数を設定すると、正式にサポートされているすべての AWS SDKsとツール ( AWS CLI と を含む AWS Tools for Windows PowerShell) の認証情報のロードに影響します。Java アプリケーションのプロファイルだけを変更する場合は、代わりにシステムプロパティ `aws.profile` を使用できます。
**注記**
環境変数はシステムプロパティより優先されます。
### 別の認証情報ファイルの場所を設定する
は、デフォルトの認証情報ファイルの場所から AWS 一時的な認証情報を自動的に AWS SDK for Java ロードします。ただし、認証情報ファイルへのフルパスを使用して `AWS_CREDENTIAL_PROFILES_FILE` 環境変数を設定することで、場所を指定することもできます。
この機能を使用して、 が認証情報ファイル AWS SDK for Java を検索する場所を一時的に変更できます (たとえば、この変数をコマンドラインで設定するなど）。または、ユーザー環境やシステム環境で環境変数を設定して、ユーザーやシステム全体に対して変数を変更できます。
#### 認証情報ファイルのデフォルトの場所を上書きするには
+ `AWS_CREDENTIAL_PROFILES_FILE` 環境変数を AWS 認証情報ファイルの場所に設定します。
+ Linux、macOS、または Unix では、次を使用します。
```
export AWS_CREDENTIAL_PROFILES_FILE=path/to/credentials_file
```
+ Windows では、次を使用します。
```
set AWS_CREDENTIAL_PROFILES_FILE=path/to/credentials_file
```
### `Credentials` ファイル形式
このガイドの[基本設定の指示](signup-create-iam-user.md#setup-temp-creds)に従うと、認証情報ファイルは次の基本形式になります。
```
[default]
aws_access_key_id=
aws_secret_access_key=
aws_session_token=
[profile2]
aws_access_key_id=
aws_secret_access_key=
aws_session_token=
```
プロファイル名では角括弧 (例: `[default]`) に続いて、キーと値のペアとして、そのプロファイルの設定可能なフィールドを指定します。`credentials` ファイルで複数のプロファイルを持つことができ、それらは `aws configure --profile PROFILE_NAME ` を使用して設定するプロファイルを選択することで追加または編集できます。
`metadata_service_timeout`、`metadata_service_num_attempts` などの追加のフィールドを指定できます。これらは、CLI で設定可能ではなく、使用する場合は手動でファイルを編集する必要があります。設定ファイルとその使用可能なフィールドの詳細については、 AWS Command Line Interface ユーザーガイドの[「 の設定 AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)」を参照してください。
### 認証情報の読み込み
一時的な認証情報を設定した後は、SDK はデフォルトの認証情報プロバイダーチェーンを使用してその認証情報をロードします。
これを行うには、次のように、ビルダーに認証情報を明示的に提供せずに AWS のサービス クライアントをインスタンス化します。
```
AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
.withRegion(Regions.US_WEST_2)
.build();
```
## 認証情報プロバイダーまたはプロバイダーチェーンの指定
クライアントビルダーを使用して、*デフォルト*の認証情報プロバイダーチェーンとは異なる認証情報プロバイダーを指定できます。
[AWSCredentialsProvider](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/AWSCredentialsProvider.html) インターフェイスを入力として受け取るクライアントビルダーに、認証情報プロバイダーまたはプロバイダーチェーンのインスタンスを指定します。以下の例は、*環境*認証情報を具体的に使用する方法を示しています。
```
AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
.withCredentials(new EnvironmentVariableCredentialsProvider())
.build();
```
AWS SDK for Java提供された認証情報プロバイダーとプロバイダーチェーンの完全なリストについては、[AWSCredentialsProvider](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/AWSCredentialsProvider.html) **のすべての既知の実装クラス**」を参照してください。
**注記**
この手法を使用して、`AWSCredentialsProvider` インターフェイスを実装する独自の認証情報プロバイダーを使用するか、[AWSCredentialsProviderChain](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/AWSCredentialsProviderChain.html) クラスをサブクラス化して、作成する認証情報プロバイダーまたはプロバイダーチェーンを指定できます。
## 一時的な認証情報を明示的に指定する
デフォルトの認証情報チェーンまたは特定あるいはカスタムのプロバイダーやプロバイダーチェーンがコードに対して機能しない場合は、明示的に指定する認証情報を設定できます。を使用して一時的な認証情報を取得した場合は AWS STS、この方法を使用して AWS アクセス用の認証情報を指定します。
1. [BasicSessionCredentials](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/BasicSessionCredentials.html) クラスをインスタンス化し、SDK が接続に使用するアクセスキー、 AWS シークレットキー、および AWS セッショントークンを提供します AWS 。
1. [ オブジェクトを使用して ](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/AWSStaticCredentialsProvider.html)AWSStaticCredentialsProvider`AWSCredentials` を作成します。
1. `AWSStaticCredentialsProvider` を使用してクライアントビルダーを設定し、クライアントをビルドします。
以下に例を示します。
```
BasicSessionCredentials awsCreds = new BasicSessionCredentials("access_key_id", "secret_key_id", "session_token");
AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
.withCredentials(new AWSStaticCredentialsProvider(awsCreds))
.build();
```
## 詳細情報
+ [にサインアップ AWS して IAM ユーザーを作成する](signup-create-iam-user.md)
+ [開発用の AWS 認証情報とリージョンを設定する](setup-credentials.md)
+ [IAM ロールを使用して の AWS リソースへのアクセスを許可する Amazon EC2](java-dg-roles.md)
# AWS リージョン 選択
リージョンを使用すると、特定の地域に物理的に存在する AWS サービスにアクセスできます。これは、冗長性と、ユーザーがアクセスする場所の近くでのデータとアプリケーションの実行を維持するために有効です。
## リージョンでのサービス可用性の確認
特定の AWS のサービス がリージョンで使用できるかどうかを確認するには、使用するリージョンで `isServiceSupported`メソッドを使用します。
```
Region.getRegion(Regions.US_WEST_2)
.isServiceSupported(AmazonDynamoDB.ENDPOINT_PREFIX);
```
指定できるリージョンに関しては、「[Regions](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/regions/Regions.html)」クラスのドキュメントを参照して、サービスのエンドポイントプレフィックスを使用してクエリを実行します。各サービスのエンドポイントプレフィックスはサービスインターフェイスで定義されています。たとえば、 DynamoDB エンドポイントプレフィックスは [AmazonDynamoDB](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/AmazonDynamoDB.html) で定義されます。
## リージョンを選択する
のバージョン 1.4 以降では AWS SDK for Java、リージョン名を指定でき、SDK は自動的に適切なエンドポイントを選択します。自分でエンドポイントを選択する場合は、「[特定のエンドポイントの選択](#region-selection-choose-endpoint)」を参照してください。
リージョンを明示的に設定するには、「[Regions](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/regions/Regions.html)」列挙型を使用することをお勧めします。これは、公開されている利用可能なすべてのリージョンを列挙したものです。その列挙型からリージョンを使用してクライアントを作成するには、以下のコードを使用します。
```
AmazonEC2 ec2 = AmazonEC2ClientBuilder.standard()
.withRegion(Regions.US_WEST_2)
.build();
```
使用するリージョンが `Regions` 列挙型にない場合は、リージョンの名前を示す *string* を使用してリージョンを設定できます。
```
AmazonEC2 ec2 = AmazonEC2ClientBuilder.standard()
.withRegion("{region_api_default}")
.build();
```
**注記**
ビルダーを使用してクライアントをビルドした後、そのクライアントは*イミュータブル*となり、リージョンは*変更不可能*です。同じサービス AWS リージョン で複数の を使用している場合は、リージョンごとに 1 つずつ、複数のクライアントを作成する必要があります。
## 特定のエンドポイントの選択
各 AWS クライアントは、クライアントの作成時に `withEndpointConfiguration`メソッドを呼び出すことで、リージョン内の*特定のエンドポイント*を使用するように設定できます。
たとえば、欧州 (アイルランド) リージョンを使用するように Amazon S3 クライアントを設定するには、次のコードを使用します。
```
AmazonS3 s3 = AmazonS3ClientBuilder.standard()
.withEndpointConfiguration(new EndpointConfiguration(
"https://s3.eu-west-1.amazonaws.com",
"eu-west-1"))
.withCredentials(CREDENTIALS_PROVIDER)
.build();
```
すべての AWS サービスの[リージョンと対応するエンドポイントの現在のリストについては、](https://docs.aws.amazon.com/general/latest/gr/rande.html)「リージョンとエンドポイント」を参照してください。
## 環境に基づくリージョンの自動的な決定
**重要**
このセクションは、[クライアントビルダー](creating-clients.md)を使用して AWS services. AWS clients にアクセスする場合にのみ適用されます。クライアントコンストラクタを使用して作成されたクライアントは、環境からリージョンを自動的に決定せず、代わりに*デフォルトの* SDK リージョン (USEast1) を使用します。
Amazon EC2 または Lambda で実行する場合、コードが実行されているリージョンと同じリージョンを使用するようにクライアントを設定することもできます。そうすることによって、コードとそれが実行される環境が分離され、レイテンシーの低減や冗長化のために複数のリージョンにデプロイすることが容易になります。
*コードが実行されているリージョンを SDK で自動的に検出するには、クライアントビルダーを使用する必要があります。*
認証情報/リージョンのデフォルトプロバイダーチェーンを使用して環境からリージョンを決定するには、クライアントビルダーの `defaultClient` メソッドを使用します。
```
AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
```
これは、`standard` に続けて `build` を使用するのと同じです。
```
AmazonEC2 ec2 = AmazonEC2ClientBuilder.standard()
.build();
```
`withRegion` メソッドを使用してリージョンを明示的に設定しない場合は、SDK がリージョンのデフォルトプロバイダーチェーンに問い合わせて、使用するリージョンを決定しようとします。
### デフォルトリージョンプロバイダーチェーン
**リージョンルックアップ手順は以下のとおりです。**
1. ビルダー自体で `withRegion` または `setRegion` を使用して設定されている明示的なリージョンは、その他の設定より優先されます。
1. `AWS_REGION` 環境変数が確認されます。設定されている場合は、そのリージョンを使用してクライアントが設定されます。
**注記**
この環境変数は Lambda コンテナによって設定されます。
1. SDK は、 AWS 共有設定ファイル (通常は にあります`~/.aws/config`) をチェックします。*リージョン*プロパティがあると、SDK はこのプロパティを使用します。
+ `AWS_CONFIG_FILE` 環境変数を使用すると、共有設定ファイルの場所をカスタマイズできます。
+ `AWS_PROFILE` 環境変数または `aws.profile` システムプロパティを使用すると、SDK によってロードされるプロファイルをカスタマイズできます。
1. SDK は、 Amazon EC2 インスタンスメタデータサービスを使用して、現在実行中の Amazon EC2 インスタンスのリージョンを決定しようとします。
1. この時点で SDK によってリージョンがまだ見つかっていない場合は、クライアント作成が失敗し、例外が発生します。
AWS アプリケーションを開発する場合の一般的なアプローチは、*共有設定ファイル* ([デフォルトの認証情報プロバイダーチェーンの使用で説明) ](credentials.md#credentials-default)を使用してローカル開発用のリージョンを設定し、 AWS インフラストラクチャで実行するときにデフォルトのリージョンプロバイダーチェーンに依存してリージョンを決定することです。これによって、クライアントの作成が大幅に簡略化され、アプリケーションの性が維持されます。
# 例外処理
が例外を AWS SDK for Java スローする方法とタイミングを理解することは、 SDK を使用して高品質のアプリケーションを構築する上で重要です。以下のセクションでは、SDK によってスローされる例外のさまざまなケース、および例外の適切な処理方法について説明します。
## 非チェック例外を使用する理由
は、次の理由により、チェック例外の代わりにランタイム (または未チェック) 例外 AWS SDK for Java を使用します。
+ 懸念がない場合には例外ケースの処理を強制的に適用せずに (さらにコードを冗長にすることなく)、開発者がエラーを細かく制御できるようにするため。
+ サイズの大きいアプリケーションで、チェック例外に関連する拡張性の問題が発生するのを防ぐため。
一般的に、チェック例外は小規模なアプリケーションでは役立ちますが、アプリケーションのサイズが大きくなり、複雑化すると、チェック例外が問題となる場合があります。
チェック例外と非チェック例外の使用方法の詳細については、以下を参照してください。
+ [非チェック例外に関する論争](http://docs.oracle.com/javase/tutorial/essential/exceptions/runtime.html)
+ [チェック例外に関連する問題点](http://www.artima.com/intv/handcuffs2.html)
+ [Java のチェック例外の誤り (およびその対処方法)](http://radio-weblogs.com/0122027/stories/2003/04/01/JavasCheckedExceptionsWereAMistake.html)
## AmazonServiceException (およびサブクラス)
[AmazonServiceException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/AmazonServiceException.html) は、 AWS SDK for Javaを使用する場合に最も多く発生する例外です。この例外は、 AWS のサービスからのエラーレスポンスを表します。たとえば、存在しない Amazon EC2 インスタンスを終了しようとすると、EC2 はエラーレスポンスを返し、そのエラーレスポンスのすべての詳細がスロー`AmazonServiceException`される に含まれます。場合によっては、`AmazonServiceException` のサブクラスがスローされ、開発者は catch ブロックを使用して、エラーケースの処理を細かく制御できるようになります。
が発生すると`AmazonServiceException`、リクエストは に正常に送信されました AWS のサービス が、正常に処理できなかったことがわかります。これは、リクエストのパラメータに含まれるエラーまたはサービス側の問題が原因です。
`AmazonServiceException` では次のような情報がわかります。
+ 返された HTTP ステータスコード
+ 返された AWS エラーコード
+ サービスからの詳細なエラーメッセージ
+ AWS 失敗したリクエストのリクエスト ID
`AmazonServiceException` には、失敗したリクエストが発信者の障害 (不正な値を含むリクエスト) であるか、 AWS のサービスの障害 (内部サービスエラー) であるかに関する情報も含まれています。
## AmazonClientException
[AmazonClientException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/AmazonClientException.html) は、 へのリクエストの送信中またはレスポンスの解析 AWS 中に、Java クライアントコード内で問題が発生したことを示します AWS。`AmazonClientException` は通常、 よりも深刻であり`AmazonServiceException`、クライアントが のサービス呼び出しを実行できない大きな問題を示します AWS 。たとえば、いずれかのクライアントで オペレーションを呼び出そうとすると、ネットワーク接続が利用`AmazonClientException`できない場合、 は を AWS SDK for Java スローします。
# 非同期プログラミング
*同期*メソッドまたは*非同期*メソッドを使用して、 AWS サービスのオペレーションを呼び出すことができます。同期メソッドは、クライアントがサービスからのレスポンスを受信するまでスレッドの実行をブロックします。非同期メソッドはすぐに応答を返し、レスポンスを待機せずに呼び出しスレッドに制御を戻します。
非同期メソッドはレスポンスが可能になる前に応答を返すため、準備ができたらレスポンスを得るための手段が必要になります。 AWS SDK for Java には、*将来のオブジェクト*と*コールバックメソッド*の 2 つの方法があります。
## Java Future
の非同期メソッドは、*将来の*非同期オペレーションの結果を含む [Future](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/concurrent/Future.html) オブジェクト AWS SDK for Java を返します。
`Future` `isDone()` メソッドを呼び出し、サービスが既に応答オブジェクトを提供したかどうかを確認します。レスポンスの準備が整うと、`Future` `get()` メソッドを呼び出して応答オブジェクトを取得できます。このメカニズムを使用して、アプリケーションで他の動作を続行しながら、定期的に非同期オペレーションの結果をポーリングすることができます。
[InvokeResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/model/InvokeResult.html) オブジェクトを保持`Future`できる を受け取る Lambda 関数を呼び出す非同期オペレーションの例を次に示します。`InvokeResult` オブジェクトは、`isDone()` が `true` になった後に限り取得されます。
```
import com.amazonaws.services.lambda.AWSLambdaAsyncClient;
import com.amazonaws.services.lambda.model.InvokeRequest;
import com.amazonaws.services.lambda.model.InvokeResult;
import java.nio.ByteBuffer;
import java.util.concurrent.Future;
import java.util.concurrent.ExecutionException;
public class InvokeLambdaFunctionAsync
{
public static void main(String[] args)
{
String function_name = "HelloFunction";
String function_input = "{\"who\":\"SDK for Java\"}";
AWSLambdaAsync lambda = AWSLambdaAsyncClientBuilder.defaultClient();
InvokeRequest req = new InvokeRequest()
.withFunctionName(function_name)
.withPayload(ByteBuffer.wrap(function_input.getBytes()));
Future future_res = lambda.invokeAsync(req);
System.out.print("Waiting for future");
while (future_res.isDone() == false) {
System.out.print(".");
try {
Thread.sleep(1000);
}
catch (InterruptedException e) {
System.err.println("\nThread.sleep() was interrupted!");
System.exit(1);
}
}
try {
InvokeResult res = future_res.get();
if (res.getStatusCode() == 200) {
System.out.println("\nLambda function returned:");
ByteBuffer response_payload = res.getPayload();
System.out.println(new String(response_payload.array()));
}
else {
System.out.format("Received a non-OK response from {AWS}: %d\n",
res.getStatusCode());
}
}
catch (InterruptedException | ExecutionException e) {
System.err.println(e.getMessage());
System.exit(1);
}
System.exit(0);
}
}
```
## 非同期コールバック
Java `Future` オブジェクトを使用して非同期リクエストのステータスをモニタリングすることに加え、SDK には [AsyncHandler](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/handlers/AsyncHandler.html) インターフェイスを使用するクラスを実装することができます。`AsyncHandler` では、リクエストがどのように完了したかに応じて呼び出される 2 つのメソッド、`onSuccess` および `onError` が提供されます。
コールバックインターフェイスアプローチの主な利点は、リクエストがいつ完了したかを調べるために `Future` オブジェクトをポーリングする必要がなくなることです。コードによってすぐに次のアクティビティを開始でき、また SDK に依存してハンドラを適時に呼び出すことができます。
```
import com.amazonaws.services.lambda.AWSLambdaAsync;
import com.amazonaws.services.lambda.AWSLambdaAsyncClientBuilder;
import com.amazonaws.services.lambda.model.InvokeRequest;
import com.amazonaws.services.lambda.model.InvokeResult;
import com.amazonaws.handlers.AsyncHandler;
import java.nio.ByteBuffer;
import java.util.concurrent.Future;
public class InvokeLambdaFunctionCallback
{
private class AsyncLambdaHandler implements AsyncHandler
{
public void onSuccess(InvokeRequest req, InvokeResult res) {
System.out.println("\nLambda function returned:");
ByteBuffer response_payload = res.getPayload();
System.out.println(new String(response_payload.array()));
System.exit(0);
}
public void onError(Exception e) {
System.out.println(e.getMessage());
System.exit(1);
}
}
public static void main(String[] args)
{
String function_name = "HelloFunction";
String function_input = "{\"who\":\"SDK for Java\"}";
AWSLambdaAsync lambda = AWSLambdaAsyncClientBuilder.defaultClient();
InvokeRequest req = new InvokeRequest()
.withFunctionName(function_name)
.withPayload(ByteBuffer.wrap(function_input.getBytes()));
Future future_res = lambda.invokeAsync(req, new AsyncLambdaHandler());
System.out.print("Waiting for async callback");
while (!future_res.isDone() && !future_res.isCancelled()) {
// perform some other tasks...
try {
Thread.sleep(1000);
}
catch (InterruptedException e) {
System.err.println("Thread.sleep() was interrupted!");
System.exit(0);
}
System.out.print(".");
}
}
}
```
## ベストプラクティス
### コールバックの実行
`AsyncHandler` の実装は、非同期クライアントが所有するスレッドプール内で実行されます。素早く実行される短いコードが `AsyncHandler` 実装内で最も適しています。ハンドラメソッド内の長期実行コードまたはブロックコードにより、非同期クライアントが使用するスレッドプールの競合が起こり、クライアントのリクエスト実行が妨げられる場合があります。コールバックで始める必要がある長期実行タスクがある場合は、コールバックを新しいスレッドで、またはアプリケーションが管理するスレッドプールで実行します。
### スレッドプールの構成
の非同期クライアントは、ほとんどのアプリケーションで機能するデフォルトのスレッドプール AWS SDK for Java を提供します。カスタム [ExecutorService](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/concurrent/ExecutorService.html) を実装し、 AWS SDK for Java 非同期クライアントに渡して、スレッドプールの管理方法をより詳細に制御できます。
たとえば、カスタムの `ExecutorService`ThreadFactory[ を使用する ](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/concurrent/ThreadFactory.html) 実装を提供し、プールのスレッドの命名方法を制御したり、スレッドの使用に関する追加情報のログを記録したりできます。
### 非同期アクセス
SDK の [TransferManager](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/TransferManager.html) クラスは、 を操作するための非同期サポートを提供します Amazon S3。 は非同期アップロードとダウンロード`TransferManager`を管理し、転送に関する詳細な進行状況レポートを提供し、さまざまなイベントへのコールバックをサポートします。
# AWS SDK for Java 通話のログ記録
AWS SDK for Java には [Apache Commons Logging](http://commons.apache.org/proper/commons-logging/guide.html) が実装されています。これは、実行時に複数のロギングシステムのいずれかを使用できるようにする抽象化レイヤーです。
サポートされるログ記録システムには、Java ロギング フレームワークや Apache Log4j などがあります。このトピックでは Log4j の使用方法を示します。SDK のログ記録機能は、アプリケーションコードを変更せずに使用できます。
[Log4j](http://logging.apache.org/log4j/2.x/) の詳細については、[Apache ウェブサイト](http://www.apache.org/)を参照してください。
**注記**
このトピックでは、Log4j 1.x について説明します。Log4j2 は Apache Commons のログ記録を直接サポートしませんが、Apache Commons ログ記録インターフェイスを使用して Log4j2 にログ記録呼び出しを自動的にダイレクトするアダプターを提供します。詳細については、Log4j2 のドキュメントの「[Commons Logging Bridge](https://logging.apache.org/log4j/2.x/log4j-jcl.html)」を参照してください。
## Log4J JAR のダウンロード
SDK で Log4j を使用するには、Apache ウェブサイトで Log4j JAR をダウンロードする必要があります。SDK に JAR は含まれていません。クラスパス上の場所に JAR ファイルをコピーします。
Log4j では、設定ファイル log4j.properties を使用します。設定ファイルの例を次に示します。クラスパス上のディレクトリに、この設定ファイルをコピーします。Log4j JAR と log4j.properties ファイルは、同じディレクトリに配置しないでください。
log4j.properties 設定ファイルは、[ログ記録レベル](http://logging.apache.org/log4j/2.x/manual/configuration.html#Loggers)、ログ記録出力の送信先 (たとえば[ファイルやコンソール](http://logging.apache.org/log4j/2.x/manual/appenders.html))、[出力形式](http://logging.apache.org/log4j/2.x/manual/layouts.html)などのプロパティを指定します。ログ記録レベルは、ロガーによって生成される出力の詳細度です。Log4j では、複数のログ記録*階層*の概念をサポートしています。ログ記録レベルは、階層ごとに個別に設定されます。次の 2 つのログ記録階層が AWS SDK for Javaで使用できます。
+ log4j.logger.com.amazonaws
+ log4j.logger.org.apache.http.wire
## クラスパスの設定
Log4j JAR および log4j.properties ファイルは、クラスパス上に配置する必要があります。[Apache Ant](http://ant.apache.org/manual/) を使用している場合は、Ant ファイルの `path` 要素でクラスパスを設定します。以下の例では、SDK に含まれている Amazon S3 [サンプル](https://github.com/aws/aws-sdk-java/blob/master/src/samples/AmazonS3/build.xml)用の Ant ファイルにある path 要素を示します。
```
```
Eclipse IDE を使用している場合は、メニューを開き、[**Project (プロジェクト)**] \$1 [**Properties (プロパティ)**] \$1 [**Java Build Path**] に移動して、クラスパスを設定します。
## サービス固有のエラーと警告
クライアントライブラリからの重要なメッセージを取得するために、"com.amazonaws" ロガー階層は必ず "WARN" に設定しておくことをお勧めします。たとえば、アプリケーションが を適切に閉じておらず、リソースがリークしている`InputStream`可能性があることを Amazon S3 クライアントが検出した場合、S3 クライアントは警告メッセージを通じてログに報告します。これにより、リクエストやレスポンスの処理でクライアントに問題が発生した場合、メッセージが必ずログに記録されます。
次の log4j.properties ファイルでは、`rootLogger` が WARN に設定されています。これにより、"com.amazonaws" 階層のすべてのロガーで生成された警告とエラーメッセージが取り込まれます。また、com.amazonaws ロガーを WARN に明示的に設定することもできます。
```
log4j.rootLogger=WARN, A1
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
# Or you can explicitly enable WARN and ERROR messages for the {AWS} Java clients
log4j.logger.com.amazonaws=WARN
```
## リクエストおよびレスポンスの概要のログ記録
へのすべてのリクエストは一意の AWS リクエスト ID AWS のサービス を生成します。これは、 AWS のサービス がリクエストを処理する方法に問題がある場合に便利です。 AWS リクエスト IDsは、失敗したサービス呼び出しに対して SDK の例外オブジェクトを介してプログラムでアクセスでき、「com.amazonaws.request」ロガーの DEBUG ログレベルを介して報告することもできます。
次の log4j.properties ファイルは、リクエスト IDs を含む AWS リクエストとレスポンスの概要を有効にします。
```
log4j.rootLogger=WARN, A1
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
# Turn on DEBUG logging in com.amazonaws.request to log
# a summary of requests/responses with {AWS} request IDs
log4j.logger.com.amazonaws.request=DEBUG
```
ログ出力の例を次に示します。
```
2009-12-17 09:53:04,269 [main] DEBUG com.amazonaws.request - Sending
Request: POST https://rds.amazonaws.com / Parameters: (MaxRecords: 20,
Action: DescribeEngineDefaultParameters, SignatureMethod: HmacSHA256,
AWSAccessKeyId: ACCESSKEYID, Version: 2009-10-16, SignatureVersion: 2,
Engine: mysql5.1, Timestamp: 2009-12-17T17:53:04.267Z, Signature:
q963XH63Lcovl5Rr71APlzlye99rmWwT9DfuQaNznkD, ) 2009-12-17 09:53:04,464
[main] DEBUG com.amazonaws.request - Received successful response: 200, {AWS}
Request ID: 694d1242-cee0-c85e-f31f-5dab1ea18bc6 2009-12-17 09:53:04,469
[main] DEBUG com.amazonaws.request - Sending Request: POST
https://rds.amazonaws.com / Parameters: (ResetAllParameters: true, Action:
ResetDBParameterGroup, SignatureMethod: HmacSHA256, DBParameterGroupName:
java-integ-test-param-group-0000000000000, AWSAccessKeyId: ACCESSKEYID,
Version: 2009-10-16, SignatureVersion: 2, Timestamp:
2009-12-17T17:53:04.467Z, Signature:
9WcgfPwTobvLVcpyhbrdN7P7l3uH0oviYQ4yZ+TQjsQ=, )
2009-12-17 09:53:04,646 [main] DEBUG com.amazonaws.request - Received
successful response: 200, {AWS} Request ID:
694d1242-cee0-c85e-f31f-5dab1ea18bc6
```
## 詳細なワイヤログ記録
場合によっては、 が AWS SDK for Java 送受信する正確なリクエストとレスポンスを確認すると便利です。大規模なリクエスト (アップロード先のファイルなど Amazon S3) やレスポンスを書き出すと、アプリケーションが大幅に遅くなる可能性があるため、本番システムでこのログ記録を有効にしないでください。この情報にアクセスする必要がある場合は、Apache HttpClient 4 ロガーを使用して、一時的に有効にすることができます。`org.apache.http.wire` ロガーの DEBUG レベルを有効にすると、すべてのリクエストデータとレスポンスデータに対するログ記録が有効になります。
次の log4j.properties ファイルでは、Apache HttpClient 4 で完全なワイヤログ記録が有効になっていますが、アプリケーションのパフォーマンスに重大な影響が及ぶため、一時的にのみ有効にする必要があります。
```
log4j.rootLogger=WARN, A1
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
# Log all HTTP content (headers, parameters, content, etc) for
# all requests and responses. Use caution with this since it can
# be very expensive to log such verbose data!
log4j.logger.org.apache.http.wire=DEBUG
```
## レイテンシーメトリクスのログ記録
トラブルシューティングを行っていて、処理に最も時間がかかっているプロセスを示すメトリクスや、サーバー側またはクライアント側のどちらに大きなレイテンシーが発生しているかを示すメトリクスなどを確認する場合、レイテンシーロガーが役立ちます。このロガーを有効にするには、`com.amazonaws.latency` ロガーを DEBUG に設定します。
**注記**
このロガーは、SDK メトリクスが有効な場合のにみ使用できます。SDK メトリクスパッケージの詳細については、「[Enabling Metrics for the AWS SDK for Java](generating-sdk-metrics.md)」を参照してください。
```
log4j.rootLogger=WARN, A1
log4j.appender.A1=org.apache.log4j.ConsoleAppender
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
log4j.logger.com.amazonaws.latency=DEBUG
```
ログ出力の例を次に示します。
```
com.amazonaws.latency - ServiceName=[{S3}], StatusCode=[200],
ServiceEndpoint=[https://list-objects-integ-test-test.s3.amazonaws.com],
RequestType=[ListObjectsV2Request], AWSRequestID=[REQUESTID], HttpClientPoolPendingCount=0,
RetryCapacityConsumed=0, HttpClientPoolAvailableCount=0, RequestCount=1,
HttpClientPoolLeasedCount=0, ResponseProcessingTime=[52.154], ClientExecuteTime=[487.041],
HttpClientSendRequestTime=[192.931], HttpRequestTime=[431.652], RequestSigningTime=[0.357],
CredentialsRequestTime=[0.011, 0.001], HttpClientReceiveResponseTime=[146.272]
```
# クライアント設定
AWS SDK for Java を使用すると、デフォルトのクライアント設定を変更できます。これは、次の場合に便利です。
+ プロキシを使用したインターネットへの接続
+ HTTP トランスポートの設定 (接続タイムアウトやリクエスト再試行など) の変更
+ TCP ソケットバッファのサイズに関するヒントの指定
## プロキシ設定
クライアントオブジェクトを構築する場合、オプションの [ClientConfiguration](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/ClientConfiguration.html) オブジェクトを渡して、クライアントの設定をカスタマイズできます。
プロキシサーバーを使用してインターネットに接続する場合は、`ClientConfiguration` オブジェクトを使用して、プロキシサーバーの設定 (プロキシホスト、ポート、ユーザー名やパスワード) を指定する必要があります。
## HTTP トランスポートの設定
[ClientConfiguration](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/ClientConfiguration.html) オブジェクトを使用して、複数の HTTP トランスポートオプションを設定できます。新しいオプションが追加されることがあります。取得または設定できるオプションの完全なリストを確認するには、 AWS SDK for Java API リファレンスを参照してください。
**注記**
設定可能な各値には、定数によって定義されるデフォルト値があります。の定数値のリストについては`ClientConfiguration`、 AWS SDK for Java API リファレンスの[「定数フィールド値](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/constant-values.html)」を参照してください。
### 最大接続数
[ClientConfiguration.setMaxConnections](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/ClientConfiguration.html#setMaxConnections-int-) メソッドを使用して、開くことができる HTTP 接続の最大数を設定できます。
**重要**
同時トランザクション数に最大接続数を設定します。接続の競合およびパフォーマンスの低下を回避します。デフォルトの最大接続値については、 AWS SDK for Java API リファレンスの[「定数フィールド値](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/constant-values.html)」を参照してください。
### タイムアウトとエラー処理
HTTP 接続でのタイムアウトとエラー処理に関連するオプションを設定できます。
+ **接続タイムアウト**
接続タイムアウトは、接続を確立するまでに HTTP 接続が待機する時間 (ミリ秒単位) です。デフォルトは 10,000 ミリ秒です。
この値を自分で設定するには、[ClientConfiguration.setConnectionTimeout](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/ClientConfiguration.html#setConnectionTimeout-int-) メソッドを使用します。
+ **接続有効期限 (TTL)**
デフォルトで、SDK は HTTP 接続を可能な限り長い時間再利用しようとします。サービスが停止したサーバーに対して接続が確立される失敗の状況では、有限の TTL がアプリケーション復旧に役立つ場合があります。たとえば、15 分の TTL を設定すれば、問題が発生しているサーバーに対して接続が確立されていても、15 分以内に新しいサーバーに接続を再確立できます。
HTTP 接続の TTL を設定するには、[ClientConfiguration.setConnectionTTL](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/ClientConfiguration.html#setConnectionTTL-long-) メソッドを使用します。
+ **エラーの最大再試行回数**
デフォルトの再試行可能なエラーの最大再試行回数は 3 です。別の値を設定するには、[ClientConfiguration.setMaxErrorRetry](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/ClientConfiguration.html#setMaxErrorRetry-int-) メソッドを使用します。
### ローカルアドレス
HTTP クライアントのバインド先となるローカルアドレスを設定するには、[ClientConfiguration.setLocalAddress](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/ClientConfiguration.html#setLocalAddress-java.net.InetAddress-) を使用します。
## TCP ソケットバッファのサイズに関するヒント
低レベルの TCP パラメーターを調整する必要がある上級ユーザーは、[ClientConfiguration](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/ClientConfiguration.html) オブジェクトを使用して、TCP バッファサイズに関するヒントを追加で設定できます。ほとんどのユーザーはこれらの値を微調整する必要はありません。これらの値は上級ユーザー向けの値です。
アプリケーションに最適な TCP バッファサイズは、ネットワークやオペレーティングシステムの設定と機能に大きく依存します。たとえば、最新のオペレーティングシステムのほとんどでは、TCP バッファサイズを自動的にチューニングするロジックが組み込まれています。このロジックは TCP 接続のパフォーマンスに大きな影響を与える可能性があります。自動チューニングロジックでバッファサイズを最適化するために、TCP 接続を長い時間開いたままにしておくためです。
バッファサイズを大きくすると (2 MB など)、リモートサーバーでその情報の受信を確認しなくてもオペレーティングシステムでメモリにバッファできるデータが多くなるため、ネットワークのレイテンシーが高い場合に役立ちます。
これは*ヒント*のみです。そのヒントを採用するかどうかはオペレーティングシステムが決定します。このオプションを使用する場合、ユーザーはオペレーティングシステムで設定されている制限とデフォルト値を必ず確認する必要があります。ほとんどのオペレーティングシステムでは、最大 TCP バッファサイズの制限が設定されており、最大 TCP バッファサイズの制限を明示的に引き上げない限り、その制限を超えることはできません。
TCP バッファサイズおよびオペレーティングシステムに固有の TCP 設定を指定するために、次を含む多数のリソースが利用できます。
+ [ホストのチューニング](http://fasterdata.es.net/host-tuning/)
# アクセスコントロールポリシー
AWS *アクセスコントロールポリシー*を使用すると、 AWS リソースにきめ細かなアクセスコントロールを指定できます。アクセスコントロールポリシーは、次のフォームを持つ*ステートメント*のコレクションで構成されます。
*アカウント A* は、*アクション B* を*リソース C* に対して実行する権限があります (*条件 D* に該当する場合)。
コードの説明は以下のとおりです。
+ ** はプリン*シパル* - AWS リソースの 1 つへのアクセスまたは変更をリクエスト AWS アカウント している です。
+ *B* は*アクション* - Amazon SQS キューへのメッセージの送信や Amazon S3 バケットへのオブジェクトの保存など、 AWS リソースにアクセスまたは変更する方法。
+ *C* は*リソース* - Amazon SQS キューや保存されているオブジェクトなど、プリンシパルがアクセスする AWS エンティティ Amazon S3です。
+ *D* は*一連の条件* - プリンシパルがリソースにアクセスすることを許可または拒否するタイミングを指定するオプションの制約。さまざまな表記の条件を使用できます。条件によっては、サービスごとに固有な条件もあります。たとえば、日付条件を使用して、特定の時刻の前または後でのみリソースへのアクセスを許可することができます。
## Amazon S3 例
次の例は、バケット内のすべてのオブジェクトを読み取るアクセスをすべてのユーザーに許可するが、そのバケットへのオブジェクトのアップロードへのアクセスを (バケット所有者のアカウントに加えて) 2 AWS アカウントつの特定の に制限するポリシーを示しています。
```
Statement allowPublicReadStatement = new Statement(Effect.Allow)
.withPrincipals(Principal.AllUsers)
.withActions(S3Actions.GetObject)
.withResources(new S3ObjectResource(myBucketName, "*"));
Statement allowRestrictedWriteStatement = new Statement(Effect.Allow)
.withPrincipals(new Principal("123456789"), new Principal("876543210"))
.withActions(S3Actions.PutObject)
.withResources(new S3ObjectResource(myBucketName, "*"));
Policy policy = new Policy()
.withStatements(allowPublicReadStatement, allowRestrictedWriteStatement);
AmazonS3 s3 = AmazonS3ClientBuilder.defaultClient();
s3.setBucketPolicy(myBucketName, policy.toJson());
```
## Amazon SQS 例
ポリシーの一般的な用途の 1 つは、Amazon SNS トピックからメッセージを受信することを Amazon SQS キューに許可することです。
```
Policy policy = new Policy().withStatements(
new Statement(Effect.Allow)
.withPrincipals(Principal.AllUsers)
.withActions(SQSActions.SendMessage)
.withConditions(ConditionFactory.newSourceArnCondition(myTopicArn)));
Map queueAttributes = new HashMap();
queueAttributes.put(QueueAttributeName.Policy.toString(), policy.toJson());
AmazonSQS sqs = AmazonSQSClientBuilder.defaultClient();
sqs.setQueueAttributes(new SetQueueAttributesRequest(myQueueUrl, queueAttributes));
```
## Amazon SNS の例
一部のサービスには、ポリシーで使用できる追加条件があります。Amazon SNS は、トピックへのサブスクライブリクエストのプロトコル (E メール、HTTP、HTTPS など Amazon SQS) とエンドポイント (E メールアドレス、URL、 Amazon SQS ARN など) に基づいて、SNS トピックへのサブスクリプションを許可または拒否するための条件を提供します。
```
Condition endpointCondition =
SNSConditionFactory.newEndpointCondition("*@mycompany.com");
Policy policy = new Policy().withStatements(
new Statement(Effect.Allow)
.withPrincipals(Principal.AllUsers)
.withActions(SNSActions.Subscribe)
.withConditions(endpointCondition));
AmazonSNS sns = AmazonSNSClientBuilder.defaultClient();
sns.setTopicAttributes(
new SetTopicAttributesRequest(myTopicArn, "Policy", policy.toJson()));
```
# DNS 名参照用の JVM TTL を設定する
Java 仮想マシン (JVM) は DNS 名参照をキャッシュします。JVM がホスト名を IP アドレスに変換するとき、*time-to-live* (TTL) と呼ばれる指定期間 IP アドレスをキャッシュします。
AWS リソースは DNS 名エントリを使用するため、TTL 値を 5 秒に設定することをお勧めします。これにより、リソースの IP アドレスが変更されたときに、アプリケーションは DNS に対して再度クエリを実行することで、リソースの新しい IP アドレスを取得し、使用できるようになります。
一部の Java 設定では JVM のデフォルトの TTL が設定されるため、JVM が再起動されるまで、DNS エントリが更新されることは*ありません*。したがって、アプリケーションの実行中に AWS リソースの IP アドレスが変更された場合、JVM *を手動で再起動*し、キャッシュされた IP 情報が更新されるまで、そのリソースを使用することはできません。この場合、キャッシュされた IP 情報が定期的に更新されるように JVM の TTL を設定することが極めて重要です。
## JVM TTL を設定する方法
JVM の TTL を変更するには、[networkaddress.cache.ttl](https://docs.oracle.com/en/java/javase/17/core/java-networking.html#GUID-A680DADB-C4C1-40F1-B568-D9A97C917F5D) セキュリティプロパティ値を設定します。`networkaddress.cache.ttl` は*セキュリティプロパティ*であり、システムプロパティではありません。つまり、`-D`コマンドラインフラグで設定することはできません。
### オプション 1: アプリケーションでプログラムで設定する
AWS SDK クライアントが作成される前、およびネットワークリクエストが行われる前に、アプリケーション起動の[https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/security/Security.html](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/security/Security.html)早い段階で を呼び出します。
```
import java.security.Security;
public class MyApplication {
public static void main(String[] args) {
Security.setProperty("networkaddress.cache.ttl", "5");
// ... create SDK clients and run application
}
}
```
### オプション 2: java.security ファイルで設定する
Java 8 の場合は `$JAVA_HOME/jre/lib/security/java.security` ファイル、Java 11 以降の場合は `$JAVA_HOME/conf/security/java.security` ファイルで `networkaddress.cache.ttl`プロパティを設定します。
以下は、TTL キャッシュが 5 秒に設定された `java.security` ファイルからのスニペットです。
```
#
# The Java-level namelookup cache policy for successful lookups:
#
# any negative value: caching forever
# any positive value: the number of seconds to cache an address for
# zero: do not cache
#
...
networkaddress.cache.ttl=5
...
```
`$JAVA_HOME` 環境変数で表される JVM で実行されるすべてのアプリケーションは、この設定を使用します。
### オプション 3: JDK システムプロパティのフォールバックを使用する (コマンドライン)
セキュリティ設定またはコードを変更できない場合は、JDK システムプロパティを使用できます。セキュリティプロパティが定義されていない場合、これらはフォールバックとして機能します。
+ `sun.net.inetaddr.ttl` – 正常なルックアップを制御する (正の TTL)
+ `sun.net.inetaddr.negative.ttl` – 失敗したルックアップを制御する (負の TTL)
```
java -Dsun.net.inetaddr.ttl=5 -Dsun.net.inetaddr.negative.ttl=1 -jar myapp.jar
```
**注記**
これらは、[「Oracle Java 8 Networking Properties](https://docs.oracle.com/javase/8/docs/technotes/guides/net/properties.html) reference as private properties that " may not be supported in future releases」に記載されている JDK 内部プロパティです。可能な場合はオプション 1～2 を使用します。
# のメトリクスの有効化 AWS SDK for Java
は、以下を測定する [Amazon CloudWatch](https://aws.amazon.com/cloudwatch/) を使用して可視化とモニタリングのメトリクスを生成 AWS SDK for Java できます。
+ アクセス時のアプリケーションのパフォーマンス AWS
+ で使用した場合の JVMsのパフォーマンス AWS
+ ヒープメモリ、スレッド数、開かれたファイル記述子などのランタイム環境の詳細
## Java SDK メトリクス生成を有効にする方法
SDK が CloudWatch にメトリクスを送信できるようにするには、次の Maven 依存関係を追加する必要があります。
```
com.amazonaws
aws-java-sdk-bom
1.12.490*
pom
import
com.amazonaws
aws-java-sdk-cloudwatchmetrics
provided
```
\$1 バージョン番号を [Maven Central](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom) で入手可能な SDK の最新バージョンに置き換えてください。
AWS SDK for Java メトリクスは*デフォルトで無効*になっています。これをローカル開発環境で有効にするには、JVM の起動時に AWS セキュリティ認証情報ファイルをポイントするシステムプロパティを含めます。例:
```
-Dcom.amazonaws.sdk.enableDefaultMetrics=credentialFile=/path/aws.properties
```
後の分析用に SDK が収集されたデータポイントを CloudWatch にアップロードできるよう、認証情報ファイルへのパスを指定する必要があります。
**注記**
Amazon EC2 インスタンスメタデータサービスを使用して Amazon EC2 インスタンス AWS から にアクセスする場合は、認証情報ファイルを指定する必要はありません。この場合、指定する必要があるのは以下だけです。
```
-Dcom.amazonaws.sdk.enableDefaultMetrics
```
によってキャプチャされたすべてのメトリクス AWS SDK for Java は、**AWSSDK/Java **という名前空間にあり、CloudWatch のデフォルトリージョン (*us-east-1*) にアップロードされます。リージョンを変更するには、システムプロパティの `cloudwatchRegion` 属性を使用して指定します。例えば、CloudWatch リージョンを *us-east-1* に設定するには、次を使用します。
```
-Dcom.amazonaws.sdk.enableDefaultMetrics=credentialFile=/path/aws.properties,cloudwatchRegion={region_api_default}
```
この機能を有効にすると、 AWS から へのサービスリクエストがあるたびに AWS SDK for Java、メトリクスデータポイントが生成され、統計概要のためにキューに入れられ、約 1 分に 1 回 CloudWatch に非同期でアップロードされます。メトリクスがアップロードされたら、[AWS マネジメントコンソール](https://console.aws.amazon.com/console/home) を使用して可視化し、メモリリーク、ファイル記述子リークなどの潜在的な問題にアラームを設定できます。
## 利用可能なメトリクスのタイプ
デフォルトのメトリクスのセットは 3 つの主要なカテゴリに分かれています。
AWS リクエストメトリクス
+ HTTP リクエスト/応答のレイテンシー、リクエスト数、例外および再試行などのエリアを扱います。
![\[RequestMetric 131111\]](http://docs.aws.amazon.com/ja_jp/sdk-for-java/v1/developer-guide/images/RequestMetric-131111.png)
AWS のサービス メトリクス
+ S3 のアップロードとダウンロードのスループットやバイト数など、インクルード AWS のサービス固有のデータ。
![\[ServiceMetric 131111\]](http://docs.aws.amazon.com/ja_jp/sdk-for-java/v1/developer-guide/images/ServiceMetric-131111.png)
マシンメトリクス
+ ヒープメモリ、スレッド数、および開いているファイル記述子を含むランタイム環境を扱います。
![\[MachineMetric 131111\]](http://docs.aws.amazon.com/ja_jp/sdk-for-java/v1/developer-guide/images/MachineMetric-131111.png)
マシンメトリクスを除外する場合は、システムプロパティに `excludeMachineMetrics` を追加します。
```
-Dcom.amazonaws.sdk.enableDefaultMetrics=credentialFile=/path/aws.properties,excludeMachineMetrics
```
## 詳細情報
+ 事前定義されたコアメトリクスタイプの詳細な一覧については、[amazonaws/metrics package summary](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/metrics/package-summary.html) を参照してください。
+ を使用した CloudWatch の操作については、[「 を使用した CloudWatch の例 AWS SDK for Java](examples-cloudwatch.md) AWS SDK for Java 」を参照してください。
+ パフォーマンスチューニングの詳細については、[「 をチューニング AWS SDK for Java して耐障害性を向上させる](https://aws.amazon.com/blogs/developer/tuning-the-aws-sdk-for-java-to-improve-resiliency)」ブログ記事を参照してください。