適用於 Java 的 AWS SDK 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)，以繼續接收新功能、可用性改善和安全性更新。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 適用於 Java 的 AWS SDK
本節提供使用 進行程式設計的重要一般資訊 適用於 Java 的 AWS SDK ，適用於您可能搭配 SDK 使用的所有 服務。
如需服務特定的程式設計資訊和範例 （例如 Amazon S3 Amazon SWF等） Amazon EC2，請參閱[適用於 Java 的 AWS SDK 程式碼範例](prog-services.md)。
**Topics**
+ [使用 AWS 開發的最佳實務 適用於 Java 的 AWS SDK](best-practices.md)
+ [建立服務用戶端](creating-clients.md)
+ [提供臨時登入資料](credentials.md)
+ [AWS 區域 選擇](java-dg-region-selection.md)
+ [例外狀況處理](java-dg-exceptions.md)
+ [非同步程式設計](basics-async.md)
+ [記錄 適用於 Java 的 AWS SDK 通話](java-dg-logging.md)
+ [客戶端組態](section-client-configuration.md)
+ [存取控制政策](java-dg-access-control.md)
+ [設定 DNS 名稱查詢的 JVM TTL](jvm-ttl-dns.md)
+ [啟用 的指標 適用於 Java 的 AWS SDK](generating-sdk-metrics.md)
# 使用 AWS 開發的最佳實務 適用於 Java 的 AWS SDK
下列最佳實務可協助您在使用 開發 AWS 應用程式時避免問題或麻煩 適用於 Java 的 AWS SDK。我們已依服務組織最佳實務。
## S3
### 避免 ResetExceptions
當您 Amazon S3 使用串流 （透過 `AmazonS3`用戶端或 `TransferManager`) 將物件上傳至 時，您可能會遇到網路連線或逾時問題。根據預設， 適用於 Java 的 AWS SDK 嘗試重試失敗的傳輸，方法是在傳輸開始之前標記輸入串流，然後在重試之前重設它。
如果串流不支援標記和重設，當發生暫時性失敗並啟用重試時，開發套件會擲回 [ResetException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/ResetException.html)。
**最佳實務**
我們建議您使用支援標記和重設操作的串流。
避免 [ResetException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/ResetException.html) 的最可靠方法是使用 [檔案](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) 來提供資料， 適用於 Java 的 AWS SDK 可以處理這些資料，而不會受限於標記和重設限制。
如果串流不是 [FileInputStream](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/FileInputStream.html)，但確實支援標記和重設，您可以使用 [RequestClientOptions](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/RequestClientOptions.html) `setReadLimit`的方法設定標記限制。其預設值為 128 KB。將讀取限制值設定為*大於串流大小的一個位元組*，可以可靠地避免 [ResetException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/ResetException.html)。
例如，如果串流的預期大小上限為 100，000 個位元組，請將讀取限制設定為 100，001 (100，000 \$1 1) 個位元組。標記和重設一律適用於 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 中使用許多流暢的設定器來自訂用戶端的屬性。例如，您可以設定自訂區域和自訂登入資料提供者，如下所示。
```
AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.standard()
.withRegion(Regions.US_WEST_2)
.withCredentials(new ProfileCredentialsProvider("myProfile"))
.build();
```
**注意**
流暢`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) 的流暢設定器，以及 [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();
```
## 建立非同步用戶端
每個服務 適用於 Java 的 AWS SDK 都有非同步 （或非同步） 用戶端 ( 除外 Amazon S3)，每個服務都有對應的非同步用戶端建置器。
### 使用預設 ExecutorService 建立非同步 DynamoDB 用戶端
```
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 lambda 表達式和方法參考互通。
### 使用自訂執行器建立非同步用戶端
```
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();
```
## 用戶端生命週期
開發套件中的服務用戶端是執行緒安全的，為了獲得最佳效能，您應該將它們視為長期物件。每個用戶端都有自己的連線集區資源。當不再需要用戶端以避免資源洩漏時，請明確將其關閉。
若要明確關閉用戶端，請呼叫 `shutdown`方法。呼叫 後`shutdown`，會釋出所有用戶端資源，且用戶端無法使用。
### 關閉用戶端
```
AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient();
ddb.shutdown();
// Client is now unusable
```
# 提供臨時登入資料給 適用於 Java 的 AWS SDK
若要向 提出請求 Amazon Web Services，您必須提供 AWS 暫時性登入資料 適用於 Java 的 AWS SDK ，讓 在呼叫 服務時使用。您可採用以下方式：
+ 使用預設登入資料供應者鏈結 *(建議)*。
+ 使用特定的登入資料供應者或供應者鏈結 (或建立您自己的項目)。
+ 在程式碼中自行提供臨時登入資料。
## 使用預設登入資料供應商鏈結
當您初始化新的服務用戶端而不提供任何引數時， 適用於 Java 的 AWS SDK 會嘗試使用 [DefaultAWSCredentialsProviderChain](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/DefaultAWSCredentialsProviderChain.html) 類別實作*的預設登入資料提供者鏈結*來尋找臨時登入資料。預設登入資料供應者鏈結會依以下順序尋找登入資料：
1. **環境變數** -`AWS_ACCESS_KEY_ID`、 `AWS_SECRET_KEY`或 `AWS_SECRET_ACCESS_KEY`，以及 `AWS_SESSION_TOKEN`。 適用於 Java 的 AWS SDK 使用 [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`。 適用於 Java 的 AWS SDK 使用 [SystemPropertiesCredentialsProvider](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/SystemPropertiesCredentialsProvider.html) 載入這些登入資料。
1. 來自環境或容器的 **Web Identity Token 登入**資料。
1. **預設登入資料設定檔檔案 **- 通常位於 `~/.aws/credentials`（每個平台的位置可能有所不同），並由許多 AWS SDKs 和 共用 AWS CLI。 適用於 Java 的 AWS SDK 使用 [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)。
1. 如果已`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`設定環境變數，則從 Amazon ECS 載入的 Amazon ECS **容器憑證**。 適用於 Java 的 AWS SDK 使用 [ContainerCredentialsProvider](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/ContainerCredentialsProvider.html) 載入這些登入資料。您可以為此值指定 IP 地址。
1. **執行個體描述檔登入**資料 - 用於 EC2 執行個體，並透過 Amazon EC2 中繼資料服務傳遞。 適用於 Java 的 AWS SDK 使用 [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 臨時登入資料，它們必須至少設定在上述*其中一個*位置。如需設定登入資料的相關資訊，請參閱下列主題：
+ 若要在*環境*或預設登入資料*設定檔檔案中指定登入*資料，請參閱 [設定臨時登入資料](setup-credentials.md#setup-credentials-setting) 。
+ 若要設定 Java *系統屬性*，請參閱官方 [Java 教學課程](http://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html)網站的*系統屬性*教學課程。
+ 若要在 EC2 執行個體中設定和使用*執行個體描述檔登入*資料，請參閱[使用 IAM 角色授予 AWS 資源的存取權 Amazon EC2](java-dg-roles.md)。
### 設定替代登入資料設定檔
根據預設， 適用於 Java 的 AWS SDK 會使用*預設*的設定檔，但有方法可以自訂從登入資料檔案取得的設定檔。
您可以使用 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`改用 系統屬性。
**注意**
環境變數會優先於系統屬性。
### 設定替代登入資料檔案位置
會自動從預設登入資料檔案位置 適用於 Java 的 AWS SDK 載入 AWS 臨時登入資料。不過，您也可以設定 `AWS_CREDENTIAL_PROFILES_FILE` 環境變數搭配登入資料檔案的完整路徑，來指定位置。
您可以使用此功能暫時變更 適用於 Java 的 AWS SDK 尋找登入資料檔案的位置 （例如，使用命令列設定此變數）。或者，您也可以在使用者或系統環境中設定環境變數，來為該使用者進行變更或是進行全系統變更。
#### 若要覆寫預設登入資料檔案位置
+ 將`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) 。
### 載入登入資料
設定臨時登入資料後，開發套件會使用預設登入資料提供者鏈結載入它們。
若要這樣做，您可以執行個體化 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();
```
如需 適用於 Java 的 AWS SDK所提供登入資料提供者和提供者鏈的完整清單，請參閱 [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) 類別，並提供 AWS 開發套件用於連線的存取金鑰、 AWS 私密金鑰和 AWS 工作階段字符。
1. 使用 `AWSCredentials` 物件建立 [AWSStaticCredentialsProvider](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/AWSStaticCredentialsProvider.html)。
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);
```
請參閱您可以指定區域的[區域](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 版開始 適用於 Java 的 AWS SDK，您可以指定區域名稱，開發套件會自動為您選擇適當的端點。若要自行選擇端點，請參閱[選擇特定端點](#region-selection-choose-endpoint)。
若要明確設定區域，建議您使用[區域](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`列舉中，您可以使用代表區域名稱的*字串*來設定區域。
```
AmazonEC2 ec2 = AmazonEC2ClientBuilder.standard()
.withRegion("{region_api_default}")
.build();
```
**注意**
使用建置器建置用戶端後，這是*不可變的*，而且區域*無法變更*。如果您 AWS 區域 針對相同的服務使用多個 ，您應該建立多個用戶端，每個區域一個。
## 選擇特定端點
每個 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 建立的用戶端不會自動從環境判斷區域，而是使用*預設* SDK 區域 (USEast1)。
在 Amazon EC2 或 Lambda 上執行時，您可能想要將用戶端設定為使用與程式碼執行所在的相同區域。這會讓您的程式碼與其執行環境分離，也更容易將應用程式部署到多個區域，以降低延遲或提供備援。
*您必須使用用戶端建置器，讓 SDK 自動偵測您程式碼執行所在的區域。*
若要使用預設的登入資料/區域供應者鏈結來從環境判斷區域，請使用用戶端建置器的 `defaultClient` 方法。
```
AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
```
這與使用 `standard`後接 相同`build`。
```
AmazonEC2 ec2 = AmazonEC2ClientBuilder.standard()
.build();
```
如果您未使用 `withRegion`方法明確設定區域，軟體開發套件會諮詢預設區域提供者鏈結，以嘗試並判斷要使用的區域。
### 預設區域供應者鏈結
**以下是區域查詢程序：**
1. 在建置器本身上使用 `withRegion`或 `setRegion` 設定的任何明確區域優先於任何其他區域。
1. 檢查 `AWS_REGION` 環境變數。如果有設定，會使用該區域來設定用戶端。
**注意**
此環境變數由 Lambda 容器設定。
1. 軟體開發套件會檢查 AWS 共用組態檔案 （通常位於 `~/.aws/config`)。如果 *region* 屬性存在，開發套件會予以使用。
+ `AWS_CONFIG_FILE` 環境變數可用於自訂共用組態檔的位置。
+ `AWS_PROFILE` 環境變數或`aws.profile`系統屬性可用來自訂 SDK 載入的設定檔。
1. SDK 會嘗試使用 Amazon EC2 執行個體中繼資料服務來判斷目前執行中 Amazon EC2 執行個體的區域。
1. 如果開發套件在這個時候仍找不到區域，用戶端建立會失敗，並出現例外狀況。
開發 AWS 應用程式時，常見的方法是使用*共用組態檔案* （如[使用預設登入資料提供者鏈](credentials.md#credentials-default)中所述） 來設定本機開發的區域，並在 AWS 基礎設施上執行時依賴預設區域提供者鏈來判斷區域。這可大幅簡化用戶端建立並讓您的應用程式保持可攜式。
# 例外狀況處理
了解 適用於 Java 的 AWS SDK 拋出例外狀況的方式和時間，對於使用 SDK 建置高品質應用程式至關重要。以下章節說明開發套件會擲回的不同例外狀況案例，以及如何正確處理這些狀況。
## 為什麼使用未檢查的例外狀況？
由於這些原因， 適用於 Java 的 AWS SDK 使用執行時間 （或未核取） 例外狀況，而非核取的例外狀況：
+ 為了讓開發人員能夠更精確的控制他們想處理的錯誤，而非強制他們處理不在乎的例外情況 (因而使得程式碼過於冗長)
+ 為了避免大型應用程式中已檢查例外狀況的固有擴展性問題
一般而言，已檢查例外狀況在小規模上可運作良好，但會隨著應用程式增長且更複雜而變得棘手。
如需使用已勾選和未勾選例外狀況的詳細資訊，請參閱：
+ [未檢查的例外狀況 - 爭用](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) 是使用 時會遇到的最常見例外狀況 適用於 Java 的 AWS SDK。此例外狀況代表來自 的錯誤回應 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) 指出在嘗試傳送請求至 或嘗試剖析回應時，Java AWS 用戶端程式碼內發生問題 AWS。`AmazonClientException` 通常比 更嚴重`AmazonServiceException`，並指出導致用戶端無法對 AWS 服務進行服務呼叫的主要問題。例如，當您嘗試呼叫其中一個用戶端上的 操作時，`AmazonClientException`如果沒有可用的網路連線， 會 適用於 Java 的 AWS SDK 擲回 。
# 非同步程式設計
您可以使用*同步**或非同步*方法來呼叫 AWS 服務上的操作。同步方法會封鎖您的執行緒執行，直到用戶端收到服務的回應。非同步方法會立即傳回，將控制權回歸給呼叫端執行緒，無需等待回應。
由於非同步方法會在有可用回應之前傳回，您需要一個方法在回應準備好時取得回應。 適用於 Java 的 AWS SDK 提供兩種方式：*未來物件*和*回呼方法*。
## Java 未來
中的非同步方法會 適用於 Java 的 AWS SDK 傳回[未來](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/concurrent/Future.html)物件，其中包含*未來*非同步操作的結果。
呼叫 `Future``isDone()`方法，以查看服務是否已提供回應物件。當回應準備就緒時，您可以透過呼叫 `Future``get()`方法取得回應物件。您可以使用此機制定期輪詢非同步操作的結果，同時您的應用程式會繼續處理其他項目。
以下是呼叫 Lambda 函數的非同步操作範例，接收可以容納 [InvokeResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/model/InvokeResult.html) 物件`Future`的 。只有在 `isDone()`為 之後，才會擷取`InvokeResult`物件`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` 物件來監控非同步請求的狀態之外， 軟體開發套件還可讓您實作使用[AsyncHandler](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/handlers/AsyncHandler.html) 界面的類別。 `AsyncHandler`提供兩種呼叫方法，取決於請求的完成方式： `onSuccess`和 `onError`。
回呼界面方法的主要優點是讓您無需輪詢`Future`物件，即可了解請求何時完成。相反地，您的程式碼可以立即開始下一個活動，並依賴軟體開發套件在正確的時間呼叫您的處理常式。
```
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`實作。處理常式方法內的長時間執行或封鎖程式碼可能會導致非同步用戶端使用的執行緒集區發生爭用，並可防止用戶端執行請求。如果您有需要從回呼開始的長期執行任務，請讓回呼在新的執行緒或由應用程式管理的執行緒集區中執行其任務。
### 執行緒集區組態
中的非同步用戶端 適用於 Java 的 AWS SDK 提供預設執行緒集區，應適用於大多數應用程式。您可以實作自訂 [ExecutorService](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/concurrent/ExecutorService.html)，並將其傳遞給 適用於 Java 的 AWS SDK 非同步用戶端，以進一步控制執行緒集區的管理方式。
例如，您可以提供使用自訂 [ThreadFactory](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/concurrent/ThreadFactory.html) 來控制集區中執行緒命名方式的`ExecutorService`實作，或記錄有關執行緒用量的其他資訊。
### 非同步存取
開發套件中的 [TransferManager](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/TransferManager.html) 類別提供使用 的非同步支援 Amazon S3。 `TransferManager`管理非同步上傳和下載、提供有關傳輸的詳細進度報告，以及支援對不同事件的回呼。
# 記錄 適用於 Java 的 AWS SDK 通話
使用 [Apache Commons Logging](http://commons.apache.org/proper/commons-logging/guide.html) 進行 適用於 Java 的 AWS SDK 檢測，Apache Commons Logging 是一種抽象層，可在執行時間使用多個記錄系統中的任何一個。
支援的記錄系統包括 Java Logging Framework 和 Apache Log4j 等等。本主題說明如何使用 Log4j。您可以使用開發套件的記錄功能，而無需更改您的應用程式程式碼。
若要進一步了解 [Log4j](http://logging.apache.org/log4j/2.x/)，請參閱 [Apache 網站](http://www.apache.org/)。
**注意**
本主題著重於 Log4j 1.x。Log4j2 不直接支援 Apache Commons Logging，但提供轉接器，使用 Apache Commons Logging 界面將記錄呼叫自動導向 Log4j2。如需詳細資訊，請參閱 Log4j2 文件中的 [Commons Logging Bridge](https://logging.apache.org/log4j/2.x/log4j-jcl.html)。
## 下載 Log4J JAR
若要搭配 SDK 使用 Log4j，您需要從 Apache 網站下載 Log4j JAR。開發套件不包含 JAR。將 JAR 檔案複製到 classpath 上的位置。
Log4j 使用組態檔案 log4j.properties。範例組態檔案如下所示。將此組態檔案複製到 classpath 上的目錄。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 支援多個記錄*階層*的概念。每個階層的記錄層級都是獨立設定。以下兩個記錄階層可用於 適用於 Java 的 AWS SDK：
+ log4j.logger.com.amazonaws
+ log4j.logger.org.apache.http.wire
## 設定 Classpath
Log4j JAR 和 log4j.properties 檔案都必須位於 classpath 上。如果您使用的是 [Apache Ant](http://ant.apache.org/manual/)，請在 Ant 檔案中的 `path`元素中設定 classpath。下列範例顯示來自 Ant 檔案的路徑元素，適用於 Amazon S3 軟體開發套件隨附的[範例](https://github.com/aws/aws-sdk-java/blob/master/src/samples/AmazonS3/build.xml)。
```
```
如果您是使用 Eclipse IDE，可以開啟選單並導覽到 **Project (專案)** \$1 **Properties (屬性)** \$1 **Java Build Path (Java 建置路徑)** 來設定 classpath。
## 服務特定錯誤與警告
我們建議您一律將 "com.amazonaws" 記錄器階層設定為 "WARN"，以從用戶端程式庫擷取任何重要訊息。例如，如果 Amazon S3 用戶端偵測到您的應用程式未正確關閉 `InputStream`並可能洩漏資源，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 請求的問題，對 的每個請求都會 AWS 服務 產生唯一的 AWS 服務 請求 ID。對於任何失敗的服務呼叫，可以透過 SDK 中的例外物件以程式設計方式存取 AWS 請求 IDs，也可以透過 "com.amazonaws.request" 記錄器中的 DEBUG 日誌層級進行報告。
下列 log4j.properties 檔案可啟用請求和回應的摘要，包括 AWS 請求 IDs。
```
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
```
## 詳細連線記錄
在某些情況下，查看 適用於 Java 的 AWS SDK 傳送和接收的確切請求和回應會很有用。您不應該在生產系統中啟用此記錄，因為寫入大型請求 （例如，上傳到的檔案 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 指標套件，請參閱[啟用 的指標 適用於 Java 的 AWS SDK](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]
```
# 客戶端組態
適用於 Java 的 AWS SDK 可讓您變更預設用戶端組態，當您想要：
+ 透過代理連線到網際網路
+ 變更 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 傳輸選項。系統偶爾會新增新選項；若要查看您可以擷取或設定的完整選項清單，請參閱 適用於 Java 的 AWS SDK API 參考。
**注意**
每個可設定的值都有一個由常數定義的預設值。如需 的恆定值清單`ClientConfiguration`，請參閱 適用於 Java 的 AWS SDK 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 連線數目上限。
**重要**
設定連線數上限到並行交易，避免連線失敗和效能不佳。如需預設的最大連線值，請參閱 適用於 Java 的 AWS SDK 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)**
根據預設，軟體開發套件會盡可能嘗試重複使用 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 Socket 緩衝區大小提示
想要調整低階 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* 具有許可，可在*條件 D* 適用的*資源 C* 上執行*動作 B*。
其中：
+ 是*委託人* **- 正在請求存取或修改其中一個 AWS 資源 AWS 帳戶 的 。
+ *B* 是*動作* - 存取或修改 AWS 資源的方式，例如傳送訊息至 Amazon SQS 佇列，或將物件存放在 Amazon S3 儲存貯體中。
+ *C* 是*資源* - 委託人想要存取的 AWS 實體，例如 Amazon SQS 佇列或存放於其中的物件 Amazon S3。
+ *D* 是*一組條件* - 選擇性限制，指定何時允許或拒絕委託人存取您的資源。有許多表達式條件可供使用，有些是針對每個服務。例如，您可以使用日期條件，僅允許在特定時間之後或之前存取您的資源。
## Amazon S3 範例
下列範例示範一個政策，允許任何人讀取儲存貯體中的所有物件，但限制將物件上傳至該儲存貯體的存取權為兩個特定的 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 範例
政策的一個常見用途是授權 Amazon SQS 佇列接收來自 Amazon SNS 主題的訊息。
```
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 提供條件，允許或拒絕根據訂閱主題之請求的通訊協定 （例如電子郵件、HTTP、HTTPS Amazon SQS) 和端點 （例如電子郵件地址、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 位址時，它會在指定的時間段內快取 IP 位址，稱為*存留時間* (TTL)。
由於 AWS 資源使用偶爾變更的 DNS 名稱項目，我們建議您將 JVM 設定為 5 秒的 TTL 值。這可確保當資源的 IP 位址變更時，您的應用程式將可透過重新查詢 DNS 來接收並使用資源的新 IP 位址。
在一些 Java 組態上，JVM 的預設 TTL 會如此設定，在重新啟動 JVM 之前，「絕不」**重新整理 DNS 項目。因此，如果 AWS 資源的 IP 地址在應用程式仍在執行時變更，在您*手動重新啟動* JVM 並重新整理快取的 IP 資訊之前，將無法使用該資源。在此情況下，設定 JVM 的 TTL 至為關鍵，以便其定期重新整理快取的 IP 資訊。
## 如何設定 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：在應用程式中以程式設計方式設定
在應用程式啟動的[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)早期、建立任何 AWS SDK 用戶端之前，以及提出任何網路請求之前呼叫 ：
```
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` 檔案中設定 `networkaddress.cache.ttl` 屬性，或在 Java 11 或更新版本的 `$JAVA_HOME/conf/security/java.security`檔案中設定 屬性。
以下是 檔案的程式碼片段`java.security`，顯示 TTL 快取設定為 5 秒。
```
#
# 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 網路屬性](https://docs.oracle.com/javase/8/docs/technotes/guides/net/properties.html)參考中記載的 JDK 內部屬性，做為「未來版本可能不支援」的私有屬性。盡可能使用選項 1-2。
# 啟用 的指標 適用於 Java 的 AWS SDK
適用於 Java 的 AWS SDK 可以使用 [Amazon CloudWatch](https://aws.amazon.com/cloudwatch/) 產生視覺化和監控的指標，以測量：
+ 存取應用程式的效能 AWS
+ 搭配 使用時，JVMs的效能 AWS
+ 執行時間環境詳細資訊，例如堆積記憶體、執行緒數目和開啟的檔案描述項
## 如何啟用 Java SDK 指標產生
您需要新增下列 Maven 相依性，才能讓 SDK 將指標傳送至 CloudWatch。
```
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。
適用於 Java 的 AWS SDK 指標*預設為停用*。若要為本機開發環境啟用此功能，請在啟動 JVM 時包含指向 AWS 安全登入資料檔案的系統屬性。例如：
```
-Dcom.amazonaws.sdk.enableDefaultMetrics=credentialFile=/path/aws.properties
```
您需要指定登入資料檔案的路徑，讓 SDK 可以將收集的資料點上傳到 CloudWatch 以供日後分析。
**注意**
如果您使用 Amazon EC2 執行個體中繼資料服務 AWS 從 Amazon EC2 執行個體存取 ，則不需要指定登入資料檔案。在這種情況下，您只需指定：
```
-Dcom.amazonaws.sdk.enableDefaultMetrics
```
擷取的所有指標 適用於 Java 的 AWS SDK 都位於命名空間 **AWSSDK/Java** 下，並上傳至 CloudWatch 預設區域 (*us-east-1*)。若要變更區域，請使用系統屬性中的 `cloudwatchRegion` 屬性來指定區域。例如，若要將 CloudWatch 區域設定為 *us-east-1*，請使用：
```
-Dcom.amazonaws.sdk.enableDefaultMetrics=credentialFile=/path/aws.properties,cloudwatchRegion={region_api_default}
```
啟用此功能後，每次 AWS 有來自 的服務請求時 適用於 Java 的 AWS SDK，都會產生指標資料點、排入統計摘要佇列，並以非同步方式上傳至 CloudWatch，大約每分鐘一次。上傳指標後，您可以使用 將其視覺化，[AWS 管理主控台](https://console.aws.amazon.com/console/home)並針對記憶體洩漏、檔案描述項洩漏等潛在問題設定警示。
## 可用的指標類型
預設指標集分為三個主要類別：
AWS 請求指標
+ 涵蓋 HTTP 請求/回應的延遲、請求數量、例外狀況和重試等領域。
![\[RequestMetric 131111\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/v1/developer-guide/images/RequestMetric-131111.png)
AWS 服務 指標
+ 包含 AWS 服務特定資料，例如 S3 上傳和下載的輸送量和位元組數。
![\[ServiceMetric 131111\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/v1/developer-guide/images/ServiceMetric-131111.png)
機器指標
+ 涵蓋執行時間環境，包括堆積記憶體、執行緒數目和開啟的檔案描述項。
![\[MachineMetric 131111\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/v1/developer-guide/images/MachineMetric-131111.png)
如果您想要排除機器指標，請將 `excludeMachineMetrics`新增至系統屬性：
```
-Dcom.amazonaws.sdk.enableDefaultMetrics=credentialFile=/path/aws.properties,excludeMachineMetrics
```
## 詳細資訊
+ 如需預先定義核心[指標類型的完整清單，請參閱 amazonaws/metrics 套件摘要](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/metrics/package-summary.html)。
+ 了解如何使用 CloudWatch 範例中的 使用 適用於 Java 的 AWS SDK CloudWatch。 [CloudWatch 適用於 Java 的 AWS SDK](examples-cloudwatch.md)
+ 進一步了解[調校 適用於 Java 的 AWS SDK 以改善彈性](https://aws.amazon.com/blogs/developer/tuning-the-aws-sdk-for-java-to-improve-resiliency)部落格文章中的效能調校。