適用於 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 v1 編寫程式 AWS 服務的教學課程和範例。
在 GitHub 上的 AWS 文件程式碼範例儲存庫中尋找這些範例和其他範例的原始程式碼。 [ GitHub](https://github.com/awsdocs/aws-doc-sdk-examples)
若要提議新的程式碼範例，讓 AWS 文件團隊考慮生產，請建立新的請求。該團隊想要產生比僅涵蓋個別 API 呼叫之簡易程式碼更為廣泛的程式碼範例，以涵蓋更為廣泛的案例和使用案例。如需說明，請參閱 GitHub 上程式碼範例儲存庫中的[貢獻指導方針](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/CONTRIBUTING.md)。 GitHub..
## 適用於 Java 的 AWS SDK 2.x
在 2018 年， AWS 發行了 [AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/home.html)。本指南包含使用最新 Java 開發套件以及範例程式碼的指示。
**注意**
如需 適用於 Java 的 AWS SDK 開發人員可用的更多範例和其他資源，請參閱[其他文件和資源](welcome.md#additional-resources)！
**Topics**
# 使用 的 CloudWatch 範例 適用於 Java 的 AWS SDK
本節提供使用[適用於 Java 的 AWS SDK](https://aws.amazon.com/sdk-for-java/)編寫 [CloudWatch](https://aws.amazon.com/cloudwatch/) 程式的範例。
Amazon CloudWatch AWS 會即時監控您的 Amazon Web Services (AWS) 資源和您在 上執行的應用程式。您可以使用 CloudWatch 收集和追蹤指標，這些是您可以為您的資源和應用程式測量的變數。CloudWatch 警示會根據您定義的規則，傳送通知或自動變更您要監控的資源。
如需 的詳細資訊 CloudWatch，請參閱[Amazon CloudWatch 《 使用者指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)》。
**注意**
這些範例僅包含示範每種技術所需的程式碼。[GitHub 上提供完整程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java)。您可以從那裡下載單一原始檔案或將儲存庫複製到本機，以取得建置和執行的所有範例。
**Topics**
+ [從 CloudWatch 取得指標](examples-cloudwatch-get-metrics.md)
+ [發佈自訂指標資料](examples-cloudwatch-publish-custom-metrics.md)
+ [使用 CloudWatch 警示](examples-cloudwatch-create-alarms.md)
+ [在 CloudWatch 中使用警示動作](examples-cloudwatch-use-alarm-actions.md)
+ [傳送事件至 CloudWatch](examples-cloudwatch-send-events.md)
# 從 CloudWatch 取得指標
## 列出指標
若要列出 CloudWatch 指標，請建立 [ListMetricsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/ListMetricsRequest.html) 並呼叫 AmazonCloudWatchClient 的 `listMetrics`方法。您可以使用 `ListMetricsRequest` 來根據命名空間、指標名稱或維度，篩選傳回的指標。
**注意**
AWS 服務發佈的指標和維度清單，請參閱 Amazon CloudWatch 《 使用者指南》中的 \$1https---docs-aws-amazon-com-AmazonCloudWatch-latest-monitoring-CW-Support-For-AWS html\$1【Amazon CloudWatch 指標和維度參考】。
**匯入**
```
import com.amazonaws.services.cloudwatch.AmazonCloudWatch;
import com.amazonaws.services.cloudwatch.AmazonCloudWatchClientBuilder;
import com.amazonaws.services.cloudwatch.model.ListMetricsRequest;
import com.amazonaws.services.cloudwatch.model.ListMetricsResult;
import com.amazonaws.services.cloudwatch.model.Metric;
```
**Code**
```
final AmazonCloudWatch cw =
AmazonCloudWatchClientBuilder.defaultClient();
ListMetricsRequest request = new ListMetricsRequest()
.withMetricName(name)
.withNamespace(namespace);
boolean done = false;
while(!done) {
ListMetricsResult response = cw.listMetrics(request);
for(Metric metric : response.getMetrics()) {
System.out.printf(
"Retrieved metric %s", metric.getMetricName());
}
request.setNextToken(response.getNextToken());
if(response.getNextToken() == null) {
done = true;
}
}
```
指標會透過呼叫其`getMetrics`方法，在 [ListMetricsResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/ListMetricsResult.html) 中傳回。結果可能會*分頁*。若要擷取下一批結果，`setNextToken`請對原始請求物件呼叫 ，並使用`ListMetricsResult`物件`getNextToken`方法的傳回值，並將修改後的請求物件傳遞回另一個呼叫給 `listMetrics`。
## 詳細資訊
+ Amazon CloudWatch API 參考中的 [ListMetrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_ListMetrics.html)。
# 發佈自訂指標資料
許多 AWS 服務會在以「`AWS`」開頭的命名空間中發佈[自己的指標](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/aws-namespaces.html)。您也可以使用自己的命名空間 （只要不是以「`AWS`」開頭） 來發佈自訂指標資料。
## 發佈自訂指標資料
若要發佈您自己的指標資料，請使用 [PutMetricDataRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/PutMetricDataRequest.html) 呼叫 AmazonCloudWatchClient 的 `putMetricData`方法。`PutMetricDataRequest` 必須在 [MetricDatum](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/MetricDatum.html) 物件中包含用於資料的自訂命名空間，以及資料點本身的相關資訊。
**注意**
您無法指定開頭為 " `AWS` " 的命名空間。以 " `AWS` " 開頭的命名空間保留供 Amazon Web Services 產品使用。
**匯入**
```
import com.amazonaws.services.cloudwatch.AmazonCloudWatch;
import com.amazonaws.services.cloudwatch.AmazonCloudWatchClientBuilder;
import com.amazonaws.services.cloudwatch.model.Dimension;
import com.amazonaws.services.cloudwatch.model.MetricDatum;
import com.amazonaws.services.cloudwatch.model.PutMetricDataRequest;
import com.amazonaws.services.cloudwatch.model.PutMetricDataResult;
import com.amazonaws.services.cloudwatch.model.StandardUnit;
```
**Code**
```
final AmazonCloudWatch cw =
AmazonCloudWatchClientBuilder.defaultClient();
Dimension dimension = new Dimension()
.withName("UNIQUE_PAGES")
.withValue("URLS");
MetricDatum datum = new MetricDatum()
.withMetricName("PAGES_VISITED")
.withUnit(StandardUnit.None)
.withValue(data_point)
.withDimensions(dimension);
PutMetricDataRequest request = new PutMetricDataRequest()
.withNamespace("SITE/TRAFFIC")
.withMetricData(datum);
PutMetricDataResult response = cw.putMetricData(request);
```
## 詳細資訊
+ Amazon CloudWatch 《 使用者指南》中的[使用 Amazon CloudWatch 指標](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html)。
+ Amazon CloudWatch 《 使用者指南[AWS 》中的命名空間](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/aws-namespaces.html)。
+ 《 Amazon CloudWatch API 參考》中的 [PutMetricData](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html)。
# 使用 CloudWatch 警示
## 建立警示
若要根據 CloudWatch 指標建立警示，請呼叫 AmazonCloudWatchClient 的 `putMetricAlarm`方法，並將 [PutMetricAlarmRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/PutMetricAlarmRequest.html) 填入警示條件。
**匯入**
```
import com.amazonaws.services.cloudwatch.AmazonCloudWatch;
import com.amazonaws.services.cloudwatch.AmazonCloudWatchClientBuilder;
import com.amazonaws.services.cloudwatch.model.ComparisonOperator;
import com.amazonaws.services.cloudwatch.model.Dimension;
import com.amazonaws.services.cloudwatch.model.PutMetricAlarmRequest;
import com.amazonaws.services.cloudwatch.model.PutMetricAlarmResult;
import com.amazonaws.services.cloudwatch.model.StandardUnit;
import com.amazonaws.services.cloudwatch.model.Statistic;
```
**Code**
```
final AmazonCloudWatch cw =
AmazonCloudWatchClientBuilder.defaultClient();
Dimension dimension = new Dimension()
.withName("InstanceId")
.withValue(instanceId);
PutMetricAlarmRequest request = new PutMetricAlarmRequest()
.withAlarmName(alarmName)
.withComparisonOperator(
ComparisonOperator.GreaterThanThreshold)
.withEvaluationPeriods(1)
.withMetricName("CPUUtilization")
.withNamespace("{AWS}/EC2")
.withPeriod(60)
.withStatistic(Statistic.Average)
.withThreshold(70.0)
.withActionsEnabled(false)
.withAlarmDescription(
"Alarm when server CPU utilization exceeds 70%")
.withUnit(StandardUnit.Seconds)
.withDimensions(dimension);
PutMetricAlarmResult response = cw.putMetricAlarm(request);
```
## 列出警示
若要列出您已建立的 CloudWatch 警示，請使用 [DescribeAlarmsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/DescribeAlarmsRequest.html) 呼叫 AmazonCloudWatchClient 的 `describeAlarms`方法，以用於設定結果的選項。
**匯入**
```
import com.amazonaws.services.cloudwatch.AmazonCloudWatch;
import com.amazonaws.services.cloudwatch.AmazonCloudWatchClientBuilder;
import com.amazonaws.services.cloudwatch.model.DescribeAlarmsRequest;
import com.amazonaws.services.cloudwatch.model.DescribeAlarmsResult;
import com.amazonaws.services.cloudwatch.model.MetricAlarm;
```
**Code**
```
final AmazonCloudWatch cw =
AmazonCloudWatchClientBuilder.defaultClient();
boolean done = false;
DescribeAlarmsRequest request = new DescribeAlarmsRequest();
while(!done) {
DescribeAlarmsResult response = cw.describeAlarms(request);
for(MetricAlarm alarm : response.getMetricAlarms()) {
System.out.printf("Retrieved alarm %s", alarm.getAlarmName());
}
request.setNextToken(response.getNextToken());
if(response.getNextToken() == null) {
done = true;
}
}
```
您可以在 傳回的 [DescribeAlarmsResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/DescribeAlarmsResult.html) `getMetricAlarms`上呼叫 ，以取得警示清單`describeAlarms`。
結果可能會*分頁*。若要擷取下一批結果，`setNextToken`請對原始請求物件呼叫 ，並使用`DescribeAlarmsResult`物件`getNextToken`方法的傳回值，並將修改後的請求物件傳遞回另一個呼叫給 `describeAlarms`。
**注意**
您也可以使用 AmazonCloudWatchClient 的 `describeAlarmsForMetric`方法，擷取特定指標的警示。其用法類似於 `describeAlarms`。
## 刪除警示
若要刪除 CloudWatch 警示，請使用 [DeleteAlarmsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/DeleteAlarmsRequest.html) 呼叫 AmazonCloudWatchClient 的 `deleteAlarms`方法，其中包含您要刪除的一或多個警示名稱。
**匯入**
```
import com.amazonaws.services.cloudwatch.AmazonCloudWatch;
import com.amazonaws.services.cloudwatch.AmazonCloudWatchClientBuilder;
import com.amazonaws.services.cloudwatch.model.DeleteAlarmsRequest;
import com.amazonaws.services.cloudwatch.model.DeleteAlarmsResult;
```
**Code**
```
final AmazonCloudWatch cw =
AmazonCloudWatchClientBuilder.defaultClient();
DeleteAlarmsRequest request = new DeleteAlarmsRequest()
.withAlarmNames(alarm_name);
DeleteAlarmsResult response = cw.deleteAlarms(request);
```
## 詳細資訊
+ Amazon CloudWatch 《 使用者指南》中的[建立 Amazon CloudWatch 警示](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)
+ Amazon CloudWatch API 參考中的 [PutMetricAlarm](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricAlarm.html)
+ Amazon CloudWatch API 參考中的 [DescribeAlarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_DescribeAlarms.html)
+ Amazon CloudWatch API 參考中的 [DeleteAlarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_DeleteAlarms.html)
# 在 CloudWatch 中使用警示動作
使用 CloudWatch 警示動作，您可以建立警示來執行自動停止、終止、重新啟動或復原 Amazon EC2 執行個體等動作。
**注意**
在[建立警示](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/PutMetricAlarmRequest.html)時，可以使用 `setAlarmActions`PutMetricAlarmRequest[ 的 ](examples-cloudwatch-create-alarms.md) 方法，將警示動作新增到警示。
## 啟用警示動作
若要啟用 CloudWatch 警示的警示動作，`enableAlarmActions`請使用 [EnableAlarmActionsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/EnableAlarmActionsRequest.html) 呼叫 AmazonCloudWatchClient 的 ，其中包含您想要啟用其動作的一或多個警示名稱。
**匯入**
```
import com.amazonaws.services.cloudwatch.AmazonCloudWatch;
import com.amazonaws.services.cloudwatch.AmazonCloudWatchClientBuilder;
import com.amazonaws.services.cloudwatch.model.EnableAlarmActionsRequest;
import com.amazonaws.services.cloudwatch.model.EnableAlarmActionsResult;
```
**Code**
```
final AmazonCloudWatch cw =
AmazonCloudWatchClientBuilder.defaultClient();
EnableAlarmActionsRequest request = new EnableAlarmActionsRequest()
.withAlarmNames(alarm);
EnableAlarmActionsResult response = cw.enableAlarmActions(request);
```
## 停用警示動作
若要停用 CloudWatch 警示的警示動作，`disableAlarmActions`請使用 [DisableAlarmActionsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/DisableAlarmActionsRequest.html) 呼叫 AmazonCloudWatchClient 的 ，其中包含您想要停用其動作的一或多個警示名稱。
**匯入**
```
import com.amazonaws.services.cloudwatch.AmazonCloudWatch;
import com.amazonaws.services.cloudwatch.AmazonCloudWatchClientBuilder;
import com.amazonaws.services.cloudwatch.model.DisableAlarmActionsRequest;
import com.amazonaws.services.cloudwatch.model.DisableAlarmActionsResult;
```
**Code**
```
final AmazonCloudWatch cw =
AmazonCloudWatchClientBuilder.defaultClient();
DisableAlarmActionsRequest request = new DisableAlarmActionsRequest()
.withAlarmNames(alarmName);
DisableAlarmActionsResult response = cw.disableAlarmActions(request);
```
## 詳細資訊
+ 《 Amazon CloudWatch 使用者指南》中的[建立警示以停止、終止、重新啟動或復原執行個體](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/UsingAlarmActions.html)
+ Amazon CloudWatch API 參考中的 [PutMetricAlarm](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricAlarm.html)
+ Amazon CloudWatch API 參考中的 [EnableAlarmActions](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_EnableAlarmActions.html)
+ API 參考中的 [DisableAlarmActions](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_DisableAlarmActions.html) Amazon CloudWatch
# 傳送事件至 CloudWatch
CloudWatch 事件提供近乎即時的系統事件串流，描述 Amazon EC2 執行個體、 Lambda 函數、 Kinesis 串流、 Amazon ECS 任務、 Step Functions 狀態機器、 Amazon SNS 主題、 Amazon SQS 佇列或內建目標 AWS 的資源變更。您可以使用簡單的規則，來比對事件，並將這些事件轉傳到一或多個目標函數或串流。
## 新增事件
若要新增自訂 CloudWatch 事件，請使用 [PutEventsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatchevents/model/PutEventsRequest.html) 物件呼叫 AmazonCloudWatchEventsClient 的 `putEvents`方法，該物件包含一或多個 [PutEventsRequestEntry](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatchevents/model/PutEventsRequestEntry.html) 物件，提供每個事件的詳細資訊。您可以指定項目的多個參數，例如事件的來源和類型、與事件相關聯的資源等等。
**注意**
對 `putEvents` 的每個呼叫最多可以指定 10 個事件。
**匯入**
```
import com.amazonaws.services.cloudwatchevents.AmazonCloudWatchEvents;
import com.amazonaws.services.cloudwatchevents.AmazonCloudWatchEventsClientBuilder;
import com.amazonaws.services.cloudwatchevents.model.PutEventsRequest;
import com.amazonaws.services.cloudwatchevents.model.PutEventsRequestEntry;
import com.amazonaws.services.cloudwatchevents.model.PutEventsResult;
```
**Code**
```
final AmazonCloudWatchEvents cwe =
AmazonCloudWatchEventsClientBuilder.defaultClient();
final String EVENT_DETAILS =
"{ \"key1\": \"value1\", \"key2\": \"value2\" }";
PutEventsRequestEntry request_entry = new PutEventsRequestEntry()
.withDetail(EVENT_DETAILS)
.withDetailType("sampleSubmitted")
.withResources(resource_arn)
.withSource("aws-sdk-java-cloudwatch-example");
PutEventsRequest request = new PutEventsRequest()
.withEntries(request_entry);
PutEventsResult response = cwe.putEvents(request);
```
## 新增規則
若要建立或更新規則，請使用 [PutRuleRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatchevents/model/PutRuleRequest.html) 呼叫 AmazonCloudWatchEventsClient 的 `putRule`方法，其中包含規則名稱和選用參數，例如[事件模式](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/CloudWatchEventsandEventPatterns.html)、與規則建立關聯 IAM 的角色，以及描述規則執行頻率的[排程表達](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html)式。
**匯入**
```
import com.amazonaws.services.cloudwatchevents.AmazonCloudWatchEvents;
import com.amazonaws.services.cloudwatchevents.AmazonCloudWatchEventsClientBuilder;
import com.amazonaws.services.cloudwatchevents.model.PutRuleRequest;
import com.amazonaws.services.cloudwatchevents.model.PutRuleResult;
import com.amazonaws.services.cloudwatchevents.model.RuleState;
```
**Code**
```
final AmazonCloudWatchEvents cwe =
AmazonCloudWatchEventsClientBuilder.defaultClient();
PutRuleRequest request = new PutRuleRequest()
.withName(rule_name)
.withRoleArn(role_arn)
.withScheduleExpression("rate(5 minutes)")
.withState(RuleState.ENABLED);
PutRuleResult response = cwe.putRule(request);
```
## 新增目標
目標是觸發規則時叫用的資源。範例目標包括 Amazon EC2 執行個體、 Lambda 函數、 Kinesis 串流、 Amazon ECS 任務、 Step Functions 狀態機器和內建目標。
若要將目標新增至規則，請使用 [PutTargetsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatchevents/model/PutTargetsRequest.html) 呼叫 AmazonCloudWatchEventsClient 的 `putTargets`方法，其中包含要更新的規則和要新增至規則的目標清單。
**匯入**
```
import com.amazonaws.services.cloudwatchevents.AmazonCloudWatchEvents;
import com.amazonaws.services.cloudwatchevents.AmazonCloudWatchEventsClientBuilder;
import com.amazonaws.services.cloudwatchevents.model.PutTargetsRequest;
import com.amazonaws.services.cloudwatchevents.model.PutTargetsResult;
import com.amazonaws.services.cloudwatchevents.model.Target;
```
**Code**
```
final AmazonCloudWatchEvents cwe =
AmazonCloudWatchEventsClientBuilder.defaultClient();
Target target = new Target()
.withArn(function_arn)
.withId(target_id);
PutTargetsRequest request = new PutTargetsRequest()
.withTargets(target)
.withRule(rule_name);
PutTargetsResult response = cwe.putTargets(request);
```
## 詳細資訊
+ 《 Amazon CloudWatch Events 使用者指南》中的[使用 PutEvents 新增事件](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/AddEventsPutEvents.html)
+ Amazon CloudWatch Events 《 使用者指南》中的[規則排程表達](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html)式
+ 《 Amazon CloudWatch Events 使用者指南》中的[CloudWatch 事件的事件類型](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/EventTypes.html)
+ Amazon CloudWatch Events 《 使用者指南》中的[事件和事件模式](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/CloudWatchEventsandEventPatterns.html)
+ Amazon CloudWatch Events API 參考中的 [PutEvents](https://docs.aws.amazon.com/AmazonCloudWatchEvents/latest/APIReference/API_PutEvents.html)
+ Amazon CloudWatch Events API 參考中的 [PutTargets](https://docs.aws.amazon.com/AmazonCloudWatchEvents/latest/APIReference/API_PutTargets.html)
+ Amazon CloudWatch Events API 參考中的 [PutRule](https://docs.aws.amazon.com/AmazonCloudWatchEvents/latest/APIReference/API_PutRule.html)
# DynamoDB 使用 的範例 適用於 Java 的 AWS SDK
本節提供使用[適用於 Java 的 AWS SDK](https://aws.amazon.com/sdk-for-java/)編寫 [DynamoDB](https://aws.amazon.com/dynamodb/) 程式的範例。
**注意**
這些範例僅包含示範每種技術所需的程式碼。[GitHub 上提供完整程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java)。您可以從那裡下載單一原始檔案或將儲存庫複製到本機，以取得建置和執行的所有範例。
**Topics**
+ [使用帳戶 AWS 型端點](#account-based-endpoint-routing)
+ [在 中使用資料表 DynamoDB](examples-dynamodb-tables.md)
+ [在 中使用項目 DynamoDB](examples-dynamodb-items.md)
## 使用帳戶 AWS 型端點
DynamoDB 提供以[AWS 帳戶為基礎的端點](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.SDKOverview.html#Programming.SDKs.endpoints)，可透過使用 AWS 您的帳戶 ID 來簡化請求路由來改善效能。
若要利用此功能，您需要使用 版本 1.12.771 或更新版本的 版本 1 適用於 Java 的 AWS SDK。您可以在 [Maven 中央儲存庫](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom)中找到最新版本的 SDK。支援版本的 SDK 處於作用中狀態後，會自動使用新的端點。
如果您想要選擇退出以帳戶為基礎的路由，您有四個選項：
+ 將 DynamoDB 服務用戶端`AccountIdEndpointMode`設定為 `DISABLED`。
+ 設定環境變數。
+ 設定 JVM 系統屬性。
+ 更新共用 AWS 組態檔案設定。
下列程式碼片段示範如何透過設定 DynamoDB 服務用戶端來停用帳戶型路由：
```
ClientConfiguration config = new ClientConfiguration()
.withAccountIdEndpointMode(AccountIdEndpointMode.DISABLED);
AWSCredentialsProvider credentialsProvider = new EnvironmentVariableCredentialsProvider();
AmazonDynamoDB dynamodb = AmazonDynamoDBClientBuilder.standard()
.withClientConfiguration(config)
.withCredentials(credentialsProvider)
.withRegion(Regions.US_WEST_2)
.build();
```
AWS SDKs 和工具參考指南提供有關最後[三個組態選項](https://docs.aws.amazon.com/sdkref/latest/guide/feature-account-endpoints.html)的詳細資訊。
# 在 中使用資料表 DynamoDB
資料表是 DynamoDB 資料庫中所有項目的容器。您必須先建立資料表 DynamoDB，才能從中新增或移除資料。
對於每個資料表，您必須定義：
+ 對於您的帳戶和區域都具有獨一性的資料表*名稱*。
+ 每個值的*主索引鍵*都必須獨一無二，資料表中任兩個項目不能有相同的主索引鍵值。
主索引鍵可以是*簡單的*，包含單一分割區 (HASH) 索引鍵；也可以是*複合的*，包含分割區和排序 (RANGE) 索引鍵。
每個索引鍵值都有一個關聯的*資料類型*，由 [ScalarAttributeType](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/ScalarAttributeType.html) 類別列舉。索引鍵值可以是二進位 (B)、數值 (N)、或字串 (S)。如需詳細資訊，請參閱《 Amazon DynamoDB 開發人員指南》中的[命名規則和資料類型](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html)。
+ 定義資料表預留讀取/寫入容量單位數量的*佈建輸送量*值。
**注意**
[Amazon DynamoDB 定價](https://aws.amazon.com/dynamodb/pricing/)是以您在資料表上設定的佈建輸送量值為基礎，因此請只預留您認為資料表所需的容量。
您可以隨時修改資料表的佈建輸送量，以便在需要變更時調整容量。
## 建立資料表
使用[DynamoDB 用戶端](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/AmazonDynamoDB.html)的 `createTable`方法來建立新的 DynamoDB 資料表。您需要建構資料表屬性和資料表結構描述，這兩項都會用來識別資料表的主索引鍵。您也必須提供初始佈建的輸送量值和資料表名稱。只有在建立資料表時，才定義索引鍵 DynamoDB 資料表屬性。
**注意**
如果具有您所選名稱的資料表已存在，則會擲回 [AmazonServiceException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/AmazonServiceException.html)。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.model.AttributeDefinition;
import com.amazonaws.services.dynamodbv2.model.CreateTableRequest;
import com.amazonaws.services.dynamodbv2.model.CreateTableResult;
import com.amazonaws.services.dynamodbv2.model.KeySchemaElement;
import com.amazonaws.services.dynamodbv2.model.KeyType;
import com.amazonaws.services.dynamodbv2.model.ProvisionedThroughput;
import com.amazonaws.services.dynamodbv2.model.ScalarAttributeType;
```
### 使用簡單主索引鍵建立資料表
此程式碼會使用簡單主索引鍵 ("Name") 來建立資料表。
**Code**
```
CreateTableRequest request = new CreateTableRequest()
.withAttributeDefinitions(new AttributeDefinition(
"Name", ScalarAttributeType.S))
.withKeySchema(new KeySchemaElement("Name", KeyType.HASH))
.withProvisionedThroughput(new ProvisionedThroughput(
new Long(10), new Long(10)))
.withTableName(table_name);
final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient();
try {
CreateTableResult result = ddb.createTable(request);
System.out.println(result.getTableDescription().getTableName());
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/CreateTable.java)。
### 使用複合主索引鍵建立資料表
新增另一個 [AttributeDefinition](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/AttributeDefinition.html) 和 [KeySchemaElement](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/KeySchemaElement.html) 到 [CreateTableRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/CreateTableRequest.html)。
**Code**
```
CreateTableRequest request = new CreateTableRequest()
.withAttributeDefinitions(
new AttributeDefinition("Language", ScalarAttributeType.S),
new AttributeDefinition("Greeting", ScalarAttributeType.S))
.withKeySchema(
new KeySchemaElement("Language", KeyType.HASH),
new KeySchemaElement("Greeting", KeyType.RANGE))
.withProvisionedThroughput(
new ProvisionedThroughput(new Long(10), new Long(10)))
.withTableName(table_name);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/CreateTableCompositeKey.java)。
## 列出資料表
您可以呼叫[DynamoDB 用戶端](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/AmazonDynamoDB.html)的 `listTables`方法，列出特定區域中的資料表。
**注意**
如果您的帳戶和區域不存在指定的資料表，會擲出 [ResourceNotFoundException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/ResourceNotFoundException.html)。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.model.ListTablesRequest;
import com.amazonaws.services.dynamodbv2.model.ListTablesResult;
```
**Code**
```
final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient();
ListTablesRequest request;
boolean more_tables = true;
String last_name = null;
while(more_tables) {
try {
if (last_name == null) {
request = new ListTablesRequest().withLimit(10);
}
else {
request = new ListTablesRequest()
.withLimit(10)
.withExclusiveStartTableName(last_name);
}
ListTablesResult table_list = ddb.listTables(request);
List table_names = table_list.getTableNames();
if (table_names.size() > 0) {
for (String cur_name : table_names) {
System.out.format("* %s\n", cur_name);
}
} else {
System.out.println("No tables found!");
System.exit(0);
}
last_name = table_list.getLastEvaluatedTableName();
if (last_name == null) {
more_tables = false;
}
```
根據預設，每次呼叫最多傳回 100 個資料表 - 在傳回的 [ListTablesResult](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/model/ListTablesResult.html) 物件`getLastEvaluatedTableName`上使用 ，以取得上次評估的資料表。您可以使用這個值，在前次列表最後傳回值之後開始列表。
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/ListTables.java)。
## 說明資料表 (取得相關資訊)
呼叫[DynamoDB 用戶端](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/AmazonDynamoDB.html)的 `describeTable`方法。
**注意**
如果您的帳戶和區域不存在指定的資料表，會擲出 [ResourceNotFoundException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/ResourceNotFoundException.html)。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.model.AttributeDefinition;
import com.amazonaws.services.dynamodbv2.model.ProvisionedThroughputDescription;
import com.amazonaws.services.dynamodbv2.model.TableDescription;
```
**Code**
```
final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient();
try {
TableDescription table_info =
ddb.describeTable(table_name).getTable();
if (table_info != null) {
System.out.format("Table name : %s\n",
table_info.getTableName());
System.out.format("Table ARN : %s\n",
table_info.getTableArn());
System.out.format("Status : %s\n",
table_info.getTableStatus());
System.out.format("Item count : %d\n",
table_info.getItemCount().longValue());
System.out.format("Size (bytes): %d\n",
table_info.getTableSizeBytes().longValue());
ProvisionedThroughputDescription throughput_info =
table_info.getProvisionedThroughput();
System.out.println("Throughput");
System.out.format(" Read Capacity : %d\n",
throughput_info.getReadCapacityUnits().longValue());
System.out.format(" Write Capacity: %d\n",
throughput_info.getWriteCapacityUnits().longValue());
List attributes =
table_info.getAttributeDefinitions();
System.out.println("Attributes");
for (AttributeDefinition a : attributes) {
System.out.format(" %s (%s)\n",
a.getAttributeName(), a.getAttributeType());
}
}
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/DescribeTable.java)。
## 修改 (更新) 資料表
您可以隨時呼叫[DynamoDB 用戶端](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/AmazonDynamoDB.html)的 `updateTable`方法，修改資料表的佈建輸送量值。
**注意**
如果您的帳戶和區域不存在指定的資料表，會擲出 [ResourceNotFoundException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/ResourceNotFoundException.html)。
**匯入**
```
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.model.ProvisionedThroughput;
import com.amazonaws.AmazonServiceException;
```
**Code**
```
ProvisionedThroughput table_throughput = new ProvisionedThroughput(
read_capacity, write_capacity);
final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient();
try {
ddb.updateTable(table_name, table_throughput);
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/UpdateTable.java)。
## 刪除資料表
呼叫[DynamoDB 用戶端](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/AmazonDynamoDB.html)的 `deleteTable`方法，並將資料表的名稱傳遞給用戶端。
**注意**
如果您的帳戶和區域不存在指定的資料表，會擲出 [ResourceNotFoundException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/ResourceNotFoundException.html)。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
```
**Code**
```
final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient();
try {
ddb.deleteTable(table_name);
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/DeleteTable.java)。
## 詳細資訊
+ 《 Amazon DynamoDB 開發人員指南》中的[使用資料表的指導方針](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GuidelinesForTables.html)
+ 《 Amazon DynamoDB 開發人員指南》中的[在 中使用資料表 DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.html)
# 在 中使用項目 DynamoDB
在 中 DynamoDB，項目是*屬性*的集合，每個屬性都有*名稱*和*值*。屬性值可以是純量、集合或文件類型。如需詳細資訊，請參閱《 Amazon DynamoDB 開發人員指南》中的[命名規則和資料類型](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html)。
## 從資料表擷取 (取得) 項目
呼叫 AmazonDynamoDB 的 `getItem`方法，並傳遞具有資料表名稱的 [GetItemRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/GetItemRequest.html) 物件，以及您想要的項目主索引鍵值。它會傳回 [GetItemResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/GetItemResult.html) 物件。
您可以使用所傳回 `GetItemResult` 物件的 `getItem()` 方法來擷取與項目關聯之索引鍵 (字串) 和值的[對應](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/Map.html) ([AttributeValue](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/AttributeValue.html)) 組。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.model.AttributeValue;
import com.amazonaws.services.dynamodbv2.model.GetItemRequest;
import java.util.HashMap;
import java.util.Map;
```
**Code**
```
HashMap key_to_get =
new HashMap();
key_to_get.put("DATABASE_NAME", new AttributeValue(name));
GetItemRequest request = null;
if (projection_expression != null) {
request = new GetItemRequest()
.withKey(key_to_get)
.withTableName(table_name)
.withProjectionExpression(projection_expression);
} else {
request = new GetItemRequest()
.withKey(key_to_get)
.withTableName(table_name);
}
final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient();
try {
Map returned_item =
ddb.getItem(request).getItem();
if (returned_item != null) {
Set keys = returned_item.keySet();
for (String key : keys) {
System.out.format("%s: %s\n",
key, returned_item.get(key).toString());
}
} else {
System.out.format("No item found with the key %s!\n", name);
}
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/GetItem.java)。
## 新增項目到資料表
建立代表項目屬性的索引鍵值組[對應](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/Map.html)。這些項目必須包含資料表主索引鍵欄位的值。如果主索引鍵識別的項目已存在，其欄位會透過請求*更新*。
**注意**
如果您的帳戶和區域不存在指定的資料表，會擲出 [ResourceNotFoundException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/ResourceNotFoundException.html)。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.model.AttributeValue;
import com.amazonaws.services.dynamodbv2.model.ResourceNotFoundException;
import java.util.ArrayList;
```
**Code**
```
HashMap item_values =
new HashMap();
item_values.put("Name", new AttributeValue(name));
for (String[] field : extra_fields) {
item_values.put(field[0], new AttributeValue(field[1]));
}
final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient();
try {
ddb.putItem(table_name, item_values);
} catch (ResourceNotFoundException e) {
System.err.format("Error: The table \"%s\" can't be found.\n", table_name);
System.err.println("Be sure that it exists and that you've typed its name correctly!");
System.exit(1);
} catch (AmazonServiceException e) {
System.err.println(e.getMessage());
System.exit(1);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/PutItem.java)。
## 更新資料表中的現有項目
您可以使用 AmazonDynamoDB 的 `updateItem`方法，提供資料表名稱、主索引鍵值和要更新的欄位映射，來更新已存在於資料表中的項目屬性。
**注意**
如果您的帳戶和區域不存在指定的資料表，或者如果您傳遞的主索引鍵所識別的項目不存在，會擲出 [ResourceNotFoundException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/ResourceNotFoundException.html)。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.model.AttributeAction;
import com.amazonaws.services.dynamodbv2.model.AttributeValue;
import com.amazonaws.services.dynamodbv2.model.AttributeValueUpdate;
import com.amazonaws.services.dynamodbv2.model.ResourceNotFoundException;
import java.util.ArrayList;
```
**Code**
```
HashMap item_key =
new HashMap();
item_key.put("Name", new AttributeValue(name));
HashMap updated_values =
new HashMap();
for (String[] field : extra_fields) {
updated_values.put(field[0], new AttributeValueUpdate(
new AttributeValue(field[1]), AttributeAction.PUT));
}
final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient();
try {
ddb.updateItem(table_name, item_key, updated_values);
} catch (ResourceNotFoundException e) {
System.err.println(e.getMessage());
System.exit(1);
} catch (AmazonServiceException e) {
System.err.println(e.getMessage());
System.exit(1);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/UpdateItem.java)。
## 使用 DynamoDBMapper 類別
[適用於 Java 的 AWS SDK](https://aws.amazon.com/sdk-for-java/) 提供 [DynamoDBMapper](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html) 類別，可讓您將用戶端類別映射至 Amazon DynamoDB 資料表。若要使用 [DynamoDBMapper](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html) 類別，您可以使用註釋 （如下列程式碼範例所示），定義 DynamoDB 資料表中項目與程式碼中對應物件執行個體之間的關係。[DynamoDBMapper](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html) 類別可讓您存取資料表；執行各種建立、讀取、更新和刪除 (CRUD) 操作；以及執行查詢。
**注意**
[DynamoDBMapper](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html) 類別不允許您建立、更新或刪除資料表。
**匯入**
```
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBAttribute;
import com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBHashKey;
import com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBMapper;
import com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBTable;
import com.amazonaws.services.dynamodbv2.datamodeling.DynamoDBRangeKey;
import com.amazonaws.services.dynamodbv2.model.AmazonDynamoDBException;
```
**Code**
下列 Java 程式碼範例示範如何使用 [DynamoDBMapper](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html) 類別將內容新增至 *Music* 資料表。將內容新增至資料表後，請注意，會使用*分割區*和*排序*索引鍵載入項目。然後，*獎勵*項目會更新。如需建立*音樂*資料表的資訊，請參閱《 Amazon DynamoDB 開發人員指南》中的[建立資料表](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/getting-started-step-1.html)。
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
MusicItems items = new MusicItems();
try{
// Add new content to the Music table
items.setArtist(artist);
items.setSongTitle(songTitle);
items.setAlbumTitle(albumTitle);
items.setAwards(Integer.parseInt(awards)); //convert to an int
// Save the item
DynamoDBMapper mapper = new DynamoDBMapper(client);
mapper.save(items);
// Load an item based on the Partition Key and Sort Key
// Both values need to be passed to the mapper.load method
String artistName = artist;
String songQueryTitle = songTitle;
// Retrieve the item
MusicItems itemRetrieved = mapper.load(MusicItems.class, artistName, songQueryTitle);
System.out.println("Item retrieved:");
System.out.println(itemRetrieved);
// Modify the Award value
itemRetrieved.setAwards(2);
mapper.save(itemRetrieved);
System.out.println("Item updated:");
System.out.println(itemRetrieved);
System.out.print("Done");
} catch (AmazonDynamoDBException e) {
e.getStackTrace();
}
}
@DynamoDBTable(tableName="Music")
public static class MusicItems {
//Set up Data Members that correspond to columns in the Music table
private String artist;
private String songTitle;
private String albumTitle;
private int awards;
@DynamoDBHashKey(attributeName="Artist")
public String getArtist() {
return this.artist;
}
public void setArtist(String artist) {
this.artist = artist;
}
@DynamoDBRangeKey(attributeName="SongTitle")
public String getSongTitle() {
return this.songTitle;
}
public void setSongTitle(String title) {
this.songTitle = title;
}
@DynamoDBAttribute(attributeName="AlbumTitle")
public String getAlbumTitle() {
return this.albumTitle;
}
public void setAlbumTitle(String title) {
this.albumTitle = title;
}
@DynamoDBAttribute(attributeName="Awards")
public int getAwards() {
return this.awards;
}
public void setAwards(int awards) {
this.awards = awards;
}
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/UseDynamoMapping.java)。
## 詳細資訊
+ 《 Amazon DynamoDB 開發人員指南》中的[使用項目的指導方針](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GuidelinesForItems.html)
+ 《 Amazon DynamoDB 開發人員指南》中的[使用 中的項目 DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html)
# Amazon EC2 使用 的範例 適用於 Java 的 AWS SDK
本節提供[Amazon EC2](https://aws.amazon.com/ec2/)使用 進行程式設計的範例 適用於 Java 的 AWS SDK。
**Topics**
+ [教學課程：啟動 EC2 執行個體](how-to-ec2.md)
+ [使用 IAM 角色授予 上 AWS 資源的存取權 Amazon EC2](java-dg-roles.md)
+ [教學課程： Amazon EC2 Spot 執行個體](tutorial-spot-instances-java.md)
+ [教學課程：進階 Amazon EC2 Spot 請求管理](tutorial-spot-adv-java.md)
+ [管理 Amazon EC2 執行個體](examples-ec2-instances.md)
+ [在 中使用彈性 IP 地址 Amazon EC2](examples-ec2-elastic-ip.md)
+ [使用區域和可用區域](examples-ec2-regions-zones.md)
+ [使用 Amazon EC2 金鑰對](examples-ec2-key-pairs.md)
+ [在 中使用安全群組 Amazon EC2](examples-ec2-security-groups.md)
# 教學課程：啟動 EC2 執行個體
本教學課程示範如何使用 適用於 Java 的 AWS SDK 來啟動 EC2 執行個體。
**Topics**
+ [先決條件](#prerequisitesec2)
+ [建立 Amazon EC2 安全群組](create-security-group.md)
+ [建立金鑰對](create-key-pair.md)
+ [執行 Amazon EC2 執行個體](run-instance.md)
## 先決條件
開始之前，請確定您已建立 ， AWS 帳戶 且已設定您的 AWS 登入資料。如需詳細資訊，請參閱 [ 入門](getting-started.md)。
# 建立 Amazon EC2 安全群組
## EC2-Classic 正在淘汰
**警告**
我們將於 2022 年 8 月 15 日淘汰 EC2-Classic。建議您從 EC2-Classic 遷移至 VPC。如需詳細資訊，請參閱部落格文章 [EC2-Classic-Classic Networking 正在淘汰 – 以下說明如何準備](https://aws.amazon.com/blogs/aws/ec2-classic-is-retiring-heres-how-to-prepare/)。
建立*安全群組*，做為虛擬防火牆，控制一或多個 EC2 執行個體的網路流量。根據預設， 會將您的執行個體與不允許傳入流量的安全群組建立 Amazon EC2 關聯。您可以建立允許您的 EC2 執行個體接受特定連接的安全群組。例如，如果您需要連線到 Linux 執行個體，您必須設定安全群組以允許 SSH 流量。您可以使用 Amazon EC2 主控台或 建立安全群組 適用於 Java 的 AWS SDK。
您可以建立安全群組，提供於 EC2-Classic 或 EC2-VPC 使用。如需 EC2-Classic 和 EC2-VPC 的詳細資訊，請參閱《Linux 執行個體 Amazon EC2 使用者指南》中的[支援的平台](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-supported-platforms.html)。
如需使用 Amazon EC2 主控台建立安全群組的詳細資訊，請參閱《Linux 執行個體 Amazon EC2 使用者指南》中的[Amazon EC2 安全群組](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html)。
1. 建立和初始化 [CreateSecurityGroupRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateSecurityGroupRequest.html) 執行個體。使用 [withGroupName](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateSecurityGroupRequest.html#withGroupName-java.lang.String-) 方法來設定安全群組名稱，並使用 [withDescription](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateSecurityGroupRequest.html#withDescription-java.lang.String-) 方法來設定安全群組描述，如下所示：
```
CreateSecurityGroupRequest csgr = new CreateSecurityGroupRequest();
csgr.withGroupName("JavaSecurityGroup").withDescription("My security group");
```
安全群組名稱在您初始化 Amazon EC2 用戶端的 AWS 區域中必須是唯一的。您必須使用 US-ASCII 字元做為安全群組名稱和描述。
1. 將請求物件做為參數傳遞至 [createSecurityGroup](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/AmazonEC2.html#createSecurityGroup-com.amazonaws.services.ec2.model.CreateSecurityGroupRequest-) 方法。方法會傳回 [CreateSecurityGroupResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateSecurityGroupResult.html) 物件，如下所示：
```
CreateSecurityGroupResult createSecurityGroupResult =
amazonEC2Client.createSecurityGroup(csgr);
```
如果您嘗試建立與現有安全群組同名的安全群組， 會`createSecurityGroup`擲回例外狀況。
根據預設，新的安全群組不允許任何傳入流量到您的 Amazon EC2 執行個體。若要允許傳入流量，您必須明確授權安全群組傳入。您可以為個別 IP 地址、一系列 IP 地址、特定通訊協定和 TCP/UDP 連接埠授權輸入。
1. 建立和初始化 [IpPermission](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/IpPermission.html) 執行個體。使用 [withIpv4Ranges](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/IpPermission.html#withIpv4Ranges-java.util.Collection-) 方法設定 IP 地址的範圍以授權輸入，並使用 [withIpProtocol](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/IpPermission.html#withIpProtocol-java.lang.String-) 方法設定 IP 通訊協定。使用 [withFromPort](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/IpPermission.html#withFromPort-java.lang.Integer-) 和 [withToPort](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/IpPermission.html#withToPort-java.lang.Integer-) 方法指定連接埠範圍以授權輸入，如下所示：
```
IpPermission ipPermission =
new IpPermission();
IpRange ipRange1 = new IpRange().withCidrIp("111.111.111.111/32");
IpRange ipRange2 = new IpRange().withCidrIp("150.150.150.150/32");
ipPermission.withIpv4Ranges(Arrays.asList(new IpRange[] {ipRange1, ipRange2}))
.withIpProtocol("tcp")
.withFromPort(22)
.withToPort(22);
```
必須符合您在 `IpPermission` 物件中指定的所有條件，才能允許輸入。
使用 CIDR 表示法指定 IP 地址。如果您將通訊協定指定為 TCP/UDP，則必須提供來源連接埠和目的地連接埠。只有在您指定 TCP 或 UDP 時，才能授權連接埠。
1. 建立和初始化 [AuthorizeSecurityGroupIngressRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AuthorizeSecurityGroupEgressRequest.html) 執行個體。使用 `withGroupName`方法指定安全群組名稱，並將您先前初始化的`IpPermission`物件傳遞至 [withIpPermissions](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AuthorizeSecurityGroupEgressRequest.html#withIpPermissions-com.amazonaws.services.ec2.model.IpPermission…-) 方法，如下所示：
```
AuthorizeSecurityGroupIngressRequest authorizeSecurityGroupIngressRequest =
new AuthorizeSecurityGroupIngressRequest();
authorizeSecurityGroupIngressRequest.withGroupName("JavaSecurityGroup")
.withIpPermissions(ipPermission);
```
1. 將請求物件傳遞至 [authorizeSecurityGroupIngress](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/AmazonEC2Client.html#authorizeSecurityGroupIngress-com.amazonaws.services.ec2.model.AuthorizeSecurityGroupIngressRequest-) 方法，如下所示：
```
amazonEC2Client.authorizeSecurityGroupIngress(authorizeSecurityGroupIngressRequest);
```
如果您`authorizeSecurityGroupIngress`使用已授權輸入 IP 地址呼叫 ，則 方法會擲回例外狀況。在呼叫 之前，建立並初始化新的`IpPermission`物件，以授權不同 IPs、連接埠和通訊協定的輸入`AuthorizeSecurityGroupIngress`。
每當您呼叫 [authorizeSecurityGroupIngress](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/AmazonEC2Client.html#authorizeSecurityGroupIngress-com.amazonaws.services.ec2.model.AuthorizeSecurityGroupIngressRequest-) 或 [authorizeSecurityGroupEgress](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/AmazonEC2Client.html#authorizeSecurityGroupEgress-com.amazonaws.services.ec2.model.AuthorizeSecurityGroupEgressRequest-) 方法時，就會將規則新增至您的安全群組。
# 建立金鑰對
您必須在啟動 EC2 執行個體時指定金鑰對，然後在連線至執行個體時指定金鑰對的私有金鑰。您可以建立金鑰對，或使用啟動其他執行個體時使用的現有金鑰對。如需詳細資訊，請參閱《Linux 執行個體 Amazon EC2 使用者指南》中的[Amazon EC2 金鑰對](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html)。
1. 建立和初始化 [CreateKeyPairRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateKeyPairRequest.html) 執行個體。使用 [withKeyName](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateKeyPairRequest.html#withKeyName-java.lang.String-) 方法來設定金鑰對名稱，如下所示：
```
CreateKeyPairRequest createKeyPairRequest = new CreateKeyPairRequest();
createKeyPairRequest.withKeyName(keyName);
```
**重要**
金鑰對名稱必須是唯一的。如果您嘗試建立與現有金鑰對具有相同金鑰名稱的金鑰對，則會收到例外狀況。
1. 將請求物件傳遞至 [createKeyPair](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/AmazonEC2.html#createKeyPair-com.amazonaws.services.ec2.model.CreateKeyPairRequest--) 方法。方法會傳回 [CreateKeyPairResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateKeyPairResult.html) 執行個體，如下所示：
```
CreateKeyPairResult createKeyPairResult =
amazonEC2Client.createKeyPair(createKeyPairRequest);
```
1. 呼叫結果物件的 [getKeyPair](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateKeyPairResult.html#getKeyPair--) 方法以取得 [KeyPair](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/KeyPair.html) 物件。呼叫`KeyPair`物件的 [getKeyMaterial](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/KeyPair.html#getKeyMaterial--) 方法，以取得未加密的 PEM 編碼私有金鑰，如下所示：
```
KeyPair keyPair = new KeyPair();
keyPair = createKeyPairResult.getKeyPair();
String privateKey = keyPair.getKeyMaterial();
```
# 執行 Amazon EC2 執行個體
使用下列程序，從相同的 Amazon Machine Image (AMI) 啟動一或多個設定相同的 EC2 執行個體。建立 EC2 執行個體後，您可以查看他們的狀態。執行 EC2 執行個體之後，您可以連線到執行個體。
1. 建立和初始化 [RunInstancesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RunInstancesRequest.html) 執行個體。請確定您在建立用戶端物件時指定的區域中存在您指定的 AMI、金鑰對和安全群組。
```
RunInstancesRequest runInstancesRequest =
new RunInstancesRequest();
runInstancesRequest.withImageId("ami-a9d09ed1")
.withInstanceType(InstanceType.T1Micro)
.withMinCount(1)
.withMaxCount(1)
.withKeyName("my-key-pair")
.withSecurityGroups("my-security-group");
```
[withImageId](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RunInstancesRequest.html#withImageId-java.lang.String-)
+ AMI 的 ID。若要了解如何尋找 Amazon 提供的公AMIs 或建立您自己的 AMI，請參閱 [Amazon Machine Image (AMI)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html)。
[withInstanceType](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RunInstancesRequest.html#withInstanceType-java.lang.String-)
+ 執行個體類型與所指定的 AMI 相容。如需詳細資訊，請參閱《Linux [執行個體使用者指南》中的執行個體類型](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html)。 Amazon EC2
[withMinCount](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RunInstancesRequest.html#withMinCount-java.lang.Integer-)
+ 要啟動執行個體的最少數量。如果這比 Amazon EC2 可在目標可用區域中啟動的執行個體更多，則 不會 Amazon EC2 啟動任何執行個體。
[withMaxCount](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RunInstancesRequest.html#withMaxCount-java.lang.Integer-)
+ 要啟動執行個體的最大數量。如果這比 Amazon EC2 可在目標可用區域中啟動的執行個體更多， 會在 上方 Amazon EC2 啟動最多的執行個體數量`MinCount`。您可以啟動的範圍數量介於 1 到執行個體類型允許的執行個體最大數量。如需詳細資訊，請參閱 Amazon EC2 一般常見問答集 Amazon EC2 中的我可以在 中執行多少執行個體。
[withKeyName](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RunInstancesRequest.html#withKeyName-java.lang.String-)
+ EC2 金鑰對的名稱。如果您未指定金鑰對而啟動執行個體，則就無法與它連線。如需詳細資訊，請參閱[建立金鑰對](create-key-pair.md)。
[withSecurityGroups](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RunInstancesRequest.html#withSecurityGroups-java.util.Collection-)
+ 一個或多個安全群組。如需詳細資訊，請參閱[建立 Amazon EC2 安全群組](create-security-group.md)。
1. 透過將請求物件傳遞至 [runInstances](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/AmazonEC2Client.html#runInstances-com.amazonaws.services.ec2.model.RunInstancesRequest-) 方法來啟動執行個體。方法會傳回 [RunInstancesResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RunInstancesResult.html) 物件，如下所示：
```
RunInstancesResult result = amazonEC2Client.runInstances(
runInstancesRequest);
```
執行個體執行後，您可以使用 金鑰對來連接至執行個體。如需詳細資訊，請參閱《[Linux 執行個體使用者指南》中的連線至您的](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstances.html) Linux 執行個體。 Amazon EC2
# 使用 IAM 角色授予 上 AWS 資源的存取權 Amazon EC2
所有對 Amazon Web Services (AWS) 的請求都必須使用 發出的登入資料進行密碼編譯簽署 AWS。您可以使用 *IAM 角色*，方便地從 Amazon EC2 執行個體授予 AWS 資源的安全存取權。
本主題提供如何搭配執行 的 Java SDK 應用程式使用 IAM 角色的相關資訊 Amazon EC2。如需 IAM 執行個體的詳細資訊，請參閱《Linux 執行個體 Amazon EC2 使用者指南》中的適用於 的 [IAM 角色 Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)。
## 預設提供者鏈和 EC2 執行個體描述檔
如果您的應用程式使用預設建構函數建立 AWS 用戶端，則用戶端將依下列順序使用*預設憑證提供者鏈結搜尋憑證*：
1. 在 Java 系統屬性中：`aws.accessKeyId` 和 `aws.secretKey`。
1. 在系統環境變數中：`AWS_ACCESS_KEY_ID` 和 `AWS_SECRET_ACCESS_KEY`。
1. 在預設登入資料檔案中 (此檔案的位置因平台而異)。
1. 如果已設定`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`環境變數，且安全管理員具有存取變數的許可，則透過 Amazon EC2 容器服務傳遞的登入資料。
1. 在*執行個體描述檔登入資料*中，這存在於與 EC2 執行個體的 IAM 角色關聯的執行個體中繼資料內。
1. 來自環境或容器的 Web Identity Token 登入資料。
預設供應商鏈中的*執行個體描述檔登入*資料步驟只有在 Amazon EC2 執行個體上執行應用程式時才能使用，但在使用 Amazon EC2 執行個體時提供最大的使用便利性和最佳安全性。您也可以直接傳遞 [InstanceProfileCredentialsProvider](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/InstanceProfileCredentialsProvider.html) 執行個體給用戶端建構函數來取得執行個體描述檔登入資料，而無須繼續進行整個預設供應者鏈結。
例如：
```
AmazonS3 s3 = AmazonS3ClientBuilder.standard()
.withCredentials(new InstanceProfileCredentialsProvider(false))
.build();
```
使用此方法時，開發套件會擷取暫時 AWS 登入資料，其許可與執行個體描述檔中與 Amazon EC2 執行個體相關聯之 IAM 角色的許可相同。雖然這些登入資料是暫時的，最終會過期， `InstanceProfileCredentialsProvider`會定期為您重新整理，以便取得的登入資料繼續允許存取 AWS。
**重要**
自動登入資料重新整理*只會*在您使用預設用戶端建構函數時發生，這會建立自己的 `InstanceProfileCredentialsProvider` 做為預設提供者鏈結的一部分，或當您將`InstanceProfileCredentialsProvider`執行個體直接傳遞給用戶端建構函數時。如果您使用其他方法來取得或傳遞執行個體描述檔登入資料，則需負責檢查和重新整理過期的登入資料。
如果用戶端建構函式無法使用登入資料提供者鏈結找到登入資料，則會擲回 [AmazonClientException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/AmazonClientException.html)。
## 逐步解說：針對 EC2 執行個體使用 IAM 角色
下列逐步解說說明如何 Amazon S3 使用 IAM 角色從 擷取物件來管理存取。
### 建立 IAM 角色
建立授予唯讀存取權的 IAM 角色 Amazon S3。
1. 開啟 [IAM 主控台](https://console.aws.amazon.com/iam/home)。
1. 在導覽窗格中，選取**角色**，然後選取**建立新角色**。
1. 輸入角色的名稱，然後選擇 **Next Step (下一步)**。請記住此名稱，因為當您啟動 Amazon EC2 執行個體時，您將需要此名稱。
1. 在**選取角色類型**頁面** AWS 服務 的角色**下，選取 ** Amazon EC2 **。
1. 在**設定許可**頁面的**選取政策範本**下，選取** Amazon S3 唯讀存取**，然後選取**下一步**。
1. 在**檢閱**頁面上，選取**建立角色**。
### 啟動 EC2 執行個體時並指定 IAM 角色
您可以使用 Amazon EC2 主控台或 啟動具有 IAM 角色的 Amazon EC2 執行個體 適用於 Java 的 AWS SDK。
+ 若要使用主控台啟動 Amazon EC2 執行個體，請遵循 [Amazon EC2 Linux 執行個體使用者指南中 Linux 執行個體入門](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html)的指示。 Amazon EC2
當您到達 **Review Instance Launch (檢閱執行個體啟動)** 頁面時，選取 **Edit instance details (編輯執行個體詳細資訊)**。在 **IAM 角色**中，選擇您先前建立的 IAM 角色。依照指示完成程序。
**注意**
您需要建立或使用現有的安全群組與金鑰對，以連接到執行個體。
+ 若要使用 啟動具有 IAM 角色的 Amazon EC2 執行個體 適用於 Java 的 AWS SDK，請參閱[執行 Amazon EC2 執行個體](run-instance.md)。
### 建立您的應用程式
讓我們建置要在 EC2 執行個體上執行的範例應用程式。首先，建立可用來保存教學課程檔案的目錄 （例如 `GetS3ObjectApp`)。
接著，將 適用於 Java 的 AWS SDK 程式庫複製到新建立的目錄。如果您將 下載 適用於 Java 的 AWS SDK 到您的`~/Downloads`目錄，您可以使用下列命令來複製它們：
```
cp -r ~/Downloads/aws-java-sdk-{1.7.5}/lib .
cp -r ~/Downloads/aws-java-sdk-{1.7.5}/third-party .
```
開啟新檔案、呼叫 `GetS3Object.java`，然後新增下列程式碼：
```
import java.io.*;
import com.amazonaws.auth.*;
import com.amazonaws.services.s3.*;
import com.amazonaws.services.s3.model.*;
import com.amazonaws.AmazonClientException;
import com.amazonaws.AmazonServiceException;
public class GetS3Object {
private static final String bucketName = "text-content";
private static final String key = "text-object.txt";
public static void main(String[] args) throws IOException
{
AmazonS3 s3Client = AmazonS3ClientBuilder.defaultClient();
try {
System.out.println("Downloading an object");
S3Object s3object = s3Client.getObject(
new GetObjectRequest(bucketName, key));
displayTextInputStream(s3object.getObjectContent());
}
catch(AmazonServiceException ase) {
System.err.println("Exception was thrown by the service");
}
catch(AmazonClientException ace) {
System.err.println("Exception was thrown by the client");
}
}
private static void displayTextInputStream(InputStream input) throws IOException
{
// Read one text line at a time and display.
BufferedReader reader = new BufferedReader(new InputStreamReader(input));
while(true)
{
String line = reader.readLine();
if(line == null) break;
System.out.println( " " + line );
}
System.out.println();
}
}
```
開啟新檔案、呼叫 `build.xml`，然後新增下列行：
```
```
建置並執行修改過的程式。請注意，程式中不會儲存任何登入資料。因此，除非您已指定 AWS 登入資料，否則程式碼會擲回 `AmazonServiceException`。例如：
```
$ ant
Buildfile: /path/to/my/GetS3ObjectApp/build.xml
build:
[javac] Compiling 1 source file to /path/to/my/GetS3ObjectApp
run:
[java] Downloading an object
[java] AmazonServiceException
BUILD SUCCESSFUL
```
### 將編譯的程式傳輸至您的 EC2 執行個體
使用安全複本 ()** `` **以及 適用於 Java 的 AWS SDK 程式庫，將程式傳輸至您的 Amazon EC2 執行個體。命令的序列如下所示。
```
scp -p -i {my-key-pair}.pem GetS3Object.class ec2-user@{public_dns}:GetS3Object.class
scp -p -i {my-key-pair}.pem build.xml ec2-user@{public_dns}:build.xml
scp -r -p -i {my-key-pair}.pem lib ec2-user@{public_dns}:lib
scp -r -p -i {my-key-pair}.pem third-party ec2-user@{public_dns}:third-party
```
**注意**
根據您使用的 Linux 發行版本，*使用者名稱*可能是 "ec2-user"、"root" 或 "ubuntu"。若要取得執行個體的公有 DNS 名稱，請開啟 [EC2 主控台](https://console.aws.amazon.com/ec2/home)，並在**描述**索引標籤中尋找**公有 DNS** 值 （例如，`ec2-198-51-100-1.compute-1.amazonaws.com`)。
在上述命令中：
+ `GetS3Object.class` 是您編譯的程式
+ `build.xml` 是用來建置和執行程式的 ant 檔案
+ `lib` 和 `third-party`目錄是來自 的對應程式庫資料夾 適用於 Java 的 AWS SDK。
+ `-r` 切換表示 `scp`應該對 適用於 Java 的 AWS SDK 分佈中 `library`和 `third-party`目錄的所有內容進行遞迴複製。
+ `-p` 切換會指出 `scp`應在來源檔案複製到目的地時保留其許可。
**注意**
`-p` 交換器僅適用於 Linux、macOS 或 Unix。如果您要從 Windows 複製檔案，您可能需要使用以下命令修正執行個體上的檔案許可：
```
chmod -R u+rwx GetS3Object.class build.xml lib third-party
```
### 在 EC2 執行個體上執行範例程式
若要執行程式，請連線至您的 Amazon EC2 執行個體。如需詳細資訊，請參閱《[Linux 執行個體使用者指南》中的連線至您的](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstances.html) Linux 執行個體。 Amazon EC2
如果您的執行個體**` ant `**無法使用 ，請使用下列命令安裝它：
```
sudo yum install ant
```
然後，使用 執行程式`ant`，如下所示：
```
ant run
```
程式會將 Amazon S3 物件的內容寫入命令視窗。
# 教學課程： Amazon EC2 Spot 執行個體
## 概觀
競價型執行個體可讓您以最高 90% 的未使用 Amazon Elastic Compute Cloud (Amazon EC2) 容量競價，並執行取得的執行個體，只要您的競價超過目前的 *Spot 價格*。 會根據供需定期 Amazon EC2 變更競價型價格，且競價符合或超過該價格的客戶可以存取可用的 Spot 執行個體。如同隨需執行個體和預留執行個體，Spot 執行個體為您提供另一個選項，讓您取得更多運算容量。
Spot 執行個體可以大幅降低批次處理、科學研究、影像處理、影片編碼、資料和網路爬取、財務分析和測試 Amazon EC2 的成本。此外，Spot 執行個體可讓您在不需要該容量時，存取大量的額外容量。
若要使用 Spot 執行個體，您可以提出 Spot 執行個體請求，並指定您願意支付每一個小時使用一個執行個體的最高預算；此為您的出價。如果您出價符合或超出目前競價型價格，則會履行您的請求，您的執行個體將會執行，直到選擇終止或競價型價格增加到高於出價 (以先到者為準)。
請務必注意：
+ 您通常每小時支付的費用比出價低。 會在請求進來時定期 Amazon EC2 調整 Spot 價格，並提供可用的供應變更。無論出價多高，在該期間每個人支付相同的 Spot 價格。因此，您支付的費用可能會低於您的出價，但永遠不會超過您的出價。
+ 如果您正在執行 Spot 執行個體，且您的出價不再符合或超過目前的 Spot 價格，您的執行個體將會終止。這表示您會希望確保您的工作負載和應用程式有足夠的彈性，以利用此機會容量。
Spot 執行個體在執行時與其他 Amazon EC2 執行個體執行完全相同，而與其他 Amazon EC2 執行個體一樣，當您不再需要 Spot 執行個體時，可以終止這些執行個體。如果您終止了您的執行個體，不足一小時則按一小時支付費用，就像使用 (如您為隨需執行個體或預留執行個體所做的那樣)。不過，如果 Spot 價格高於您的出價，且您的執行個體被 終止 Amazon EC2，則不會向您收取任何部分使用時數的費用。
本教學課程說明如何使用 適用於 Java 的 AWS SDK 執行下列動作。
+ 提交 Spot 請求
+ 判斷 Spot 請求何時履行
+ 取消 Spot 請求
+ 終止關聯的執行個體
## 先決條件
若要使用此教學課程，您必須 適用於 Java 的 AWS SDK 安裝 ，並符合其基本安裝先決條件。如需詳細資訊[，請參閱設定 適用於 Java 的 AWS SDK](setup-install.md) 。
## 步驟 1：設定您的登入資料
若要開始使用此程式碼範例，您需要設定 AWS 登入資料。如需如何執行此作業的說明，請參閱[設定開發的 AWS 登入資料和區域](setup-credentials.md)。
**注意**
我們建議您使用 IAM 使用者的登入資料來提供這些值。如需詳細資訊，請參閱[註冊 AWS 和建立 IAM 使用者](signup-create-iam-user.md)。
現在您已設定 設定，您可以開始使用範例中的程式碼。
## 步驟 2：設定安全群組
*安全群組*可做為防火牆，控制允許進出一組執行個體的流量。根據預設，執行個體會在沒有任何安全群組的情況下啟動，這表示在任何 TCP 連接埠上的所有傳入 IP 流量都會遭到拒絕。因此，在提交 Spot 請求之前，我們會設定允許必要網路流量的安全群組。基於本教學的目的，我們將建立新的安全群組，稱為「GettingStarted」，允許來自您執行應用程式的 IP 地址的 Secure Shell (SSH) 流量。若要設定新的安全群組，您需要包含或執行下列程式碼範例，以程式設計方式設定安全群組。
建立`AmazonEC2`用戶端物件之後，我們會建立名稱為「GettingStarted」的`CreateSecurityGroupRequest`物件，以及安全群組的描述。然後，我們呼叫 `ec2.createSecurityGroup` API 來建立群組。
為了啟用對群組的存取，我們會建立 IP 地址範圍設為本機電腦子網路 CIDR 表示的`ipPermission`物件；IP 地址上的 "/10" 尾碼表示指定 IP 地址的子網路。我們也使用 TCP 通訊協定和連接埠 22 (SSH) 設定`ipPermission`物件。最後一個步驟是`ec2.authorizeSecurityGroupIngress`使用安全群組的名稱和 `ipPermission` 物件呼叫 。
```
// Create the AmazonEC2 client so we can call various APIs.
AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
// Create a new security group.
try {
CreateSecurityGroupRequest securityGroupRequest = new CreateSecurityGroupRequest("GettingStartedGroup", "Getting Started Security Group");
ec2.createSecurityGroup(securityGroupRequest);
} catch (AmazonServiceException ase) {
// Likely this means that the group is already created, so ignore.
System.out.println(ase.getMessage());
}
String ipAddr = "0.0.0.0/0";
// Get the IP of the current host, so that we can limit the Security
// Group by default to the ip range associated with your subnet.
try {
InetAddress addr = InetAddress.getLocalHost();
// Get IP Address
ipAddr = addr.getHostAddress()+"/10";
} catch (UnknownHostException e) {
}
// Create a range that you would like to populate.
ArrayList ipRanges = new ArrayList();
ipRanges.add(ipAddr);
// Open up port 22 for TCP traffic to the associated IP
// from above (e.g. ssh traffic).
ArrayList ipPermissions = new ArrayList ();
IpPermission ipPermission = new IpPermission();
ipPermission.setIpProtocol("tcp");
ipPermission.setFromPort(new Integer(22));
ipPermission.setToPort(new Integer(22));
ipPermission.setIpRanges(ipRanges);
ipPermissions.add(ipPermission);
try {
// Authorize the ports to the used.
AuthorizeSecurityGroupIngressRequest ingressRequest =
new AuthorizeSecurityGroupIngressRequest("GettingStartedGroup",ipPermissions);
ec2.authorizeSecurityGroupIngress(ingressRequest);
} catch (AmazonServiceException ase) {
// Ignore because this likely means the zone has
// already been authorized.
System.out.println(ase.getMessage());
}
```
請注意，您只需要執行此應用程式一次，即可建立新的安全群組。
您也可以使用 建立安全群組 AWS Toolkit for Eclipse。如需詳細資訊，請參閱[從 管理安全群組 AWS Cost Explorer](https://docs.aws.amazon.com/toolkit-for-eclipse/v1/user-guide/tke-sg.html)。
## 步驟 3：提交 Spot 請求
若要提交 Spot 請求，您必須先判斷要使用的執行個體類型、Amazon Machine Image (AMI) 和最高出價。您還必須包含我們先前設定的安全群組，以便您可以視需要登入執行個體。
有多種執行個體類型可供選擇；請前往 Amazon EC2 執行個體類型以取得完整清單。在本教學課程中，我們將使用 t1.micro，這是最便宜的可用執行個體類型。接下來，我們將決定要使用的 AMI 類型。我們將使用 ami-a9d09ed1，這是撰寫本教學課程時可用的up-to-date Amazon Linux AMI。最新的 AMI 可能會隨著時間而變更，但您可以始終遵循以下步驟來確定最新版本的 AMI：
1. 開啟 [Amazon EC2 主控台](https://console.aws.amazon.com/ec2/home)。
1. 選擇**啟動執行個體**按鈕。
1. 第一個視窗會顯示可用的 AMIs。AMI ID 會列在每個 AMI 標題旁。或者，您可以使用 `DescribeImages` API，但利用該命令超出本教學課程的範圍。
有多種方法可以對 Spot 執行個體進行競價；若要全面了解各種方法，您應該檢視[競價 Spot 執行個體](https://www.youtube.com/watch?v=WD9N73F3Fao&feature=player_embedded)影片。不過，若要開始使用，我們將描述三種常見策略：競價以確保成本低於隨需定價；根據產生的運算值競價；競價以盡快取得運算容量。
+ *降低隨需成本* 您有批次處理任務，需要數小時或數天才能執行。不過，在啟動和完成時，您具有彈性。您想要查看是否可以以比隨需執行個體更低的成本完成它。您可以使用 AWS 管理主控台 或 Amazon EC2 API 來檢查執行個體類型的 Spot 價格歷史記錄。如需詳細資訊，請至 [查閱 Spot 歷史價格](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-spot-instances-history.html)。在指定可用區域中分析所需執行個體類型的價格歷史記錄之後，您有兩種替代的競價方法：
+ 您可以出價此 Spot 價格範圍的上限 (仍低於隨需執行個體的價格)、期待您的一次性 Spot 要求可以履行並執行，有一段足夠的連續時間完成工作。
+ 或者，您可以指定您願意為 Spot 執行個體支付的金額，做為隨需執行個體價格 的 %，並計劃透過持久性請求結合隨時間啟動的許多執行個體。如果超過指定的價格 , 則 Spot 執行個體將會終止。(我們將說明如何使這個任務自動進行。)
+ *支付不超過結果的值* 您有要執行的資料處理任務。您很了解此任務結果的價值，換言之您知道成本為多少。分析執行個體類型的 Spot 價格歷史記錄後，您可以選擇出價，計算時間的成本不超過任務結果的值。您建立可以長久出價的方式，且允許它間歇性地執行，當 Spot 價格出現波動，或 Spot 價格低於您的出價時。
+ *快速取得運算容量* 您對無法透過隨需執行個體取得的額外容量有非預期的短期需求。分析執行個體類型的 Spot 價格歷史記錄後，您競價高於最高歷史價格，以提供快速履行請求的高度可能性，並繼續運算，直到完成為止。
在您選擇您的出價金額後，您可以要求 Spot 執行個體了。在本教學課程中，我們將出價隨需價格 (0.03 USD)，以最大限度地提高完成出價的機會。您可以前往 Amazon EC2 定價頁面，判斷可用執行個體的類型和執行個體的隨需價格。當 Spot 執行個體執行時，您需要支付執行個體執行期間生效的 Spot 價格。Spot 執行個體價格由 設定 Amazon EC2 ，並根據 Spot 執行個體容量供需的長期趨勢逐步調整。您也可以指定您願意為 Spot 執行個體支付的金額，做為隨需執行個體 price.To 請求 Spot 執行個體的 %，您只需要使用您稍早選擇的參數來建置您的請求即可。我們從建立`RequestSpotInstanceRequest`物件開始。請求物件需要您要啟動的執行個體數量和出價。此外，您需要`LaunchSpecification`為請求設定 ，其中包含要使用的執行個體類型、AMI ID 和安全群組。填入請求後，您可以在 `AmazonEC2Client` 物件上呼叫 `requestSpotInstances`方法。下列範例示範如何請求 Spot 執行個體。
```
// Create the AmazonEC2 client so we can call various APIs.
AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
// Initializes a Spot Instance Request
RequestSpotInstancesRequest requestRequest = new RequestSpotInstancesRequest();
// Request 1 x t1.micro instance with a bid price of $0.03.
requestRequest.setSpotPrice("0.03");
requestRequest.setInstanceCount(Integer.valueOf(1));
// Setup the specifications of the launch. This includes the
// instance type (e.g. t1.micro) and the latest Amazon Linux
// AMI id available. Note, you should always use the latest
// Amazon Linux AMI id or another of your choosing.
LaunchSpecification launchSpecification = new LaunchSpecification();
launchSpecification.setImageId("ami-a9d09ed1");
launchSpecification.setInstanceType(InstanceType.T1Micro);
// Add the security group to the request.
ArrayList securityGroups = new ArrayList();
securityGroups.add("GettingStartedGroup");
launchSpecification.setSecurityGroups(securityGroups);
// Add the launch specifications to the request.
requestRequest.setLaunchSpecification(launchSpecification);
// Call the RequestSpotInstance API.
RequestSpotInstancesResult requestResult = ec2.requestSpotInstances(requestRequest);
```
執行此程式碼將啟動新的 Spot 執行個體請求。您可以使用其他選項來設定 Spot 請求。若要進一步了解，請造訪 適用於 Java 的 AWS SDK API 參考中的[教學課程：進階 Amazon EC2 Spot 請求管理](tutorial-spot-adv-java.md)或 [RequestSpotInstances](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RequestSpotInstancesRequest.html) 類別。
**注意**
您將需要支付實際啟動的任何 Spot 執行個體的費用，因此請務必取消任何請求並終止啟動的任何執行個體，以減少任何相關費用。
## 步驟 4：判斷 Spot 請求的狀態
接下來，我們希望建立程式碼以等待 Spot 請求達到「作用中」狀態，再繼續進行最後一個步驟。為了判斷 Spot 請求的狀態，我們會輪詢 [describeSpotInstanceRequests](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/AmazonEC2Client.html#describeSpotInstanceRequests) 方法，以取得要監控的 Spot 請求 ID 狀態。
在步驟 2 中建立的請求 ID 內嵌在我們`requestSpotInstances`請求的回應中。下列範例程式碼示範如何從`requestSpotInstances`回應中收集請求 IDs，並使用它們來填入 `ArrayList`。
```
// Call the RequestSpotInstance API.
RequestSpotInstancesResult requestResult = ec2.requestSpotInstances(requestRequest);
List requestResponses = requestResult.getSpotInstanceRequests();
// Setup an arraylist to collect all of the request ids we want to
// watch hit the running state.
ArrayList spotInstanceRequestIds = new ArrayList();
// Add all of the request ids to the hashset, so we can determine when they hit the
// active state.
for (SpotInstanceRequest requestResponse : requestResponses) {
System.out.println("Created Spot Request: "+requestResponse.getSpotInstanceRequestId());
spotInstanceRequestIds.add(requestResponse.getSpotInstanceRequestId());
}
```
若要監控您的請求 ID，請呼叫 `describeSpotInstanceRequests`方法來判斷請求的狀態。然後循環直到請求未處於「開啟」狀態。請注意，我們監控的狀態不是「開啟」，而是「作用中」，因為如果您的請求引數有問題，請求可能會直接進入「關閉」。下列程式碼範例提供如何完成此任務的詳細資訊。
```
// Create a variable that will track whether there are any
// requests still in the open state.
boolean anyOpen;
do {
// Create the describeRequest object with all of the request ids
// to monitor (e.g. that we started).
DescribeSpotInstanceRequestsRequest describeRequest = new DescribeSpotInstanceRequestsRequest();
describeRequest.setSpotInstanceRequestIds(spotInstanceRequestIds);
// Initialize the anyOpen variable to false - which assumes there
// are no requests open unless we find one that is still open.
anyOpen=false;
try {
// Retrieve all of the requests we want to monitor.
DescribeSpotInstanceRequestsResult describeResult = ec2.describeSpotInstanceRequests(describeRequest);
List describeResponses = describeResult.getSpotInstanceRequests();
// Look through each request and determine if they are all in
// the active state.
for (SpotInstanceRequest describeResponse : describeResponses) {
// If the state is open, it hasn't changed since we attempted
// to request it. There is the potential for it to transition
// almost immediately to closed or cancelled so we compare
// against open instead of active.
if (describeResponse.getState().equals("open")) {
anyOpen = true;
break;
}
}
} catch (AmazonServiceException e) {
// If we have an exception, ensure we don't break out of
// the loop. This prevents the scenario where there was
// blip on the wire.
anyOpen = true;
}
try {
// Sleep for 60 seconds.
Thread.sleep(60*1000);
} catch (Exception e) {
// Do nothing because it woke up early.
}
} while (anyOpen);
```
執行此程式碼後，您的 Spot 執行個體請求將已完成或失敗，並出現錯誤，將輸出至畫面。在任何一種情況下，我們都可以繼續進行下一個步驟，以清除任何作用中的請求並終止任何執行中的執行個體。
## 步驟 5：清除 Spot 請求和執行個體
最後，我們需要清除請求和執行個體。請務必同時取消任何未完成的請求*並*終止任何執行個體。只要取消請求，您的執行個體就不會終止，這表示您將繼續支付這些請求的費用。如果您終止執行個體，Spot 請求可能會遭到取消，但在某些情況下，例如如果您使用持續競價，而終止執行個體不足以阻止您的請求重新履行。因此，最好的方式是取消所有作用中的競價和終止所有執行中的執行個體。
下列程式碼示範如何取消您的請求。
```
try {
// Cancel requests.
CancelSpotInstanceRequestsRequest cancelRequest =
new CancelSpotInstanceRequestsRequest(spotInstanceRequestIds);
ec2.cancelSpotInstanceRequests(cancelRequest);
} catch (AmazonServiceException e) {
// Write out any exceptions that may have occurred.
System.out.println("Error cancelling instances");
System.out.println("Caught Exception: " + e.getMessage());
System.out.println("Reponse Status Code: " + e.getStatusCode());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
}
```
若要終止任何未完成的執行個體，您將需要與啟動執行個體的請求相關聯的執行個體 ID。下列程式碼範例採用原始程式碼來監控執行個體，並新增 `ArrayList`，其中存放與`describeInstance`回應相關聯的執行個體 ID。
```
// Create a variable that will track whether there are any requests
// still in the open state.
boolean anyOpen;
// Initialize variables.
ArrayList instanceIds = new ArrayList();
do {
// Create the describeRequest with all of the request ids to
// monitor (e.g. that we started).
DescribeSpotInstanceRequestsRequest describeRequest = new DescribeSpotInstanceRequestsRequest();
describeRequest.setSpotInstanceRequestIds(spotInstanceRequestIds);
// Initialize the anyOpen variable to false, which assumes there
// are no requests open unless we find one that is still open.
anyOpen = false;
try {
// Retrieve all of the requests we want to monitor.
DescribeSpotInstanceRequestsResult describeResult =
ec2.describeSpotInstanceRequests(describeRequest);
List describeResponses =
describeResult.getSpotInstanceRequests();
// Look through each request and determine if they are all
// in the active state.
for (SpotInstanceRequest describeResponse : describeResponses) {
// If the state is open, it hasn't changed since we
// attempted to request it. There is the potential for
// it to transition almost immediately to closed or
// cancelled so we compare against open instead of active.
if (describeResponse.getState().equals("open")) {
anyOpen = true; break;
}
// Add the instance id to the list we will
// eventually terminate.
instanceIds.add(describeResponse.getInstanceId());
}
} catch (AmazonServiceException e) {
// If we have an exception, ensure we don't break out
// of the loop. This prevents the scenario where there
// was blip on the wire.
anyOpen = true;
}
try {
// Sleep for 60 seconds.
Thread.sleep(60*1000);
} catch (Exception e) {
// Do nothing because it woke up early.
}
} while (anyOpen);
```
使用存放在 中的執行個體 IDs`ArrayList`，使用以下程式碼片段終止任何執行中的執行個體。
```
try {
// Terminate instances.
TerminateInstancesRequest terminateRequest = new TerminateInstancesRequest(instanceIds);
ec2.terminateInstances(terminateRequest);
} catch (AmazonServiceException e) {
// Write out any exceptions that may have occurred.
System.out.println("Error terminating instances");
System.out.println("Caught Exception: " + e.getMessage());
System.out.println("Reponse Status Code: " + e.getStatusCode());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
}
```
## 將一切結合在一起
為了整合所有這些，我們提供更以物件為導向的方法，結合先前顯示的步驟：初始化 EC2 用戶端、提交 Spot 請求、判斷 Spot 請求何時不再處於開啟狀態，以及清除任何保留的 Spot 請求和相關聯的執行個體。我們建立名為 的類別`Requests`，以執行這些動作。
我們也建立一個`GettingStartedApp`類別，它具有主要方法，用於執行高階函數呼叫。具體而言，我們會初始化前述的`Requests`物件。我們提交 Spot 執行個體請求。然後，我們等待 Spot 請求達到「作用中」狀態。最後，我們會清除請求和執行個體。
您可以在 [GitHub](https://github.com/aws/aws-sdk-java/tree/master/src/samples/AmazonEC2SpotInstances-GettingStarted) 檢視或下載此範例的完整原始程式碼。
恭喜您！您剛完成使用 開發 Spot 執行個體軟體的入門教學課程 適用於 Java 的 AWS SDK。
## 後續步驟
繼續[教學課程：進階 Amazon EC2 Spot 請求管理](tutorial-spot-adv-java.md)。
# 教學課程：進階 Amazon EC2 Spot 請求管理
Amazon EC2 Spot 執行個體可讓您競價未使用的 Amazon EC2 容量，並在競價超過目前 *Spot 價格*時執行這些執行個體。 會根據供需定期 Amazon EC2 變更 Spot 價格。如需 Spot 執行個體的詳細資訊，請參閱《Linux [執行個體使用者指南》中的 Spot](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-spot-instances.html) 執行個體。 Amazon EC2
## 先決條件
若要使用此教學課程，您必須 適用於 Java 的 AWS SDK 安裝 ，並符合其基本安裝先決條件。如需詳細資訊[，請參閱設定 適用於 Java 的 AWS SDK](setup-install.md) 。
## 設定您的登入資料
若要開始使用此程式碼範例，您需要設定 AWS 登入資料。如需如何執行此作業的說明，請參閱[設定開發的 AWS 登入資料和區域](setup-credentials.md)。
**注意**
我們建議您使用 IAM 使用者的登入資料來提供這些值。如需詳細資訊，請參閱[註冊 AWS 和建立 IAM 使用者](signup-create-iam-user.md)。
現在您已設定好設定，您可以開始使用範例中的程式碼。
## 設定安全群組
安全群組可做為防火牆，控制允許進出一組執行個體的流量。根據預設，執行個體會在沒有任何安全群組的情況下啟動，這表示在任何 TCP 連接埠上的所有傳入 IP 流量都會遭到拒絕。因此，在提交 Spot 請求之前，我們會設定允許必要網路流量的安全群組。基於本教學的目的，我們將建立新的安全群組，名為「GettingStarted」，允許來自您執行應用程式的 IP 地址的安全殼層 (SSH) 流量。若要設定新的安全群組，您需要包含或執行下列程式碼範例，以程式設計方式設定安全群組。
建立`AmazonEC2`用戶端物件之後，我們會建立名稱為「GettingStarted」的`CreateSecurityGroupRequest`物件，以及安全群組的描述。然後，我們呼叫 `ec2.createSecurityGroup` API 來建立 群組。
為了啟用群組的存取，我們會建立 IP 地址範圍設為本機電腦子網路 CIDR 表示法的`ipPermission`物件；IP 地址上的 "/10" 尾碼表示指定 IP 地址的子網路。我們也使用 TCP 通訊協定和連接埠 22 (SSH) 設定`ipPermission`物件。最後一個步驟是`ec2 .authorizeSecurityGroupIngress`使用安全群組的名稱和 `ipPermission` 物件呼叫 。
（下列程式碼與我們在第一個教學課程中所使用的程式碼相同。)
```
// Create the AmazonEC2Client object so we can call various APIs.
AmazonEC2 ec2 = AmazonEC2ClientBuilder.standard()
.withCredentials(credentials)
.build();
// Create a new security group.
try {
CreateSecurityGroupRequest securityGroupRequest =
new CreateSecurityGroupRequest("GettingStartedGroup",
"Getting Started Security Group");
ec2.createSecurityGroup(securityGroupRequest);
} catch (AmazonServiceException ase) {
// Likely this means that the group is already created, so ignore.
System.out.println(ase.getMessage());
}
String ipAddr = "0.0.0.0/0";
// Get the IP of the current host, so that we can limit the Security Group
// by default to the ip range associated with your subnet.
try {
// Get IP Address
InetAddress addr = InetAddress.getLocalHost();
ipAddr = addr.getHostAddress()+"/10";
}
catch (UnknownHostException e) {
// Fail here...
}
// Create a range that you would like to populate.
ArrayList ipRanges = new ArrayList();
ipRanges.add(ipAddr);
// Open up port 22 for TCP traffic to the associated IP from
// above (e.g. ssh traffic).
ArrayList ipPermissions = new ArrayList ();
IpPermission ipPermission = new IpPermission();
ipPermission.setIpProtocol("tcp");
ipPermission.setFromPort(new Integer(22));
ipPermission.setToPort(new Integer(22));
ipPermission.setIpRanges(ipRanges);
ipPermissions.add(ipPermission);
try {
// Authorize the ports to the used.
AuthorizeSecurityGroupIngressRequest ingressRequest =
new AuthorizeSecurityGroupIngressRequest(
"GettingStartedGroup",ipPermissions);
ec2.authorizeSecurityGroupIngress(ingressRequest);
}
catch (AmazonServiceException ase) {
// Ignore because this likely means the zone has already
// been authorized.
System.out.println(ase.getMessage());
}
```
您可以在程式碼範例中檢視整個`advanced.CreateSecurityGroupApp.java`程式碼範例。請注意，您只需要執行此應用程式一次，即可建立新的安全群組。
**注意**
您也可以使用 建立安全群組 AWS Toolkit for Eclipse。如需詳細資訊，請參閱 AWS Toolkit for Eclipse 《 使用者指南》中的[從 管理安全群組 AWS Cost Explorer](https://docs.aws.amazon.com/toolkit-for-eclipse/v1/user-guide/tke-sg.html)。
## 詳細的 Spot 執行個體請求建立選項
如[我們在教學課程： Amazon EC2 Spot 執行個體](tutorial-spot-instances-java.md)中所說明，您需要使用執行個體類型、Amazon Machine Image (AMI) 和最高出價來建置請求。
讓我們從建立`RequestSpotInstanceRequest`物件開始。請求物件需要您想要的執行個體數量和出價。此外，我們需要`LaunchSpecification`為 請求設定 ，其中包括您想要使用的執行個體類型、AMI ID 和安全群組。填入請求後，我們會在 `AmazonEC2Client` 物件上呼叫 `requestSpotInstances`方法。以下範例說明如何請求 Spot 執行個體。
（下列程式碼與我們在第一個教學課程中所使用的程式碼相同。)
```
// Create the AmazonEC2 client so we can call various APIs.
AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
// Initializes a Spot Instance Request
RequestSpotInstancesRequest requestRequest = new RequestSpotInstancesRequest();
// Request 1 x t1.micro instance with a bid price of $0.03.
requestRequest.setSpotPrice("0.03");
requestRequest.setInstanceCount(Integer.valueOf(1));
// Set up the specifications of the launch. This includes the
// instance type (e.g. t1.micro) and the latest Amazon Linux
// AMI id available. Note, you should always use the latest
// Amazon Linux AMI id or another of your choosing.
LaunchSpecification launchSpecification = new LaunchSpecification();
launchSpecification.setImageId("ami-a9d09ed1");
launchSpecification.setInstanceType(InstanceType.T1Micro);
// Add the security group to the request.
ArrayList securityGroups = new ArrayList();
securityGroups.add("GettingStartedGroup");
launchSpecification.setSecurityGroups(securityGroups);
// Add the launch specification.
requestRequest.setLaunchSpecification(launchSpecification);
// Call the RequestSpotInstance API.
RequestSpotInstancesResult requestResult =
ec2.requestSpotInstances(requestRequest);
```
## 持久性與一次性請求
建置 Spot 請求時，您可以指定數個選用參數。首先是您的請求是一次性還是持久性。根據預設，這是一次性請求。一次性請求只能履行一次，在請求的執行個體終止後，請求將會關閉。每當相同請求沒有執行的 Spot 執行個體時，就會考慮持續請求。若要指定請求類型，您只需在 Spot 請求上設定類型。這可以使用下列程式碼來完成。
```
// Retrieves the credentials from an AWSCredentials.properties file.
AWSCredentials credentials = null;
try {
credentials = new PropertiesCredentials(
GettingStartedApp.class.getResourceAsStream("AwsCredentials.properties"));
}
catch (IOException e1) {
System.out.println(
"Credentials were not properly entered into AwsCredentials.properties.");
System.out.println(e1.getMessage());
System.exit(-1);
}
// Create the AmazonEC2 client so we can call various APIs.
AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
// Initializes a Spot Instance Request
RequestSpotInstancesRequest requestRequest =
new RequestSpotInstancesRequest();
// Request 1 x t1.micro instance with a bid price of $0.03.
requestRequest.setSpotPrice("0.03");
requestRequest.setInstanceCount(Integer.valueOf(1));
// Set the type of the bid to persistent.
requestRequest.setType("persistent");
// Set up the specifications of the launch. This includes the
// instance type (e.g. t1.micro) and the latest Amazon Linux
// AMI id available. Note, you should always use the latest
// Amazon Linux AMI id or another of your choosing.
LaunchSpecification launchSpecification = new LaunchSpecification();
launchSpecification.setImageId("ami-a9d09ed1");
launchSpecification.setInstanceType(InstanceType.T1Micro);
// Add the security group to the request.
ArrayList securityGroups = new ArrayList();
securityGroups.add("GettingStartedGroup");
launchSpecification.setSecurityGroups(securityGroups);
// Add the launch specification.
requestRequest.setLaunchSpecification(launchSpecification);
// Call the RequestSpotInstance API.
RequestSpotInstancesResult requestResult =
ec2.requestSpotInstances(requestRequest);
```
## 限制請求的持續時間
您也可以選擇性地指定請求將保持有效的時間長度。您可以指定此期間的開始和結束時間。根據預設，Spot 請求將從建立開始考慮履行，直到您履行或取消為止。不過，如有需要，您可以限制有效期間。以下程式碼顯示如何指定此期間的範例。
```
// Create the AmazonEC2 client so we can call various APIs.
AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
// Initializes a Spot Instance Request
RequestSpotInstancesRequest requestRequest = new RequestSpotInstancesRequest();
// Request 1 x t1.micro instance with a bid price of $0.03.
requestRequest.setSpotPrice("0.03");
requestRequest.setInstanceCount(Integer.valueOf(1));
// Set the valid start time to be two minutes from now.
Calendar cal = Calendar.getInstance();
cal.add(Calendar.MINUTE, 2);
requestRequest.setValidFrom(cal.getTime());
// Set the valid end time to be two minutes and two hours from now.
cal.add(Calendar.HOUR, 2);
requestRequest.setValidUntil(cal.getTime());
// Set up the specifications of the launch. This includes
// the instance type (e.g. t1.micro)
// and the latest Amazon Linux AMI id available.
// Note, you should always use the latest Amazon
// Linux AMI id or another of your choosing.
LaunchSpecification launchSpecification = new LaunchSpecification();
launchSpecification.setImageId("ami-a9d09ed1");
launchSpecification.setInstanceType("t1.micro");
// Add the security group to the request.
ArrayList securityGroups = new ArrayList();
securityGroups.add("GettingStartedGroup");
launchSpecification.setSecurityGroups(securityGroups);
// Add the launch specification.
requestRequest.setLaunchSpecification(launchSpecification);
// Call the RequestSpotInstance API.
RequestSpotInstancesResult requestResult = ec2.requestSpotInstances(requestRequest);
```
## 分組 Spot Amazon EC2 執行個體請求
您可以選擇以數種不同的方式分組 Spot 執行個體請求。我們將探討使用啟動群組、可用區域群組和置放群組的優點。
如果您想要確保 Spot 執行個體一起啟動和終止，則可以選擇利用啟動群組。啟動群組是將一組出價分組在一起的標籤。啟動群組中的所有執行個體會同時啟動和終止。請注意，如果已滿足啟動群組中的執行個體，則無法保證也會滿足使用相同啟動群組啟動的新執行個體。下列程式碼範例顯示如何設定啟動群組的範例。
```
// Create the AmazonEC2 client so we can call various APIs.
AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
// Initializes a Spot Instance Request
RequestSpotInstancesRequest requestRequest = new RequestSpotInstancesRequest();
// Request 5 x t1.micro instance with a bid price of $0.03.
requestRequest.setSpotPrice("0.03");
requestRequest.setInstanceCount(Integer.valueOf(5));
// Set the launch group.
requestRequest.setLaunchGroup("ADVANCED-DEMO-LAUNCH-GROUP");
// Set up the specifications of the launch. This includes
// the instance type (e.g. t1.micro) and the latest Amazon Linux
// AMI id available. Note, you should always use the latest
// Amazon Linux AMI id or another of your choosing.
LaunchSpecification launchSpecification = new LaunchSpecification();
launchSpecification.setImageId("ami-a9d09ed1");
launchSpecification.setInstanceType(InstanceType.T1Micro);
// Add the security group to the request.
ArrayList securityGroups = new ArrayList();
securityGroups.add("GettingStartedGroup");
launchSpecification.setSecurityGroups(securityGroups);
// Add the launch specification.
requestRequest.setLaunchSpecification(launchSpecification);
// Call the RequestSpotInstance API.
RequestSpotInstancesResult requestResult =
ec2.requestSpotInstances(requestRequest);
```
如果您想要確保在相同可用區域中啟動請求中的所有執行個體，而且您不在乎哪個執行個體，您可以利用可用區域群組。可用區域群組是將一組執行個體分組在相同可用區域中的標籤。所有共用可用區域群組且同時履行的執行個體都會在相同的可用區域中開始。以下範例說明如何設定可用區域群組。
```
// Create the AmazonEC2 client so we can call various APIs.
AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
// Initializes a Spot Instance Request
RequestSpotInstancesRequest requestRequest = new RequestSpotInstancesRequest();
// Request 5 x t1.micro instance with a bid price of $0.03.
requestRequest.setSpotPrice("0.03");
requestRequest.setInstanceCount(Integer.valueOf(5));
// Set the availability zone group.
requestRequest.setAvailabilityZoneGroup("ADVANCED-DEMO-AZ-GROUP");
// Set up the specifications of the launch. This includes the instance
// type (e.g. t1.micro) and the latest Amazon Linux AMI id available.
// Note, you should always use the latest Amazon Linux AMI id or another
// of your choosing.
LaunchSpecification launchSpecification = new LaunchSpecification();
launchSpecification.setImageId("ami-a9d09ed1");
launchSpecification.setInstanceType(InstanceType.T1Micro);
// Add the security group to the request.
ArrayList securityGroups = new ArrayList();
securityGroups.add("GettingStartedGroup");
launchSpecification.setSecurityGroups(securityGroups);
// Add the launch specification.
requestRequest.setLaunchSpecification(launchSpecification);
// Call the RequestSpotInstance API.
RequestSpotInstancesResult requestResult =
ec2.requestSpotInstances(requestRequest);
```
您可以指定 Spot 執行個體所需的可用區域。下列程式碼範例示範如何設定可用區域。
```
// Create the AmazonEC2 client so we can call various APIs.
AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
// Initializes a Spot Instance Request
RequestSpotInstancesRequest requestRequest = new RequestSpotInstancesRequest();
// Request 1 x t1.micro instance with a bid price of $0.03.
requestRequest.setSpotPrice("0.03");
requestRequest.setInstanceCount(Integer.valueOf(1));
// Set up the specifications of the launch. This includes the instance
// type (e.g. t1.micro) and the latest Amazon Linux AMI id available.
// Note, you should always use the latest Amazon Linux AMI id or another
// of your choosing.
LaunchSpecification launchSpecification = new LaunchSpecification();
launchSpecification.setImageId("ami-a9d09ed1");
launchSpecification.setInstanceType(InstanceType.T1Micro);
// Add the security group to the request.
ArrayList securityGroups = new ArrayList();
securityGroups.add("GettingStartedGroup");
launchSpecification.setSecurityGroups(securityGroups);
// Set up the availability zone to use. Note we could retrieve the
// availability zones using the ec2.describeAvailabilityZones() API. For
// this demo we will just use us-east-1a.
SpotPlacement placement = new SpotPlacement("us-east-1b");
launchSpecification.setPlacement(placement);
// Add the launch specification.
requestRequest.setLaunchSpecification(launchSpecification);
// Call the RequestSpotInstance API.
RequestSpotInstancesResult requestResult =
ec2.requestSpotInstances(requestRequest);
```
最後，如果您使用的是高效能運算 (HPC) Spot 執行個體，例如叢集運算執行個體或叢集 GPU 執行個體，您可以指定*置放群組*。置放群組可在執行個體之間提供較低的延遲和高頻寬連線。以下範例說明如何設定置放群組。
```
// Create the AmazonEC2 client so we can call various APIs.
AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
// Initializes a Spot Instance Request
RequestSpotInstancesRequest requestRequest = new RequestSpotInstancesRequest();
// Request 1 x t1.micro instance with a bid price of $0.03.
requestRequest.setSpotPrice("0.03");
requestRequest.setInstanceCount(Integer.valueOf(1));
// Set up the specifications of the launch. This includes the instance
// type (e.g. t1.micro) and the latest Amazon Linux AMI id available.
// Note, you should always use the latest Amazon Linux AMI id or another
// of your choosing.
LaunchSpecification launchSpecification = new LaunchSpecification();
launchSpecification.setImageId("ami-a9d09ed1");
launchSpecification.setInstanceType(InstanceType.T1Micro);
// Add the security group to the request.
ArrayList securityGroups = new ArrayList();
securityGroups.add("GettingStartedGroup");
launchSpecification.setSecurityGroups(securityGroups);
// Set up the placement group to use with whatever name you desire.
// For this demo we will just use "ADVANCED-DEMO-PLACEMENT-GROUP".
SpotPlacement placement = new SpotPlacement();
placement.setGroupName("ADVANCED-DEMO-PLACEMENT-GROUP");
launchSpecification.setPlacement(placement);
// Add the launch specification.
requestRequest.setLaunchSpecification(launchSpecification);
// Call the RequestSpotInstance API.
RequestSpotInstancesResult requestResult =
ec2.requestSpotInstances(requestRequest);
```
本節顯示的所有參數都是選用的。也請務必了解，除了您的出價是一次性還是持久性之外，大多數這些參數都可能降低出價履行的可能性。因此，只有在您需要時才利用這些選項非常重要。上述所有程式碼範例都會合併為一個長程式碼範例，可在 `com.amazonaws.codesamples.advanced.InlineGettingStartedCodeSampleApp.java`類別中找到。
## 如何在中斷或終止後保留根分割區
管理 Spot 執行個體中斷最簡單的方式之一，就是確保您的資料定期檢查點至 Amazon Elastic Block Store (Amazon Amazon EBS) 磁碟區。透過定期檢查點，如果發生中斷，您只會遺失自上次檢查點之後建立的資料 （假設之間沒有執行其他非等冪動作）。若要讓此程序更簡單，您可以設定 Spot 請求，以確保根分割區不會在中斷或終止時遭到刪除。我們已在下列範例中插入新的程式碼，示範如何啟用此案例。
在新增的程式碼中，我們會建立`BlockDeviceMapping`物件，並將其 associated Amazon Elastic Block Store (Amazon EBS) 設定為在 Spot 執行個體終止時，已設定`not`刪除的 Amazon EBS 物件。然後`BlockDeviceMapping`，我們會將此新增至我們在啟動規格中包含的映射 ArrayList。
```
// Retrieves the credentials from an AWSCredentials.properties file.
AWSCredentials credentials = null;
try {
credentials = new PropertiesCredentials(
GettingStartedApp.class.getResourceAsStream("AwsCredentials.properties"));
}
catch (IOException e1) {
System.out.println(
"Credentials were not properly entered into AwsCredentials.properties.");
System.out.println(e1.getMessage());
System.exit(-1);
}
// Create the AmazonEC2 client so we can call various APIs.
AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
// Initializes a Spot Instance Request
RequestSpotInstancesRequest requestRequest = new RequestSpotInstancesRequest();
// Request 1 x t1.micro instance with a bid price of $0.03.
requestRequest.setSpotPrice("0.03");
requestRequest.setInstanceCount(Integer.valueOf(1));
// Set up the specifications of the launch. This includes the instance
// type (e.g. t1.micro) and the latest Amazon Linux AMI id available.
// Note, you should always use the latest Amazon Linux AMI id or another
// of your choosing.
LaunchSpecification launchSpecification = new LaunchSpecification();
launchSpecification.setImageId("ami-a9d09ed1");
launchSpecification.setInstanceType(InstanceType.T1Micro);
// Add the security group to the request.
ArrayList securityGroups = new ArrayList();
securityGroups.add("GettingStartedGroup");
launchSpecification.setSecurityGroups(securityGroups);
// Create the block device mapping to describe the root partition.
BlockDeviceMapping blockDeviceMapping = new BlockDeviceMapping();
blockDeviceMapping.setDeviceName("/dev/sda1");
// Set the delete on termination flag to false.
EbsBlockDevice ebs = new EbsBlockDevice();
ebs.setDeleteOnTermination(Boolean.FALSE);
blockDeviceMapping.setEbs(ebs);
// Add the block device mapping to the block list.
ArrayList blockList = new ArrayList();
blockList.add(blockDeviceMapping);
// Set the block device mapping configuration in the launch specifications.
launchSpecification.setBlockDeviceMappings(blockList);
// Add the launch specification.
requestRequest.setLaunchSpecification(launchSpecification);
// Call the RequestSpotInstance API.
RequestSpotInstancesResult requestResult =
ec2.requestSpotInstances(requestRequest);
```
假設您想要在啟動時將此磁碟區重新連接至執行個體，您也可以使用區塊型設備映射設定。或者，如果您連接了非根分割區，您可以在 Spot 執行個體恢復後指定要連接到 Spot 執行個體的 Amazon Amazon EBS 磁碟區。您只需在 中指定快照 ID，`EbsBlockDevice`並在 `BlockDeviceMapping` 物件中指定替代裝置名稱即可。透過利用區塊型設備映射，您可以更輕鬆地引導執行個體。
使用根分割區來檢查點您的關鍵資料，是管理執行個體中斷可能性的絕佳方式。如需管理中斷可能性的更多方法，請造訪[管理中斷](https://www.youtube.com/watch?feature=player_embedded&v=wcPNnUo60pc)影片。
## 如何標記 Spot 請求和執行個體
將標籤新增至 Amazon EC2 資源可以簡化雲端基礎設施的管理。標籤是一種中繼資料形式，可用來建立易用的名稱、增強可搜尋性，並改善多個使用者之間的協調性。您也可以使用標籤來自動化指令碼和部分程序。若要進一步了解標記 Amazon EC2 資源，請前往《Linux 執行個體 Amazon EC2 使用者指南》中的[使用標籤](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html)。
### 標記 請求
若要將標籤新增至 Spot 請求，您需要在請求*之後*標記它們。的傳回值`requestSpotInstances()`為您提供 [RequestSpotInstancesResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RequestSpotInstancesResult.html) 物件，您可以用來取得標記的 Spot IDs：
```
// Call the RequestSpotInstance API.
RequestSpotInstancesResult requestResult = ec2.requestSpotInstances(requestRequest);
List requestResponses = requestResult.getSpotInstanceRequests();
// A list of request IDs to tag
ArrayList spotInstanceRequestIds = new ArrayList();
// Add the request ids to the hashset, so we can determine when they hit the
// active state.
for (SpotInstanceRequest requestResponse : requestResponses) {
System.out.println("Created Spot Request: "+requestResponse.getSpotInstanceRequestId());
spotInstanceRequestIds.add(requestResponse.getSpotInstanceRequestId());
}
```
擁有 IDs後，您可以將請求IDs 新增至 [CreateTagsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateTagsRequest.html) 並呼叫 Amazon EC2 用戶端的 `createTags()`方法，以標記請求：
```
// The list of tags to create
ArrayList requestTags = new ArrayList();
requestTags.add(new Tag("keyname1","value1"));
// Create the tag request
CreateTagsRequest createTagsRequest_requests = new CreateTagsRequest();
createTagsRequest_requests.setResources(spotInstanceRequestIds);
createTagsRequest_requests.setTags(requestTags);
// Tag the spot request
try {
ec2.createTags(createTagsRequest_requests);
}
catch (AmazonServiceException e) {
System.out.println("Error terminating instances");
System.out.println("Caught Exception: " + e.getMessage());
System.out.println("Reponse Status Code: " + e.getStatusCode());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
}
```
### 標記執行個體
與 spot 請求本身類似，您只能在執行個體建立後標記執行個體，這會在 Spot 請求滿足後發生 （不再處於*開啟*狀態）。
您可以使用 [DescribeSpotInstanceRequestsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeSpotInstanceRequestsRequest.html) 物件呼叫 Amazon EC2 用戶端的 `describeSpotInstanceRequests()`方法，來檢查請求的狀態。傳回的 [DescribeSpotInstanceRequestsResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeSpotInstanceRequestsResult.html) 物件包含 [SpotInstanceRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/SpotInstanceRequest.html) 物件清單，您可以用來查詢 Spot 請求的狀態，並在執行個體不再處於*開啟*狀態時取得其執行個體 IDs。
一旦 Spot 請求不再開啟，您可以透過呼叫其`getInstanceId()`方法，從`SpotInstanceRequest`物件擷取其執行個體 ID。
```
boolean anyOpen; // tracks whether any requests are still open
// a list of instances to tag.
ArrayList instanceIds = new ArrayList();
do {
DescribeSpotInstanceRequestsRequest describeRequest =
new DescribeSpotInstanceRequestsRequest();
describeRequest.setSpotInstanceRequestIds(spotInstanceRequestIds);
anyOpen=false; // assume no requests are still open
try {
// Get the requests to monitor
DescribeSpotInstanceRequestsResult describeResult =
ec2.describeSpotInstanceRequests(describeRequest);
List describeResponses =
describeResult.getSpotInstanceRequests();
// are any requests open?
for (SpotInstanceRequest describeResponse : describeResponses) {
if (describeResponse.getState().equals("open")) {
anyOpen = true;
break;
}
// get the corresponding instance ID of the spot request
instanceIds.add(describeResponse.getInstanceId());
}
}
catch (AmazonServiceException e) {
// Don't break the loop due to an exception (it may be a temporary issue)
anyOpen = true;
}
try {
Thread.sleep(60*1000); // sleep 60s.
}
catch (Exception e) {
// Do nothing if the thread woke up early.
}
} while (anyOpen);
```
現在您可以標記傳回的執行個體：
```
// Create a list of tags to create
ArrayList instanceTags = new ArrayList();
instanceTags.add(new Tag("keyname1","value1"));
// Create the tag request
CreateTagsRequest createTagsRequest_instances = new CreateTagsRequest();
createTagsRequest_instances.setResources(instanceIds);
createTagsRequest_instances.setTags(instanceTags);
// Tag the instance
try {
ec2.createTags(createTagsRequest_instances);
}
catch (AmazonServiceException e) {
// Write out any exceptions that may have occurred.
System.out.println("Error terminating instances");
System.out.println("Caught Exception: " + e.getMessage());
System.out.println("Reponse Status Code: " + e.getStatusCode());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
}
```
## 取消 Spot 請求和終止執行個體
### 取消 Spot 請求
若要取消 Spot 執行個體請求，請在 Amazon EC2 用戶端`cancelSpotInstanceRequests`上使用 [CancelSpotInstanceRequestsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CancelSpotInstanceRequestsRequest.html) 物件呼叫 。
```
try {
CancelSpotInstanceRequestsRequest cancelRequest = new CancelSpotInstanceRequestsRequest(spotInstanceRequestIds);
ec2.cancelSpotInstanceRequests(cancelRequest);
} catch (AmazonServiceException e) {
System.out.println("Error cancelling instances");
System.out.println("Caught Exception: " + e.getMessage());
System.out.println("Reponse Status Code: " + e.getStatusCode());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
}
```
### 終止 Spot 執行個體
您可以透過將任何正在執行的 Spot 執行個體 IDs傳遞至 Amazon EC2 用戶端的 `terminateInstances()`方法來終止這些執行個體。
```
try {
TerminateInstancesRequest terminateRequest = new TerminateInstancesRequest(instanceIds);
ec2.terminateInstances(terminateRequest);
} catch (AmazonServiceException e) {
System.out.println("Error terminating instances");
System.out.println("Caught Exception: " + e.getMessage());
System.out.println("Reponse Status Code: " + e.getStatusCode());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
}
```
## 全部整合
為了將這些整合在一起，我們提供更以物件為導向的方法，將我們在本教學課程中顯示的步驟合併為一個易於使用的類別。我們會執行個體化名為 的類別`Requests`，以執行這些動作。我們也建立一個`GettingStartedApp`類別，它具有主要方法，用於執行高階函數呼叫。
您可以在 [GitHub](https://github.com/aws/aws-sdk-java/tree/master/src/samples/AmazonEC2SpotInstances-Advanced) 檢視或下載此範例的完整原始程式碼。
恭喜您！您已完成使用 開發 Spot 執行個體軟體的進階請求功能教學課程 適用於 Java 的 AWS SDK。
# 管理 Amazon EC2 執行個體
## 建立執行個體
透過呼叫 AmazonEC2Client 的 `runInstances`方法建立新的 Amazon EC2 執行個體，提供 [RunInstancesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RunInstancesRequest.html)，其中包含要使用的 [Amazon Machine Image (AMI)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) 和[執行個體類型](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html)。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.InstanceType;
import com.amazonaws.services.ec2.model.RunInstancesRequest;
import com.amazonaws.services.ec2.model.RunInstancesResult;
import com.amazonaws.services.ec2.model.Tag;
```
**Code**
```
RunInstancesRequest run_request = new RunInstancesRequest()
.withImageId(ami_id)
.withInstanceType(InstanceType.T1Micro)
.withMaxCount(1)
.withMinCount(1);
RunInstancesResult run_response = ec2.runInstances(run_request);
String reservation_id = run_response.getReservation().getInstances().get(0).getInstanceId();
```
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/CreateInstance.java)。
## 啟動執行個體
若要啟動 Amazon EC2 執行個體，請呼叫 AmazonEC2Client 的 `startInstances`方法，為其提供 [StartInstancesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/StartInstancesRequest.html)，其中包含要啟動的執行個體 ID。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.StartInstancesRequest;
```
**Code**
```
final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
StartInstancesRequest request = new StartInstancesRequest()
.withInstanceIds(instance_id);
ec2.startInstances(request);
```
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/StartStopInstance.java)。
## 停止執行個體
若要停止 Amazon EC2 執行個體，請呼叫 AmazonEC2Client 的 `stopInstances`方法，為其提供 [StopInstancesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/StopInstancesRequest.html)，其中包含要停止的執行個體 ID。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.StopInstancesRequest;
```
**Code**
```
final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
StopInstancesRequest request = new StopInstancesRequest()
.withInstanceIds(instance_id);
ec2.stopInstances(request);
```
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/StartStopInstance.java)。
## 重新啟動執行個體
若要重新啟動 Amazon EC2 執行個體，請呼叫 AmazonEC2Client 的 `rebootInstances`方法，為其提供 [RebootInstancesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RebootInstancesRequest.html)，其中包含要重新啟動的執行個體 ID。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.RebootInstancesRequest;
import com.amazonaws.services.ec2.model.RebootInstancesResult;
```
**Code**
```
final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
RebootInstancesRequest request = new RebootInstancesRequest()
.withInstanceIds(instance_id);
RebootInstancesResult response = ec2.rebootInstances(request);
```
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/RebootInstance.java)。
## 描述執行個體
若要列出您的執行個體，請建立 [DescribeInstancesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeInstancesRequest.html) 並呼叫 AmazonEC2Client 的 `describeInstances`方法。它會傳回 [DescribeInstancesResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeInstancesResult.html) 物件，您可以用來列出您帳戶和區域的 Amazon EC2 執行個體。
執行個體依照*保留*分組。每個保留對應到呼叫 `startInstances`，用以啟動執行個體。若要列出您的執行個體，您必須先在每個傳回的[預留](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/Reservation.html)物件`getReservations' method, and then call `getInstances`上呼叫 `DescribeInstancesResult`類別。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.DescribeInstancesRequest;
import com.amazonaws.services.ec2.model.DescribeInstancesResult;
import com.amazonaws.services.ec2.model.Instance;
import com.amazonaws.services.ec2.model.Reservation;
```
**Code**
```
final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
boolean done = false;
DescribeInstancesRequest request = new DescribeInstancesRequest();
while(!done) {
DescribeInstancesResult response = ec2.describeInstances(request);
for(Reservation reservation : response.getReservations()) {
for(Instance instance : reservation.getInstances()) {
System.out.printf(
"Found instance with id %s, " +
"AMI %s, " +
"type %s, " +
"state %s " +
"and monitoring state %s",
instance.getInstanceId(),
instance.getImageId(),
instance.getInstanceType(),
instance.getState().getName(),
instance.getMonitoring().getState());
}
}
request.setNextToken(response.getNextToken());
if(response.getNextToken() == null) {
done = true;
}
}
```
結果是分頁的；您可以將結果物件的 `getNextToken`方法傳回的值傳遞至原始請求物件的 `setNextToken`方法，然後在下一次呼叫 時使用相同的請求物件，以取得進一步的結果`describeInstances`。
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DescribeInstances.java)。
## 監控執行個體
您可以監控 Amazon EC2 執行個體的各個層面，例如 CPU 和網路使用率、可用的記憶體，以及剩餘的磁碟空間。若要進一步了解執行個體監控，請參閱《Linux 執行個體 Amazon EC2 使用者指南》中的[監控 Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/monitoring_ec2.html)。
若要開始監控執行個體，您必須使用要監控的執行個體 ID 建立 [MonitorInstancesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/MonitorInstancesRequest.html)，並將其傳遞至 AmazonEC2Client 的 `monitorInstances`方法。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.MonitorInstancesRequest;
```
**Code**
```
final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
MonitorInstancesRequest request = new MonitorInstancesRequest()
.withInstanceIds(instance_id);
ec2.monitorInstances(request);
```
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/MonitorInstance.java)。
## 停止執行個體監控
若要停止監控執行個體，請使用執行個體的 ID 建立 [UnmonitorInstancesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/UnmonitorInstancesRequest.html) 以停止監控，並將其傳遞至 AmazonEC2Client 的 `unmonitorInstances`方法。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.UnmonitorInstancesRequest;
```
**Code**
```
final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
UnmonitorInstancesRequest request = new UnmonitorInstancesRequest()
.withInstanceIds(instance_id);
ec2.unmonitorInstances(request);
```
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/MonitorInstance.java)。
## 詳細資訊
+ Amazon EC2 API 參考中的 [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html)
+ Amazon EC2 API 參考中的 [DescribeInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html)
+ Amazon EC2 API 參考中的 [StartInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_StartInstances.html)
+ Amazon EC2 API 參考中的 [StopInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_StopInstances.html)
+ API Amazon EC2 參考中的 [RebootInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RebootInstances.html)
+ Amazon EC2 API 參考中的 [MonitorInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_MonitorInstances.html)
+ Amazon EC2 API 參考中的 [UnmonitorInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_UnmonitorInstances.html)
# 在 中使用彈性 IP 地址 Amazon EC2
## EC2-Classic 正在淘汰
**警告**
我們將於 2022 年 8 月 15 日淘汰 EC2-Classic。建議您從 EC2-Classic 遷移至 VPC。如需詳細資訊，請參閱部落格文章 [EC2-Classic-Classic Networking 正在淘汰 – 以下說明如何準備](https://aws.amazon.com/blogs/aws/ec2-classic-is-retiring-heres-how-to-prepare/)。
## 配置彈性 IP 地址
若要使用彈性 IP 位址，您可以先將一個地址配置給帳戶，再將其與您的執行個體或網路介面建立關聯。
若要配置彈性 IP 地址，請使用包含 網路類型的 [AllocateAddressRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AllocateAddressRequest.html) 物件 （傳統 EC2 或 VPC) 呼叫 AmazonEC2Client 的 `allocateAddress`方法。
傳回的 [AllocateAddressResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AllocateAddressResult.html) 包含配置 ID，您可以透過將 [AssociateAddressRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AssociateAddressRequest.html) 中的配置 ID 和執行個體 ID 傳遞至 AmazonEC2Client 的 `associateAddress`方法，來用來將地址與執行個體建立關聯。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.AllocateAddressRequest;
import com.amazonaws.services.ec2.model.AllocateAddressResult;
import com.amazonaws.services.ec2.model.AssociateAddressRequest;
import com.amazonaws.services.ec2.model.AssociateAddressResult;
import com.amazonaws.services.ec2.model.DomainType;
```
**Code**
```
final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
AllocateAddressRequest allocate_request = new AllocateAddressRequest()
.withDomain(DomainType.Vpc);
AllocateAddressResult allocate_response =
ec2.allocateAddress(allocate_request);
String allocation_id = allocate_response.getAllocationId();
AssociateAddressRequest associate_request =
new AssociateAddressRequest()
.withInstanceId(instance_id)
.withAllocationId(allocation_id);
AssociateAddressResult associate_response =
ec2.associateAddress(associate_request);
```
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/AllocateAddress.java)。
## 描述彈性 IP 地址
若要列出指派給您帳戶的彈性 IP 地址，請呼叫 AmazonEC2Client 的 `describeAddresses`方法。它會傳回 [DescribeAddressesResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeAddressesResult.html)，您可以使用它來取得代表您帳戶中彈性 IP 地址的[位址](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/Address.html)物件清單。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.Address;
import com.amazonaws.services.ec2.model.DescribeAddressesResult;
```
**Code**
```
final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
DescribeAddressesResult response = ec2.describeAddresses();
for(Address address : response.getAddresses()) {
System.out.printf(
"Found address with public IP %s, " +
"domain %s, " +
"allocation id %s " +
"and NIC id %s",
address.getPublicIp(),
address.getDomain(),
address.getAllocationId(),
address.getNetworkInterfaceId());
}
```
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DescribeAddresses.java)。
## 釋放彈性 IP 地址
若要釋出彈性 IP 地址，請呼叫 AmazonEC2Client 的 `releaseAddress`方法，將包含您要釋出之彈性 IP 地址配置 ID 的 [ReleaseAddressRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/ReleaseAddressRequest.html) 傳遞給它。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.ReleaseAddressRequest;
import com.amazonaws.services.ec2.model.ReleaseAddressResult;
```
**Code**
```
final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
ReleaseAddressRequest request = new ReleaseAddressRequest()
.withAllocationId(alloc_id);
ReleaseAddressResult response = ec2.releaseAddress(request);
```
釋出彈性 IP 地址後，該地址會釋出到 AWS IP 地址集區，您之後可能無法使用。請務必更新您的 DNS 記錄以及與該地址通訊的任何伺服器或裝置。如果您嘗試釋出已釋出的彈性 IP 地址，如果地址已配置給另一個 ，則會收到 *AuthFailure* 錯誤 AWS 帳戶。
如果您使用 *EC2-Classic* 或*預設 VPC*，則釋出彈性 IP 地址會自動將其與任何已關聯的執行個體取消關聯。若要取消與彈性 IP 地址的關聯而不將其釋出，請使用 AmazonEC2Client 的 `disassociateAddress`方法。
如果您是使用非預設 VPC，在嘗試釋出該彈性 IP 地址前，您*必須*先使用 `disassociateAddress` 將其取消關聯。否則， 會 Amazon EC2 傳回錯誤 (*InvalidIPAddress.InUse*)。
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/ReleaseAddress.java)。
## 詳細資訊
+ Linux 執行個體 Amazon EC2 使用者指南中的[彈性 IP 地址](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html)
+ Amazon EC2 API 參考中的 [AllocateAddress](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_AllocateAddress.html)
+ Amazon EC2 API 參考中的 [DescribeAddresses](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeAddresses.html)
+ Amazon EC2 API 參考中的 [ReleaseAddress](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ReleaseAddress.html)
# 使用區域和可用區域
## 描述區域
若要列出您的帳戶可用的區域，請呼叫 AmazonEC2Client 的 `describeRegions`方法。它會傳回 [DescribeRegionsResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeRegionsResult.html)。呼叫傳回物件的 `getRegions` 方法以取得代表每個區域的 [Region](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/Region.html) 物件清單。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.DescribeRegionsResult;
import com.amazonaws.services.ec2.model.Region;
import com.amazonaws.services.ec2.model.AvailabilityZone;
import com.amazonaws.services.ec2.model.DescribeAvailabilityZonesResult;
```
**Code**
```
DescribeRegionsResult regions_response = ec2.describeRegions();
for(Region region : regions_response.getRegions()) {
System.out.printf(
"Found region %s " +
"with endpoint %s",
region.getRegionName(),
region.getEndpoint());
}
```
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DescribeRegionsAndZones.java)。
## 描述可用區域
若要列出您帳戶可用的每個可用區域，請呼叫 AmazonEC2Client 的 `describeAvailabilityZones`方法。它會傳回 [DescribeAvailabilityZonesResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeAvailabilityZonesResult.html)。呼叫其 `getAvailabilityZones` 方法以取得代表每個可用區域的 [AvailabilityZone](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AvailabilityZone.html) 物件清單。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.DescribeRegionsResult;
import com.amazonaws.services.ec2.model.Region;
import com.amazonaws.services.ec2.model.AvailabilityZone;
import com.amazonaws.services.ec2.model.DescribeAvailabilityZonesResult;
```
**Code**
```
DescribeAvailabilityZonesResult zones_response =
ec2.describeAvailabilityZones();
for(AvailabilityZone zone : zones_response.getAvailabilityZones()) {
System.out.printf(
"Found availability zone %s " +
"with status %s " +
"in region %s",
zone.getZoneName(),
zone.getState(),
zone.getRegionName());
}
```
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DescribeRegionsAndZones.java)。
## 描述帳戶
若要描述您的帳戶，請呼叫 AmazonEC2Client 的 `describeAccountAttributes`方法。此方法會傳回 [DescribeAccountAttributesResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeAccountAttributesResult.html) 物件。叫用此物件的 `getAccountAttributes` 方法來取得 [AccountAttribute](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AccountAttribute.html) 物件的清單。您可以逐一查看清單以擷取 [AccountAttribute](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AccountAttribute.html) 物件。
您可以透過叫用 [AccountAttribute](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AccountAttribute.html) 對象的 `getAttributeValues` 方法來取得您帳戶的屬性值。此方法會傳回 [AccountAttributeValue](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AccountAttributeValue.html) 物件的清單。您可以逐一查看第二個清單以顯示屬性值 (請參閱下列程式碼範例)。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.AccountAttributeValue;
import com.amazonaws.services.ec2.model.DescribeAccountAttributesResult;
import com.amazonaws.services.ec2.model.AccountAttribute;
import java.util.List;
import java.util.ListIterator;
```
**Code**
```
AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
try{
DescribeAccountAttributesResult accountResults = ec2.describeAccountAttributes();
List accountList = accountResults.getAccountAttributes();
for (ListIterator iter = accountList.listIterator(); iter.hasNext(); ) {
AccountAttribute attribute = (AccountAttribute) iter.next();
System.out.print("\n The name of the attribute is "+attribute.getAttributeName());
List values = attribute.getAttributeValues();
//iterate through the attribute values
for (ListIterator iterVals = values.listIterator(); iterVals.hasNext(); ) {
AccountAttributeValue myValue = (AccountAttributeValue) iterVals.next();
System.out.print("\n The value of the attribute is "+myValue.getAttributeValue());
}
}
System.out.print("Done");
}
catch (Exception e)
{
e.getStackTrace();
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DescribeAccount.java)。
## 其他資訊
+ Linux 執行個體 Amazon EC2 使用者指南中的[區域和可用區域](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html)
+ Amazon EC2 API 參考中的 [DescribeRegions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeRegions.html)
+ Amazon EC2 API 參考中的 [DescribeAvailabilityZones](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeAvailabilityZones.html)
# 使用 Amazon EC2 金鑰對
## 建立金鑰對
若要建立金鑰對，請使用包含金鑰名稱的 [CreateKeyPairRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateKeyPairRequest.html) 呼叫 AmazonEC2Client 的 `createKeyPair`方法。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.CreateKeyPairRequest;
import com.amazonaws.services.ec2.model.CreateKeyPairResult;
```
**Code**
```
final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
CreateKeyPairRequest request = new CreateKeyPairRequest()
.withKeyName(key_name);
CreateKeyPairResult response = ec2.createKeyPair(request);
```
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/CreateKeyPair.java)。
## 描述金鑰對
若要列出金鑰對或取得相關資訊，請呼叫 AmazonEC2Client 的 `describeKeyPairs`方法。它會傳回 [DescribeKeyPairsResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeKeyPairsResult.html)，您可以透過呼叫其`getKeyPairs`方法來存取金鑰對的清單，這會傳回 [KeyPairInfo](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/KeyPairInfo.html) 物件的清單。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.DescribeKeyPairsResult;
import com.amazonaws.services.ec2.model.KeyPairInfo;
```
**Code**
```
final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
DescribeKeyPairsResult response = ec2.describeKeyPairs();
for(KeyPairInfo key_pair : response.getKeyPairs()) {
System.out.printf(
"Found key pair with name %s " +
"and fingerprint %s",
key_pair.getKeyName(),
key_pair.getKeyFingerprint());
}
```
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DescribeKeyPairs.java)。
## 刪除金鑰對
若要刪除金鑰對，請呼叫 AmazonEC2Client 的 `deleteKeyPair`方法，並向其傳遞 [DeleteKeyPairRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DeleteKeyPairRequest.html)，其中包含要刪除的金鑰對名稱。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.DeleteKeyPairRequest;
import com.amazonaws.services.ec2.model.DeleteKeyPairResult;
```
**Code**
```
final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
DeleteKeyPairRequest request = new DeleteKeyPairRequest()
.withKeyName(key_name);
DeleteKeyPairResult response = ec2.deleteKeyPair(request);
```
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DeleteKeyPair.java)。
## 詳細資訊
+ Linux 執行個體 Amazon EC2 使用者指南中的[Amazon EC2 金鑰對](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html)
+ Amazon EC2 API 參考中的 [CreateKeyPair](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CreateKeyPair.html)
+ Amazon EC2 API 參考中的 [DescribeKeyPairs](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeKeyPairs.html)
+ Amazon EC2 API 參考中的 [DeleteKeyPair](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DeleteKeyPair.html)
# 在 中使用安全群組 Amazon EC2
## 建立安全群組
若要建立安全群組，請使用包含金鑰名稱的 [CreateSecurityGroupRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateSecurityGroupRequest.html) 呼叫 AmazonEC2Client 的 `createSecurityGroup`方法。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.CreateSecurityGroupRequest;
import com.amazonaws.services.ec2.model.CreateSecurityGroupResult;
```
**Code**
```
final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
CreateSecurityGroupRequest create_request = new
CreateSecurityGroupRequest()
.withGroupName(group_name)
.withDescription(group_desc)
.withVpcId(vpc_id);
CreateSecurityGroupResult create_response =
ec2.createSecurityGroup(create_request);
```
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/CreateSecurityGroup.java)。
## 設定安全群組
安全群組可以控制執行個體的傳入 （傳入） 和傳出 （傳出） 流量 Amazon EC2 。
若要將輸入規則新增至您的安全群組，請使用 AmazonEC2Client 的 `authorizeSecurityGroupIngress`方法，提供安全群組的名稱，以及您想要在 [AuthorizeSecurityGroupIngressRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AuthorizeSecurityGroupIngressRequest.html) 物件中為其指派的存取規則 ([IpPermission](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/IpPermission.html))。以下範例說明如何將 IP 許可新增至安全群組。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.CreateSecurityGroupRequest;
import com.amazonaws.services.ec2.model.CreateSecurityGroupResult;
```
**Code**
```
IpRange ip_range = new IpRange()
.withCidrIp("0.0.0.0/0");
IpPermission ip_perm = new IpPermission()
.withIpProtocol("tcp")
.withToPort(80)
.withFromPort(80)
.withIpv4Ranges(ip_range);
IpPermission ip_perm2 = new IpPermission()
.withIpProtocol("tcp")
.withToPort(22)
.withFromPort(22)
.withIpv4Ranges(ip_range);
AuthorizeSecurityGroupIngressRequest auth_request = new
AuthorizeSecurityGroupIngressRequest()
.withGroupName(group_name)
.withIpPermissions(ip_perm, ip_perm2);
AuthorizeSecurityGroupIngressResult auth_response =
ec2.authorizeSecurityGroupIngress(auth_request);
```
若要將輸出規則新增至安全群組，請將 [AuthorizeSecurityGroupEgressRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AuthorizeSecurityGroupEgressRequest.html) 中的類似資料提供給 AmazonEC2Client 的 `authorizeSecurityGroupEgress`方法。
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/CreateSecurityGroup.java)。
## 描述安全群組
若要描述您的安全群組或取得相關資訊，請呼叫 AmazonEC2Client 的 `describeSecurityGroups`方法。它會傳回 [DescribeSecurityGroupsResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeSecurityGroupsResult.html)，您可以透過呼叫其`getSecurityGroups`方法來存取安全群組清單，這會傳回 [SecurityGroup](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/ec2/model/SecurityGroup.html) 物件清單。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.DescribeSecurityGroupsRequest;
import com.amazonaws.services.ec2.model.DescribeSecurityGroupsResult;
```
**Code**
```
final String USAGE =
"To run this example, supply a group id\n" +
"Ex: DescribeSecurityGroups \n";
if (args.length != 1) {
System.out.println(USAGE);
System.exit(1);
}
String group_id = args[0];
```
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DescribeSecurityGroups.java)。
## 刪除安全群組
若要刪除安全群組，請呼叫 AmazonEC2Client 的 `deleteSecurityGroup`方法，並向其傳遞 [DeleteSecurityGroupRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DeleteSecurityGroupRequest.html)，其中包含要刪除的安全群組 ID。
**匯入**
```
import com.amazonaws.services.ec2.AmazonEC2;
import com.amazonaws.services.ec2.AmazonEC2ClientBuilder;
import com.amazonaws.services.ec2.model.DeleteSecurityGroupRequest;
import com.amazonaws.services.ec2.model.DeleteSecurityGroupResult;
```
**Code**
```
final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
DeleteSecurityGroupRequest request = new DeleteSecurityGroupRequest()
.withGroupId(group_id);
DeleteSecurityGroupResult response = ec2.deleteSecurityGroup(request);
```
請參閱[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DeleteSecurityGroup.java)。
## 詳細資訊
+ Linux 執行個體 Amazon EC2 使用者指南中的[Amazon EC2 安全群組](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html)
+ 《[Linux 執行個體使用者指南》中的授權 Linux 執行個體的傳入流量](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/authorizing-access-to-an-instance.html) Amazon EC2
+ Amazon EC2 API 參考中的 [CreateSecurityGroup](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CreateSecurityGroup.html)
+ Amazon EC2 API 參考中的 [DescribeSecurityGroups](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSecurityGroups.html)
+ Amazon EC2 API 參考中的 [DeleteSecurityGroup](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DeleteSecurityGroup.html)
+ Amazon EC2 API 參考中的 [AuthorizeSecurityGroupIngress](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_AuthorizeSecurityGroupIngress.html)
# 使用 的 IAM 範例 適用於 Java 的 AWS SDK
本節提供使用 程式設計 [IAM](https://aws.amazon.com/iam/) 的範例[適用於 Java 的 AWS SDK](https://aws.amazon.com/sdk-for-java/)。
AWS Identity and Access Management (IAM) 可讓您安全地控制使用者對 AWS 服務和資源的存取。使用 IAM，您可以建立和管理 AWS 使用者和群組，並使用許可來允許和拒絕他們存取 AWS 資源。如需 IAM 的完整指南，請造訪 [IAM 使用者指南](https://docs.aws.amazon.com/IAM/latest/UserGuide/)。
**注意**
這些範例僅包含示範每種技術所需的程式碼。[GitHub 上提供完整程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java)。您可以從那裡下載單一原始檔案或將儲存庫複製到本機，以取得建置和執行的所有範例。
**Topics**
+ [管理 IAM 存取金鑰](examples-iam-access-keys.md)
+ [管理 IAM 使用者](examples-iam-users.md)
+ [使用 IAM 帳戶別名](examples-iam-account-aliases.md)
+ [處理 IAM 政策](examples-iam-policies.md)
+ [處理 IAM 伺服器憑證](examples-iam-server-certificates.md)
# 管理 IAM 存取金鑰
## 建立存取金鑰
若要建立 IAM 存取金鑰，請使用 [CreateAccessKeyRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/CreateAccessKeyRequest.html) 物件呼叫 AmazonIdentityManagementClient`createAccessKey` 方法。
`CreateAccessKeyRequest` 有兩個建構函數：一個採用使用者名稱，另一個沒有參數。如果您使用不使用參數的版本，則必須使用 `withUserName` setter 方法設定使用者名稱，然後再將其傳遞給 `createAccessKey`方法。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.CreateAccessKeyRequest;
import com.amazonaws.services.identitymanagement.model.CreateAccessKeyResult;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
CreateAccessKeyRequest request = new CreateAccessKeyRequest()
.withUserName(user);
CreateAccessKeyResult response = iam.createAccessKey(request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/CreateAccessKey.java)。
## 列出存取金鑰
若要列出指定使用者的存取金鑰，請建立 [ListAccessKeysRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/ListAccessKeysRequest.html) 物件，其中包含要列出金鑰的使用者名稱，並將其傳遞至 AmazonIdentityManagementClient 的 `listAccessKeys`方法。
**注意**
如果您未提供使用者名稱給 `listAccessKeys`，則會嘗試列出與簽署請求 AWS 帳戶 之 相關聯的存取金鑰。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.AccessKeyMetadata;
import com.amazonaws.services.identitymanagement.model.ListAccessKeysRequest;
import com.amazonaws.services.identitymanagement.model.ListAccessKeysResult;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
boolean done = false;
ListAccessKeysRequest request = new ListAccessKeysRequest()
.withUserName(username);
while (!done) {
ListAccessKeysResult response = iam.listAccessKeys(request);
for (AccessKeyMetadata metadata :
response.getAccessKeyMetadata()) {
System.out.format("Retrieved access key %s",
metadata.getAccessKeyId());
}
request.setMarker(response.getMarker());
if (!response.getIsTruncated()) {
done = true;
}
}
```
`listAccessKeys` 的結果會分頁 (每個呼叫預設最多 100 個記錄)。您可以在傳回的 [ListAccessKeysResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/ListAccessKeysResult.html) 物件`getIsTruncated`上呼叫 ，以查看查詢是否傳回較少的結果，則可供使用。如果是這樣，請在 `setMarker`上呼叫 ，`ListAccessKeysRequest`並將其傳遞給下一次叫用 `listAccessKeys`。
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/ListAccessKeys.java)。
## 擷取存取金鑰的上次使用時間
若要取得上次使用存取金鑰的時間，請呼叫 AmazonIdentityManagementClient 的 `getAccessKeyLastUsed`方法與存取金鑰的 ID （可以使用 [GetAccessKeyLastUsedRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/GetAccessKeyLastUsedRequest.html) 物件傳入，或直接傳送到直接取得存取金鑰 ID 的過載。
然後，您可以使用傳回的 [GetAccessKeyLastUsedResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/GetAccessKeyLastUsedResult.html) 物件來擷取金鑰的上次使用時間。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.GetAccessKeyLastUsedRequest;
import com.amazonaws.services.identitymanagement.model.GetAccessKeyLastUsedResult;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
GetAccessKeyLastUsedRequest request = new GetAccessKeyLastUsedRequest()
.withAccessKeyId(access_id);
GetAccessKeyLastUsedResult response = iam.getAccessKeyLastUsed(request);
System.out.println("Access key was last used at: " +
response.getAccessKeyLastUsed().getLastUsedDate());
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/AccessKeyLastUsed.java)。
## 啟用或停用存取金鑰
您可以透過建立 [UpdateAccessKeyRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/UpdateAccessKeyRequest.html) 物件、提供存取金鑰 ID、選擇性地提供使用者名稱和所需[狀態](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/StatusType.html)來啟用或停用存取金鑰，然後將請求物件傳遞至 AmazonIdentityManagementClient 的 `updateAccessKey`方法。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.UpdateAccessKeyRequest;
import com.amazonaws.services.identitymanagement.model.UpdateAccessKeyResult;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
UpdateAccessKeyRequest request = new UpdateAccessKeyRequest()
.withAccessKeyId(access_id)
.withUserName(username)
.withStatus(status);
UpdateAccessKeyResult response = iam.updateAccessKey(request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/UpdateAccessKey.java)。
## 刪除存取金鑰
若要永久刪除存取金鑰，請呼叫 AmazonIdentityManagementClient 的 `deleteKey`方法，為其提供 [DeleteAccessKeyRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/DeleteAccessKeyRequest.html)，其中包含存取金鑰的 ID 和使用者名稱。
**注意**
金鑰一旦刪除，就不能再擷取或使用。若要暫時停用金鑰，稍後再行啟動，請改為使用 [updateAccessKey](#iam-access-keys-update) 方法。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.DeleteAccessKeyRequest;
import com.amazonaws.services.identitymanagement.model.DeleteAccessKeyResult;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
DeleteAccessKeyRequest request = new DeleteAccessKeyRequest()
.withAccessKeyId(access_key)
.withUserName(username);
DeleteAccessKeyResult response = iam.deleteAccessKey(request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/DeleteAccessKey.java)。
## 詳細資訊
+ IAM API 參考中的 [CreateAccessKey](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateAccessKey.html)
+ IAM API 參考中的 [ListAccessKeys](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListAccessKeys.html)
+ IAM API 參考中的 [GetAccessKeyLastUsed](https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetAccessKeyLastUsed.html)
+ IAM API 參考中的 [UpdateAccessKey](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateAccessKey.html)
+ IAM API 參考中的 [DeleteAccessKey](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteAccessKey.html)
# 管理 IAM 使用者
## 建立使用者
直接或使用包含使用者名稱的 [CreateUserRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/CreateUserRequest.html) 物件，將使用者名稱提供給 AmazonIdentityManagementClient 的 `createUser`方法，以建立新的 IAM 使用者。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.CreateUserRequest;
import com.amazonaws.services.identitymanagement.model.CreateUserResult;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
CreateUserRequest request = new CreateUserRequest()
.withUserName(username);
CreateUserResult response = iam.createUser(request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/CreateUser.java)。
## 列出使用者
若要列出帳戶的 IAM 使用者，請建立新的 [ListUsersRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/ListUsersRequest.html)，並將其傳遞至 AmazonIdentityManagementClient 的 `listUsers`方法。您可以在傳回的 [ListUsersResult](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/identitymanagement/model/ListUsersResult.html) 物件`getUsers`上呼叫 來擷取使用者清單。
`listUsers` 傳回的使用者清單會分頁。您可以呼叫回應物件的 `getIsTruncated` 方法，檢查是否有更多可擷取的結果。如果傳回 `true`，則呼叫請求物件的 `setMarker()`方法，傳遞回應物件`getMarker()`方法的傳回值。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.ListUsersRequest;
import com.amazonaws.services.identitymanagement.model.ListUsersResult;
import com.amazonaws.services.identitymanagement.model.User;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
boolean done = false;
ListUsersRequest request = new ListUsersRequest();
while(!done) {
ListUsersResult response = iam.listUsers(request);
for(User user : response.getUsers()) {
System.out.format("Retrieved user %s", user.getUserName());
}
request.setMarker(response.getMarker());
if(!response.getIsTruncated()) {
done = true;
}
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/ListUsers.java)。
## 更新使用者
若要更新使用者，請呼叫 AmazonIdentityManagementClient 物件的 `updateUser`方法，該方法採用 [UpdateUserRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/UpdateUserRequest.html) 物件，您可以用來變更使用者名稱**或*路徑*。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.UpdateUserRequest;
import com.amazonaws.services.identitymanagement.model.UpdateUserResult;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
UpdateUserRequest request = new UpdateUserRequest()
.withUserName(cur_name)
.withNewUserName(new_name);
UpdateUserResult response = iam.updateUser(request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/UpdateUser.java)。
## 刪除使用者
若要刪除使用者，請使用 [UpdateUserRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/UpdateUserRequest.html) 物件集呼叫 AmazonIdentityManagementClient 的`deleteUser`請求，並設定要刪除的使用者名稱。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.DeleteConflictException;
import com.amazonaws.services.identitymanagement.model.DeleteUserRequest;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
DeleteUserRequest request = new DeleteUserRequest()
.withUserName(username);
try {
iam.deleteUser(request);
} catch (DeleteConflictException e) {
System.out.println("Unable to delete user. Verify user is not" +
" associated with any resources");
throw e;
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/DeleteUser.java)。
## 詳細資訊
+ 《 使用者指南》中的 [IAM 使用者](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html) IAM
+ 《 使用者指南》中的[管理 IAM 使用者](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_manage.html) IAM
+ IAM API 參考中的 [CreateUser](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateUser.html)
+ IAM API 參考中的 [ListUsers](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListUsers.html)
+ IAM API 參考中的 [UpdateUser](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateUser.html)
+ IAM API 參考中的 [DeleteUser](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteUser.html)
# 使用 IAM 帳戶別名
如果您希望登入頁面的 URL 包含您的公司名稱或其他易記識別符，而不是您的 AWS 帳戶 ID，您可以為您的 建立別名 AWS 帳戶。
**注意**
AWS 每個帳戶僅支援一個帳戶別名。
## 建立帳戶別名
若要建立帳戶別名，請使用包含別名名稱的 [CreateAccountAliasRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/CreateAccountAliasRequest.html) 物件呼叫 AmazonIdentityManagementClient 的 `createAccountAlias`方法。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.CreateAccountAliasRequest;
import com.amazonaws.services.identitymanagement.model.CreateAccountAliasResult;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
CreateAccountAliasRequest request = new CreateAccountAliasRequest()
.withAccountAlias(alias);
CreateAccountAliasResult response = iam.createAccountAlias(request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/CreateAccountAlias.java)。
## 列出帳戶別名
若要列出您帳戶的別名，如果有的話，請呼叫 AmazonIdentityManagementClient 的 `listAccountAliases`方法。
**注意**
傳回的 [ListAccountAliasesResult](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/identitymanagement/model/ListAccountAliasesResult.html) 支援與其他 適用於 Java 的 AWS SDK *清單*`getMarker`方法相同的 `getIsTruncated`和 方法，但 只能 AWS 帳戶 有一個**帳戶別名。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.ListAccountAliasesResult;
```
**code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
ListAccountAliasesResult response = iam.listAccountAliases();
for (String alias : response.getAccountAliases()) {
System.out.printf("Retrieved account alias %s", alias);
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/ListAccountAliases.java)。
## 刪除帳戶別名
若要刪除帳戶的別名，請呼叫 AmazonIdentityManagementClient 的 `deleteAccountAlias`方法。刪除帳戶別名時，您必須使用 [DeleteAccountAliasRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/DeleteAccountAliasRequest.html) 物件提供其名稱。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.DeleteAccountAliasRequest;
import com.amazonaws.services.identitymanagement.model.DeleteAccountAliasResult;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
DeleteAccountAliasRequest request = new DeleteAccountAliasRequest()
.withAccountAlias(alias);
DeleteAccountAliasResult response = iam.deleteAccountAlias(request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/DeleteAccountAlias.java)。
## 詳細資訊
+ IAM 《 使用者指南》中的[AWS 您的帳戶 ID 及其別名](https://docs.aws.amazon.com/IAM/latest/UserGuide/console_account-alias.html)
+ IAM API 參考中的 [CreateAccountAlias](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateAccountAlias.html)
+ IAM API 參考中的 [ListAccountAliases](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListAccountAliases.html)
+ IAM API 參考中的 [DeleteAccountAlias](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteAccountAlias.html)
# 處理 IAM 政策
## 建立政策
若要建立新的政策，請在 [CreatePolicyRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/CreatePolicyRequest.html) 中提供政策的名稱和 JSON 格式的政策文件給 AmazonIdentityManagementClient 的 `createPolicy`方法。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.CreatePolicyRequest;
import com.amazonaws.services.identitymanagement.model.CreatePolicyResult;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
CreatePolicyRequest request = new CreatePolicyRequest()
.withPolicyName(policy_name)
.withPolicyDocument(POLICY_DOCUMENT);
CreatePolicyResult response = iam.createPolicy(request);
```
IAM 政策文件是具有[妥善記錄語法的](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_grammar.html) JSON 字串。以下範例提供存取權以便對 DynamoDB提出特定請求。
```
public static final String POLICY_DOCUMENT =
"{" +
" \"Version\": \"2012-10-17\", " +
" \"Statement\": [" +
" {" +
" \"Effect\": \"Allow\"," +
" \"Action\": \"logs:CreateLogGroup\"," +
" \"Resource\": \"%s\"" +
" }," +
" {" +
" \"Effect\": \"Allow\"," +
" \"Action\": [" +
" \"dynamodb:DeleteItem\"," +
" \"dynamodb:GetItem\"," +
" \"dynamodb:PutItem\"," +
" \"dynamodb:Scan\"," +
" \"dynamodb:UpdateItem\"" +
" ]," +
" \"Resource\": \"RESOURCE_ARN\"" +
" }" +
" ]" +
"}";
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/CreatePolicy.java)。
## 取得政策
若要擷取現有政策，請呼叫 AmazonIdentityManagementClient 的 `getPolicy`方法，在 [GetPolicyRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/GetPolicyRequest.html) 物件中提供政策的 ARN。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.GetPolicyRequest;
import com.amazonaws.services.identitymanagement.model.GetPolicyResult;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
GetPolicyRequest request = new GetPolicyRequest()
.withPolicyArn(policy_arn);
GetPolicyResult response = iam.getPolicy(request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/GetPolicy.java)。
## 附加角色政策
您可以透過呼叫 AmazonIdentityManagementClient 的 `attachRolePolicy`方法，在 [AttachRolePolicyRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/AttachRolePolicyRequest.html) 中提供角色名稱和政策 ARN，將政策連接到 IAMhttp：//docs.aws.amazon.com/IAM/latest/UserGuide/id\$1roles.html【角色】。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.AttachRolePolicyRequest;
import com.amazonaws.services.identitymanagement.model.AttachedPolicy;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
AttachRolePolicyRequest attach_request =
new AttachRolePolicyRequest()
.withRoleName(role_name)
.withPolicyArn(POLICY_ARN);
iam.attachRolePolicy(attach_request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/AttachRolePolicy.java)。
## 列出附加的角色政策
呼叫 AmazonIdentityManagementClient 的 `listAttachedRolePolicies`方法，列出角色上的附加政策。它採用 [ListAttachedRolePoliciesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/ListAttachedRolePoliciesRequest.html) 物件，其中包含要列出其政策的角色名稱。
在傳回的 [ListAttachedRolePoliciesResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/ListAttachedRolePoliciesResult.html) 物件`getAttachedPolicies`上呼叫 ，以取得連接的政策清單。結果可能會截斷；如果`ListAttachedRolePoliciesResult`物件的 `getIsTruncated`方法傳回 `true`，請呼叫`ListAttachedRolePoliciesRequest`物件的 `setMarker`方法，並使用它`listAttachedRolePolicies`再次呼叫 以取得下一批結果。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.ListAttachedRolePoliciesRequest;
import com.amazonaws.services.identitymanagement.model.ListAttachedRolePoliciesResult;
import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
ListAttachedRolePoliciesRequest request =
new ListAttachedRolePoliciesRequest()
.withRoleName(role_name);
List matching_policies = new ArrayList<>();
boolean done = false;
while(!done) {
ListAttachedRolePoliciesResult response =
iam.listAttachedRolePolicies(request);
matching_policies.addAll(
response.getAttachedPolicies()
.stream()
.filter(p -> p.getPolicyName().equals(role_name))
.collect(Collectors.toList()));
if(!response.getIsTruncated()) {
done = true;
}
request.setMarker(response.getMarker());
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/AttachRolePolicy.java)。
## 分離角色政策
若要從角色分離政策，請呼叫 AmazonIdentityManagementClient 的 `detachRolePolicy`方法，在 [DetachRolePolicyRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/DetachRolePolicyRequest.html) 中提供角色名稱和政策 ARN。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.DetachRolePolicyRequest;
import com.amazonaws.services.identitymanagement.model.DetachRolePolicyResult;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
DetachRolePolicyRequest request = new DetachRolePolicyRequest()
.withRoleName(role_name)
.withPolicyArn(policy_arn);
DetachRolePolicyResult response = iam.detachRolePolicy(request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/DetachRolePolicy.java)。
## 詳細資訊
+ 《 使用者指南》中的 [IAM 政策概觀](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html)。 IAM
+ IAM 《 使用者指南》中的 [AWS IAM 政策參考](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html)。
+ IAM API 參考中的 [CreatePolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreatePolicy.html)
+ IAM API 參考中的 [GetPolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetPolicy.html)
+ IAM API 參考中的 [AttachRolePolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_AttachRolePolicy.html)
+ IAM API 參考中的 [ListAttachedRolePolicies](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListAttachedRolePolicies.html)
+ IAM API 參考中的 [DetachRolePolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DetachRolePolicy.html)
# 處理 IAM 伺服器憑證
若要在 上啟用網站或應用程式的 HTTPS 連線 AWS，您需要 SSL/TLS *伺服器憑證*。您可以使用 AWS Certificate Manager 提供的伺服器憑證，或是從外部供應商取得的憑證。
建議您使用 ACM 來佈建、管理和部署伺服器憑證。使用 ACM，您可以請求憑證、將其部署到您的 AWS 資源，並讓 ACM 為您處理憑證續約。ACM 提供的憑證是免費的。如需 ACM 的詳細資訊，請參閱 [ACM 使用者指南](https://docs.aws.amazon.com/acm/latest/userguide/)。
## 取得伺服器憑證
您可以透過呼叫 AmazonIdentityManagementClient 的 `getServerCertificate`方法來擷取伺服器憑證，並使用憑證的名稱傳遞 [GetServerCertificateRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/GetServerCertificateRequest.html)。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.GetServerCertificateRequest;
import com.amazonaws.services.identitymanagement.model.GetServerCertificateResult;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
GetServerCertificateRequest request = new GetServerCertificateRequest()
.withServerCertificateName(cert_name);
GetServerCertificateResult response = iam.getServerCertificate(request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/GetServerCertificate.java)。
## 列出伺服器憑證
若要列出您的伺服器憑證，請使用 [ListServerCertificatesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/ListServerCertificatesRequest.html) 呼叫 AmazonIdentityManagementClient 的 `listServerCertificates`方法。它會傳回 [ListServerCertificatesResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/ListServerCertificatesResult.html)。
呼叫傳回 `ListServerCertificateResult` 物件的 `getServerCertificateMetadataList` 方法以取得 [ServerCertificateMetadata](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/ServerCertificateMetadata.html) 物件的清單，您可以用來取得每個憑證的相關資訊。
結果可能會截斷；如果`ListServerCertificateResult`物件的 `getIsTruncated`方法傳回 `true`，請呼叫`ListServerCertificatesRequest`物件的 `setMarker`方法，並用它`listServerCertificates`再次呼叫 以取得下一批結果。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.ListServerCertificatesRequest;
import com.amazonaws.services.identitymanagement.model.ListServerCertificatesResult;
import com.amazonaws.services.identitymanagement.model.ServerCertificateMetadata;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
boolean done = false;
ListServerCertificatesRequest request =
new ListServerCertificatesRequest();
while(!done) {
ListServerCertificatesResult response =
iam.listServerCertificates(request);
for(ServerCertificateMetadata metadata :
response.getServerCertificateMetadataList()) {
System.out.printf("Retrieved server certificate %s",
metadata.getServerCertificateName());
}
request.setMarker(response.getMarker());
if(!response.getIsTruncated()) {
done = true;
}
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/ListServerCertificates.java)。
## 更新伺服器憑證
您可以透過呼叫 AmazonIdentityManagementClient 的 `updateServerCertificate`方法來更新伺服器憑證的名稱或路徑。它需要設定 [UpdateServerCertificateRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/UpdateServerCertificateRequest.html) 物件，並搭配伺服器憑證的目前名稱以及要使用的新名稱或新路徑。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.UpdateServerCertificateRequest;
import com.amazonaws.services.identitymanagement.model.UpdateServerCertificateResult;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
UpdateServerCertificateRequest request =
new UpdateServerCertificateRequest()
.withServerCertificateName(cur_name)
.withNewServerCertificateName(new_name);
UpdateServerCertificateResult response =
iam.updateServerCertificate(request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/UpdateServerCertificate.java)。
## 刪除伺服器憑證
若要刪除伺服器憑證，請使用包含憑證名稱的 [DeleteServerCertificateRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/DeleteServerCertificateRequest.html) 呼叫 AmazonIdentityManagementClient 的 `deleteServerCertificate`方法。
**匯入**
```
import com.amazonaws.services.identitymanagement.AmazonIdentityManagement;
import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder;
import com.amazonaws.services.identitymanagement.model.DeleteServerCertificateRequest;
import com.amazonaws.services.identitymanagement.model.DeleteServerCertificateResult;
```
**Code**
```
final AmazonIdentityManagement iam =
AmazonIdentityManagementClientBuilder.defaultClient();
DeleteServerCertificateRequest request =
new DeleteServerCertificateRequest()
.withServerCertificateName(cert_name);
DeleteServerCertificateResult response =
iam.deleteServerCertificate(request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/DeleteServerCertificate.java)。
## 詳細資訊
+ IAM 《 使用者指南[》中的使用伺服器憑證](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_server-certs.html)
+ IAM API 參考中的 [GetServerCertificate](https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetServerCertificate.html)
+ IAM API 參考中的 [ListServerCertificates](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListServerCertificates.html)
+ IAM API 參考中的 [UpdateServerCertificate](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateServerCertificate.html)
+ IAM API 參考中的 [DeleteServerCertificate](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteServerCertificate.html)
+ [ACM 使用者指南](https://docs.aws.amazon.com/acm/latest/userguide/)
# Lambda 使用 的範例 適用於 Java 的 AWS SDK
本節提供 Lambda 使用 進行程式設計的範例 適用於 Java 的 AWS SDK。
**注意**
這些範例僅包含示範每種技術所需的程式碼。[GitHub 上提供完整程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java)。您可以從那裡下載單一原始檔案或將儲存庫複製到本機，以取得建置和執行的所有範例。
**Topics**
+ [服務操作](examples-lambda.md)
# 叫用、列出和刪除 Lambda 函數
本節提供使用 搭配 Lambda 服務用戶端進行程式設計的範例 適用於 Java 的 AWS SDK。若要了解如何建立 Lambda 函數，請參閱[如何建立 AWS Lambda 函數](https://docs.aws.amazon.com/toolkit-for-eclipse/v1/user-guide/lambda-tutorial.html)。
**Topics**
+ [呼叫函數](#invoke-function)
+ [列出函數](#list-function)
+ [刪除函數](#delete-function)
## 呼叫函數
您可以透過建立 [AWSLambda](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/AWSLambda.html) 物件並叫用其`invoke`方法來叫用 Lambda 函數。建立 [InvokeRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/model/InvokeRequest.html) 物件以指定其他資訊，例如函數名稱和要傳遞給 Lambda 函數的承載。函數名稱會顯示為 *arn：aws：lambda：us-east-1：555556330391：function：HelloFunction*。您可以查看 中的 函數來擷取值 AWS 管理主控台。
若要將承載資料傳遞至函數，請呼叫 [InvokeRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/model/InvokeRequest.html) 物件的 `withPayload`方法，並以 JSON 格式指定字串，如下列程式碼範例所示。
**匯入**
```
import com.amazonaws.auth.profile.ProfileCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.lambda.AWSLambda;
import com.amazonaws.services.lambda.AWSLambdaClientBuilder;
import com.amazonaws.services.lambda.model.InvokeRequest;
import com.amazonaws.services.lambda.model.InvokeResult;
import com.amazonaws.services.lambda.model.ServiceException;
import java.nio.charset.StandardCharsets;
```
**Code**
下列程式碼範例示範如何叫用 Lambda 函數。
```
String functionName = args[0];
InvokeRequest invokeRequest = new InvokeRequest()
.withFunctionName(functionName)
.withPayload("{\n" +
" \"Hello \": \"Paris\",\n" +
" \"countryCode\": \"FR\"\n" +
"}");
InvokeResult invokeResult = null;
try {
AWSLambda awsLambda = AWSLambdaClientBuilder.standard()
.withCredentials(new ProfileCredentialsProvider())
.withRegion(Regions.US_WEST_2).build();
invokeResult = awsLambda.invoke(invokeRequest);
String ans = new String(invokeResult.getPayload().array(), StandardCharsets.UTF_8);
//write out the return value
System.out.println(ans);
} catch (ServiceException e) {
System.out.println(e);
}
System.out.println(invokeResult.getStatusCode());
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/lambda/src/main/java/com/example/lambda/LambdaInvokeFunction.java)。
## 列出函數
建置 [AWSLambda](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/AWSLambda.html) 物件並叫用其`listFunctions`方法。此方法會傳回 [ListFunctionsResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/model/ListFunctionsResult.html) 物件。您可以叫用此物件的 `getFunctions` 方法來傳回 [FunctionConfiguration](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/model/FunctionConfiguration.html) 物件的清單。您可以逐一查看清單以擷取函數的相關資訊。例如，下列 Java 程式碼範例示範如何取得每個函數名稱。
**匯入**
```
import com.amazonaws.auth.profile.ProfileCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.lambda.AWSLambda;
import com.amazonaws.services.lambda.AWSLambdaClientBuilder;
import com.amazonaws.services.lambda.model.FunctionConfiguration;
import com.amazonaws.services.lambda.model.ListFunctionsResult;
import com.amazonaws.services.lambda.model.ServiceException;
import java.util.Iterator;
import java.util.List;
```
**Code**
下列 Java 程式碼範例示範如何擷取 Lambda 函數名稱清單。
```
ListFunctionsResult functionResult = null;
try {
AWSLambda awsLambda = AWSLambdaClientBuilder.standard()
.withCredentials(new ProfileCredentialsProvider())
.withRegion(Regions.US_WEST_2).build();
functionResult = awsLambda.listFunctions();
List list = functionResult.getFunctions();
for (Iterator iter = list.iterator(); iter.hasNext(); ) {
FunctionConfiguration config = (FunctionConfiguration)iter.next();
System.out.println("The function name is "+config.getFunctionName());
}
} catch (ServiceException e) {
System.out.println(e);
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/lambda/src/main/java/com/example/lambda/ListFunctions.java)。
## 刪除函數
建置 [AWSLambda](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/AWSLambda.html) 物件並叫用其`deleteFunction`方法。建立一個 [DeleteFunctionRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/model/DeleteFunctionRequest.html) 物件並將其傳遞給 `deleteFunction` 方法。此物件包含資訊，例如要刪除的函數名稱。函數名稱會顯示為 *arn：aws：lambda：us-east-1：555556330391：function：HelloFunction*。您可以透過查看 中的 函數來擷取值 AWS 管理主控台。
**匯入**
```
import com.amazonaws.auth.profile.ProfileCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.lambda.AWSLambda;
import com.amazonaws.services.lambda.AWSLambdaClientBuilder;
import com.amazonaws.services.lambda.model.ServiceException;
import com.amazonaws.services.lambda.model.DeleteFunctionRequest;
```
**Code**
下列 Java 程式碼示範如何刪除 Lambda 函數。
```
String functionName = args[0];
try {
AWSLambda awsLambda = AWSLambdaClientBuilder.standard()
.withCredentials(new ProfileCredentialsProvider())
.withRegion(Regions.US_WEST_2).build();
DeleteFunctionRequest delFunc = new DeleteFunctionRequest();
delFunc.withFunctionName(functionName);
//Delete the function
awsLambda.deleteFunction(delFunc);
System.out.println("The function is deleted");
} catch (ServiceException e) {
System.out.println(e);
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/lambda/src/main/java/com/example/lambda/DeleteFunction.java)。
# Amazon Pinpoint 使用 的範例 適用於 Java 的 AWS SDK
本節提供使用[適用於 Java 的 AWS SDK](https://aws.amazon.com/sdk-for-java/)編寫 [Amazon Pinpoint](https://aws.amazon.com/pinpoint/) 程式的範例。
**注意**
這些範例僅包含示範每種技術所需的程式碼。[GitHub 上提供完整程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java)。您可以從那裡下載單一原始檔案或將儲存庫複製到本機，以取得建置和執行的所有範例。
**Topics**
+ [在 中建立和刪除應用程式 Amazon Pinpoint](examples-pinpoint-create-app.md)
+ [在 中建立端點 Amazon Pinpoint](examples-pinpoint-create-endpoint.md)
+ [在 中建立客群 Amazon Pinpoint](examples-pinpoint-create-segment.md)
+ [在 中建立行銷活動 Amazon Pinpoint](examples-pinpoint-create-campaign.md)
+ [在 中更新頻道 Amazon Pinpoint](examples-pinpoint-update-channel.md)
# 在 中建立和刪除應用程式 Amazon Pinpoint
應用程式是一種 Amazon Pinpoint 專案，您可以在其中定義不同應用程式的對象，並以量身打造的訊息吸引此對象。本頁面上的範例示範如何建立新的應用程式或刪除現有的應用程式。
## 建立應用程式
在 中提供應用程式名稱給 [CreateAppRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/CreateAppRequest.html) 物件，然後將該物件傳遞給 AmazonPinpointClient 的 `createApp`方法， Amazon Pinpoint 以在 中建立新的應用程式。
**匯入**
```
import com.amazonaws.services.pinpoint.AmazonPinpoint;
import com.amazonaws.services.pinpoint.AmazonPinpointClientBuilder;
import com.amazonaws.services.pinpoint.model.CreateAppRequest;
import com.amazonaws.services.pinpoint.model.CreateAppResult;
import com.amazonaws.services.pinpoint.model.CreateApplicationRequest;
```
**Code**
```
CreateApplicationRequest appRequest = new CreateApplicationRequest()
.withName(appName);
CreateAppRequest request = new CreateAppRequest();
request.withCreateApplicationRequest(appRequest);
CreateAppResult result = pinpoint.createApp(request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/pinpoint/src/main/java/com/example/pinpoint/CreateApp.java)。
## 刪除應用程式
若要刪除應用程式，請呼叫 AmazonPinpointClient 的`deleteApp`請求，並呼叫 [DeleteAppRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/DeleteAppRequest.html) 物件，該物件已設定為要刪除的應用程式名稱。
**匯入**
```
import com.amazonaws.services.pinpoint.AmazonPinpoint;
import com.amazonaws.services.pinpoint.AmazonPinpointClientBuilder;
```
**Code**
```
DeleteAppRequest deleteRequest = new DeleteAppRequest()
.withApplicationId(appID);
pinpoint.deleteApp(deleteRequest);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/pinpoint/src/main/java/com/example/pinpoint/DeleteApp.java)。
## 詳細資訊
+ Amazon Pinpoint API 參考中的[應用程式](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-apps.html)
+ Amazon Pinpoint API 參考中的[應用程式](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-app.html)
# 在 中建立端點 Amazon Pinpoint
端點可唯一識別可向其傳送推送通知的使用者裝置 Amazon Pinpoint。如果您的應用程式已啟用 Amazon Pinpoint 支援，則當新使用者開啟您的應用程式 Amazon Pinpoint 時，您的應用程式會自動向 註冊端點。下列範例示範如何以程式設計方式新增端點。
## 建立端點
透過 Amazon Pinpoint 在 [EndpointRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/EndpointRequest.html) 物件中提供端點資料，在 中建立新的端點。
**匯入**
```
import com.amazonaws.services.pinpoint.AmazonPinpoint;
import com.amazonaws.services.pinpoint.AmazonPinpointClientBuilder;
import com.amazonaws.services.pinpoint.model.UpdateEndpointRequest;
import com.amazonaws.services.pinpoint.model.UpdateEndpointResult;
import com.amazonaws.services.pinpoint.model.EndpointDemographic;
import com.amazonaws.services.pinpoint.model.EndpointLocation;
import com.amazonaws.services.pinpoint.model.EndpointRequest;
import com.amazonaws.services.pinpoint.model.EndpointResponse;
import com.amazonaws.services.pinpoint.model.EndpointUser;
import com.amazonaws.services.pinpoint.model.GetEndpointRequest;
import com.amazonaws.services.pinpoint.model.GetEndpointResult;
```
**Code**
```
HashMap> customAttributes = new HashMap<>();
List favoriteTeams = new ArrayList<>();
favoriteTeams.add("Lakers");
favoriteTeams.add("Warriors");
customAttributes.put("team", favoriteTeams);
EndpointDemographic demographic = new EndpointDemographic()
.withAppVersion("1.0")
.withMake("apple")
.withModel("iPhone")
.withModelVersion("7")
.withPlatform("ios")
.withPlatformVersion("10.1.1")
.withTimezone("America/Los_Angeles");
EndpointLocation location = new EndpointLocation()
.withCity("Los Angeles")
.withCountry("US")
.withLatitude(34.0)
.withLongitude(-118.2)
.withPostalCode("90068")
.withRegion("CA");
Map metrics = new HashMap<>();
metrics.put("health", 100.00);
metrics.put("luck", 75.00);
EndpointUser user = new EndpointUser()
.withUserId(UUID.randomUUID().toString());
DateFormat df = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm'Z'"); // Quoted "Z" to indicate UTC, no timezone offset
String nowAsISO = df.format(new Date());
EndpointRequest endpointRequest = new EndpointRequest()
.withAddress(UUID.randomUUID().toString())
.withAttributes(customAttributes)
.withChannelType("APNS")
.withDemographic(demographic)
.withEffectiveDate(nowAsISO)
.withLocation(location)
.withMetrics(metrics)
.withOptOut("NONE")
.withRequestId(UUID.randomUUID().toString())
.withUser(user);
```
然後使用該 EndpointRequest 物件建立 [UpdateEndpointRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/UpdateEndpointRequest.html) 物件。 EndpointRequest 最後，將 UpdateEndpointRequest 物件傳遞至 AmazonPinpointClient 的 `updateEndpoint`方法。
**Code**
```
UpdateEndpointRequest updateEndpointRequest = new UpdateEndpointRequest()
.withApplicationId(appId)
.withEndpointId(endpointId)
.withEndpointRequest(endpointRequest);
UpdateEndpointResult updateEndpointResponse = client.updateEndpoint(updateEndpointRequest);
System.out.println("Update Endpoint Response: " + updateEndpointResponse.getMessageBody());
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/pinpoint/src/main/java/com/example/pinpoint/CreateEndpoint.java)。
## 詳細資訊
+ 《 Amazon Pinpoint 開發人員指南》中的[新增端點](https://docs.aws.amazon.com/pinpoint/latest/developerguide/endpoints.html)
+ Amazon Pinpoint API 參考中的[端點](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-endpoint.html)
# 在 中建立客群 Amazon Pinpoint
使用者客群代表以共用特性為基礎的使用者子集，例如使用者最近開啟您的應用程式或使用的裝置。下列範例示範如何定義使用者區段。
## 建立客群
透過在 [SegmentDimensions](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/SegmentDimensions.html) 物件中定義區段的維度，在 Amazon Pinpoint 中建立新的區段。
**匯入**
```
import com.amazonaws.services.pinpoint.AmazonPinpoint;
import com.amazonaws.services.pinpoint.AmazonPinpointClientBuilder;
import com.amazonaws.services.pinpoint.model.CreateSegmentRequest;
import com.amazonaws.services.pinpoint.model.CreateSegmentResult;
import com.amazonaws.services.pinpoint.model.AttributeDimension;
import com.amazonaws.services.pinpoint.model.AttributeType;
import com.amazonaws.services.pinpoint.model.RecencyDimension;
import com.amazonaws.services.pinpoint.model.SegmentBehaviors;
import com.amazonaws.services.pinpoint.model.SegmentDemographics;
import com.amazonaws.services.pinpoint.model.SegmentDimensions;
import com.amazonaws.services.pinpoint.model.SegmentLocation;
import com.amazonaws.services.pinpoint.model.SegmentResponse;
import com.amazonaws.services.pinpoint.model.WriteSegmentRequest;
```
**Code**
```
Pinpoint pinpoint = AmazonPinpointClientBuilder.standard().withRegion(Regions.US_EAST_1).build();
Map segmentAttributes = new HashMap<>();
segmentAttributes.put("Team", new AttributeDimension().withAttributeType(AttributeType.INCLUSIVE).withValues("Lakers"));
SegmentBehaviors segmentBehaviors = new SegmentBehaviors();
SegmentDemographics segmentDemographics = new SegmentDemographics();
SegmentLocation segmentLocation = new SegmentLocation();
RecencyDimension recencyDimension = new RecencyDimension();
recencyDimension.withDuration("DAY_30").withRecencyType("ACTIVE");
segmentBehaviors.setRecency(recencyDimension);
SegmentDimensions dimensions = new SegmentDimensions()
.withAttributes(segmentAttributes)
.withBehavior(segmentBehaviors)
.withDemographic(segmentDemographics)
.withLocation(segmentLocation);
```
接著，在 [WriteSegmentRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/WriteSegmentRequest.html) 中設定 [SegmentDimensions](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/SegmentDimensions.html) 物件，接著會用來建立 [CreateSegmentRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/CreateSegmentRequest.html) 物件。然後將 CreateSegmentRequest 物件傳遞至 AmazonPinpointClient 的 `createSegment`方法。
**Code**
```
WriteSegmentRequest writeSegmentRequest = new WriteSegmentRequest()
.withName("MySegment").withDimensions(dimensions);
CreateSegmentRequest createSegmentRequest = new CreateSegmentRequest()
.withApplicationId(appId).withWriteSegmentRequest(writeSegmentRequest);
CreateSegmentResult createSegmentResult = client.createSegment(createSegmentRequest);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/pinpoint/src/main/java/com/example/pinpoint/CreateSegment.java)。
## 詳細資訊
+ Amazon Pinpoint 《 使用者指南》中的[Amazon Pinpoint 客群](https://docs.aws.amazon.com/pinpoint/latest/userguide/segments.html)
+ 《 Amazon Pinpoint 開發人員指南[》中的建立客群](https://docs.aws.amazon.com/pinpoint/latest/developerguide/segments.html)
+ Amazon Pinpoint API 參考中的[區段](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-segments.html)
+ Amazon Pinpoint API 參考中的[客群](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-segment.html)
# 在 中建立行銷活動 Amazon Pinpoint
您可以使用行銷活動來協助提高應用程式與使用者之間的參與度。您可以建立行銷活動，透過量身打造的訊息或特殊促銷來聯絡使用者的特定客群。此範例示範如何建立新的標準行銷活動，將自訂推送通知傳送至指定的客群。
## 建立行銷活動
在建立新的行銷活動之前，您必須定義[排程](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/Schedule.html)和[訊息](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/Message.html)，並在 [WriteCampaignRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/WriteCampaignRequest.html) 物件中設定這些值。
**匯入**
```
import com.amazonaws.services.pinpoint.AmazonPinpoint;
import com.amazonaws.services.pinpoint.AmazonPinpointClientBuilder;
import com.amazonaws.services.pinpoint.model.CreateCampaignRequest;
import com.amazonaws.services.pinpoint.model.CreateCampaignResult;
import com.amazonaws.services.pinpoint.model.Action;
import com.amazonaws.services.pinpoint.model.CampaignResponse;
import com.amazonaws.services.pinpoint.model.Message;
import com.amazonaws.services.pinpoint.model.MessageConfiguration;
import com.amazonaws.services.pinpoint.model.Schedule;
import com.amazonaws.services.pinpoint.model.WriteCampaignRequest;
```
**Code**
```
Schedule schedule = new Schedule()
.withStartTime("IMMEDIATE");
Message defaultMessage = new Message()
.withAction(Action.OPEN_APP)
.withBody("My message body.")
.withTitle("My message title.");
MessageConfiguration messageConfiguration = new MessageConfiguration()
.withDefaultMessage(defaultMessage);
WriteCampaignRequest request = new WriteCampaignRequest()
.withDescription("My description.")
.withSchedule(schedule)
.withSegmentId(segmentId)
.withName("MyCampaign")
.withMessageConfiguration(messageConfiguration);
```
然後在 中透過向 CreateCampaignRequest 物件 Amazon Pinpoint 提供具有行銷活動組態的 [CreateCampaignRequest](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/pinpoint/model/CreateCampaignRequest.html) 來建立新的行銷活動。 [WriteCampaignRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/WriteCampaignRequest.html) 最後，將 CreateCampaignRequest 物件傳遞至 AmazonPinpointClient 的 `createCampaign`方法。
**Code**
```
CreateCampaignRequest createCampaignRequest = new CreateCampaignRequest()
.withApplicationId(appId).withWriteCampaignRequest(request);
CreateCampaignResult result = client.createCampaign(createCampaignRequest);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/pinpoint/src/main/java/com/example/pinpoint/CreateApp.java)。
## 詳細資訊
+ Amazon Pinpoint 《 使用者指南》中的[Amazon Pinpoint 行銷活動](https://docs.aws.amazon.com/pinpoint/latest/userguide/campaigns.html)
+ 《 Amazon Pinpoint 開發人員指南》中的[建立行銷活動](https://docs.aws.amazon.com/pinpoint/latest/developerguide/campaigns.html)
+ Amazon Pinpoint API 參考中的[行銷活動](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-campaigns.html)
+ Amazon Pinpoint API 參考中的[行銷活動](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-campaign.html)
+ Amazon Pinpoint API 參考中的[行銷活動](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-campaign-activities.html)
+ Amazon Pinpoint API 參考中的[行銷活動版本](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-campaign-versions.html)
+ Amazon Pinpoint API 參考中的[行銷活動版本](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-campaign-version.html)
# 在 中更新頻道 Amazon Pinpoint
頻道定義您可以傳送訊息的平台類型。此範例說明如何使用 APNs 頻道來傳送訊息。
## 更新頻道
Amazon Pinpoint 透過提供您要更新之頻道類型的應用程式 ID 和請求物件，在 中啟用頻道。此範例會更新需要 [APNSChannelRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/APNSChannelRequest.html) 物件的 APNs 頻道。在 [UpdateApnsChannelRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/UpdateApnsChannelRequest.html) 中設定這些物件，並將該物件傳遞至 AmazonPinpointClient 的 `updateApnsChannel`方法。
**匯入**
```
import com.amazonaws.services.pinpoint.AmazonPinpoint;
import com.amazonaws.services.pinpoint.AmazonPinpointClientBuilder;
import com.amazonaws.services.pinpoint.model.APNSChannelRequest;
import com.amazonaws.services.pinpoint.model.APNSChannelResponse;
import com.amazonaws.services.pinpoint.model.GetApnsChannelRequest;
import com.amazonaws.services.pinpoint.model.GetApnsChannelResult;
import com.amazonaws.services.pinpoint.model.UpdateApnsChannelRequest;
import com.amazonaws.services.pinpoint.model.UpdateApnsChannelResult;
```
**Code**
```
APNSChannelRequest request = new APNSChannelRequest()
.withEnabled(enabled);
UpdateApnsChannelRequest updateRequest = new UpdateApnsChannelRequest()
.withAPNSChannelRequest(request)
.withApplicationId(appId);
UpdateApnsChannelResult result = client.updateApnsChannel(updateRequest);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/pinpoint/src/main/java/com/example/pinpoint/UpdateChannel.java)。
## 詳細資訊
+ Amazon Pinpoint 《 使用者指南》中的[Amazon Pinpoint 頻道](https://docs.aws.amazon.com/pinpoint/latest/userguide/channels.html)
+ Amazon Pinpoint API [參考中的 ADM 頻道](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-adm-channel.html)
+ Amazon Pinpoint API [參考中的 APNs 頻道](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-apns-channel.html)
+ [API 參考中的 APNs 沙盒頻道](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-apns-sandbox-channel.html) Amazon Pinpoint
+ [API 參考中的 APNs VoIP 頻道](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-apns-voip-channel.html) Amazon Pinpoint
+ [API 參考中的 APNs VoIP 沙盒頻道](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-apns-voip-sandbox-channel.html) Amazon Pinpoint
+ Amazon Pinpoint API 參考中的[百度頻道](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-baidu-channel.html)
+ Amazon Pinpoint API 參考中的[電子郵件管道](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-email-channel.html)
+ Amazon Pinpoint API 參考中的 [GCM 頻道](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-gcm-channel.html)
+ Amazon Pinpoint API 參考中的[簡訊管道](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-sms-channel.html)
# Amazon S3 使用 的範例 適用於 Java 的 AWS SDK
本節提供使用[適用於 Java 的 AWS SDK](https://aws.amazon.com/sdk-for-java/)編寫 [Amazon S3](https://aws.amazon.com/s3/) 程式的範例。
**注意**
這些範例僅包含示範每種技術所需的程式碼。[GitHub 上提供完整程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java)。您可以從那裡下載單一原始檔案或將儲存庫複製到本機，以取得建置和執行的所有範例。
**Topics**
+ [建立、列出和刪除 Amazon S3 儲存貯體](examples-s3-buckets.md)
+ [在 Amazon S3 物件上執行操作](examples-s3-objects.md)
+ [管理儲存貯體和物件的 Amazon S3 存取許可](examples-s3-access-permissions.md)
+ [使用 Amazon S3 儲存貯體政策管理對儲存貯體的存取](examples-s3-bucket-policies.md)
+ [使用 TransferManager 進行 Amazon S3 操作](examples-s3-transfermanager.md)
+ [將 Amazon S3 儲存貯體設定為網站](examples-s3-website-configuration.md)
+ [使用 Amazon S3 用戶端加密](examples-crypto.md)
# 建立、列出和刪除 Amazon S3 儲存貯體
中的每個物件 （檔案） Amazon S3 都必須位於代表物件集合 （容器） 的*儲存貯*體中。每個儲存貯體都是由索引*鍵* （名稱） 所知道，該索引鍵必須是唯一的。如需儲存貯體及其組態的詳細資訊，請參閱 Amazon Simple Storage Service 《 使用者指南》中的[使用 Amazon S3 儲存貯體](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html)。
**注意**
最佳實務
建議您在 Amazon S3 儲存貯體上啟用 [AbortIncompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTlifecycle.html) 生命週期規則。
此規則 Amazon S3 會指示 中止未在啟動後指定天數內完成的分段上傳。超過設定的時間限制時， 會 Amazon S3 中止上傳，然後刪除不完整的上傳資料。
如需詳細資訊，請參閱 Amazon S3 《 使用者指南》中的[使用版本控制的儲存貯體生命週期組態](https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-configuration-bucket-with-versioning.html)。
**注意**
這些程式碼範例假設您了解[使用 適用於 Java 的 AWS SDK](basics.md) 中的資料，並使用設定 AWS 登入資料[和開發區域中的資訊來設定預設 AWS 登入](setup-credentials.md)資料。
## 建立儲存貯體
使用 AmazonS3 用戶端的 `createBucket`方法。傳回新的[儲存貯體](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Bucket.html)。如果儲存貯體已存在，則 `createBucket`方法將引發例外狀況。
**注意**
若要在嘗試建立具有相同名稱的儲存貯體之前檢查儲存貯體是否已存在，請呼叫 `doesBucketExist`方法。`true` 如果儲存貯體存在，則會傳回 ，`false`否則傳回 。
**匯入**
```
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.AmazonS3Exception;
import com.amazonaws.services.s3.model.Bucket;
import java.util.List;
```
**Code**
```
if (s3.doesBucketExistV2(bucket_name)) {
System.out.format("Bucket %s already exists.\n", bucket_name);
b = getBucket(bucket_name);
} else {
try {
b = s3.createBucket(bucket_name);
} catch (AmazonS3Exception e) {
System.err.println(e.getErrorMessage());
}
}
return b;
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/CreateBucket.java)。
## 列出儲存貯體
使用 AmazonS3 用戶端的 `listBucket`方法。如果成功，則會傳回[儲存貯體](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Bucket.html)清單。
**匯入**
```
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.Bucket;
import java.util.List;
```
**Code**
```
List buckets = s3.listBuckets();
System.out.println("Your {S3} buckets are:");
for (Bucket b : buckets) {
System.out.println("* " + b.getName());
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/ListBuckets.java)。
## 刪除儲存貯體
您必須先確認儲存 Amazon S3 貯體為空，否則將發生錯誤，才能刪除儲存貯體。如果您有[版本控制的儲存貯](https://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html)體，您也必須刪除與儲存貯體相關聯的任何版本控制的物件。
**注意**
[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java)依序包含這些步驟，提供刪除 儲存 Amazon S3 貯體及其內容的完整解決方案。
**Topics**
+ [從未版本控制的儲存貯體移除物件，然後再刪除](#remove-objects-from-an-unversioned-bucket-before-deleting-it)
+ [從已版本控制的儲存貯體移除物件，然後再將其刪除](#remove-objects-from-a-versioned-bucket-before-deleting-it)
+ [刪除空的儲存貯體](#delete-an-empty-bucket)
### 從未版本控制的儲存貯體移除物件，然後再刪除
使用 AmazonS3 用戶端的 `listObjects`方法擷取物件清單`deleteObject`，並刪除每個物件清單。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.*;
import java.util.Iterator;
```
**Code**
```
System.out.println(" - removing objects from bucket");
ObjectListing object_listing = s3.listObjects(bucket_name);
while (true) {
for (Iterator iterator =
object_listing.getObjectSummaries().iterator();
iterator.hasNext(); ) {
S3ObjectSummary summary = (S3ObjectSummary) iterator.next();
s3.deleteObject(bucket_name, summary.getKey());
}
// more object_listing to retrieve?
if (object_listing.isTruncated()) {
object_listing = s3.listNextBatchOfObjects(object_listing);
} else {
break;
}
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java)。
### 從已版本控制的儲存貯體移除物件，然後再將其刪除
如果您使用的是[版本控制的儲存貯](https://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html)體，您也需要移除儲存貯體中物件的任何存放版本，才能刪除儲存貯體。
使用類似於移除儲存貯體中物件時所使用的模式，透過使用 AmazonS3 用戶端的 `listVersions`方法來列出任何版本控制的物件，然後刪除每個物件`deleteVersion`，以移除版本控制的物件。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.*;
import java.util.Iterator;
```
**Code**
```
System.out.println(" - removing versions from bucket");
VersionListing version_listing = s3.listVersions(
new ListVersionsRequest().withBucketName(bucket_name));
while (true) {
for (Iterator iterator =
version_listing.getVersionSummaries().iterator();
iterator.hasNext(); ) {
S3VersionSummary vs = (S3VersionSummary) iterator.next();
s3.deleteVersion(
bucket_name, vs.getKey(), vs.getVersionId());
}
if (version_listing.isTruncated()) {
version_listing = s3.listNextBatchOfVersions(
version_listing);
} else {
break;
}
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java)。
### 刪除空的儲存貯體
從儲存貯體移除物件後 （包括任何版本控制的物件），您可以使用 AmazonS3 用戶端的 `deleteBucket`方法刪除儲存貯體本身。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.*;
import java.util.Iterator;
```
**Code**
```
System.out.println(" OK, bucket ready to delete!");
s3.deleteBucket(bucket_name);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java)。
# 在 Amazon S3 物件上執行操作
Amazon S3 物件代表*檔案*或資料集合。每個物件都必須位於儲存[貯](examples-s3-buckets.md)體中。
**注意**
這些程式碼範例假設您了解[使用 中的資料， 適用於 Java 的 AWS SDK](basics.md)並使用設定 AWS 登入資料[和開發區域中的資訊來設定預設 AWS 登入](setup-credentials.md)資料。
**Topics**
+ [上傳物件](#upload-object)
+ [列出物件](#list-objects)
+ [下載物件](#download-object)
+ [複製、移動或重新命名物件](#copy-object)
+ [刪除物件](#delete-object)
+ [一次刪除多個物件](#delete-objects)
## 上傳物件
使用 AmazonS3 用戶端的 `putObject`方法，提供儲存貯體名稱、金鑰名稱和要上傳的檔案。*儲存貯體必須存在，否則會產生錯誤*。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
```
**Code**
```
System.out.format("Uploading %s to S3 bucket %s...\n", file_path, bucket_name);
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
s3.putObject(bucket_name, key_name, new File(file_path));
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/PutObject.java)。
## 列出物件
若要取得儲存貯體中的物件清單，請使用 AmazonS3 用戶端的 `listObjects`方法，並提供儲存貯體的名稱。
`listObjects` 方法會傳回 [ObjectListing](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/ObjectListing.html) 物件，提供儲存貯體中物件的相關資訊。若要列出物件名稱 （金鑰），請使用 `getObjectSummaries`方法取得 [S3ObjectSummary](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/S3ObjectSummary.html) 物件清單，每個物件都代表儲存貯體中的單一物件。然後呼叫其 `getKey`方法來擷取物件的名稱。
**匯入**
```
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.ListObjectsV2Result;
import com.amazonaws.services.s3.model.S3ObjectSummary;
```
**Code**
```
System.out.format("Objects in S3 bucket %s:\n", bucket_name);
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
ListObjectsV2Result result = s3.listObjectsV2(bucket_name);
List objects = result.getObjectSummaries();
for (S3ObjectSummary os : objects) {
System.out.println("* " + os.getKey());
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/ListObjects.java)。
## 下載物件
使用 AmazonS3 用戶端的 `getObject`方法，將要下載的儲存貯體和物件的名稱傳遞給用戶端。如果成功， 方法會傳回 [S3Object](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/S3Object.html)。*指定的儲存貯體和物件金鑰必須存在，否則會產生錯誤*。
您可以在 `getObjectContent`上呼叫 ，以取得物件的內容`S3Object`。這會傳回做為標準 Java `InputStream` 物件的 [S3ObjectInputStream](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/S3ObjectInputStream.html)。
下列範例會從 S3 下載物件，並將其內容儲存至檔案 （使用與物件金鑰相同的名稱）。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.S3Object;
import com.amazonaws.services.s3.model.S3ObjectInputStream;
import java.io.File;
```
**Code**
```
System.out.format("Downloading %s from S3 bucket %s...\n", key_name, bucket_name);
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
S3Object o = s3.getObject(bucket_name, key_name);
S3ObjectInputStream s3is = o.getObjectContent();
FileOutputStream fos = new FileOutputStream(new File(key_name));
byte[] read_buf = new byte[1024];
int read_len = 0;
while ((read_len = s3is.read(read_buf)) > 0) {
fos.write(read_buf, 0, read_len);
}
s3is.close();
fos.close();
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
} catch (FileNotFoundException e) {
System.err.println(e.getMessage());
System.exit(1);
} catch (IOException e) {
System.err.println(e.getMessage());
System.exit(1);
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/GetObject.java)。
## 複製、移動或重新命名物件
您可以使用 AmazonS3 用戶端的 `copyObject`方法，將物件從一個儲存貯體複製到另一個儲存貯體。它接受要複製的儲存貯體名稱、要複製的物件，以及目的地儲存貯體名稱。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
```
**Code**
```
try {
s3.copyObject(from_bucket, object_key, to_bucket, object_key);
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
System.out.println("Done!");
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/CopyObject.java)。
**注意**
您可以`copyObject`搭配 [deleteObject](#delete-object) 使用 來**移動**或**重新命名**物件，方法是先將物件複製到新名稱 （您可以使用與來源和目的地相同的儲存貯體），然後從舊位置刪除物件。
## 刪除物件
使用 AmazonS3 用戶端的 `deleteObject`方法，將要刪除的儲存貯體和物件的名稱傳遞給用戶端。*指定的儲存貯體和物件金鑰必須存在，否則會產生錯誤*。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
```
**Code**
```
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
s3.deleteObject(bucket_name, object_key);
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteObject.java)。
## 一次刪除多個物件
使用 AmazonS3 用戶端的 `deleteObjects`方法，您可以將多個物件從相同儲存貯體中刪除，方法是將它們的名稱傳遞至 link：sdk-for-java/v1/reference/com/amazonaws/services/s3/model/DeleteObjectsRequest.html`` 方法。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
```
**Code**
```
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
DeleteObjectsRequest dor = new DeleteObjectsRequest(bucket_name)
.withKeys(object_keys);
s3.deleteObjects(dor);
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteObjects.java)。
# 管理儲存貯體和物件的 Amazon S3 存取許可
您可以針對 Amazon S3 儲存貯體和物件使用存取控制清單 (ACLs)，以精細控制 Amazon S3 資源。
**注意**
這些程式碼範例假設您了解[使用 適用於 Java 的 AWS SDK](basics.md) 中的資料，並使用設定 AWS 登入資料[和開發區域中的資訊來設定預設 AWS 登入](setup-credentials.md)資料。
## 取得儲存貯體的存取控制清單
若要取得儲存貯體的目前 ACL，請呼叫 AmazonS3 的 `getBucketAcl`方法，將儲存*貯體名稱*傳遞給它以進行查詢。此方法會傳回 [AccessControlList](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/AccessControlList.html) 物件。若要取得清單中的每個存取授權，請呼叫其 `getGrantsAsList` 方法，這會傳回標準 Java [授予](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Grant.html)物件清單。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.AccessControlList;
import com.amazonaws.services.s3.model.Grant;
```
**Code**
```
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
AccessControlList acl = s3.getBucketAcl(bucket_name);
List grants = acl.getGrantsAsList();
for (Grant grant : grants) {
System.out.format(" %s: %s\n", grant.getGrantee().getIdentifier(),
grant.getPermission().toString());
}
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/GetAcl.java)。
## 設定儲存貯體的存取控制清單
若要新增或修改儲存貯體的 ACL 許可，請呼叫 AmazonS3 的 `setBucketAcl`方法。它需要 [AccessControlList](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/AccessControlList.html) 物件，其中包含要設定的承授者和存取層級清單。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.AccessControlList;
import com.amazonaws.services.s3.model.EmailAddressGrantee;
```
**Code**
```
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
// get the current ACL
AccessControlList acl = s3.getBucketAcl(bucket_name);
// set access for the grantee
EmailAddressGrantee grantee = new EmailAddressGrantee(email);
Permission permission = Permission.valueOf(access);
acl.grantPermission(grantee, permission);
s3.setBucketAcl(bucket_name, acl);
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
```
**注意**
您可以直接使用承授者類別提供[承授](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Grantee.html)者的唯一識別符，或使用 [EmailAddressGrantee](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/EmailAddressGrantee.html) 類別來透過電子郵件設定承授者，如同我們在這裡所做的。
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/SetAcl.java)。
## 取得物件的存取控制清單
若要取得物件的目前 ACL，請呼叫 AmazonS3 的 `getObjectAcl`方法，將要查詢的儲存*貯體名稱*和*物件名稱*傳遞給它。如同 `getBucketAcl`，此方法會傳回 [AccessControlList](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/AccessControlList.html) 物件，您可以用來檢查每個[授與](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Grant.html)。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.AccessControlList;
import com.amazonaws.services.s3.model.Grant;
```
**Code**
```
try {
AccessControlList acl = s3.getObjectAcl(bucket_name, object_key);
List grants = acl.getGrantsAsList();
for (Grant grant : grants) {
System.out.format(" %s: %s\n", grant.getGrantee().getIdentifier(),
grant.getPermission().toString());
}
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/GetAcl.java)。
## 設定物件的存取控制清單
若要新增或修改物件的 ACL 許可，請呼叫 AmazonS3 的 `setObjectAcl`方法。它需要 [AccessControlList](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/AccessControlList.html) 物件，其中包含要設定的承授者和存取層級清單。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.AccessControlList;
import com.amazonaws.services.s3.model.EmailAddressGrantee;
```
**Code**
```
try {
// get the current ACL
AccessControlList acl = s3.getObjectAcl(bucket_name, object_key);
// set access for the grantee
EmailAddressGrantee grantee = new EmailAddressGrantee(email);
Permission permission = Permission.valueOf(access);
acl.grantPermission(grantee, permission);
s3.setObjectAcl(bucket_name, object_key, acl);
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
}
```
**注意**
您可以直接使用承授者類別提供[承授](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Grantee.html)者的唯一識別符，或使用 [EmailAddressGrantee](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/EmailAddressGrantee.html) 類別來透過電子郵件設定承授者，如同我們在這裡所做的。
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/SetAcl.java)。
## 詳細資訊
+ Amazon S3 API 參考中的 [GET 儲存貯體 acl](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketGETacl.html)
+ Amazon S3 API 參考中的 [PUT 儲存貯體 acl](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTacl.html)
+ Amazon S3 API 參考中的 [GET 物件 acl](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGETacl.html)
+ Amazon S3 API 參考中的 [PUT 物件 acl](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUTacl.html)
# 使用 Amazon S3 儲存貯體政策管理對儲存貯體的存取
您可以設定、取得或刪除儲存*貯體政策*，以管理對儲存 Amazon S3 貯體的存取。
## 設定儲存貯體政策
您可以透過下列方式設定特定 S3 儲存貯體的儲存貯體政策：
+ 呼叫 AmazonS3 用戶端的 ，`setBucketPolicy`並提供 [SetBucketPolicyRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/SetBucketPolicyRequest.html)
+ 使用採用儲存貯體名稱和政策文字的`setBucketPolicy`過載直接設定政策 (JSON 格式）
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.auth.policy.Policy;
import com.amazonaws.auth.policy.Principal;
```
**Code**
```
s3.setBucketPolicy(bucket_name, policy_text);
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
```
### 使用政策類別來產生或驗證政策
提供儲存貯體政策給 時`setBucketPolicy`，您可以執行下列動作：
+ 直接將政策指定為 JSON 格式文字的字串
+ 使用 政策類別建置[政策](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/policy/Policy.html)
透過使用 `Policy`類別，您不需要擔心文字字串的格式是否正確。若要從 `Policy`類別取得 JSON 政策文字，請使用其 `toJson` 方法。
**匯入**
```
import com.amazonaws.auth.policy.Resource;
import com.amazonaws.auth.policy.Statement;
import com.amazonaws.auth.policy.actions.S3Actions;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
```
**Code**
```
new Statement(Statement.Effect.Allow)
.withPrincipals(Principal.AllUsers)
.withActions(S3Actions.GetObject)
.withResources(new Resource(
"{region-arn}s3:::" + bucket_name + "/*")));
return bucket_policy.toJson();
```
`Policy` 類別也提供`fromJson`一種方法，可嘗試使用傳入的 JSON 字串來建置政策。方法會進行驗證，以確保文字可轉換為有效的政策結構，如果政策文字無效`IllegalArgumentException`， 便會失敗。
```
Policy bucket_policy = null;
try {
bucket_policy = Policy.fromJson(file_text.toString());
} catch (IllegalArgumentException e) {
System.out.format("Invalid policy text in file: \"%s\"",
policy_file);
System.out.println(e.getMessage());
}
```
您可以使用此技術預先驗證從檔案或其他方式讀取的政策。
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/SetBucketPolicy.java)。
## 取得儲存貯體政策
若要擷取 儲存 Amazon S3 貯體的政策，請呼叫 AmazonS3 用戶端的 `getBucketPolicy`方法，將儲存貯體的名稱傳遞給它以從中取得政策。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
```
**Code**
```
try {
BucketPolicy bucket_policy = s3.getBucketPolicy(bucket_name);
policy_text = bucket_policy.getPolicyText();
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
```
如果命名的儲存貯體不存在，如果您無法存取它，或如果它沒有儲存貯體政策，`AmazonServiceException`則會擲出 。
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/GetBucketPolicy.java)。
## 刪除儲存貯體政策
若要刪除儲存貯體政策，請呼叫 AmazonS3 用戶端的 `deleteBucketPolicy`，並提供儲存貯體名稱。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
```
**Code**
```
try {
s3.deleteBucketPolicy(bucket_name);
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
```
即使儲存貯體還沒有政策，此方法也會成功。如果您指定的儲存貯體名稱不存在，或者您無法存取儲存貯體，`AmazonServiceException`則會擲回 。
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteBucketPolicy.java)。
## 詳細資訊
+ Amazon Simple Storage Service 《 使用者指南》中的[存取政策語言概觀](https://docs.aws.amazon.com/AmazonS3/latest/dev/access-policy-language-overview.html)
+ Amazon Simple Storage Service 《 使用者指南》中的[儲存貯體政策範例](https://docs.aws.amazon.com/AmazonS3/latest/dev/example-bucket-policies.html)
# 使用 TransferManager 進行 Amazon S3 操作
您可以使用 適用於 Java 的 AWS SDK TransferManager 類別，可靠地將檔案從本機環境傳輸到另一個 S3 位置 Amazon S3 ，以及將物件複製到另一個位置。 `TransferManager`可以取得傳輸進度，並暫停或繼續上傳和下載。
**注意**
最佳實務
建議您在 Amazon S3 儲存貯體上啟用 [AbortIncompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTlifecycle.html) 生命週期規則。
此規則 Amazon S3 會指示 中止在啟動後指定天數內未完成的分段上傳。超過設定的時間限制時， 會 Amazon S3 中止上傳，然後刪除不完整的上傳資料。
如需詳細資訊，請參閱 Amazon S3 《 使用者指南[》中的使用版本控制的儲存貯體生命週期組態](https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-configuration-bucket-with-versioning.html)。
**注意**
這些程式碼範例假設您了解[使用 適用於 Java 的 AWS SDK](basics.md) 中的資料，並使用設定 AWS 登入資料[和開發區域中的資訊來設定預設 AWS 登入](setup-credentials.md)資料。
## 上傳檔案和目錄
TransferManager 可以將檔案、檔案清單和目錄上傳至您[先前建立](examples-s3-buckets.md#create-bucket)的任何儲存 Amazon S3 貯體。
**Topics**
+ [上傳單一檔案](#transfermanager-upload-file)
+ [上傳檔案清單](#transfermanager-upload-file-list)
+ [上傳目錄](#transfermanager-upload-directory)
### 上傳單一檔案
呼叫 TransferManager 的 `upload`方法，提供儲存 Amazon S3 貯體名稱、金鑰 （物件） 名稱，以及代表要上傳之檔案的標準 Java [檔案](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html)物件。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.MultipleFileUpload;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;
import com.amazonaws.services.s3.transfer.Upload;
import java.io.File;
import java.util.ArrayList;
import java.util.Arrays;
```
**Code**
```
File f = new File(file_path);
TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
Upload xfer = xfer_mgr.upload(bucket_name, key_name, f);
// loop with Transfer.isDone()
XferMgrProgress.showTransferProgress(xfer);
// or block with Transfer.waitForCompletion()
XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
xfer_mgr.shutdownNow();
```
`upload` 方法*會立即*傳回，提供 `Upload` 物件以用來檢查傳輸狀態或等待它完成。
請參閱[等待轉接完成](#transfermanager-wait-for-completion)，以取得在呼叫 TransferManager 的 `shutdownNow`方法之前`waitForCompletion`，使用 成功完成轉接的相關資訊。等待傳輸完成時，您可以輪詢或接聽其狀態和進度的更新。如需詳細資訊，請參閱[取得傳輸狀態和進度](#transfermanager-get-status-and-progress)。
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrUpload.java)。
### 上傳檔案清單
若要在一個操作中上傳多個檔案，請呼叫 TransferManager`uploadFileList` 方法，並提供下列項目：
+ 儲存 Amazon S3 貯體名稱
+ *金鑰字首*，以建立物件的名稱開頭 （在儲存貯體中放置物件的路徑）
+ 代表從中建立[檔案](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html)路徑之相對目錄的檔案物件
+ [清單](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/List.html)物件，其中包含一組要上傳[的檔案](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html)物件
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.MultipleFileUpload;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;
import com.amazonaws.services.s3.transfer.Upload;
import java.io.File;
import java.util.ArrayList;
import java.util.Arrays;
```
**Code**
```
ArrayList files = new ArrayList();
for (String path : file_paths) {
files.add(new File(path));
}
TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
MultipleFileUpload xfer = xfer_mgr.uploadFileList(bucket_name,
key_prefix, new File("."), files);
// loop with Transfer.isDone()
XferMgrProgress.showTransferProgress(xfer);
// or block with Transfer.waitForCompletion()
XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
xfer_mgr.shutdownNow();
```
請參閱[等待轉接完成](#transfermanager-wait-for-completion)，以取得在呼叫 TransferManager 的 `shutdownNow`方法之前`waitForCompletion`，使用 成功完成轉接的相關資訊。等待傳輸完成時，您可以輪詢或接聽其狀態和進度的更新。如需詳細資訊，請參閱[取得傳輸狀態和進度](#transfermanager-get-status-and-progress)。
傳回的 [MultipleFileUpload](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/MultipleFileUpload.html) 物件`uploadFileList`可用來查詢傳輸狀態或進度。如需詳細資訊，請參閱使用 ProgressListener [輪詢傳輸的目前進度](#transfermanager-get-progress-polling)和取得傳輸進度。 [ ProgressListener](#transfermanager-progress-listener)
您也可以使用 `MultipleFileUpload`的 `getSubTransfers`方法，取得每個要傳輸檔案的個別`Upload`物件。如需詳細資訊，請參閱[取得子轉移進度](#transfermanager-get-subtransfer-progress)。
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrUpload.java)。
### 上傳目錄
您可以使用 TransferManager 的 `uploadDirectory`方法上傳整個檔案目錄，並可選擇以遞迴方式複製子目錄中的檔案。您提供儲存 Amazon S3 貯體名稱、S3 金鑰字首、代表要複製之本機目錄[的檔案](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html)物件，以及指出是否要以遞迴方式 (*true* 或 *false*) 複製子目錄`boolean`的值。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.MultipleFileUpload;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;
import com.amazonaws.services.s3.transfer.Upload;
import java.io.File;
import java.util.ArrayList;
import java.util.Arrays;
```
**Code**
```
TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
MultipleFileUpload xfer = xfer_mgr.uploadDirectory(bucket_name,
key_prefix, new File(dir_path), recursive);
// loop with Transfer.isDone()
XferMgrProgress.showTransferProgress(xfer);
// or block with Transfer.waitForCompletion()
XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
xfer_mgr.shutdownNow();
```
請參閱[等待轉接完成](#transfermanager-wait-for-completion)，以取得在呼叫 TransferManager 的 `shutdownNow`方法之前`waitForCompletion`，使用 成功完成轉接的相關資訊。等待傳輸完成時，您可以輪詢或接聽其狀態和進度的更新。如需詳細資訊，請參閱[取得傳輸狀態和進度](#transfermanager-get-status-and-progress)。
傳回的 [MultipleFileUpload](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/MultipleFileUpload.html) 物件`uploadFileList`可用來查詢傳輸狀態或進度。如需詳細資訊，請參閱使用 ProgressListener [輪詢傳輸的目前進度](#transfermanager-get-progress-polling)和取得傳輸進度。 [ ProgressListener](#transfermanager-progress-listener)
您也可以使用 `MultipleFileUpload`的 `getSubTransfers`方法，取得每個要傳輸檔案的個別`Upload`物件。如需詳細資訊，請參閱[取得子轉移進度](#transfermanager-get-subtransfer-progress)。
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrUpload.java)。
## 下載檔案或目錄
使用 TransferManager 類別從中下載單一檔案 (Amazon S3 物件） 或目錄 ( Amazon S3 儲存貯體名稱後接物件字首） Amazon S3。
**Topics**
+ [下載單一檔案](#transfermanager-download-file)
+ [下載目錄](#tranfermanager-download-directory)
### 下載單一檔案
使用 TransferManager 的 `download`方法，提供儲存 Amazon S3 貯體名稱，其中包含您要下載的物件、金鑰 （物件） 名稱，以及代表要在本機系統上建立之檔案的檔案[https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html)物件。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.Download;
import com.amazonaws.services.s3.transfer.MultipleFileDownload;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;
import java.io.File;
```
**Code**
```
File f = new File(file_path);
TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
Download xfer = xfer_mgr.download(bucket_name, key_name, f);
// loop with Transfer.isDone()
XferMgrProgress.showTransferProgress(xfer);
// or block with Transfer.waitForCompletion()
XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
xfer_mgr.shutdownNow();
```
請參閱[等待轉接完成](#transfermanager-wait-for-completion)，以取得有關使用 `waitForCompletion` 成功完成轉接的資訊，然後再呼叫 TransferManager 的 `shutdownNow`方法。等待傳輸完成時，您可以輪詢或接聽其狀態和進度的更新。如需詳細資訊，請參閱[取得傳輸狀態和進度](#transfermanager-get-status-and-progress)。
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrDownload.java)。
### 下載目錄
若要從中下載一組共用常見金鑰字首 （類似於檔案系統上的目錄） 的檔案 Amazon S3，請使用 TransferManager`downloadDirectory` 方法。方法採用儲存 Amazon S3 貯體名稱，其中包含您要下載的物件、所有物件共用的物件字首，以及代表要在本機系統上下載檔案的目錄[的檔案](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html)物件。如果名為 的目錄尚不存在，則會建立該目錄。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.Download;
import com.amazonaws.services.s3.transfer.MultipleFileDownload;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;
import java.io.File;
```
**Code**
```
TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
MultipleFileDownload xfer = xfer_mgr.downloadDirectory(
bucket_name, key_prefix, new File(dir_path));
// loop with Transfer.isDone()
XferMgrProgress.showTransferProgress(xfer);
// or block with Transfer.waitForCompletion()
XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
xfer_mgr.shutdownNow();
```
請參閱[等待轉接完成](#transfermanager-wait-for-completion)，以取得在呼叫 TransferManager 的 `shutdownNow`方法之前`waitForCompletion`，使用 成功完成轉接的相關資訊。等待傳輸完成時，您可以輪詢或接聽其狀態和進度的更新。如需詳細資訊，請參閱[取得傳輸狀態和進度](#transfermanager-get-status-and-progress)。
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrDownload.java)。
## 複製物件
若要將物件從一個 S3 儲存貯體複製到另一個儲存貯體，請使用 TransferManager`copy` 方法。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.Copy;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;
```
**Code**
```
System.out.println("Copying s3 object: " + from_key);
System.out.println(" from bucket: " + from_bucket);
System.out.println(" to s3 object: " + to_key);
System.out.println(" in bucket: " + to_bucket);
TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
Copy xfer = xfer_mgr.copy(from_bucket, from_key, to_bucket, to_key);
// loop with Transfer.isDone()
XferMgrProgress.showTransferProgress(xfer);
// or block with Transfer.waitForCompletion()
XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
xfer_mgr.shutdownNow();
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrCopy.java)。
## 等待轉接完成
如果您的應用程式 （或執行緒） 可以在傳輸完成之前封鎖，您可以使用 [Transfer](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Transfer.html) 介面的 `waitForCompletion`方法封鎖，直到傳輸完成或發生例外狀況為止。
```
try {
xfer.waitForCompletion();
} catch (AmazonServiceException e) {
System.err.println("Amazon service error: " + e.getMessage());
System.exit(1);
} catch (AmazonClientException e) {
System.err.println("Amazon client error: " + e.getMessage());
System.exit(1);
} catch (InterruptedException e) {
System.err.println("Transfer interrupted: " + e.getMessage());
System.exit(1);
}
```
如果您在呼叫 *之前*輪詢事件`waitForCompletion`、在個別執行緒上實作輪詢機制，或使用 [ProgressListener](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/event/ProgressListener.html) 非同步接收進度更新，就會取得傳輸進度。
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java)。
## 取得傳輸狀態和進度
TransferManager`upload*`、 `download*`和 `copy`方法傳回的每個類別都會傳回下列其中一個類別的執行個體，視其為單一檔案或多檔案操作而定。
****
| 類別 | 傳回者 |
| --- | --- |
| [Copy (複製)](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Copy.html) | `copy` |
| [下載](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Download.html) | `download` |
| [MultipleFileDownload](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/MultipleFileDownload.html) | `downloadDirectory` |
| [上傳](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Upload.html) | `upload` |
| [MultipleFileUpload](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/MultipleFileUpload.html) | `uploadFileList`, `uploadDirectory` |
所有這些類別都會實作 [Transfer](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Transfer.html) 界面。 `Transfer`提供實用方法來取得傳輸進度、暫停或繼續傳輸，以及取得傳輸的目前或最終狀態。
**Topics**
+ [輪詢傳輸的目前進度](#transfermanager-get-progress-polling)
+ [使用 ProgressListener 取得傳輸進度](#transfermanager-progress-listener)
+ [取得子轉移進度](#transfermanager-get-subtransfer-progress)
### 輪詢傳輸的目前進度
此迴圈會列印傳輸的進度、在執行時檢查其目前的進度，並在完成時列印其最終狀態。
**匯入**
```
import com.amazonaws.AmazonClientException;
import com.amazonaws.AmazonServiceException;
import com.amazonaws.event.ProgressEvent;
import com.amazonaws.event.ProgressListener;
import com.amazonaws.services.s3.transfer.*;
import com.amazonaws.services.s3.transfer.Transfer.TransferState;
import java.io.File;
import java.util.ArrayList;
import java.util.Collection;
```
**Code**
```
// print the transfer's human-readable description
System.out.println(xfer.getDescription());
// print an empty progress bar...
printProgressBar(0.0);
// update the progress bar while the xfer is ongoing.
do {
try {
Thread.sleep(100);
} catch (InterruptedException e) {
return;
}
// Note: so_far and total aren't used, they're just for
// documentation purposes.
TransferProgress progress = xfer.getProgress();
long so_far = progress.getBytesTransferred();
long total = progress.getTotalBytesToTransfer();
double pct = progress.getPercentTransferred();
eraseProgressBar();
printProgressBar(pct);
} while (xfer.isDone() == false);
// print the final state of the transfer.
TransferState xfer_state = xfer.getState();
System.out.println(": " + xfer_state);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java)。
### 使用 ProgressListener 取得傳輸進度
您可以使用 Transfer 介面的 `addProgressListener`方法，將 [ProgressListener](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/event/ProgressListener.html) 連接到任何[傳輸](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Transfer.html)。
[ProgressListener](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/event/ProgressListener.html) 只需要一個方法 `progressChanged`，它需要 [ProgressEvent](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/event/ProgressEvent.html) 物件。您可以使用 物件來呼叫`getBytes`操作的總位元組數，以及呼叫 到目前為止傳輸的位元組數`getBytesTransferred`。
**匯入**
```
import com.amazonaws.AmazonClientException;
import com.amazonaws.AmazonServiceException;
import com.amazonaws.event.ProgressEvent;
import com.amazonaws.event.ProgressListener;
import com.amazonaws.services.s3.transfer.*;
import com.amazonaws.services.s3.transfer.Transfer.TransferState;
import java.io.File;
import java.util.ArrayList;
import java.util.Collection;
```
**Code**
```
File f = new File(file_path);
TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
Upload u = xfer_mgr.upload(bucket_name, key_name, f);
// print an empty progress bar...
printProgressBar(0.0);
u.addProgressListener(new ProgressListener() {
public void progressChanged(ProgressEvent e) {
double pct = e.getBytesTransferred() * 100.0 / e.getBytes();
eraseProgressBar();
printProgressBar(pct);
}
});
// block with Transfer.waitForCompletion()
XferMgrProgress.waitForCompletion(u);
// print the final state of the transfer.
TransferState xfer_state = u.getState();
System.out.println(": " + xfer_state);
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.exit(1);
}
xfer_mgr.shutdownNow();
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java)。
### 取得子轉移進度
[MultipleFileUpload](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/MultipleFileUpload.html) 類別可以透過呼叫其`getSubTransfers`方法傳回其子傳輸的相關資訊。它會傳回無法修改的[上傳](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Upload.html)物件[集合](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/Collection.html)，提供每個子傳輸的個別傳輸狀態和進度。
**匯入**
```
import com.amazonaws.AmazonClientException;
import com.amazonaws.AmazonServiceException;
import com.amazonaws.event.ProgressEvent;
import com.amazonaws.event.ProgressListener;
import com.amazonaws.services.s3.transfer.*;
import com.amazonaws.services.s3.transfer.Transfer.TransferState;
import java.io.File;
import java.util.ArrayList;
import java.util.Collection;
```
**Code**
```
Collection sub_xfers = new ArrayList();
sub_xfers = multi_upload.getSubTransfers();
do {
System.out.println("\nSubtransfer progress:\n");
for (Upload u : sub_xfers) {
System.out.println(" " + u.getDescription());
if (u.isDone()) {
TransferState xfer_state = u.getState();
System.out.println(" " + xfer_state);
} else {
TransferProgress progress = u.getProgress();
double pct = progress.getPercentTransferred();
printProgressBar(pct);
System.out.println();
}
}
// wait a bit before the next update.
try {
Thread.sleep(200);
} catch (InterruptedException e) {
return;
}
} while (multi_upload.isDone() == false);
// print the final state of the transfer.
TransferState xfer_state = multi_upload.getState();
System.out.println("\nMultipleFileUpload " + xfer_state);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java)。
## 詳細資訊
+ Amazon Simple Storage Service 《 使用者指南》中的[物件金鑰](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html)
# 將 Amazon S3 儲存貯體設定為網站
您可以設定 儲存 Amazon S3 貯體做為網站運作。若要這樣做，您需要設定其網站組態。
**注意**
這些程式碼範例假設您了解[使用 適用於 Java 的 AWS SDK](basics.md) 中的資料，並使用設定 AWS 登入資料[和開發區域中的資訊來設定預設 AWS 登入](setup-credentials.md)資料。
## 設定儲存貯體的網站組態
若要設定儲存 Amazon S3 貯體的網站組態，請使用儲存貯體名稱呼叫 AmazonS3 的 `setWebsiteConfiguration`方法來設定組態，以及包含儲存貯體網站組態的 [BucketWebsiteConfiguration](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/BucketWebsiteConfiguration.html) 物件。
*需要*設定索引文件；所有其他參數都是選用的。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.BucketWebsiteConfiguration;
```
**Code**
```
String bucket_name, String index_doc, String error_doc) {
BucketWebsiteConfiguration website_config = null;
if (index_doc == null) {
website_config = new BucketWebsiteConfiguration();
} else if (error_doc == null) {
website_config = new BucketWebsiteConfiguration(index_doc);
} else {
website_config = new BucketWebsiteConfiguration(index_doc, error_doc);
}
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
s3.setBucketWebsiteConfiguration(bucket_name, website_config);
} catch (AmazonServiceException e) {
System.out.format(
"Failed to set website configuration for bucket '%s'!\n",
bucket_name);
System.err.println(e.getErrorMessage());
System.exit(1);
}
```
**注意**
設定網站組態不會修改儲存貯體的存取許可。若要在 Web 上顯示您的檔案，您還需要設定儲存*貯體政策*，允許公開讀取儲存貯體中的檔案。如需詳細資訊，請參閱[使用 Amazon S3 儲存貯體政策管理對儲存貯體的存取](examples-s3-bucket-policies.md)。
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/SetWebsiteConfiguration.java)。
## 取得儲存貯體的網站組態
若要取得儲存 Amazon S3 貯體的網站組態，請呼叫 AmazonS3 的 `getWebsiteConfiguration`方法，並指定儲存貯體的名稱來擷取其組態。
組態會以 [BucketWebsiteConfiguration](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/BucketWebsiteConfiguration.html) 物件傳回。如果儲存貯體沒有網站組態，`null`則會傳回 。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.BucketWebsiteConfiguration;
```
**Code**
```
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
BucketWebsiteConfiguration config =
s3.getBucketWebsiteConfiguration(bucket_name);
if (config == null) {
System.out.println("No website configuration found!");
} else {
System.out.format("Index document: %s\n",
config.getIndexDocumentSuffix());
System.out.format("Error document: %s\n",
config.getErrorDocument());
}
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.out.println("Failed to get website configuration!");
System.exit(1);
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/GetWebsiteConfiguration.java)。
## 刪除儲存貯體的網站組態
若要刪除儲存 Amazon S3 貯體的網站組態，請使用儲存貯體的名稱呼叫 AmazonS3 的 `deleteWebsiteConfiguration`方法，從中刪除組態。
**匯入**
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
```
**Code**
```
final AmazonS3 s3 = AmazonS3ClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
try {
s3.deleteBucketWebsiteConfiguration(bucket_name);
} catch (AmazonServiceException e) {
System.err.println(e.getErrorMessage());
System.out.println("Failed to delete website configuration!");
System.exit(1);
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteWebsiteConfiguration.java)。
## 詳細資訊
+ Amazon S3 API 參考中的 [PUT 儲存貯體網站](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTwebsite.html)
+ Amazon S3 API 參考中的 [GET 儲存貯體網站](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketGETwebsite.html)
+ Amazon S3 API 參考中的 [DELETE 儲存貯體網站](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketDELETEwebsite.html)
# 使用 Amazon S3 用戶端加密
使用加密用戶端 Amazon S3 加密資料是您可以為存放在其中的敏感資訊提供額外一層保護的方式之一 Amazon S3。本節中的範例示範如何為您的應用程式建立和設定 Amazon S3 加密用戶端。
如果您是初次使用密碼編譯，請參閱 AWS KMS 開發人員指南中的[密碼編譯基本概念](https://docs.aws.amazon.com/kms/latest/developerguide/crypto-intro.html)，以取得密碼編譯術語和演算法的基本概觀。如需有關跨 AWS SDKs加密支援的資訊，請參閱《 Amazon Web Services 一般參考》中的[AWSAmazon S3 用戶端加密的 SDK 支援](https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html)。
**注意**
這些程式碼範例假設您了解[使用 適用於 Java 的 AWS SDK](basics.md) 中的資料，並使用設定 AWS 登入資料[和開發區域中的資訊來設定預設 AWS 登入](setup-credentials.md)資料。
如果您使用的是 1.11.836 版或更早的版本 適用於 Java 的 AWS SDK，請參閱[Amazon S3 加密用戶端遷移](s3-encryption-migration.md)，以取得將應用程式遷移至更新版本的相關資訊。如果您無法遷移，請參閱 GitHub 上的[此完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java)。
否則，如果您使用的是 1.11.837 版或更新版本 適用於 Java 的 AWS SDK，請探索下列範例主題，以使用 Amazon S3 用戶端加密。
**Topics**
+ [Amazon S3 使用用戶端主金鑰的用戶端加密](examples-crypto-masterkey.md)
+ [Amazon S3 使用 AWS KMS 受管金鑰的用戶端加密](examples-crypto-kms.md)
# Amazon S3 使用用戶端主金鑰的用戶端加密
下列範例使用 [AmazonS3EncryptionClientV2Builder](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/AmazonS3EncryptionClientV2Builder.html) 類別來建立已啟用用戶端加密的 Amazon S3 用戶端。啟用後，您 Amazon S3 使用此用戶端上傳到 的任何物件都會加密。您從 Amazon S3 使用此用戶端取得的任何物件都會自動解密。
**注意**
下列範例示範搭配客戶受管 Amazon S3 用戶端主金鑰使用用戶端加密。若要了解如何搭配 AWS KMS 受管金鑰使用加密，請參閱搭配 [Amazon S3AWS KMS 受管金鑰的用戶端加密](examples-crypto-kms.md)。
啟用用戶端加密時，您可以選擇兩種 Amazon S3 加密模式：嚴格驗證或驗證。下列各節說明如何啟用每種類型。若要了解每個模式使用哪些演算法，請參閱 [CryptoMode](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/CryptoMode.html) 定義。
## 必要的匯入
匯入下列類別以取得這些範例。
**匯入**
```
import com.amazonaws.ClientConfiguration;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3EncryptionClientV2Builder;
import com.amazonaws.services.s3.AmazonS3EncryptionV2;
import com.amazonaws.services.s3.model.CryptoConfigurationV2;
import com.amazonaws.services.s3.model.CryptoMode;
import com.amazonaws.services.s3.model.EncryptionMaterials;
import com.amazonaws.services.s3.model.StaticEncryptionMaterialsProvider;
```
## 嚴格驗證加密
如果`CryptoMode`未指定 ，嚴格驗證加密是預設模式。
若要明確啟用此模式，請在 `withCryptoConfiguration`方法中指定 `StrictAuthenticatedEncryption`值。
**注意**
若要使用用戶端驗證加密，您必須在應用程式的 classpath 中包含最新的 [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) 檔案。
**Code**
```
AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
.withRegion(Regions.US_WEST_2)
.withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.StrictAuthenticatedEncryption)))
.withEncryptionMaterialsProvider(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey)))
.build();
s3Encryption.putObject(bucket_name, ENCRYPTED_KEY2, "This is the 2nd content to encrypt");
```
## 已驗證的加密模式
當您使用 `AuthenticatedEncryption` 模式時，會在加密期間套用改進的金鑰包裝演算法。在此模式下解密時，演算法可以驗證解密物件的完整性，並在檢查失敗時擲回例外狀況。如需驗證加密運作方式的詳細資訊，請參閱[Amazon S3 用戶端驗證加密](https://aws.amazon.com/blogs/developer/amazon-s3-client-side-authenticated-encryption)部落格文章。
**注意**
若要使用用戶端驗證加密，您必須在應用程式的 classpath 中包含最新的 [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) 檔案。
若要啟用此模式，請在 `withCryptoConfiguration`方法中指定 `AuthenticatedEncryption`值。
**Code**
```
AmazonS3EncryptionV2 s3EncryptionClientV2 = AmazonS3EncryptionClientV2Builder.standard()
.withRegion(Regions.DEFAULT_REGION)
.withClientConfiguration(new ClientConfiguration())
.withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode(CryptoMode.AuthenticatedEncryption))
.withEncryptionMaterialsProvider(new StaticEncryptionMaterialsProvider(new EncryptionMaterials(secretKey)))
.build();
s3EncryptionClientV2.putObject(bucket_name, ENCRYPTED_KEY1, "This is the 1st content to encrypt");
```
# Amazon S3 使用 AWS KMS 受管金鑰的用戶端加密
下列範例使用 [AmazonS3EncryptionClientV2Builder](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/AmazonS3EncryptionClientV2Builder.html) 類別來建立已啟用用戶端加密的 Amazon S3 用戶端。設定完成後，任何使用此用戶端上傳到 Amazon S3 的物件都會加密。您從 Amazon S3 使用此用戶端取得的任何物件都會自動解密。
**注意**
下列範例示範如何搭配 AWS KMS 受管金鑰使用 Amazon S3 用戶端加密。若要了解如何使用加密搭配您自己的金鑰，請參閱[Amazon S3 用戶端加密搭配用戶端主金鑰](examples-crypto-masterkey.md)。
啟用用戶端加密時，您可以選擇兩種 Amazon S3 加密模式：嚴格驗證或驗證。下列各節說明如何啟用每種類型。若要了解每個模式使用哪些演算法，請參閱 [CryptoMode](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/CryptoMode.html) 定義。
## 必要的匯入
匯入下列類別以取得這些範例。
**匯入**
```
import com.amazonaws.ClientConfiguration;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.kms.AWSKMS;
import com.amazonaws.services.kms.AWSKMSClientBuilder;
import com.amazonaws.services.kms.model.GenerateDataKeyRequest;
import com.amazonaws.services.kms.model.GenerateDataKeyResult;
import com.amazonaws.services.s3.AmazonS3EncryptionClientV2Builder;
import com.amazonaws.services.s3.AmazonS3EncryptionV2;
import com.amazonaws.services.s3.model.CryptoConfigurationV2;
import com.amazonaws.services.s3.model.CryptoMode;
import com.amazonaws.services.s3.model.EncryptionMaterials;
import com.amazonaws.services.s3.model.KMSEncryptionMaterialsProvider;
```
## 嚴格驗證加密
如果`CryptoMode`未指定 ，嚴格驗證加密是預設模式。
若要明確啟用此模式，請在 `withCryptoConfiguration`方法中指定 `StrictAuthenticatedEncryption`值。
**注意**
若要使用用戶端驗證加密，您必須在應用程式的 classpath 中包含最新的 [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) 檔案。
**Code**
```
AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
.withRegion(Regions.US_WEST_2)
.withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.StrictAuthenticatedEncryption)))
.withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId))
.build();
s3Encryption.putObject(bucket_name, ENCRYPTED_KEY3, "This is the 3rd content to encrypt with a key created in the {console}");
System.out.println(s3Encryption.getObjectAsString(bucket_name, ENCRYPTED_KEY3));
```
在 Amazon S3 加密用戶端上呼叫 `putObject`方法以上傳物件。
**Code**
```
s3Encryption.putObject(bucket_name, ENCRYPTED_KEY3, "This is the 3rd content to encrypt with a key created in the {console}");
```
您可以使用相同的用戶端擷取物件。此範例會呼叫 `getObjectAsString`方法，以擷取存放的字串。
**Code**
```
System.out.println(s3Encryption.getObjectAsString(bucket_name, ENCRYPTED_KEY3));
```
## 已驗證的加密模式
當您使用 `AuthenticatedEncryption` 模式時，會在加密期間套用改進的金鑰包裝演算法。在此模式下解密時，演算法可以驗證解密物件的完整性，並在檢查失敗時擲回例外狀況。如需驗證加密運作方式的詳細資訊，請參閱[Amazon S3 用戶端驗證加密](https://aws.amazon.com/blogs/developer/amazon-s3-client-side-authenticated-encryption)部落格文章。
**注意**
若要使用用戶端驗證加密，您必須在應用程式的 classpath 中包含最新的 [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) 檔案。
若要啟用此模式，請在 `withCryptoConfiguration`方法中指定 `AuthenticatedEncryption`值。
**Code**
```
AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
.withRegion(Regions.US_WEST_2)
.withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.AuthenticatedEncryption)))
.withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId))
.build();
```
## 設定 AWS KMS 用戶端
除非明確指定，否則 Amazon S3 加密用戶端預設會建立 AWS KMS 用戶端。
若要為此自動建立的 AWS KMS 用戶端設定區域，請設定 `awsKmsRegion`。
**Code**
```
Region kmsRegion = Region.getRegion(Regions.AP_NORTHEAST_1);
AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
.withRegion(Regions.US_WEST_2)
.withCryptoConfiguration(new CryptoConfigurationV2().withAwsKmsRegion(kmsRegion))
.withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId))
.build();
```
或者，您可以使用自己的 AWS KMS 用戶端來初始化加密用戶端。
**Code**
```
AWSKMS kmsClient = AWSKMSClientBuilder.standard()
.withRegion(Regions.US_WEST_2);
.build();
AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard()
.withRegion(Regions.US_WEST_2)
.withKmsClient(kmsClient)
.withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.AuthenticatedEncryption)))
.withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId))
.build();
```
# Amazon SQS 使用 的範例 適用於 Java 的 AWS SDK
本節提供使用[適用於 Java 的 AWS SDK](https://aws.amazon.com/sdk-for-java/)編寫 [Amazon SQS](https://aws.amazon.com/sqs/) 程式的範例。
**注意**
這些範例僅包含示範每種技術所需的程式碼。[GitHub 上提供完整程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java)。您可以從那裡下載單一原始檔案或將儲存庫複製到本機，以取得建置和執行的所有範例。
**Topics**
+ [使用 Amazon SQS 訊息佇列](examples-sqs-message-queues.md)
+ [傳送、接收和刪除 Amazon SQS 訊息](examples-sqs-messages.md)
+ [啟用 Amazon SQS 訊息佇列的長輪詢](examples-sqs-long-polling.md)
+ [在 中設定可見性逾時 Amazon SQS](examples-sqs-visibility-timeout.md)
+ [在 中使用無效字母佇列 Amazon SQS](examples-sqs-dead-letter-queues.md)
# 使用 Amazon SQS 訊息佇列
*訊息佇列*是用來可靠地傳送訊息的邏輯容器 Amazon SQS。有兩種佇列類型：*標準*和*先進先出* (FIFO)。若要進一步了解佇列和這些類型之間的差異，請參閱 [Amazon SQS 開發人員指南](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/)。
本主題說明如何使用 建立、列出、刪除和取得 Amazon SQS 佇列的 URL 適用於 Java 的 AWS SDK。
## 建立佇列
使用 AmazonSQS 用戶端的 `createQueue`方法，提供描述佇列參數的 [CreateQueueRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/CreateQueueRequest.html) 物件。
**匯入**
```
import com.amazonaws.services.sqs.AmazonSQS;
import com.amazonaws.services.sqs.AmazonSQSClientBuilder;
import com.amazonaws.services.sqs.model.AmazonSQSException;
import com.amazonaws.services.sqs.model.CreateQueueRequest;
```
**Code**
```
AmazonSQS sqs = AmazonSQSClientBuilder.defaultClient();
CreateQueueRequest create_request = new CreateQueueRequest(QUEUE_NAME)
.addAttributesEntry("DelaySeconds", "60")
.addAttributesEntry("MessageRetentionPeriod", "86400");
try {
sqs.createQueue(create_request);
} catch (AmazonSQSException e) {
if (!e.getErrorCode().equals("QueueAlreadyExists")) {
throw e;
}
}
```
您可以使用簡化形式的 `createQueue`，只需要佇列名稱來建立標準佇列。
```
sqs.createQueue("MyQueue" + new Date().getTime());
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java)。
## 列出佇列
若要列出帳戶的 Amazon SQS 佇列，請呼叫 AmazonSQS 用戶端的 `listQueues`方法。
**匯入**
```
import com.amazonaws.services.sqs.AmazonSQS;
import com.amazonaws.services.sqs.AmazonSQSClientBuilder;
import com.amazonaws.services.sqs.model.ListQueuesResult;
```
**Code**
```
AmazonSQS sqs = AmazonSQSClientBuilder.defaultClient();
ListQueuesResult lq_result = sqs.listQueues();
System.out.println("Your SQS Queue URLs:");
for (String url : lq_result.getQueueUrls()) {
System.out.println(url);
}
```
使用無任何參數的`listQueues`過載會傳回*所有佇列*。您可以透過傳遞`ListQueuesRequest`物件來篩選傳回的結果。
**匯入**
```
import com.amazonaws.services.sqs.AmazonSQS;
import com.amazonaws.services.sqs.AmazonSQSClientBuilder;
import com.amazonaws.services.sqs.model.ListQueuesRequest;
```
**Code**
```
AmazonSQS sqs = AmazonSQSClientBuilder.defaultClient();
String name_prefix = "Queue";
lq_result = sqs.listQueues(new ListQueuesRequest(name_prefix));
System.out.println("Queue URLs with prefix: " + name_prefix);
for (String url : lq_result.getQueueUrls()) {
System.out.println(url);
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java)。
## 取得佇列 URL
呼叫 AmazonSQS 用戶端的 `getQueueUrl`方法。
**匯入**
```
import com.amazonaws.services.sqs.AmazonSQS;
import com.amazonaws.services.sqs.AmazonSQSClientBuilder;
```
**Code**
```
AmazonSQS sqs = AmazonSQSClientBuilder.defaultClient();
String queue_url = sqs.getQueueUrl(QUEUE_NAME).getQueueUrl();
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java)。
## 刪除佇列
將佇列的 [URL](#sqs-get-queue-url) 提供給 AmazonSQS 用戶端的 `deleteQueue`方法。
**匯入**
```
import com.amazonaws.services.sqs.AmazonSQS;
import com.amazonaws.services.sqs.AmazonSQSClientBuilder;
```
**Code**
```
AmazonSQS sqs = AmazonSQSClientBuilder.defaultClient();
sqs.deleteQueue(queue_url);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java)。
## 詳細資訊
+ 《 [Amazon SQS 開發人員指南》中的佇列如何運作](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-how-it-works.html) Amazon SQS
+ Amazon SQS API 參考中的 [CreateQueue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_CreateQueue.html)
+ API Amazon SQS 參考中的 [GetQueueUrl](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_GetQueueUrl.html)
+ Amazon SQS API 參考中的 [ListQueues](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ListQueues.html)
+ Amazon SQS API 參考中的 [DeleteQueues](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteQueues.html)
# 傳送、接收和刪除 Amazon SQS 訊息
本主題說明如何傳送、接收和刪除 Amazon SQS 訊息。訊息一律使用 [SQS 佇列](examples-sqs-message-queues.md)來傳送。
## 傳送訊息
呼叫 AmazonSQS 用戶端的 `sendMessage`方法，將單一訊息新增至 Amazon SQS 佇列。提供 [SendMessageRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/SendMessageRequest.html) 物件，其中包含佇列的 [URL](examples-sqs-message-queues.md#sqs-get-queue-url)、訊息本文，以及選用的延遲值 (以秒為單位)。
**匯入**
```
import com.amazonaws.services.sqs.AmazonSQS;
import com.amazonaws.services.sqs.AmazonSQSClientBuilder;
import com.amazonaws.services.sqs.model.SendMessageRequest;
```
**Code**
```
SendMessageRequest send_msg_request = new SendMessageRequest()
.withQueueUrl(queueUrl)
.withMessageBody("hello world")
.withDelaySeconds(5);
sqs.sendMessage(send_msg_request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/SendReceiveMessages.java)。
### 一次傳送多個訊息
您可以在單一請求中傳送多個訊息。若要傳送多則訊息，請使用 AmazonSQS 用戶端的 `sendMessageBatch`方法，該方法會採用 [SendMessageBatchRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/SendMessageBatchRequest.html)，其中包含要傳送的佇列 URL 和訊息清單 （每個都包含一個 [SendMessageBatchRequestEntry](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/SendMessageBatchRequestEntry.html))。您也可以為每個訊息設定選用的延遲值。
**匯入**
```
import com.amazonaws.services.sqs.model.SendMessageBatchRequest;
import com.amazonaws.services.sqs.model.SendMessageBatchRequestEntry;
```
**Code**
```
SendMessageBatchRequest send_batch_request = new SendMessageBatchRequest()
.withQueueUrl(queueUrl)
.withEntries(
new SendMessageBatchRequestEntry(
"msg_1", "Hello from message 1"),
new SendMessageBatchRequestEntry(
"msg_2", "Hello from message 2")
.withDelaySeconds(10));
sqs.sendMessageBatch(send_batch_request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/SendReceiveMessages.java)。
## 接收訊息
呼叫 AmazonSQS 用戶端的 `receiveMessage`方法，將佇列的 URL 傳遞給佇列，以擷取目前佇列中的任何訊息。訊息會以 [Message](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/Message.html) 物件清單的形式傳回。
**匯入**
```
import com.amazonaws.services.sqs.AmazonSQSClientBuilder;
import com.amazonaws.services.sqs.model.AmazonSQSException;
import com.amazonaws.services.sqs.model.SendMessageBatchRequest;
```
**Code**
```
List messages = sqs.receiveMessage(queueUrl).getMessages();
```
## 在收到訊息後刪除訊息
收到訊息並處理其內容後，將訊息的接收控點和佇列 URL 傳送至 AmazonSQS 用戶端的 `deleteMessage`方法，從佇列刪除訊息。
**Code**
```
for (Message m : messages) {
sqs.deleteMessage(queueUrl, m.getReceiptHandle());
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/SendReceiveMessages.java)。
## 詳細資訊
+ 《 [Amazon SQS 開發人員指南》中的佇列如何運作](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-how-it-works.html) Amazon SQS
+ API Amazon SQS 參考中的 [SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html)
+ API Amazon SQS 參考中的 [SendMessageBatch](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html)
+ Amazon SQS API 參考中的 [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html)
+ Amazon SQS API 參考中的 [DeleteMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html)
# 啟用 Amazon SQS 訊息佇列的長輪詢
Amazon SQS 根據預設， 會使用*短輪詢*，根據加權隨機分佈僅查詢伺服器子集，以判斷回應中是否包含任何訊息。
當沒有訊息可傳回以回覆傳送至 Amazon SQS 佇列的 ReceiveMessage 請求並消除誤報時，長輪詢有助於 Amazon SQS 降低使用 的成本。
**注意**
您可以將長輪詢頻率設定為 *1-20 秒*。
## 建立佇列時啟用長輪詢
若要在建立 Amazon SQS 佇列時啟用長輪詢，請在 [CreateQueueRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/CreateQueueRequest.html) 物件上設定 `ReceiveMessageWaitTimeSeconds` 屬性，然後再呼叫 AmazonSQS 類別的 `createQueue`方法。
**匯入**
```
import com.amazonaws.services.sqs.AmazonSQS;
import com.amazonaws.services.sqs.AmazonSQSClientBuilder;
import com.amazonaws.services.sqs.model.AmazonSQSException;
import com.amazonaws.services.sqs.model.CreateQueueRequest;
```
**Code**
```
final AmazonSQS sqs = AmazonSQSClientBuilder.defaultClient();
// Enable long polling when creating a queue
CreateQueueRequest create_request = new CreateQueueRequest()
.withQueueName(queue_name)
.addAttributesEntry("ReceiveMessageWaitTimeSeconds", "20");
try {
sqs.createQueue(create_request);
} catch (AmazonSQSException e) {
if (!e.getErrorCode().equals("QueueAlreadyExists")) {
throw e;
}
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/LongPolling.java)。
## 在現有佇列上啟用長輪詢
除了在建立佇列時啟用長輪詢之外，您也可以在呼叫 AmazonSQS 類別的 `setQueueAttributes`方法之前，在 [SetQueueAttributesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/SetQueueAttributesRequest.html) `ReceiveMessageWaitTimeSeconds`上設定 ，在現有佇列上啟用它。
**匯入**
```
import com.amazonaws.services.sqs.model.SetQueueAttributesRequest;
```
**Code**
```
SetQueueAttributesRequest set_attrs_request = new SetQueueAttributesRequest()
.withQueueUrl(queue_url)
.addAttributesEntry("ReceiveMessageWaitTimeSeconds", "20");
sqs.setQueueAttributes(set_attrs_request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/LongPolling.java)。
## 在收到訊息時啟用長輪詢
您可以在接收訊息時啟用長輪詢，方法是在您提供給 AmazonSQS 類別的 [ReceiveMessageRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/ReceiveMessageRequest.html) `receiveMessage`方法上設定等待時間，以秒為單位。
**注意**
您應該確保 AWS 用戶端的請求逾時大於最長輪詢時間 (20 秒），以便您的`receiveMessage`請求在等待下一個輪詢事件時不會逾時！
**匯入**
```
import com.amazonaws.services.sqs.model.ReceiveMessageRequest;
```
**Code**
```
ReceiveMessageRequest receive_request = new ReceiveMessageRequest()
.withQueueUrl(queue_url)
.withWaitTimeSeconds(20);
sqs.receiveMessage(receive_request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/LongPolling.java)。
## 詳細資訊
+ 《 Amazon SQS 開發人員指南》中的[Amazon SQS 長輪詢](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-long-polling.html)
+ Amazon SQS API 參考中的 [CreateQueue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_CreateQueue.html)
+ Amazon SQS API 參考中的 [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html)
+ Amazon SQS API 參考中的 [SetQueueAttributes](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SetQueueAttributes.html)
# 在 中設定可見性逾時 Amazon SQS
在 中接收訊息時 Amazon SQS，訊息會保留在佇列中，直到刪除為止，以確保接收。在指定的*可見性逾時*後，後續請求中將可取得已接收但未刪除的訊息，以協助防止訊息在處理和刪除之前收到超過一次。
**注意**
使用[標準佇列](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/standard-queues.html)時，可見性逾時並不能保證接收訊息兩次。如果您使用的是標準佇列，請確定您的程式碼可以處理相同訊息已交付多次的情況。
## 設定單一訊息的訊息可見性逾時
當您收到訊息時，您可以透過在傳遞給 AmazonSQS 類別`changeMessageVisibility`的 [ChangeMessageVisibilityRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/ChangeMessageVisibilityRequest.html) 中傳遞其接收控點，來修改其可見性逾時。
**匯入**
```
import com.amazonaws.services.sqs.AmazonSQS;
import com.amazonaws.services.sqs.AmazonSQSClientBuilder;
```
**Code**
```
AmazonSQS sqs = AmazonSQSClientBuilder.defaultClient();
// Get the receipt handle for the first message in the queue.
String receipt = sqs.receiveMessage(queue_url)
.getMessages()
.get(0)
.getReceiptHandle();
sqs.changeMessageVisibility(queue_url, receipt, timeout);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/VisibilityTimeout.java)。
## 一次設定多個訊息的訊息可見性逾時
若要一次設定多個訊息的訊息可見性逾時，請建立 [ChangeMessageVisibilityBatchRequestEntry](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/ChangeMessageVisibilityBatchRequestEntry.html) 物件清單，每個物件都包含唯一的 ID 字串和接收控點。然後，將清單傳遞至 Amazon SQS 用戶端類別的 `changeMessageVisibilityBatch`方法。
**匯入**
```
import com.amazonaws.services.sqs.AmazonSQS;
import com.amazonaws.services.sqs.AmazonSQSClientBuilder;
import com.amazonaws.services.sqs.model.ChangeMessageVisibilityBatchRequestEntry;
import java.util.ArrayList;
import java.util.List;
```
**Code**
```
AmazonSQS sqs = AmazonSQSClientBuilder.defaultClient();
List entries =
new ArrayList();
entries.add(new ChangeMessageVisibilityBatchRequestEntry(
"unique_id_msg1",
sqs.receiveMessage(queue_url)
.getMessages()
.get(0)
.getReceiptHandle())
.withVisibilityTimeout(timeout));
entries.add(new ChangeMessageVisibilityBatchRequestEntry(
"unique_id_msg2",
sqs.receiveMessage(queue_url)
.getMessages()
.get(0)
.getReceiptHandle())
.withVisibilityTimeout(timeout + 200));
sqs.changeMessageVisibilityBatch(queue_url, entries);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/VisibilityTimeout.java)。
## 詳細資訊
+ 《 Amazon SQS 開發人員指南》中的[可見性逾時](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html)
+ Amazon SQS API 參考中的 [SetQueueAttributes](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SetQueueAttributes.html)
+ Amazon SQS API 參考中的 [GetQueueAttributes](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_GetQueueAttributes.html)
+ Amazon SQS API 參考中的 [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html)
+ Amazon SQS API 參考中的 [ChangeMessageVisibility](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ChangeMessageVisibility.html)
+ Amazon SQS API 參考中的 [ChangeMessageVisibilityBatch](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ChangeMessageVisibilityBatch.html)
# 在 中使用無效字母佇列 Amazon SQS
Amazon SQS 支援*無效字母佇列*。無效字母佇列是其他 （來源） 佇列可以針對無法成功處理的訊息設定目標的佇列。您可以在無效字母佇列中擱置並隔離這類訊息，以確定無法成功處理訊息的原因。
## 建立無效字母佇列
無效字母佇列的建立方式與一般佇列相同，但有下列限制：
+ 無效字母佇列必須與來源佇列的佇列類型相同 (FIFO 或標準）。
+ 無效字母佇列必須使用與來源佇列相同的 AWS 帳戶 和 區域建立。
在這裡，我們建立兩個相同的 Amazon SQS 佇列，其中一個將做為無效字母佇列：
**匯入**
```
import com.amazonaws.services.sqs.AmazonSQS;
import com.amazonaws.services.sqs.AmazonSQSClientBuilder;
import com.amazonaws.services.sqs.model.AmazonSQSException;
```
**Code**
```
final AmazonSQS sqs = AmazonSQSClientBuilder.defaultClient();
// Create source queue
try {
sqs.createQueue(src_queue_name);
} catch (AmazonSQSException e) {
if (!e.getErrorCode().equals("QueueAlreadyExists")) {
throw e;
}
}
// Create dead-letter queue
try {
sqs.createQueue(dl_queue_name);
} catch (AmazonSQSException e) {
if (!e.getErrorCode().equals("QueueAlreadyExists")) {
throw e;
}
}
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/DeadLetterQueues.java)。
## 指定來源佇列的無效字母佇列
若要指定無效字母佇列，您必須先建立*再驅動政策*，然後在佇列的屬性中設定政策。再驅動政策是在 JSON 中指定，並指定無效字母佇列的 ARN，以及在傳送至無效字母佇列之前可接收和處理訊息的次數上限。
若要設定來源佇列的再驅動政策，請使用 [SetQueueAttributesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/SetQueueAttributesRequest.html) 物件呼叫 AmazonSQS 類別的 `setQueueAttributes`方法，而您已使用 JSON 再驅動政策設定 `RedrivePolicy` 屬性。
**匯入**
```
import com.amazonaws.services.sqs.model.GetQueueAttributesRequest;
import com.amazonaws.services.sqs.model.GetQueueAttributesResult;
import com.amazonaws.services.sqs.model.SetQueueAttributesRequest;
```
**Code**
```
String dl_queue_url = sqs.getQueueUrl(dl_queue_name)
.getQueueUrl();
GetQueueAttributesResult queue_attrs = sqs.getQueueAttributes(
new GetQueueAttributesRequest(dl_queue_url)
.withAttributeNames("QueueArn"));
String dl_queue_arn = queue_attrs.getAttributes().get("QueueArn");
// Set dead letter queue with redrive policy on source queue.
String src_queue_url = sqs.getQueueUrl(src_queue_name)
.getQueueUrl();
SetQueueAttributesRequest request = new SetQueueAttributesRequest()
.withQueueUrl(src_queue_url)
.addAttributesEntry("RedrivePolicy",
"{\"maxReceiveCount\":\"5\", \"deadLetterTargetArn\":\""
+ dl_queue_arn + "\"}");
sqs.setQueueAttributes(request);
```
請參閱 GitHub 上的[完整範例](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/DeadLetterQueues.java)。
## 詳細資訊
+ 《 Amazon SQS 開發人員指南》中的[使用 Amazon SQS 無效字母佇列](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html)
+ Amazon SQS API 參考中的 [SetQueueAttributes](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SetQueueAttributes.html)
# Amazon SWF 使用 的範例 適用於 Java 的 AWS SDK
[Amazon SWF](https://aws.amazon.com/swf/) 是一種工作流程管理服務，可協助開發人員建置和擴展分散式工作流程，這些工作流程可以具有由活動、子工作流程或甚至是 [Lambda](https://aws.amazon.com/lambda/) 任務組成的平行或循序步驟。
Amazon SWF 使用 適用於 Java 的 AWS SDK、使用 SWF *用戶端*物件或使用 AWS Flow Framework 適用於 Java 的 有兩種方式。 AWS Flow Framework 適用於 Java 的 一開始較難設定，因為它會大量使用註釋，並依賴其他程式庫，例如 AspectJ 和 Spring Framework。不過，對於大型或複雜的專案，您可以使用 AWS Flow Framework 適用於 Java 的 來節省編碼時間。如需詳細資訊，請參閱適用於 [AWS Flow Framework Java 的 開發人員指南](https://docs.aws.amazon.com/amazonswf/latest/awsflowguide/)。
本節提供直接 Amazon SWF 使用 適用於 Java 的 AWS SDK 用戶端的程式設計範例。
**Topics**
+ [SWF 基本概念](swf-basics.md)
+ [建置簡單的 Amazon SWF 應用程式](swf-hello.md)
+ [Lambda 任務](swf-lambda-task.md)
+ [正常關閉活動和工作流程工作者](swf-graceful-shutdown.md)
+ [註冊網域](prog-services-swf-register-domain.md)
+ [列出網域](prog-services-swf-list-domains.md)
# SWF 基本概念
這些是 Amazon SWF 使用 的一般模式 適用於 Java 的 AWS SDK。它主要用於參考。如需更完整的簡介教學課程，請參閱[建置簡易 Amazon SWF 應用程式](swf-hello.md)。
## 相依性
基本 Amazon SWF 應用程式將需要下列相依性，這些相依性包含在 中 適用於 Java 的 AWS SDK：
+ aws-java-sdk-1.12.\$1.jar
+ commons-logging-1.2.\$1.jar
+ httpclient-4.3.\$1.jar
+ httpcore-4.3.\$1.jar
+ jackson-annotations-2.12.\$1.jar
+ jackson-core-2.12.\$1.jar
+ jackson-databind-2.12.\$1.jar
+ joda-time-2.8.\$1.jar
**注意**
這些套件的版本編號會根據您擁有的開發套件版本而有所不同，但開發套件隨附的版本已經過相容性測試，且是您應使用的版本。
AWS Flow Framework for Java 應用程式需要額外的設定*和其他*相依性。如需使用架構的詳細資訊，請參閱[AWS Flow Framework 適用於 Java 的 開發人員指南](https://docs.aws.amazon.com/amazonswf/latest/awsflowguide/)。
## 匯入
一般而言，您可以使用下列匯入進行程式碼開發：
```
import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflowClientBuilder;
import com.amazonaws.services.simpleworkflow.model.*;
```
不過，最好只匯入您需要的類別。最後，您可能會在`com.amazonaws.services.simpleworkflow.model`工作區中指定特定類別：
```
import com.amazonaws.services.simpleworkflow.model.PollForActivityTaskRequest;
import com.amazonaws.services.simpleworkflow.model.RespondActivityTaskCompletedRequest;
import com.amazonaws.services.simpleworkflow.model.RespondActivityTaskFailedRequest;
import com.amazonaws.services.simpleworkflow.model.TaskList;
```
如果您使用的是 AWS Flow Framework 適用於 Java 的 ，則會從`com.amazonaws.services.simpleworkflow.flow`工作區匯入類別。例如：
```
import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflow;
import com.amazonaws.services.simpleworkflow.flow.ActivityWorker;
```
**注意**
AWS Flow Framework 適用於 Java 的 具有 基礎以外的其他需求 適用於 Java 的 AWS SDK。如需詳細資訊，請參閱適用於 [AWS Flow Framework Java 的 開發人員指南](https://docs.aws.amazon.com/amazonswf/latest/awsflowguide/)。
## 使用 SWF 用戶端類別
您的 基本界面 Amazon SWF 是透過 [AmazonSimpleWorkflowClient](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/AmazonSimpleWorkflowClient.html) 或 [AmazonSimpleWorkflowAsyncClient](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/AmazonSimpleWorkflowAsyncClient.html) 類別。兩者之間的主要區別在於 `\*AsyncClient`類別會傳回[未來](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/concurrent/Future.html)物件，以進行並行 （非同步） 程式設計。
```
AmazonSimpleWorkflowClient swf = AmazonSimpleWorkflowClientBuilder.defaultClient();
```
# 建置簡單的 Amazon SWF 應用程式
本主題將介紹如何使用 編寫[Amazon SWF](https://aws.amazon.com/swf/)應用程式 適用於 Java 的 AWS SDK，同時在整個過程中介紹幾個重要概念。
## 關於範例
此範例專案會建立工作流程，其中包含單一活動，接受透過 AWS 雲端傳遞的工作流程資料 （在 HelloWorld 的傳統中，它會是有人打招呼的名稱），然後列印問候語以回應。
雖然這在表面上看起來非常簡單， Amazon SWF 但應用程式由多個組件一起運作：
+ **網域**，用作工作流程執行資料的邏輯容器。
+ 一或多個**工作流程**，代表定義工作流程活動和子工作流程之邏輯執行順序的程式碼元件。
+ **工作流程工作者**，也稱為*決策者*，會輪詢決策任務並排程活動或子工作流程以回應。
+ 一或多個**活動**，每個活動代表工作流程中的工作單位。
+ **輪詢活動任務並執行活動方法以回應的活動工作者**。
+ 一或多個**任務清單**，這些是 維護的佇列， Amazon SWF 用於向工作流程和活動工作者發出請求。任務清單上適用於工作流程工作者的任務稱為*決策任務*。適用於活動工作者的那些任務稱為*活動任務*。
+ 開始工作流程執行的工作流程**啟動**者。
在幕後， Amazon SWF 會協調這些元件的操作、協調其來自 AWS 雲端的流程、在它們之間傳遞資料、處理逾時和活動訊號通知，以及記錄工作流程執行歷史記錄。
## 先決條件
### 開發環境
本教學中使用的開發環境包含：
+ [適用於 Java 的 AWS SDK](https://aws.amazon.com/sdk-for-java/)。
+ [Apache Maven](http://maven.apache.org/) (3.3.1)。
+ JDK 1.7 或更新版本。本教學課程是使用 JDK 1.8.0 進行開發和測試。
+ 良好的 Java 文字編輯器 （由您選擇）。
**注意**
如果您使用與 Maven 不同的建置系統，您仍然可以使用適合您環境的步驟建立專案，並使用此處提供的概念來遵循。有關設定和使用 適用於 Java 的 AWS SDK 搭配各種建置系統的詳細資訊，請參閱 [入門](getting-started.md)。
同樣地，但只要付出更多努力，就可以使用任何支援 AWS SDKs 實作此處顯示的步驟 Amazon SWF。
包含所有必要的外部相依性 適用於 Java 的 AWS SDK，因此無需下載任何額外的項目。
### AWS 存取
若要成功完成本教學課程，您必須能夠存取 AWS 存取入口網站，如[本指南的基本設定一節所述](signup-create-iam-user.md#signup-create-iam-user-overview)。
這些指示說明如何存取您複製並貼到本機共用`credentials`檔案的臨時登入資料。您貼上的臨時登入資料必須與 中的 IAM 角色相關聯 AWS IAM Identity Center ，該角色具有存取 Amazon SWF 的許可。貼上臨時登入資料後，您的`credentials`檔案看起來會類似以下內容。
```
[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token=IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE
```
這些臨時登入資料與`default`設定檔相關聯。
## 建立 SWF 專案
1. 使用 Maven 啟動新專案：
```
mvn archetype:generate -DartifactId=helloswf \
-DgroupId=aws.example.helloswf -DinteractiveMode=false
```
這會建立具有標準 maven 專案結構的新專案：
```
helloswf
├── pom.xml
└── src
├── main
│ └── java
│ └── aws
│ └── example
│ └── helloswf
│ └── App.java
└── test
└── ...
```
您可以忽略或刪除`test`目錄及其包含的所有內容，我們不會將其用於本教學課程。您也可以刪除 `App.java`，因為我們會將它取代為新的類別。
1. 編輯專案`pom.xml`的檔案，並在 ``區塊中新增其相依性，以新增 **aws-java-sdk-simpleworkflow** 模組。
```
com.amazonaws
aws-java-sdk-simpleworkflow
1.11.1000
```
1. *請確定 Maven 使用 JDK 1.7\$1 支援建置您的專案。*在 中將下列項目新增至您的專案 (``區塊之前或之後）`pom.xml`：
```
maven-compiler-plugin
3.6.1
1.8
1.8
```
## 為專案編寫程式碼
範例專案將包含四個不同的應用程式，我們將逐一造訪：
+ **HelloTypes.java** - 包含與其他元件共用的專案網域、活動和工作流程類型資料。它還處理向 SWF 註冊這些類型。
+ **ActivityWorker.java** - 包含活動工作者，它會輪詢活動任務並執行活動以回應。
+ **WorkflowWorker.java** - 包含工作流程工作者 （決策者），它會輪詢決策任務並排程新活動。
+ **WorkflowStarter.java** - 包含工作流程啟動器，這會啟動新的工作流程執行，這將導致 SWF 開始產生決策和工作流程任務，以供工作者使用。
### 所有來源檔案的常見步驟
您為容納 Java 類別而建立的所有檔案都會有幾個共同點。基於時間考量，*每次將新檔案新增至專案時，這些步驟都會隱含*：
1. 在專案`src/main/java/aws/example/helloswf/`目錄中的 中建立 檔案。
1. 將`package`宣告新增至每個檔案的開頭，以宣告其命名空間。範例專案使用：
```
package aws.example.helloswf;
```
1. 新增 [AmazonSimpleWorkflowClient](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/AmazonSimpleWorkflowClient.html) 類別和 `com.amazonaws.services.simpleworkflow.model` 命名空間中多個類別的`import`宣告。為了簡化物件，我們將使用：
```
import com.amazonaws.regions.Regions;
import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflow;
import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflowClientBuilder;
import com.amazonaws.services.simpleworkflow.model.*;
```
### 註冊網域、工作流程和活動類型
首先，我們會建立新的可執行檔類別 `HelloTypes.java`。此檔案將包含工作流程不同部分需要知道的共用資料，例如活動的名稱和版本，以及工作流程類型、網域名稱和任務清單名稱。
1. 開啟文字編輯器並建立檔案 `HelloTypes.java`，根據[常見步驟](#swf-hello-common)新增套件宣告和匯入。
1. 宣告 `HelloTypes`類別，並提供用於已註冊活動和工作流程類型的值：
```
public static final String DOMAIN = "HelloDomain";
public static final String TASKLIST = "HelloTasklist";
public static final String WORKFLOW = "HelloWorkflow";
public static final String WORKFLOW_VERSION = "1.0";
public static final String ACTIVITY = "HelloActivity";
public static final String ACTIVITY_VERSION = "1.0";
```
這些值將在整個程式碼中使用。
1. 在字串宣告之後，建立 [AmazonSimpleWorkflowClient](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/AmazonSimpleWorkflowClient.html) 類別的執行個體。這是 所提供 Amazon SWF 方法的基本界面 適用於 Java 的 AWS SDK。
```
private static final AmazonSimpleWorkflow swf =
AmazonSimpleWorkflowClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
```
上一個程式碼片段假設暫時登入資料與`default`設定檔相關聯。如果您使用不同的設定檔，請修改上述程式碼，如下所示，並將 *profile\$1name *取代為實際的設定檔名稱。
```
private static final AmazonSimpleWorkflow swf =
AmazonSimpleWorkflowClientBuilder
.standard()
.withCredentials(new ProfileCredentialsProvider("profile_name"))
.withRegion(Regions.DEFAULT_REGION)
.build();
```
1. 新增函數以註冊 SWF 網域。*網域*是許多相關 SWF 活動和工作流程類型的邏輯容器。SWF 元件只能在相同網域中存在時互相通訊。
```
try {
System.out.println("** Registering the domain '" + DOMAIN + "'.");
swf.registerDomain(new RegisterDomainRequest()
.withName(DOMAIN)
.withWorkflowExecutionRetentionPeriodInDays("1"));
} catch (DomainAlreadyExistsException e) {
System.out.println("** Domain already exists!");
}
```
註冊網域時，您會提供*名稱* （一組 1 到 256 個字元，不包括 `:`、`/`、`|`、控制字元或常值字串 '`arn') 和*保留期間*，這是工作流程執行完成後 Amazon SWF ，工作流程執行歷史記錄資料的保留天數。工作流程執行保留期上限為 90 天。如需詳細資訊，請參閱 [RegisterDomainRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/RegisterDomainRequest.html)。
如果具有該名稱的網域已存在，則會引發 [DomainAlreadyExistsException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/DomainAlreadyExistsException.html)。由於我們未考量網域是否已建立，因此可以忽略例外狀況。
**注意**
此程式碼示範使用 適用於 Java 的 AWS SDK 方法時的常見模式，方法的資料是由 `simpleworkflow.model` 命名空間中的類別提供，您可以使用可鏈結`0with*`的方法執行個體化和填入。
1. 新增函數以註冊新的活動類型。*活動*代表工作流程中的工作單位。
```
try {
System.out.println("** Registering the activity type '" + ACTIVITY +
"-" + ACTIVITY_VERSION + "'.");
swf.registerActivityType(new RegisterActivityTypeRequest()
.withDomain(DOMAIN)
.withName(ACTIVITY)
.withVersion(ACTIVITY_VERSION)
.withDefaultTaskList(new TaskList().withName(TASKLIST))
.withDefaultTaskScheduleToStartTimeout("30")
.withDefaultTaskStartToCloseTimeout("600")
.withDefaultTaskScheduleToCloseTimeout("630")
.withDefaultTaskHeartbeatTimeout("10"));
} catch (TypeAlreadyExistsException e) {
System.out.println("** Activity type already exists!");
}
```
活動類型由*名稱*和*版本*識別，用於唯一識別其註冊網域中任何其他人的活動。活動也包含許多選用參數，例如用於從 SWF 接收任務和資料的預設任務清單，以及可用於限制活動執行不同部分需要多長時間的不同逾時。如需詳細資訊，請參閱 [RegisterActivityTypeRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/RegisterActivityTypeRequest.html)。
**注意**
所有逾時值都以*秒*為單位指定。如需[Amazon SWF 逾時如何影響工作流程執行的完整說明，請參閱逾時類型](https://docs.aws.amazon.com/amazonswf/latest/developerguide/swf-timeout-types.html)。
如果您嘗試註冊的活動類型已存在，則會引發 [TypeAlreadyExistsException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/TypeAlreadyExistsException.html)。新增 函數以註冊新的工作流程類型。*工作流程*也稱為*決策者*，代表工作流程執行的邏輯。
\$1
```
try {
System.out.println("** Registering the workflow type '" + WORKFLOW +
"-" + WORKFLOW_VERSION + "'.");
swf.registerWorkflowType(new RegisterWorkflowTypeRequest()
.withDomain(DOMAIN)
.withName(WORKFLOW)
.withVersion(WORKFLOW_VERSION)
.withDefaultChildPolicy(ChildPolicy.TERMINATE)
.withDefaultTaskList(new TaskList().withName(TASKLIST))
.withDefaultTaskStartToCloseTimeout("30"));
} catch (TypeAlreadyExistsException e) {
System.out.println("** Workflow type already exists!");
}
```
\$1
與活動類型類似，工作流程類型會依*名稱*和*版本*識別，並具有可設定的逾時。如需詳細資訊，請參閱 [RegisterWorkflowTypeRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/RegisterWorkflowTypeRequest.html)。
\$1
如果您嘗試註冊的工作流程類型已存在，則會引發 [TypeAlreadyExistsException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/TypeAlreadyExistsException.html)。最後，提供 `main`方法讓類別可執行，進而註冊網域、活動類型和工作流程類型：
\$1
```
registerDomain();
registerWorkflowType();
registerActivityType();
```
您可以立即[建置](#swf-hello-build)並[執行](#swf-hello-run-register)應用程式以執行註冊指令碼，或繼續編碼活動和工作流程工作者。網域、工作流程和活動註冊完成後，就不需要再次執行此操作，這些類型會持續存在，直到您自行棄用它們為止。
### 實作活動工作者
*活動*是工作流程中的基本工作單位。工作流程提供邏輯、排程要執行的活動 （或其他要採取的動作） 以回應決策任務。典型的工作流程通常包含許多可以同步、非同步或兩者組合執行的活動。
*活動工作者*是輪詢 為 Amazon SWF 回應工作流程決策而產生之活動任務的程式碼位元。收到活動任務時，它會執行對應的活動，並將成功/失敗回應傳回工作流程。
我們將實作簡單的活動工作者，以推動單一活動。
1. 開啟您的文字編輯器並建立檔案 `ActivityWorker.java`，根據[常見步驟](#swf-hello-common)新增套件宣告和匯入。
```
import com.amazonaws.regions.Regions;
import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflow;
import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflowClientBuilder;
import com.amazonaws.services.simpleworkflow.model.*;
```
1. 將 `ActivityWorker`類別新增至 檔案，並為其提供資料成員，以保留我們將用來與之互動的 SWF 用戶端 Amazon SWF：
```
private static final AmazonSimpleWorkflow swf =
AmazonSimpleWorkflowClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
```
1. 新增我們將用作活動的方法：
```
private static String sayHello(String input) throws Throwable {
return "Hello, " + input + "!";
}
```
活動只需要一個字串，將其合併為問候語並傳回結果。雖然此活動不太可能引發例外狀況，但最好設計活動，以便在發生錯誤時引發錯誤。
1. 新增`main`我們將用作活動任務輪詢方法的方法。我們會新增一些程式碼來輪詢活動任務的任務清單，以開始執行此作業：
```
System.out.println("Polling for an activity task from the tasklist '"
+ HelloTypes.TASKLIST + "' in the domain '" +
HelloTypes.DOMAIN + "'.");
ActivityTask task = swf.pollForActivityTask(
new PollForActivityTaskRequest()
.withDomain(HelloTypes.DOMAIN)
.withTaskList(
new TaskList().withName(HelloTypes.TASKLIST)));
String task_token = task.getTaskToken();
```
活動 Amazon SWF 透過呼叫 SWF 用戶端的 `pollForActivityTask`方法接收來自 的任務，指定要在傳入 [PollForActivityTaskRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/PollForActivityTaskRequest.html) 中使用的網域和任務清單。
收到任務後，我們會呼叫任務的 `getTaskToken`方法來擷取其唯一識別符。
1. 接著，撰寫一些程式碼來處理進來的任務。在輪詢任務並擷取其任務字符的程式碼之後，立即將以下內容新增至您的`main`方法。
```
if (task_token != null) {
String result = null;
Throwable error = null;
try {
System.out.println("Executing the activity task with input '" +
task.getInput() + "'.");
result = sayHello(task.getInput());
} catch (Throwable th) {
error = th;
}
if (error == null) {
System.out.println("The activity task succeeded with result '"
+ result + "'.");
swf.respondActivityTaskCompleted(
new RespondActivityTaskCompletedRequest()
.withTaskToken(task_token)
.withResult(result));
} else {
System.out.println("The activity task failed with the error '"
+ error.getClass().getSimpleName() + "'.");
swf.respondActivityTaskFailed(
new RespondActivityTaskFailedRequest()
.withTaskToken(task_token)
.withReason(error.getClass().getSimpleName())
.withDetails(error.getMessage()));
}
}
```
如果任務字符不是 `null`，我們可以開始執行活動方法 (`sayHello`)，提供它與任務一起傳送的輸入資料。
如果任務*成功 *（未產生錯誤），則工作者會使用包含任務字符和活動結果資料的 [RespondActivityTaskCompletedRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/RespondActivityTaskCompletedRequest.html) 物件呼叫 SWF 用戶端的 `respondActivityTaskCompleted`方法來回應 SWF。
另一方面，如果任務*失敗*，我們會透過使用 [RespondActivityTaskFailedRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/RespondActivityTaskFailedRequest.html) 物件呼叫 `respondActivityTaskFailed`方法，將任務權杖和錯誤的相關資訊傳遞給它來回應。
**注意**
如果終止，此活動將不會正常關閉。雖然它超出本教學課程的範圍，但此活動工作者的替代實作會在隨附的主題中提供，[即關閉活動和工作流程工作者 Gracefully](swf-graceful-shutdown.md)。
### 實作工作流程工作者
您的工作流程邏輯位於稱為**工作流程工作者**的程式碼中。工作流程工作者會輪詢網域 Amazon SWF 中由 傳送的決策任務，以及在預設任務清單上註冊工作流程類型的決策任務。
當工作流程工作者收到任務時，會做出某種決策 （通常是是否排程新活動），並採取適當的動作 （例如排程活動）。
1. 開啟文字編輯器並建立檔案 `WorkflowWorker.java`，根據[常見步驟](#swf-hello-common)新增套件宣告和匯入。
1. 將一些額外的匯入新增至 檔案：
```
import com.amazonaws.regions.Regions;
import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflow;
import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflowClientBuilder;
import com.amazonaws.services.simpleworkflow.model.*;
import java.util.ArrayList;
import java.util.List;
import java.util.UUID;
```
1. 宣告 `WorkflowWorker`類別，並建立用於存取 SWF 方法的 [AmazonSimpleWorkflowClient](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/AmazonSimpleWorkflowClient.html) 類別執行個體。
```
private static final AmazonSimpleWorkflow swf =
AmazonSimpleWorkflowClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
```
1. 新增 `main`方法。方法會持續循環，使用 SWF 用戶端的 `pollForDecisionTask`方法輪詢決策任務。[PollForDecisionTaskRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/PollForDecisionTaskRequest.html) 提供詳細資訊。
```
PollForDecisionTaskRequest task_request =
new PollForDecisionTaskRequest()
.withDomain(HelloTypes.DOMAIN)
.withTaskList(new TaskList().withName(HelloTypes.TASKLIST));
while (true) {
System.out.println(
"Polling for a decision task from the tasklist '" +
HelloTypes.TASKLIST + "' in the domain '" +
HelloTypes.DOMAIN + "'.");
DecisionTask task = swf.pollForDecisionTask(task_request);
String taskToken = task.getTaskToken();
if (taskToken != null) {
try {
executeDecisionTask(taskToken, task.getEvents());
} catch (Throwable th) {
th.printStackTrace();
}
}
}
```
一旦收到任務，我們就會呼叫其`getTaskToken`方法，傳回可用來識別任務的字串。如果傳回的字符不是 `null`，我們會在 `executeDecisionTask`方法中進一步處理它，並傳遞任務字符和隨任務傳送的 [HistoryEvent](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/HistoryEvent.html) 物件清單。
1. 新增 `executeDecisionTask`方法，取得任務字符 (`String`) 和 `HistoryEvent`清單。
```
List decisions = new ArrayList();
String workflow_input = null;
int scheduled_activities = 0;
int open_activities = 0;
boolean activity_completed = false;
String result = null;
```
我們也設定一些資料成員來追蹤下列項目：
+ 用於報告處理任務結果的[決策](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/Decision.html)物件清單。
+ 保留「WorkflowExecutionStarted」事件提供之工作流程輸入的字串
+ 排程和開啟 （執行中） 活動的計數，以避免在已排程或目前正在執行時排程相同的活動。
+ 布林值，表示活動已完成。
+ 保留活動結果的字串，用於將其作為我們的工作流程結果傳回。
1. 接下來，新增一些程式碼到 `executeDecisionTask` ，根據 `getEventType`方法報告的事件類型，處理與任務一起傳送的`HistoryEvent`物件。
```
System.out.println("Executing the decision task for the history events: [");
for (HistoryEvent event : events) {
System.out.println(" " + event);
switch(event.getEventType()) {
case "WorkflowExecutionStarted":
workflow_input =
event.getWorkflowExecutionStartedEventAttributes()
.getInput();
break;
case "ActivityTaskScheduled":
scheduled_activities++;
break;
case "ScheduleActivityTaskFailed":
scheduled_activities--;
break;
case "ActivityTaskStarted":
scheduled_activities--;
open_activities++;
break;
case "ActivityTaskCompleted":
open_activities--;
activity_completed = true;
result = event.getActivityTaskCompletedEventAttributes()
.getResult();
break;
case "ActivityTaskFailed":
open_activities--;
break;
case "ActivityTaskTimedOut":
open_activities--;
break;
}
}
System.out.println("]");
```
基於工作流程的目的，我們最感興趣的是：
+ 「WorkflowExecutionStarted」事件，表示工作流程執行已開始 （通常表示您應該在工作流程中執行第一個活動），並提供提供給工作流程的初始輸入。在這種情況下，它是我們問候語的名稱部分，因此會儲存在字串中，以便在排程要執行的活動時使用。
+ 「ActivityTaskCompleted」事件，會在排程活動完成後傳送。事件資料也包含已完成活動的傳回值。由於我們只有一個活動，我們將使用該值作為整個工作流程的結果。
如果您的工作流程需要，則可以使用其他事件類型。如需每個事件類型的相關資訊，請參閱 [HistoryEvent](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/HistoryEvent.html) 類別描述。
\$1 注意：Java 7 中引入`switch`了陳述式中的字串。如果您使用的是舊版 Java，則可以使用 [EventType](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/model/EventType.html) 類別，將 `String`傳回的 `history_event.getType()` 轉換為列舉值，然後`String`視需要返回 ：
```
EventType et = EventType.fromValue(event.getEventType());
```
1. 在`switch`陳述式之後，新增更多程式碼，根據收到的任務做出適當的*決策*來回應。
```
if (activity_completed) {
decisions.add(
new Decision()
.withDecisionType(DecisionType.CompleteWorkflowExecution)
.withCompleteWorkflowExecutionDecisionAttributes(
new CompleteWorkflowExecutionDecisionAttributes()
.withResult(result)));
} else {
if (open_activities == 0 && scheduled_activities == 0) {
ScheduleActivityTaskDecisionAttributes attrs =
new ScheduleActivityTaskDecisionAttributes()
.withActivityType(new ActivityType()
.withName(HelloTypes.ACTIVITY)
.withVersion(HelloTypes.ACTIVITY_VERSION))
.withActivityId(UUID.randomUUID().toString())
.withInput(workflow_input);
decisions.add(
new Decision()
.withDecisionType(DecisionType.ScheduleActivityTask)
.withScheduleActivityTaskDecisionAttributes(attrs));
} else {
// an instance of HelloActivity is already scheduled or running. Do nothing, another
// task will be scheduled once the activity completes, fails or times out
}
}
System.out.println("Exiting the decision task with the decisions " + decisions);
```
+ 如果活動尚未排程，我們會回應決策，該`ScheduleActivityTask`決策會在 [ScheduleActivityTaskDecisionAttributes](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/ScheduleActivityTaskDecisionAttributes.html) 結構中提供 Amazon SWF 後續排程活動的相關資訊，也包括 Amazon SWF 應傳送至活動的任何資料。
+ 如果活動已完成，我們將整個工作流程視為已完成，並以`CompletedWorkflowExecution`決策回應，填寫 [CompleteWorkflowExecutionDecisionAttributes](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/CompleteWorkflowExecutionDecisionAttributes.html) 結構，以提供已完成工作流程的詳細資訊。在這種情況下，我們會傳回活動的結果。
無論哪種情況，決策資訊都會新增至方法頂端宣告的`Decision`清單。
1. 傳回處理任務時收集的`Decision`物件清單，以完成決策任務。在我們撰寫`executeDecisionTask`的方法結尾新增此程式碼：
```
swf.respondDecisionTaskCompleted(
new RespondDecisionTaskCompletedRequest()
.withTaskToken(taskToken)
.withDecisions(decisions));
```
SWF 用戶端的 `respondDecisionTaskCompleted`方法會取得識別任務的任務字符，以及`Decision`物件清單。
### 實作工作流程啟動者
最後，我們將編寫一些程式碼來開始工作流程執行。
1. 開啟文字編輯器並建立檔案 `WorkflowStarter.java`，根據[常見步驟](#swf-hello-common)新增套件宣告和匯入。
1. 新增 `WorkflowStarter`類別：
```
package aws.example.helloswf;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflow;
import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflowClientBuilder;
import com.amazonaws.services.simpleworkflow.model.*;
public class WorkflowStarter {
private static final AmazonSimpleWorkflow swf =
AmazonSimpleWorkflowClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
public static final String WORKFLOW_EXECUTION = "HelloWorldWorkflowExecution";
public static void main(String[] args) {
String workflow_input = "{SWF}";
if (args.length > 0) {
workflow_input = args[0];
}
System.out.println("Starting the workflow execution '" + WORKFLOW_EXECUTION +
"' with input '" + workflow_input + "'.");
WorkflowType wf_type = new WorkflowType()
.withName(HelloTypes.WORKFLOW)
.withVersion(HelloTypes.WORKFLOW_VERSION);
Run run = swf.startWorkflowExecution(new StartWorkflowExecutionRequest()
.withDomain(HelloTypes.DOMAIN)
.withWorkflowType(wf_type)
.withWorkflowId(WORKFLOW_EXECUTION)
.withInput(workflow_input)
.withExecutionStartToCloseTimeout("90"));
System.out.println("Workflow execution started with the run id '" +
run.getRunId() + "'.");
}
}
```
`WorkflowStarter` 類別由單一方法 組成`main`，採用在命令列上傳遞的選用引數做為工作流程的輸入資料。
SWF 用戶端方法 `startWorkflowExecution`採用 [StartWorkflowExecutionRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/StartWorkflowExecutionRequest.html) 物件做為輸入。在這裡，除了指定要執行的網域和工作流程類型之外，我們還提供它：
+ 人類可讀取的工作流程執行名稱
+ 工作流程輸入資料 （在範例中的命令列提供）
+ 逾時值，代表整個工作流程執行所需的時間，以秒為單位。
`startWorkflowExecution` 傳回的[執行](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/Run.html)物件提供*執行 ID*，此值可用來識別工作流程執行 Amazon SWF歷史記錄中的此特定工作流程執行。
\$1 注意：執行 ID 是由 產生 Amazon SWF，與您在啟動工作流程執行時傳入的工作流程執行名稱*不同*。
## 建置範例
若要使用 Maven 建置範例專案，請前往 `helloswf`目錄並輸入：
```
mvn package
```
產生的 `helloswf-1.0.jar`會在 `target`目錄中產生。
## 執行範例
此範例包含四個獨立的可執行檔類別，彼此獨立執行。
**注意**
如果您使用的是 Linux、macOS 或 Unix 系統，您可以在單一終端機視窗中逐一執行所有系統。如果您執行 Windows，您應該開啟兩個額外的命令列執行個體，並導覽至每個執行個體中的`helloswf`目錄。
### 設定 Java classpath
雖然 Maven 已為您處理相依性，但若要執行範例，您需要在 Java classpath 上提供 AWS SDK 程式庫及其相依性。您可以將`CLASSPATH`環境變數設定為 AWS SDK 程式庫的位置和 SDK 中的`third-party/lib`目錄，其中包括必要的相依性：
```
export CLASSPATH='target/helloswf-1.0.jar:/path/to/sdk/lib/*:/path/to/sdk/third-party/lib/*'
java example.swf.hello.HelloTypes
```
或使用 **` java `**命令`-cp`的選項，在執行每個應用程式時設定 classpath。
```
java -cp target/helloswf-1.0.jar:/path/to/sdk/lib/*:/path/to/sdk/third-party/lib/* \
example.swf.hello.HelloTypes
```
您使用的樣式由您決定。如果您在建置程式碼時沒有問題，則嘗試執行範例並取得一系列的 "NoClassDefFound" 錯誤，這可能是因為 classpath 設定不正確。
### 註冊網域、工作流程和活動類型
在執行工作者和工作流程啟動者之前，您需要註冊網域以及工作流程和活動類型。要執行此操作的程式碼是在[註冊網域工作流程和活動類型](#swf-hello-hellotypes)中實作。
建置之後，如果您已[設定 CLASSPATH](#swf-hello-set-classpath)，您可以執行 命令來執行註冊碼：
```
echo 'Supply the name of one of the example classes as an argument.'
```
### 啟動活動和工作流程工作者
現在類型已註冊，您可以啟動活動和工作流程工作者。這些任務將繼續執行並輪詢任務，直到它們被刪除，因此您應該在單獨的終端視窗中執行它們，或者，如果您在 Linux、macOS 或 Unix 上執行，您可以使用 `&`運算子在執行時使它們產生單獨的程序。
```
echo 'If there are arguments to the class, put them in quotes after the class name.'
exit 1
```
如果您在不同的視窗中執行這些命令，請省略每行的最終`&`運算子。
### 啟動工作流程執行
現在您的活動和工作流程工作者正在輪詢，您可以開始工作流程執行。此程序將執行，直到工作流程傳回完成的狀態。您應該在新的終端機視窗中執行它 （除非您使用 `&`運算子，將工作者執行為新產生的程序）。
```
fi
```
**注意**
如果您想要提供自己的輸入資料，這些資料會先傳遞至工作流程，然後再傳遞至活動，請將其新增至命令列。例如：
```
echo "## Running $className..."
```
開始工作流程執行後，您應該會開始看到工作者和工作流程執行本身交付的輸出。當工作流程最終完成時，其輸出將列印到螢幕。
## 此範例的完整來源
您可以在 *aws-java-developer-guide* 儲存庫的 Github 上瀏覽此範例[的完整來源](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java/example_code/swf)。
## 如需詳細資訊
+ 如果工作者在工作流程輪詢進行時關閉，則此處顯示的工作者可能會導致任務遺失。若要了解如何正常關閉工作者，請參閱[關閉活動和工作流程工作者。](swf-graceful-shutdown.md)
+ 若要進一步了解 Amazon SWF，請造訪 [Amazon SWF](https://aws.amazon.com/swf/) 首頁或檢視 [Amazon SWF 開發人員指南](https://docs.aws.amazon.com/amazonswf/latest/developerguide/)。
+ 您可以使用 AWS Flow Framework 適用於 Java 的 ，使用 註釋，以優雅 Java 樣式撰寫更複雜的工作流程。若要進一步了解，請參閱適用於 [AWS Flow Framework Java 的 開發人員指南](https://docs.aws.amazon.com/amazonswf/latest/awsflowguide/)。
# Lambda 任務
做為活動或與其結合 Amazon SWF 使用的替代方案，您可以使用 [Lambda](https://aws.amazon.com/lambda/) 函數來代表工作流程中的工作單位，並以類似活動的方式進行排程。
本主題著重於如何使用 實作 Amazon SWF Lambda 任務 適用於 Java 的 AWS SDK。如需一般 Lambda 任務的詳細資訊，請參閱《 Amazon SWF 開發人員指南》中的[AWS Lambda 任務](https://docs.aws.amazon.com/amazonswf/latest/developerguide/lambda-task.html)。
## 設定跨服務 IAM 角色來執行 Lambda 函數
Amazon SWF 您必須先設定 IAM 角色，以授予代表您執行 Lambda 函數的 Amazon SWF 許可，才能執行 Lambda 函數。如需如何執行此操作的完整資訊，請參閱[AWS Lambda 任務](https://docs.aws.amazon.com/amazonswf/latest/developerguide/lambda-task.html)。
當您註冊將使用 Lambda 任務的工作流程時，將需要此 IAM 角色的 Amazon Resource Name (ARN)。
## 建立 Lambda 函數
您可以使用多種不同的語言撰寫 Lambda 函數，包括 Java。如需如何撰寫、部署和使用 Lambda 函數的完整資訊，請參閱 [AWS Lambda 開發人員指南](https://docs.aws.amazon.com/lambda/latest/dg/)。
**注意**
無論您使用哪種語言來撰寫 Lambda 函數，都可以排程和執行*任何* Amazon SWF 工作流程，無論您的工作流程程式碼是使用哪種語言撰寫。 會 Amazon SWF 處理執行函數和將資料傳出和傳出的詳細資訊。
以下是一個簡單的 Lambda 函數，可用於取代[建置簡單 Amazon SWF 應用程式](swf-hello.md)中的活動。
+ 此版本以 JavaScript 撰寫，可直接使用 輸入[AWS 管理主控台](https://console.aws.amazon.com/console/home)：
```
exports.handler = function(event, context) {
context.succeed("Hello, " + event.who + "!");
};
```
+ 以下是以 Java 撰寫的相同函數，您也可以在 Lambda 上部署和執行：
```
package example.swf.hellolambda;
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import com.amazonaws.util.json.JSONException;
import com.amazonaws.util.json.JSONObject;
public class SwfHelloLambdaFunction implements RequestHandler {
@Override
public Object handleRequest(Object input, Context context) {
String who = "{SWF}";
if (input != null) {
JSONObject jso = null;
try {
jso = new JSONObject(input.toString());
who = jso.getString("who");
} catch (JSONException e) {
e.printStackTrace();
}
}
return ("Hello, " + who + "!");
}
}
```
**注意**
若要進一步了解如何將 Java 函數部署至 Lambda，請參閱《 AWS Lambda 開發人員指南》中的[建立部署套件 (Java)](https://docs.aws.amazon.com/lambda/latest/dg/lambda-java-how-to-create-deployment-package.html)。您也想要查看標題為 [Java 中編寫 Lambda 函數程式設計模型的](https://docs.aws.amazon.com/lambda/latest/dg/java-programming-model.html)章節。
Lambda 函數會將*事件*或*輸入*物件做為第一個參數，並將*內容*物件做為第二個參數，提供執行 Lambda 函數之請求的相關資訊。此特定函數預期輸入會以 JSON 表示，`who`欄位設定為用來建立問候語的名稱。
## 註冊工作流程以搭配 Lambda 使用
若要讓工作流程排程 Lambda 函數，您必須提供 IAM 角色的名稱，該角色 Amazon SWF 提供叫用 Lambda 函數的許可。您可以使用 [RegisterWorkflowTypeRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/RegisterWorkflowTypeRequest.html) 的 `withDefaultLambdaRole`或 `setDefaultLambdaRole`方法，在工作流程註冊期間設定此項目。
```
System.out.println("** Registering the workflow type '" + WORKFLOW + "-" + WORKFLOW_VERSION
+ "'.");
try {
swf.registerWorkflowType(new RegisterWorkflowTypeRequest()
.withDomain(DOMAIN)
.withName(WORKFLOW)
.withDefaultLambdaRole(lambda_role_arn)
.withVersion(WORKFLOW_VERSION)
.withDefaultChildPolicy(ChildPolicy.TERMINATE)
.withDefaultTaskList(new TaskList().withName(TASKLIST))
.withDefaultTaskStartToCloseTimeout("30"));
}
catch (TypeAlreadyExistsException e) {
```
## 排程 Lambda 任務
排程 Lambda 任務與排程活動類似。您可以使用 `ScheduleLambdaFunction`[DecisionType](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/DecisionType.html) 和 [ScheduleLambdaFunctionDecisionAttributes](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/ScheduleLambdaFunctionDecisionAttributes.html) 提供[決策](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/Decision.html)。
```
running_functions == 0 && scheduled_functions == 0) {
AWSLambda lam = AWSLambdaClientBuilder.defaultClient();
GetFunctionConfigurationResult function_config =
lam.getFunctionConfiguration(
new GetFunctionConfigurationRequest()
.withFunctionName("HelloFunction"));
String function_arn = function_config.getFunctionArn();
ScheduleLambdaFunctionDecisionAttributes attrs =
new ScheduleLambdaFunctionDecisionAttributes()
.withId("HelloFunction (Lambda task example)")
.withName(function_arn)
.withInput(workflow_input);
decisions.add(
```
在 中`ScheduleLambdaFuntionDecisionAttributes`，您必須提供*名稱*，也就是要呼叫的 Lambda 函數的 ARN，以及 *id*，這是 Amazon SWF 用來識別歷史記錄日誌中 Lambda 函數的名稱。
您也可以為 Lambda 函數提供選用*輸入*，並設定其*開始關閉逾時*值，這是允許 Lambda 函數在產生`LambdaFunctionTimedOut`事件之前執行的秒數。
**注意**
此程式碼使用 [AWSLambdaClient](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/AWSLambdaClient.html) 來擷取 Lambda 函數的 ARN，並指定函數名稱。您可以使用此技術來避免在程式碼中硬式編碼完整的 ARN （包括您的 AWS 帳戶 ID)。
## 在決策者中處理 Lambda 函數事件
Lambda 任務將產生許多事件，您可以在工作流程工作者中輪詢決策任務時對其採取動作，對應於 Lambda 任務的生命週期，並使用 [EventType](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/EventType.html) 值，例如 `LambdaFunctionScheduled`、 `LambdaFunctionStarted`和 `LambdaFunctionCompleted`。如果 Lambda 函數失敗，或執行時間超過其設定的逾時值，您分別會收到 `LambdaFunctionFailed`或 `LambdaFunctionTimedOut`事件類型。
```
boolean function_completed = false;
String result = null;
System.out.println("Executing the decision task for the history events: [");
for (HistoryEvent event : events) {
System.out.println(" " + event);
EventType event_type = EventType.fromValue(event.getEventType());
switch(event_type) {
case WorkflowExecutionStarted:
workflow_input =
event.getWorkflowExecutionStartedEventAttributes()
.getInput();
break;
case LambdaFunctionScheduled:
scheduled_functions++;
break;
case ScheduleLambdaFunctionFailed:
scheduled_functions--;
break;
case LambdaFunctionStarted:
scheduled_functions--;
running_functions++;
break;
case LambdaFunctionCompleted:
running_functions--;
function_completed = true;
result = event.getLambdaFunctionCompletedEventAttributes()
.getResult();
break;
case LambdaFunctionFailed:
running_functions--;
break;
case LambdaFunctionTimedOut:
running_functions--;
break;
```
## 從 Lambda 函數接收輸出
當您在 [HistoryEvent](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/HistoryEvent.html) `LambdaFunctionCompleted`[EventType](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/EventType.html), you can retrieve your 0 function’s return value by first calling `getLambdaFunctionCompletedEventAttributes`上收到 以取得 [LambdaFunctionCompletedEventAttributes](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/LambdaFunctionCompletedEventAttributes.html) 物件，然後呼叫其`getResult`方法擷取 Lambda 函數的輸出：
```
LambdaFunctionCompleted:
running_functions--;
```
## 此範例的完整來源
您可以在 *aws-java-developer-guide 儲存庫的 Github 上瀏覽此範例的完整來源 ：github：`*。 *aws-java-developer-guide*
# 正常關閉活動和工作流程工作者
[建置簡易 Amazon SWF 應用程式](swf-hello.md)主題提供簡單工作流程應用程式的完整實作，其中包含註冊應用程式、活動和工作流程工作者，以及工作流程入門。
工作者類別旨在持續執行，輪詢 Amazon SWF 傳送的任務，以執行活動或傳回決策。提出輪詢請求後， 會 Amazon SWF 記錄輪詢器，並嘗試指派任務給輪詢器。
如果工作流程工作者在長時間輪詢期間終止， Amazon SWF 可能仍會嘗試將任務傳送至已終止的工作者，導致任務遺失 （直到任務逾時）。
處理這種情況的一種方法是等待所有長輪詢請求傳回，再讓工作者終止。
在本主題中，我們將從 重寫活動工作者`helloswf`，使用 Java 的關閉勾點來嘗試正常關閉活動工作者。
以下是完整的程式碼：
```
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflow;
import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflowClientBuilder;
import com.amazonaws.services.simpleworkflow.model.ActivityTask;
import com.amazonaws.services.simpleworkflow.model.PollForActivityTaskRequest;
import com.amazonaws.services.simpleworkflow.model.RespondActivityTaskCompletedRequest;
import com.amazonaws.services.simpleworkflow.model.RespondActivityTaskFailedRequest;
import com.amazonaws.services.simpleworkflow.model.TaskList;
public class ActivityWorkerWithGracefulShutdown {
private static final AmazonSimpleWorkflow swf =
AmazonSimpleWorkflowClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build();
private static final CountDownLatch waitForTermination = new CountDownLatch(1);
private static volatile boolean terminate = false;
private static String executeActivityTask(String input) throws Throwable {
return "Hello, " + input + "!";
}
public static void main(String[] args) {
Runtime.getRuntime().addShutdownHook(new Thread() {
@Override
public void run() {
try {
terminate = true;
System.out.println("Waiting for the current poll request" +
" to return before shutting down.");
waitForTermination.await(60, TimeUnit.SECONDS);
}
catch (InterruptedException e) {
// ignore
}
}
});
try {
pollAndExecute();
}
finally {
waitForTermination.countDown();
}
}
public static void pollAndExecute() {
while (!terminate) {
System.out.println("Polling for an activity task from the tasklist '"
+ HelloTypes.TASKLIST + "' in the domain '" +
HelloTypes.DOMAIN + "'.");
ActivityTask task = swf.pollForActivityTask(new PollForActivityTaskRequest()
.withDomain(HelloTypes.DOMAIN)
.withTaskList(new TaskList().withName(HelloTypes.TASKLIST)));
String taskToken = task.getTaskToken();
if (taskToken != null) {
String result = null;
Throwable error = null;
try {
System.out.println("Executing the activity task with input '"
+ task.getInput() + "'.");
result = executeActivityTask(task.getInput());
}
catch (Throwable th) {
error = th;
}
if (error == null) {
System.out.println("The activity task succeeded with result '"
+ result + "'.");
swf.respondActivityTaskCompleted(
new RespondActivityTaskCompletedRequest()
.withTaskToken(taskToken)
.withResult(result));
}
else {
System.out.println("The activity task failed with the error '"
+ error.getClass().getSimpleName() + "'.");
swf.respondActivityTaskFailed(
new RespondActivityTaskFailedRequest()
.withTaskToken(taskToken)
.withReason(error.getClass().getSimpleName())
.withDetails(error.getMessage()));
}
}
}
}
}
```
在此版本中，原始版本中`main`函數中的輪詢程式碼已移至自己的方法 `pollAndExecute`。
`main` 函數現在使用 [CountDownLatch](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/concurrent/CountDownLatch.html) 搭配[關機掛](https://docs.oracle.com/javase/8/docs/api/index.html?java/lang/Runtime.html)鉤，讓執行緒在請求終止後等待最多 60 秒，然後讓執行緒關閉。
# 註冊網域
中的每個工作流程和活動[Amazon SWF](https://aws.amazon.com/swf/)都需要*網域*才能執行。
1. 建立新的 [RegisterDomainRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/RegisterDomainRequest.html) 物件，提供至少網域名稱和工作流程執行保留期 （這些參數都是必要的）。
1. 使用 RegisterDomainRequest 物件呼叫 [AmazonSimpleWorkflowClient.registerDomain](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/AmazonSimpleWorkflowClient.html#registerDomain-com.amazonaws.services.simpleworkflow.model.RegisterDomainRequest-) *RegisterDomainRequest*方法。
1. 如果您請求的網域已存在 （在此情況下，通常不需要採取任何動作），請擷取 [DomainAlreadyExistsException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/DomainAlreadyExistsException.html)。
下列程式碼示範此程序：
```
public void register_swf_domain(AmazonSimpleWorkflowClient swf, String name)
{
RegisterDomainRequest request = new RegisterDomainRequest().withName(name);
request.setWorkflowExecutionRetentionPeriodInDays("10");
try
{
swf.registerDomain(request);
}
catch (DomainAlreadyExistsException e)
{
System.out.println("Domain already exists!");
}
}
```
# 列出網域
您可以依註冊類型列出與您的帳戶和 AWS 區域相關聯的[Amazon SWF](https://aws.amazon.com/swf/)網域。
1. 建立 [ListDomainsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/ListDomainsRequest.html) 物件，並指定您感興趣的網域註冊狀態，這是必要的。
1. 使用 ListDomainRequest 物件呼叫 [AmazonSimpleWorkflowClient.listDomains](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/AmazonSimpleWorkflowClient.html#listDomains-com.amazonaws.services.simpleworkflow.model.ListDomainsRequest-)。 *ListDomainRequest* 結果會在 [DomainInfos](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/DomainInfos.html) 物件中提供。
1. 在傳回的物件上呼叫 [getDomainInfos](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/DomainInfos.html#getDomainInfos--)，以取得 [DomainInfo](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/DomainInfo.html) 物件的清單。
1. 在每個 *DomainInfo* 物件上呼叫 [getName](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/DomainInfo.html#getName--) 以取得其名稱。
下列程式碼示範此程序：
```
public void list_swf_domains(AmazonSimpleWorkflowClient swf)
{
ListDomainsRequest request = new ListDomainsRequest();
request.setRegistrationStatus("REGISTERED");
DomainInfos domains = swf.listDomains(request);
System.out.println("Current Domains:");
for (DomainInfo di : domains.getDomainInfos())
{
System.out.println(" * " + di.getName());
}
}
```
# 軟體開發套件隨附的程式碼範例
適用於 Java 的 AWS SDK 隨附程式碼範例，可在可建置、可執行的程式中示範開發套件的許多功能。您可以使用 來研究或修改這些項目，以實作您自己的 AWS 解決方案 適用於 Java 的 AWS SDK。
## 如何取得範例
適用於 Java 的 AWS SDK 程式碼範例提供於 SDK *的範例*目錄中。如果您使用[設定 適用於 Java 的 AWS SDK](setup-install.md) 中的資訊下載並安裝 SDK，則表示您已在系統上擁有範例。
您也可以在 src/samples 目錄中檢視 適用於 Java 的 AWS SDK GitHub 儲存庫上的最新範例。 [https://github.com/aws/aws-sdk-java/tree/master/src/samples](https://github.com/aws/aws-sdk-java/tree/master/src/samples)
## 使用命令列建置和執行範例
這些範例包含 [Ant](http://ant.apache.org/) 建置指令碼，讓您可以輕鬆地從命令列建置和執行指令碼。每個範例也包含 HTML 格式的 README 檔案，其中包含每個範例的特定資訊。
**注意**
如果您在 GitHub 上瀏覽範本程式碼，請在檢視範例的 README.html 檔案時，按一下原始程式碼顯示中的**原始**按鈕。在原始模式中，HTML 會在瀏覽器中如預期呈現。
### 先決條件
在執行任何 適用於 Java 的 AWS SDK 範例之前，您需要在環境或使用 設定 AWS 登入資料 AWS CLI，如[設定 AWS 登入資料和開發區域](setup-credentials.md)所指定。這些範例會盡可能使用預設登入資料提供者鏈結。因此，透過以這種方式設定您的登入資料，您可以避免將 AWS 登入資料插入來源碼目錄中的檔案中 （在其中可能不小心簽入和公開共用） 的風險實務。
### 執行範例
1. 變更為包含範例程式碼的目錄。例如，如果您位於 AWS SDK 下載的根目錄中，並想要執行`AwsConsoleApp`範例，您可以輸入：
```
cd samples/AwsConsoleApp
```
1. 使用 Ant 建置並執行範例。預設建置目標會執行兩個動作，因此您只需要輸入：
```
ant
```
範例會將資訊列印至標準輸出，例如：
```
===========================================
Welcome to the {AWS} Java SDK!
===========================================
You have access to 4 Availability Zones.
You have 0 {EC2} instance(s) running.
You have 13 Amazon SimpleDB domain(s) containing a total of 62 items.
You have 23 {S3} bucket(s), containing 44 objects with a total size of 154767691 bytes.
```
## 使用 Eclipse IDE 建置和執行範例
如果您使用 AWS Toolkit for Eclipse，也可以根據 在 Eclipse 中啟動新專案， 適用於 Java 的 AWS SDK 或將 SDK 新增至現有的 Java 專案。
### 先決條件
安裝 之後 AWS Toolkit for Eclipse，建議您使用安全登入資料設定 Toolkit。您可以隨時從 Eclipse 的**視窗**選單中選擇**偏好設定**，然後選擇** AWS 工具組**區段，以執行此操作。
### 執行範例
1. 開啟 Eclipse。
1. 建立新的 AWS Java 專案。在 Eclipse ****的檔案功能表上，選擇**新增**，然後按一下**專案**。**新專案**精靈隨即開啟。
1. 展開** AWS **類別，然後選擇 ** AWS Java 專案**。
1. 選擇 **Next (下一步)**。專案設定頁面隨即顯示。
1. 在**專案名稱**方塊中輸入名稱。 適用於 Java 的 AWS SDK 範例群組會顯示 SDK 中可用的範例，如前所述。
1. 選取每個核取方塊，以選取要包含在專案中的範例。
1. 輸入您的 AWS 登入資料。如果您已 AWS Toolkit for Eclipse 使用登入資料設定 ，則會自動填入。
1. 選擇 **Finish** (完成)。專案已建立並新增至 **Project Explorer**。
1. 選擇您要執行的範例`.java`檔案。例如，針對 Amazon S3 範例，選擇 `S3Sample.java`。
1. 從**執行**功能表中選擇**執行**。
1. 在 **Project Explorer** 中的專案上按一下滑鼠右鍵，指向**建置路徑**，然後選擇**新增程式庫**。
1. 選擇 ** AWS Java 開發套件**，選擇**下一步**，然後遵循其餘的螢幕指示。