本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 CloudTrail 處理程式庫

CloudTrail 處理庫是一個 Java 庫，提供了一個簡單的方法來處理 AWS CloudTrail 日誌。您可以提供有關 CloudTrail SQS佇列的組態詳細資料，並撰寫程式碼以處理事件。 CloudTrail 處理庫完成剩下的工作。它會輪詢您的 Amazon SQS 佇列、讀取和剖析佇列訊息、下載 CloudTrail 日誌檔案、剖析日誌檔中的事件，以及將事件作為 Java 物件傳遞至程式碼。

CloudTrail 處理庫具有高度可擴展性和容錯性。它會處理日誌檔案的平行處理，讓您可以處理所需數目的日誌。它會處理與網路逾時和無法存取資源相關的網路失敗。

下列主題說明如何使用 CloudTrail 處理程式庫來處理 Java 專案中的 CloudTrail 記錄檔。

該庫作為 APACHE 許可的開源項目提供，可在以下位置獲得：。 GitHub https://github.com/aws/aws-cloudtrail-processing-library此程式庫來源包括可用作您自己專案基礎的範本程式碼。

最低需求

若要使用「 CloudTrail 處理程式庫」，您必須具備下列項目：

處理 CloudTrail 記錄

若要在 Java 應用程式中處理 CloudTrail 記錄檔：

將 CloudTrail 處理程式庫新增至您的專案

要使用 CloudTrail 處理庫，請將其添加到 Java 項目的類路徑中。

將程式庫新增至 Apache Ant 專案

將程式庫新增至 Apache Maven 專案

CloudTrail 處理庫可用於阿帕奇的 Maven。您可以將它新增至專案，方法是在專案的 pom.xml 檔案中編寫單一相依性。

將程式庫新增至 Eclipse 專案

將程式庫新增至 IntelliJ 專案

配置 CloudTrail 處理程式庫

您可以建立在執行階段載入的類別路徑屬性檔案，或透過建立ClientConfiguration物件並手動設定選項，來設定 CloudTrail 處理程序庫。

提供屬性檔案

您可以編寫 classpath 屬性檔案，以將組態選項提供給您的應用程式。下列範例檔案顯示您可設定的選項：

# AWS access key. (Required)
accessKey = your_access_key

# AWS secret key. (Required)
secretKey = your_secret_key

# The SQS URL used to pull CloudTrail notification from. (Required)
sqsUrl = your_sqs_queue_url

# The SQS end point specific to a region.
sqsRegion = us-east-1

# A period of time during which Amazon SQS prevents other consuming components
# from receiving and processing that message.
visibilityTimeout = 60

# The S3 region to use.
s3Region = us-east-1

# Number of threads used to download S3 files in parallel. Callbacks can be
# invoked from any thread.
threadCount = 1

# The time allowed, in seconds, for threads to shut down after
# AWSCloudTrailEventProcessingExecutor.stop() is called. If they are still
# running beyond this time, they will be forcibly terminated.
threadTerminationDelaySeconds = 60

# The maximum number of AWSCloudTrailClientEvents sent to a single invocation
# of processEvents().
maxEventsPerEmit = 10

# Whether to include raw event information in CloudTrailDeliveryInfo.
enableRawEventInfo = false

# Whether to delete SQS message when the CloudTrail Processing Library is unable to process the notification.
deleteMessageUponFailure = false

下列是必要參數：

accessKey和secretKey參數提供您的 AWS 程式庫的認證，以便程式庫可以存取 AWS 代表您。

其他參數的預設值是透過程式庫所設定。如需詳細資訊，請參閱 AWS CloudTrail 處理程式庫參考。

創建一個 ClientConfiguration

您可以初始化和設定 AWSCloudTrailProcessingExecutor 物件的選項，以將選項提供給 ClientConfiguration，而不是在 classpath 屬性中設定選項，如下列範例所示：

ClientConfiguration basicConfig = new ClientConfiguration(
    "http://sqs.us-east-1.amazonaws.com/123456789012/queue2",
    new DefaultAWSCredentialsProviderChain());

basicConfig.setEnableRawEventInfo(true);
basicConfig.setThreadCount(4);
basicConfig.setnEventsPerEmit(20);

實作事件處理器

若要處理 CloudTrail 記錄，您必須實作EventsProcessor接收記 CloudTrail 錄資料的。下列是範例實作：

public class SampleEventsProcessor implements EventsProcessor {

    public void process(List<CloudTrailEvent> events) {
        int i = 0;
        for (CloudTrailEvent event : events) {
            System.out.println(String.format("Process event %d : %s", i++, event.getEventData()));
        }
    }
}

實施時EventsProcessor，您實現了AWSCloudTrailProcessingExecutor用於向您發送 CloudTrail 事件的process()回調。事件是以 CloudTrailClientEvent 物件清單形式提供。

CloudTrailClientEvent物件提供了CloudTrailEvent和CloudTrailEventMetadata，您可以用來讀取 CloudTrail 事件和遞送資訊。

此簡單範例會列印每個傳遞至 SampleEventsProcessor 之事件的事件資訊。在您自己的實作中，您可以在符合您需求時處理日誌。AWSCloudTrailProcessingExecutor 只要有要傳送的事件且仍在執行，就會持續將事件傳送至 EventsProcessor。

