本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 AWS Health API AWS Health 與其他系統整合 AWS Health 是一種 RESTful Web 服務，使用 HTTPS 做為傳輸，並使用 JSON 做為訊息序列化格式。您的應用程式程式碼能夠直接向 AWS Health API 發出請求。當您直接使用 REST API 時，您必須撰寫必要的程式碼來簽署和驗證您的請求。如需 AWS Health 操作和參數的詳細資訊，請參閱 [AWS Health API 參考](https://docs.aws.amazon.com/health/latest/APIReference/)。 **注意** 您必須擁有來自 的 AWS Business Support\$1、 AWS Enterprise Support 或 AWS Unified Operations 計劃[AWS 支援](https://aws.amazon.com/premiumsupport/)，才能使用 AWS Health API。如果您所在的 AWS 區域 未提供其中一個 AWS 支援 計劃，或者您尚未轉換至其中一個計劃，則可以使用 AWS Health API 搭配 Business、Enterprise On-Ramp 或 Enterprise Support 計劃。如果您從 AWS 帳戶 未註冊這些其中一個計劃的 呼叫 AWS Health API，則會收到`SubscriptionRequiredException`錯誤。 您可以使用 AWS SDKs來包裝 AWS Health REST API 呼叫，這可以簡化您的應用程式開發。您可以指定您的 AWS 登入資料，這些程式庫會為您處理身分驗證和請求簽署。 AWS Health 也在 中提供 AWS Health 儀表板 AWS 管理主控台 ，可讓您用來檢視和搜尋事件和受影響的實體。請參閱 [AWS Health 儀表板入門](getting-started-health-dashboard.md)。 **Topics** + [簽署 AWS Health API 請求](#signing) + [選擇 AWS Health API 請求的端點](#endpoints) + [示範：以程式設計方式擷取過去七天 AWS Health 的事件資料](using-global-endpoints-demo.md) + [教學課程：搭配 Java 範例使用 AWS Health API](code-sample-java.md) ## 簽署 AWS Health API 請求 當您使用 AWS SDKs或 AWS Command Line Interface (AWS CLI) 向 提出請求時 AWS，這些工具會自動使用您在設定工具時指定的存取金鑰來簽署請求。例如，如果您將 適用於 Java 的 AWS SDK 用於先前的高可用性端點示範，則不需要自行簽署請求。 **Java 程式碼範例** 如需如何搭配 使用 AWS Health API 的更多範例 適用於 Java 的 AWS SDK，請參閱此[範例程式碼](code-sample-java.md)。 當您提出請求時，強烈建議您不要將 AWS 根帳戶登入資料用於定期存取 AWS Health。您可以使用 IAM 使用者的登入資料。如需詳細資訊，請參閱《*IAM 使用者指南*》中的[鎖定 AWS 您的帳戶根使用者存取金鑰](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials)。 如果您不使用 AWS SDKs或 AWS CLI，則必須自行簽署請求。我們建議您使用 AWS Signature 第 4 版。如需詳細資訊，請參閱《》中的[簽署 AWS API 請求](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html)*AWS 一般參考*。 ## 選擇 AWS Health API 請求的端點 AWS Health API 遵循多區域應用程式架構，並在主動-被動組態中有兩個區域端點。為了支援主動-被動 DNS 容錯移轉， AWS Health 提供單一的全域端點。您可以在全域端點上執行 DNS 查詢，以判斷作用中端點和對應的簽署 AWS 區域。這可協助您了解要在程式碼中使用的端點，以便從中取得最新資訊 AWS Health。 當您向 全域端點提出請求時，您必須指定對目標區域端點的 AWS 存取憑證，並為區域設定簽署。否則，您的身分驗證可能會失敗。如需詳細資訊，請參閱[簽署 AWS Health API 請求](#signing)。 對於IPv6-only的請求，我們建議您在全域端點上執行 DNS 查詢，以判斷作用中的 ， AWS 區域 然後呼叫該區域的 IPv6 支援的雙堆疊端點。 下表代表預設組態。 **** | Description | 簽署區域 | Endpoint | 通訊協定 | | --- | --- | --- | --- | | 作用中 | us-east-1 | health.us-east-1.amazonaws.com （僅限 IPv4) health.us-east-1.api.aws （支援 IPv4 和 IPv6) | HTTPS | | 被動 | us-east-2 | health.us-east-2.amazonaws.com （僅限 IPv4) health.us-east-2.api.aws （支援 IPv4 和 IPv6) | HTTPS | | 全域 | us-east-1 這是目前作用中端點的簽署區域。 | global.health.amazonaws.com | HTTPS | 若要判斷端點是否為*作用中端點*，請在*全域端點* CNAME 上執行 DNS 查詢，然後從解析的名稱擷取 AWS 區域。 **Example ：全域端點上的 DNS 查詢** 下列命令會在 global.health.amazonaws.com 端點上完成 DNS 查詢。命令接著會傳回 us-east-1 區域端點。此輸出會告訴您應使用哪個端點 AWS Health。 ``` dig global.health.amazonaws.com | grep CNAME global.health.amazonaws.com. 10 IN CNAME health.us-east-1.amazonaws.com ``` **提示** 主動和被動端點都會傳回 AWS Health 資料。不過，最新的 AWS Health 資料只能從作用中端點取得。來自被動端點的資料最終將與主動端點一致。我們建議您在作用中端點變更時重新啟動任何工作流程。 # 示範：以程式設計方式擷取過去七天 AWS Health 的事件資料 在下列程式碼範例中， 針對全域端點 AWS Health 使用 DNS 查詢來判斷作用中的區域端點和簽署區域。 AWS Health 會使用此資訊來擷取過去七天的事件資料報告。如果作用中端點變更，程式碼會重新啟動工作流程。 **Topics** + [示範：使用 Java 擷取過去七天 AWS Health 的事件資料](#using-the-java-sample-code) + [示範：使用 Python 擷取過去七天 AWS Health 的事件資料](#using-the-python-code) ## 示範：使用 Java 擷取過去七天 AWS Health 的事件資料 **先決條件** 您必須安裝 [Gradle](https://docs.gradle.org/current/userguide/installation.html)。 **使用 Java 範例** 1. 從 GitHub 下載[AWS Health 高可用性端點示範](https://github.com/aws/aws-health-tools/tree/master/high-availability-endpoint)。 1. 導覽至示範專案`high-availability-endpoint/java`目錄。 1. 在命令列視窗中，輸入下列命令。 ``` gradle build ``` 1. 輸入下列命令來指定您的 AWS 登入資料。 ``` export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE" export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" export AWS_SESSION_TOKEN="your-aws-token" ``` 1. 輸入下列命令來執行示範。 ``` gradle run ``` **Example ： AWS Health 事件輸出** 程式碼範例會傳回您 AWS 帳戶中過去七天內最近的 AWS Health 事件。在下列範例中，輸出包含 AWS Config 服務 AWS Health 的事件。 ``` > Task :run [main] INFO aws.health.high.availability.endpoint.demo.HighAvailabilityV2Workflow - EventDetails(Event=Event(Arn=arn:aws:health:global::event/CONFIG/AWS_CONFIG_OPERATIONAL_NOTIFICATION/AWS_CONFIG_OPERATIONAL_NOTIFICATION_88a43e8a-e419-4ca7-9baa-56bcde4dba3, Service=CONFIG, EventTypeCode=AWS_CONFIG_OPERATIONAL_NOTIFICATION, EventTypeCategory=accountNotification, Region=global, StartTime=2020-09-11T02:55:49.899Z, LastUpdatedTime=2020-09-11T03:46:31.764Z, StatusCode=open, EventScopeCode=ACCOUNT_SPECIFIC), EventDescription=EventDescription(LatestDescription=As part of our ongoing efforts to optimize costs associated with recording changes related to certain ephemeral workloads, AWS Config is scheduled to release an update to relationships modeled within ConfigurationItems (CI) for 7 EC2 resource types on August 1, 2021. Examples of ephemeral workloads include changes to Amazon Elastic Compute Cloud (Amazon EC2) Spot Instances, Amazon Elastic MapReduce jobs, and Amazon EC2 Autoscaling. This update will optimize CI models for EC2 Instance, SecurityGroup, Network Interface, Subnet, VPC, VPN Gateway, and Customer Gateway resource types to record direct relationships and deprecate indirect relationships. A direct relationship is defined as a one-way relationship (A->B) between a resource (A) and another resource (B), and is typically derived from the Describe API response of resource (A). An indirect relationship, on the other hand, is a relationship that AWS Config infers (B->A), in order to create a bidirectional relationship. For example, EC2 instance -> Security Group is a direct relationship, since security groups are returned as part of the describe API response for an EC2 instance. But Security Group -> EC2 instance is an indirect relationship, since EC2 instances are not returned when describing an EC2 Security group. Until now, AWS Config has recorded both direct and indirect relationships. With the launch of Advanced queries in March 2019, indirect relationships can easily be answered by running Structured Query Language (SQL) queries such as: SELECT resourceId, resourceType WHERE resourceType ='AWS::EC2::Instance' AND relationships.resourceId = 'sg-234213' By deprecating indirect relationships, we can optimize the information contained within a Configuration Item while reducing AWS Config costs related to relationship changes. This is especially useful in case of ephemeral workloads where there is a high volume of configuration changes for EC2 resource types. Which resource relationships are being removed? Resource Type: Related Resource Type 1 AWS::EC2::CustomerGateway: AWS::VPN::Connection 2 AWS::EC2::Instance: AWS::EC2::EIP, AWS::EC2::RouteTable 3 AWS::EC2::NetworkInterface: AWS::EC2::EIP, AWS::EC2::RouteTable 4 AWS::EC2::SecurityGroup: AWS::EC2::Instance, AWS::EC2::NetworkInterface 5 AWS::EC2::Subnet: AWS::EC2::Instance, AWS::EC2::NetworkACL, AWS::EC2::NetworkInterface, AWS::EC2::RouteTable 6 AWS::EC2::VPC: AWS::EC2::Instance, AWS::EC2::InternetGateway, AWS::EC2::NetworkACL, AWS::EC2::NetworkInterface, AWS::EC2::RouteTable, AWS::EC2::Subnet, AWS::EC2::VPNGateway, AWS::EC2::SecurityGroup 7 AWS::EC2::VPNGateway: AWS::EC2::RouteTable, AWS::EC2::VPNConnection Alternate mechanism to retrieve this relationship information: The SelectResourceConfig API accepts a SQL SELECT command, performs the corresponding search, and returns resource configurations matching the properties. You can use this API to retrieve the same relationship information. For example, to retrieve the list of all EC2 Instances related to a particular VPC vpc-1234abc, you can use the following query: SELECT resourceId, resourceType WHERE resourceType ='AWS::EC2::Instance' AND relationships.resourceId = 'vpc-1234abc' If you have any questions regarding this deprecation plan, please contact AWS 支援 [1]. Additional sample queries to retrieve the relationship information for the resources listed above is provided in [2]. [1] https://aws.amazon.com/support [2] https://docs.aws.amazon.com/config/latest/developerguide/examplerelationshipqueries.html), EventMetadata={}) ``` ### Java 資源 + 如需詳細資訊，請參閱 *適用於 Java 的 AWS SDK API 參考*中的[介面 HealthClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/health/HealthClient.html) 和[原始程式碼](https://repo1.maven.org/maven2/software/amazon/awssdk/health/2.14.2/)。 + 如需此示範中用於 DNS 查詢的程式庫詳細資訊，請參閱 GitHub 中的 [dnsjava](https://github.com/dnsjava/dnsjava)。 ## 示範：使用 Python 擷取過去七天 AWS Health 的事件資料 **先決條件** 您必須安裝 [Python 3](https://www.python.org/downloads/)。 **使用 Python 範例** 1. 從 GitHub 下載[AWS Health 高可用性端點示範](https://github.com/aws/aws-health-tools/tree/master/high-availability-endpoint)。 1. 導覽至示範專案`high-availability-endpoint/python`目錄。 1. 在命令列視窗中，輸入下列命令。 ``` pip3 install virtualenv virtualenv -p python3 v-aws-health-env ``` **注意** 對於 Python 3.3 和更新版本，您可以使用內建`venv`模組來建立虛擬環境，而不是安裝 `virtualenv`。如需詳細資訊，請參閱 Python 網站上的 [venv - 虛擬環境的建立](https://docs.python.org/3/library/venv.html)。 ``` python3 -m venv v-aws-health-env ``` 1. 輸入下列命令以啟用虛擬環境。 ``` source v-aws-health-env/bin/activate ``` 1. 輸入下列命令來安裝相依性。 ``` pip install -r requirements.txt ``` 1. 輸入下列命令來指定您的 AWS 登入資料。 ``` export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE" export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" export AWS_SESSION_TOKEN="your-aws-token" ``` 1. 輸入下列命令來執行示範。 ``` python3 main.py ``` **Example ： AWS Health 事件輸出** 程式碼範例會傳回您 AWS 帳戶中過去七天內最近的 AWS Health 事件。下列輸出會傳回 AWS 安全通知 AWS Health 的事件。 ``` INFO:botocore.credentials:Found credentials in environment variables. INFO:root:Details: {'arn': 'arn:aws:health:global::event/SECURITY/AWS_SECURITY_NOTIFICATION/AWS_SECURITY_NOTIFICATION_0e35e47e-2247-47c4-a9a5-876544042721', 'service': 'SECURITY', 'eventTypeCode': 'AWS_SECURITY_NOTIFICATION', 'eventTypeCategory': 'accountNotification', 'region': 'global', 'startTime': datetime.datetime(2020, 8, 19, 23, 30, 42, 476000, tzinfo=tzlocal()), 'lastUpdatedTime': datetime.datetime(2020, 8, 20, 20, 44, 9, 547000, tzinfo=tzlocal()), 'statusCode': 'open', 'eventScopeCode': 'PUBLIC'}, description: {'latestDescription': 'This is the second notice regarding TLS requirements on FIPS endpoints.\n\nWe are in the process of updating all AWS Federal Information Processing Standard (FIPS) endpoints across all AWS regions to Transport Layer Security (TLS) version 1.2 by March 31, 2021 . In order to avoid an interruption in service, we encourage you to act now, by ensuring that you connect to AWS FIPS endpoints at a TLS version of 1.2. If your client applications fail to support TLS 1.2 it will result in connection failures when TLS versions below 1.2 are no longer supported.\n\nBetween now and March 31, 2021 AWS will remove TLS 1.0 and TLS 1.1 support from each FIPS endpoint where no connections below TLS 1.2 are detected over a 30-day period. After March 31, 2021 we may deploy this change to all AWS FIPS endpoints, even if there continue to be customer connections detected at TLS versions below 1.2. \n\nWe will provide additional updates and reminders on the AWS Security Blog, with a ‘TLS’ tag [1]. If you need further guidance or assistance, please contact AWS 支援 [2] or your Technical Account Manager (TAM). Additional information is below.\n\nHow can I identify clients that are connecting with TLS 1.0/1.1?\nFor customers using S3 [3], Cloudfront [4] or Application Load Balancer [5] you can use your access logs to view the TLS connection information for these services, and identify client connections that are not at TLS 1.2. If you are using the AWS Developer Tools on your clients, you can find information on how to properly configure your client’s TLS versions by visiting Tools to Build on AWS [7] or our associated AWS Security Blog has a link for each unique code language [7].\n\nWhat is Transport Layer Security (TLS)?\nTransport Layer Security (TLS Protocols) are cryptographic protocols designed to provide secure communication across a computer network [6].\n\nWhat are AWS FIPS endpoints? \nAll AWS services offer Transport Layer Security (TLS) 1.2 encrypted endpoints that can be used for all API calls. Some AWS services also offer FIPS 140-2 endpoints [9] for customers that require use of FIPS validated cryptographic libraries. \n\n[1] https://aws.amazon.com/blogs/security/tag/tls/\n[2] https://aws.amazon.com/support\n[3] https://docs.aws.amazon.com/AmazonS3/latest/dev/LogFormat.html\n[4] https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/AccessLogs.html\n[5] https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-access-logs.html\n[6] https://aws.amazon.com/tools\n[7] https://aws.amazon.com/blogs/security/tls-1-2-to-become-the-minimum-for-all-aws-fips-endpoints\n[8] https://en.wikipedia.org/wiki/Transport_Layer_Security\n[9] https://aws.amazon.com/compliance/fips'} ``` 1. 完成後，請輸入下列命令來停用虛擬機器。 ``` deactivate ``` ### Python 資源 + 如需 的詳細資訊`Health. Client`，請參閱[AWS 適用於 Python (Boto3) 的 SDK API 參考](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/health.html#Health.Client)。 + 如需此示範中用於 DNS 查詢的程式庫詳細資訊，請參閱 GitHub 上的 [dnspython](https://dnspython.readthedocs.io/en/stable/) 工具組和[原始程式碼](https://github.com/rthalley/dnspython/)。 # 教學課程：搭配 Java 範例使用 AWS Health API 下列 Java 程式碼範例示範如何初始化 AWS Health 用戶端，以及擷取事件和實體的相關資訊。 ## 步驟 1：初始化登入資料 需要有效的登入資料才能與 AWS Health API 通訊。您可以使用與 AWS 帳戶相關聯之任何 IAM 使用者的金鑰對。 建立和初始化 [AWSCredentials](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/AWSCredentials.html) 執行個體： ``` AWSCredentials credentials = null; try { credentials = new ProfileCredentialsProvider("default").getCredentials(); } catch (Exception e) { throw new AmazonClientException( "Cannot load the credentials from the credential profiles file. " + "Please make sure that your credentials file is at the correct " + "location (/home/username/.aws/credentials), and is in valid format.", e); } ``` ## 步驟 2：初始化 AWS Health API 用戶端 使用之前步驟初始化的登入資料物件來建立 AWS Health 用戶端： ``` import com.amazonaws.services.health.AWSHealthClient; AWSHealth awsHealthClient = new AWSHealthClient(credentials); ``` ## 步驟 3：使用 AWS Health API 操作來取得事件資訊 **DescribeEvents** ``` import com.amazonaws.services.health.model.DescribeEventsRequest; import com.amazonaws.services.health.model.DescribeEventsResult; import com.amazonaws.services.health.model.Event; import com.amazonaws.services.health.model.EventFilter; DescribeEventsRequest request = new DescribeEventsRequest(); EventFilter filter = new EventFilter(); // Filter on any field from the supported AWS Health EventFilter model. // Here is an example for Region us-east-1 events from the EC2 service. filter.setServices(singletonList("EC2")); filter.setRegions(singletonList("us-east-1")); request.setFilter(filter); DescribeEventsResult response = awsHealthClient.describeEvents(request); List resultEvents = response.getEvents(); Event currentEvent = null; for (Event event : resultEvents) { // Display result event data; here is a subset. System.out.println(event.getArn()); System.out.println(event.getService()); System.out.println(event.getRegion()); System.out.println(event.getAvailabilityZone()); System.out.println(event.getStartTime()); System.out.println(event.getEndTime()); } ``` **DescribeEventAggregates** ``` import com.amazonaws.services.health.model.DescribeEventAggregatesRequest; import com.amazonaws.services.health.model.DescribeEventAggregatesResult; import com.amazonaws.services.health.model.EventAggregate; import com.amazonaws.services.health.model.EventFilter; DescribeEventAggregatesRequest request = new DescribeEventAggregatesRequest(); // set the aggregation field request.setAggregateField("eventTypeCategory"); // filter more on result if needed EventFilter filter = new EventFilter(); filter.setRegions(singleton("us-east-1")); request.setFilter(filter); DescribeEventAggregatesResult response = awsHealthClient.describeEventAggregates(request); // print event count for each eventTypeCategory for (EventAggregate aggregate: response.getEventAggregates()) { System.out.println("Event Category:" + aggregate.getAggregateValue()); System.out.println("Event Count:" + aggregate.getCount()); } ``` **DescribeEventDetails** ``` import com.amazonaws.services.health.model.DescribeEventDetailsRequest; import com.amazonaws.services.health.model.DescribeEventDetailsResult; import com.amazonaws.services.health.model.Event; import com.amazonaws.services.health.model.EventDetails; DescribeEventDetailsRequest describeEventDetailsRequest = new DescribeEventDetailsRequest(); // set event ARN and local value describeEventDetailsRequest.setEventArns(singletonList("arn:aws:health:us-east-1::event/service/eventTypeCode/eventId")); describeEventDetailsRequest.setLocale("en-US"); filter.setEventArns DescribeEventDetailsResult describeEventDetailsResult = awsHealthClient.describeEventDetails(request); EventDetails eventDetail = describeEventDetailsResult.getSuccessfulSet().get(0); // check event-related fields Event event = eventDetail.getEvent(); System.out.println(event.getService()); System.out.println(event.getRegion()); System.out.println(event.getAvailabilityZone()); System.out.println(event.getStartTime()); System.out.println(event.getEndTime()); // print out event description System.out.println(eventDetail.getEventDescription().getLatestDescription()); ``` **DescribeAffectedEntities** ``` import com.amazonaws.services.health.model.AffectedEntity; import com.amazonaws.services.health.model.DateTimeRange; import com.amazonaws.services.health.model.DescribeAffectedEntitiesRequest; import com.amdescribeEventDetailsRequestazonaws.services.health.model.DescribeAffectedEntitiesResult; DescribeAffectedEntitiesRequest request = new DescribeAffectedEntitiesRequest(); EntityFilter filter = new EntityFilter(); filter.setEventArns(singletonList("arn:aws:health:us-east-1::event/service/eventTypeCode/eventId")); DescribeAffectedEntitiesResult response = awsHealthClient.describeAffectedEntities(request); for (AffectedEntity affectedEntity: response.getEntities()) { System.out.println(affectedEntity.getEntityValue()); System.out.println(affectedEntity.getAwsAccountId()); System.out.println(affectedEntity.getEntityArn()); } ``` **DescribeEntityAggregates** ``` import com.amazonaws.services.health.model.DescribeEntityAggregatesRequest; import com.amazonaws.services.health.model.DescribeEntityAggregatesResult; import com.amazonaws.services.health.model.EntityAggregate; DescribeEntityAggregatesRequest request = new DescribeEntityAggregatesRequest(); request.setEventArns(singletonList("arn:aws:health:us-east-1::event/service/eventTypeCode/eventId")); DescribeEntityAggregatesResult response = awsHealthClient.describeEntityAggregates(request); for (EntityAggregate entityAggregate : response.getEntityAggregates()) { System.out.println(entityAggregate.getEventArn()); System.out.println(entityAggregate.getCount()); } ```