實例化和執行處理執行器

在您為 CloudTrail 處理程式庫撰寫EventsProcessor並設定組態值之後 (無論是在屬性檔案中或使用ClientConfiguration類別)，您就可以使用這些元素來初始化和使用AWSCloudTrailProcessingExecutor.

public class SampleApp {
  public static void main(String[] args) throws InterruptedException {
    AWSCloudTrailProcessingExecutor executor = new
      AWSCloudTrailProcessingExecutor.Builder(new SampleEventsProcessor(),
        "/myproject/cloudtrailprocessing.properties").build();

    executor.start();
    Thread.sleep(24 * 60 * 60 * 1000); // let it run for a while (optional)
    executor.stop(); // optional
  }
}

進階主題

篩選要處理的事件

根據預設，Amazon SQS 佇列 S3 儲存貯體中的所有日誌及其中包含的所有事件都會傳送到您的EventsProcessor. Process Library 提供選 CloudTrail 用的介面，您可以實作這些介面來篩選用來取得 CloudTrail 記錄檔的來源，以及篩選您有興趣處理的事件。

處理資料事件

CloudTrail 處理資料事件時，會以原始格式保留數字，無論是整數 (int) 還是 float (包含小數的數字)。在資料事件欄位中具有整數的事件中， CloudTrail 歷史上會將這些數字當作浮點數處理。目前，透過保留原始格式來 CloudTrail 處理這些欄位中的數字。

為了避免中斷自動化作業的最佳作法，請在您用來處理或篩選 CloudTrail 資料事件的任何程float式碼或自動化作業中保持彈性，並同時int允許和格式化的數字。為獲得最佳結果，請使用 CloudTrail 處理庫的 1.4.0 或更高版本。

下列範例片段顯示 float 格式化的數字，2.0，適用於資料事件的 ResponseParameters 區塊中的 desiredCount 參數。

"eventName": "CreateService",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "000.00.00.00",
    "userAgent": "console.amazonaws.com",
    "requestParameters": {
        "clientToken": "EXAMPLE",
        "cluster": "default",
        "desiredCount": 2.0
...

下列範例片段顯示 int 格式化的數字，2，適用於資料事件的 ResponseParameters 區塊中的 desiredCount 參數。

"eventName": "CreateService",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "000.00.00.00",
    "userAgent": "console.amazonaws.com",
    "requestParameters": {
        "clientToken": "EXAMPLE",
        "cluster": "default",
        "desiredCount": 2
...

報告進度

實作ProgressReporter介面以自訂 CloudTrail 處理程式庫進度報告。 ProgressReporter聲明兩種方法：reportStart()和reportEnd()，它們在以下操作的開始和結束時調用：

兩種方法都會收到 ProgressStatus 物件，其中包含所執行操作的資訊。progressState 成員擁有可識別目前操作之 ProgressState 列舉的成員。這個成員可以在 progressInfo 成員中包含其他資訊。此外，您從 reportStart() 傳回的任何物件都會傳遞至 reportEnd()，因此您可以提供內容資訊 (例如開始處理事件的時間)。

下列範例實作提供操作需要多久時間才能完成的資訊：

public class SampleProgressReporter implements ProgressReporter {
  private static final Log logger =
    LogFactory.getLog(DefaultProgressReporter.class);

  @Override
  public Object reportStart(ProgressStatus status) {
    return new Date();
  }

  @Override
  public void reportEnd(ProgressStatus status, Object startDate) {
    System.out.println(status.getProgressState().toString() + " is " +
      status.getProgressInfo().isSuccess() + " , and latency is " +
      Math.abs(((Date) startDate).getTime()-new Date().getTime()) + "
      milliseconds.");
  }
}

如果您未實作自己的 ProgressReporter，則會改用 DefaultExceptionHandler，以列印所執行狀態的名稱。

處理錯誤

ExceptionHandler 界面可讓您在日誌處理期間發生例外狀況時提供特殊處理。ExceptionHandler 宣告單一回呼方法 handleException()，以接收包含所發生例外狀況之內容的 ProcessingLibraryException 物件。

您可以使用傳入之 ProcessingLibraryException 的 getStatus() 方法，了解發生例外狀況時所執行的操作，並取得操作狀態的其他資訊。ProcessingLibraryException 衍生自 Java 的標準 Exception 類別，因此您也可以呼叫任何例外狀況方法來擷取例外狀況的資訊。

請參閱下列範例實作：

public class SampleExceptionHandler implements ExceptionHandler{
  private static final Log logger =
    LogFactory.getLog(DefaultProgressReporter.class);

  @Override
  public void handleException(ProcessingLibraryException exception) {
    ProgressStatus status = exception.getStatus();
    ProgressState state = status.getProgressState();
    ProgressInfo info = status.getProgressInfo();

    System.err.println(String.format(
      "Exception. Progress State: %s. Progress Information: %s.", state, info));
  }
}

如果您未提供自己的 ExceptionHandler，則會改用 DefaultExceptionHandler，以列印標準錯誤訊息。

其他資源

如需有關 CloudTrail 處理程式庫的詳細資訊，請參閱下列內容：