翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # CloudTrail Processing Library の使用 CloudTrail Processing Library は、 AWS CloudTrail ログを簡単に処理できる Java ライブラリです。ユーザーは、CloudTrail の SQS キューに関する設定の詳細を提供し、イベントを処理するコードを記述します。CloudTrail Processing Library が残りを処理します。これにより Amazon SQS キューをポーリングし、キューメッセージの読み取りと解析、CloudTrail ログファイルのダウンロード、ログファイル内のイベントの解析を行い、イベントを Java オブジェクトとしてコードに渡します。 CloudTrail Processing Library は耐障害性が高く、スケーラブルです。ログファイルの並列処理を行うため、必要な数だけのログを処理することができます。ネットワークタイムアウトや、アクセスできないリソースに関するネットワーク障害に対応します。次のトピックでは、CloudTrail Processing Library を使用して Java プロジェクトの CloudTrail ログを処理する方法を示します。ライブラリは、Apache ライセンスの付いたオープンソースプロジェクトとして提供され、GitHub で入手できます。[https://github.com/aws/aws-cloudtrail-processing-library](https://github.com/aws/aws-cloudtrail-processing-library)。ライブラリソースには、独自のプロジェクトのベースとして使用できるサンプルコードが含まれます。 **Topics** + [最小要件](#use-the-cloudtrail-processing-library-prerequisites) + [CloudTrail ログを処理しています](#use-the-cloudtrail-processing-library-how-to) + [高度なトピック](#use-the-cloudtrail-processing-library-advanced) + [その他のリソース](#UsingProcessingLib-ar) ## 最小要件 CloudTrail Processing Library を使用するには、以下のものが必要です。 + [AWS SDK for Java 1.11.830](https://github.com/aws/aws-sdk-java) + [Java 1.8 (Java SE 8)](https://www.oracle.com/java/technologies/java-se-glance.html) ## CloudTrail ログを処理しています Java アプリケーションで CloudTrail ログを処理するには: 1. [CloudTrail Processing Library をプロジェクトに追加する](#use-the-cloudtrail-processing-library-add-to-project) 1. [CloudTrail Processing Library の設定](#use-the-cloudtrail-processing-library-configure) 1. [イベントプロセッサを実装する](#use-the-cloudtrail-processing-library-implement-events-processor) 1. [処理エグゼキューターをインスタンス化して実行する](#use-the-cloudtrail-processing-library-instantiate-and-run-executor) ### CloudTrail Processing Library をプロジェクトに追加する CloudTrail Processing Library を使用するには、Java プロジェクトのクラスパスに追加します。 **Contents** + [Apache Ant プロジェクトにライブラリを追加する](#use-the-cloudtrail-processing-library-add-to-project-apache-ant) + [Apache Maven プロジェクトにライブラリを追加する](#use-the-cloudtrail-processing-library-add-to-project-apache-maven) + [Eclipse プロジェクトにライブラリを追加する](#use-the-cloudtrail-processing-library-add-to-project-eclipse) + [IntelliJ プロジェクトにライブラリを追加する](#use-the-cloudtrail-processing-library-add-to-intellij-project) #### Apache Ant プロジェクトにライブラリを追加する **Apache Ant プロジェクトに CloudTrail Processing Library を追加するには** 1. GitHub から CloudTrail Processing Library のソースコードをダウンロードまたはクローンします。 + [https://github.com/aws/aws-cloudtrail-processing-library](https://github.com/aws/aws-cloudtrail-processing-library) 1. 「[README](https://github.com/aws/aws-cloudtrail-processing-library/blob/master/README.rst)」で説明されているように、ソースから .jar ファイルを構築します。 ``` mvn clean install -Dgpg.skip=true ``` 1. 作成された .jar ファイルをプロジェクトにコピーし、プロジェクトの `build.xml` ファイルに追加します。以下はその例です。 ``` ``` #### Apache Maven プロジェクトにライブラリを追加する CloudTrail Processing Library は、[Apache Maven](https://maven.apache.org/) で利用可能です。プロジェクトの `pom.xml` ファイルに依存関係を 1 つ書くことで、プロジェクトに追加できます。 **Maven プロジェクトに CloudTrail Processing Library を追加するには** + Maven プロジェクトの `pom.xml` ファイルを開き、次の依存関係を追加します。 ``` com.amazonaws aws-cloudtrail-processing-library 1.6.1 ``` #### Eclipse プロジェクトにライブラリを追加する **Eclipse プロジェクトに CloudTrail Processing Library を追加するには** 1. GitHub から CloudTrail Processing Library のソースコードをダウンロードまたはクローンします。 + [https://github.com/aws/aws-cloudtrail-processing-library](https://github.com/aws/aws-cloudtrail-processing-library) 1. 「[README](https://github.com/aws/aws-cloudtrail-processing-library/blob/master/README.rst)」で説明されているように、ソースから .jar ファイルを構築します。 ``` mvn clean install -Dgpg.skip=true ``` 1. 構築した aws-cloudtrail-processing-library-1.6.1.jar をプロジェクトのディレクトリ (通常は `lib`) にコピーします。 1. Eclipse の [**Project Explorer**] でプロジェクト名を右クリックし、[**Build Path**]、[**Configure**] の順に選択します。 1. [**Java Build Path**] ウィンドウで、[**Libraries**] タブを選択します。 1. **[Add JARs...]** (JAR を追加...) をクリックして、aws-cloudtrail-processing-library-1.6.1.jar をコピーしたパスに移動します。 1. [**OK**] を選択すると、プロジェクトに `.jar` が追加されます。 #### IntelliJ プロジェクトにライブラリを追加する **IntelliJ プロジェクトに CloudTrail Processing Library を追加するには** 1. GitHub から CloudTrail Processing Library のソースコードをダウンロードまたはクローンします。 + [https://github.com/aws/aws-cloudtrail-processing-library](https://github.com/aws/aws-cloudtrail-processing-library) 1. 「[README](https://github.com/aws/aws-cloudtrail-processing-library/blob/master/README.rst)」で説明されているように、ソースから .jar ファイルを構築します。 ``` mvn clean install -Dgpg.skip=true ``` 1. [**File**] で、[**Project Structure**] を選択します。 1. [**Modules**]、[**Dependencies**] の順に選択します。 1. [**\$1 JARS or Directories**] を選択し、構築した `aws-cloudtrail-processing-library-1.6.1.jar` のパスに移動します。 1. [**Apply**]、[**OK**] の順に選択すると、プロジェクトに `.jar` が追加されます。 ### CloudTrail Processing Library の設定実行時にロードされるクラスパスプロパティファイルを作成することにより、または `ClientConfiguration` オブジェクトを作成してオプションを手動で設定することにより、CloudTrail Processing Library を設定できます。 #### プロパティファイルを提供するアプリケーションに設定オプションを提供するクラスパスプロパティファイルを作成できます。次のサンプルファイルでは、設定できるオプションを示します。 ``` # 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 ``` 以下のパラメータは必須です。 + `sqsUrl` – CloudTrail 通知をプルする元の URL を提供します。この値を指定しない場合、`AWSCloudTrailProcessingExecutor` が `IllegalStateException` をスローします。 + `accessKey` – アカウントの一意の識別子 (AKIAIOSFODNN7EXAMPLE など)。 + `secretKey` – アカウントの一意の識別子 (wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY など)。 `accessKey` および `secretKey`パラメータは、 AWS ライブラリが AWS ユーザーに代わってにアクセスできるように、ライブラリに認証情報を提供します。他のパラメータのデフォルト値は、ライブラリによって設定されます。詳細については、「[AWS CloudTrail Processing Library リファレンス](https://docs.aws.amazon.com/awscloudtrail/latest/processinglib/)」を参照してください。 #### ClientConfiguration を作成するクラスパスプロパティでオプションを設定する代わりに、次の例のように、`ClientConfiguration` オブジェクトでオプションを初期化して設定することにより、`AWSCloudTrailProcessingExecutor` にオプションを提供できます。 ``` 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 ログを処理するには、CloudTrail ログデータを受け取る `EventsProcessor` を実装する必要があります。以下に実装例を示します。 ``` public class SampleEventsProcessor implements EventsProcessor { public void process(List 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` へのイベントの送信を続けます。 ### 処理エグゼキューターをインスタンス化して実行する `EventsProcessor` を作成し、CloudTrail の設定値を (プロパティファイルまたは `ClientConfiguration` クラスを使用して) 設定した後は、これらの要素を使用することで、`AWSCloudTrailProcessingExecutor` を初期化して使用できます。 **`AWSCloudTrailProcessingExecutor` を使用して CloudTrail イベントを処理するには** 1. `AWSCloudTrailProcessingExecutor.Builder` オブジェクトをインスタンス化します。`Builder` のコンストラクタは、`EventsProcessor` オブジェクトとクラスパスのプロパティファイル名を受け取ります。 1. `Builder` の `build()` ファクトリメソッドを呼び出し、`AWSCloudTrailProcessingExecutor` オブジェクトを設定して取得します。 1. `AWSCloudTrailProcessingExecutor` の `start()` および `stop()` メソッドとメソッドを使用して、CloudTrail イベントの処理を開始および終了します。 ``` 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 } } ``` ## 高度なトピック **Topics** + [処理するイベントのフィルタリング](#use-the-cloudtrail-processing-library-advanced-filter-events) + [データイベントの処理](#use-the-cpl-advanced-integers-floats) + [進行状況のレポート](#use-the-cloudtrail-processing-library-advanced-report-progress) + [エラー処理](#use-the-cloudtrail-processing-library-advanced-handle-errors) ### 処理するイベントのフィルタリングデフォルトでは、Amazon SQS キューの S3 バケット内のすべてのログと、それに含まれるすべてのイベントが、`EventsProcessor` に送信されます。CloudTrail Processing Library で提供されるオプションのインターフェイスを実装して、CloudTrail ログの取得に使用されるソースおよび処理対象のイベントをフィルタリングできます。 `SourceFilter` `SourceFilter` インターフェイスを実装して、提供されたソースからのログを処理するかどうかを選択できます。`SourceFilter` で 1 つだけ宣言されているコールバックメソッド `filterSource()` は、`CloudTrailSource` オブジェクトを受け取ります。ソースからのイベントが処理されないようにするには、`filterSource()` から `false` を返します。 CloudTrail Processing Library はライブラリが Amazon SQS キューでログをポーリングした後で、`filterSource()` メソッドを呼び出します。これは、ライブラリがイベントのフィルタリングまたはログの処理を開始する前に発生します。以下に実装例を示します。 ``` public class SampleSourceFilter implements SourceFilter{ private static final int MAX_RECEIVED_COUNT = 3; private static List accountIDs ; static { accountIDs = new ArrayList<>(); accountIDs.add("123456789012"); accountIDs.add("234567890123"); } @Override public boolean filterSource(CloudTrailSource source) throws CallbackException { source = (SQSBasedSource) source; Map sourceAttributes = source.getSourceAttributes(); String accountId = sourceAttributes.get( SourceAttributeKeys.ACCOUNT_ID.getAttributeKey()); String receivedCount = sourceAttributes.get( SourceAttributeKeys.APPROXIMATE_RECEIVE_COUNT.getAttributeKey()); int approximateReceivedCount = Integer.parseInt(receivedCount); return approximateReceivedCount <= MAX_RECEIVED_COUNT && accountIDs.contains(accountId); } } ``` 独自の `SourceFilter` を提供しない場合に使用される `DefaultSourceFilter` では、すべてのソースの処理が許可されます (常に `true` を返します)。 `EventFilter` `EventFilter` インターフェイスを実装して、CloudTrail イベントを`EventsProcessor` に送信するかどうかを選択できます。`EventFilter` で 1 つだけ宣言されているコールバックメソッド、`filterEvent()` は、`CloudTrailEvent` オブジェクトを受け取ります。イベントが処理されないようにするには、`filterEvent()` から `false` を返します。 CloudTrail Processing Library はライブラリが Amazon SQS キューでログをポーリングし、ソースのフィルタリングをした後で、`filterEvent()` メソッドを呼び出します。これは、ライブラリがログのイベント処理を開始する前に発生します。次の実装例を参照してください。 ``` public class SampleEventFilter implements EventFilter{ private static final String EC2_EVENTS = "ec2.amazonaws.com"; @Override public boolean filterEvent(CloudTrailClientEvent clientEvent) throws CallbackException { CloudTrailEvent event = clientEvent.getEvent(); String eventSource = event.getEventSource(); String eventName = event.getEventName(); return eventSource.equals(EC2_EVENTS) && eventName.startsWith("Delete"); } } ``` 独自の `EventFilter` を提供しない場合に使用される `DefaultEventFilter` では、すべてのイベントの処理が許可されます (常に `true` を返します)。 ### データイベントの処理 CloudTrail はデータイベントを処理するときに、整数 (`int`) であるか `float` (少数を含む数値) であるかにかかわらず元の形式で数値を保持します。データイベントのフィールドに整数を含むイベントでは、CloudTrail は従来、これらの数値を浮動小数点数として処理していました。現在、CloudTrail はこれらのフィールドの数値を元の形式を維持して処理しています。ベストプラクティスとして、自動化が中断されないように、CloudTrail データイベントの処理またはフィルタリングに使用しているコードまたは自動化に柔軟に対応し、`int` および `float` のフォーマットされた数値の両方を許可します。最良の結果を得るには、CloudTrail Processing Library のバージョン 1.4.0 以降を使用してください。次のスニペット例ではデータイベントの `ResponseParameters` ブロックの `desiredCount` パラメータ用にフォーマットされた `float` の数値、`2.0` を示しています。 ``` "eventName": "CreateService", "awsRegion": "us-east-1", "sourceIPAddress": "000.00.00.00", "userAgent": "console.amazonaws.com", "requestParameters": { "clientToken": "EXAMPLE", "cluster": "default", "desiredCount": 2.0 ... ``` 次のスニペット例ではデータイベントの `ResponseParameters` ブロックの `desiredCount` パラメータ用にフォーマットされた `int` の数値、`2` を示しています。 ``` "eventName": "CreateService", "awsRegion": "us-east-1", "sourceIPAddress": "000.00.00.00", "userAgent": "console.amazonaws.com", "requestParameters": { "clientToken": "EXAMPLE", "cluster": "default", "desiredCount": 2 ... ``` ### 進行状況のレポート `ProgressReporter` インターフェイスを実装して、CloudTrail Processing Library の進行状況レポートをカスタマイズします。`ProgressReporter`で宣言されている 2 つのメソッド `reportStart()` と `reportEnd()` は、以下の操作の開始時と終了時に呼び出されます。 + Amazon SQS からのメッセージのポーリング + Amazon SQS からのメッセージの解析 + CloudTrail ログの Amazon SQS ソースの処理 + Amazon SQS からのメッセージの削除 + CloudTrail ログファイルのダウンロード + CloudTrail ログファイルの処理どちらの方法でも、実行されたオペレーションに関する情報が含まれる `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` で 1 つだけ宣言されている `handleException()` メソッドは、発生した例外についてのコンテキストを含む `ProcessingLibraryException` オブジェクトを受け取ります。渡された `ProcessingLibraryException` の `getStatus()` メソッドを使用して、例外発生時に実行された操作を明らかにし、操作のステータスに関する追加情報を取得できます。`ProcessingLibraryException` は Java の標準的な `Exception` クラスから派生しているので、いずれかの 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` は、標準エラーメッセージを表示します。 **注記** この `deleteMessageUponFailure` パラメータが `true` の場合、CloudTrail Processing Library は一般的な例外処理と処理エラーとを区別せず、キューメッセージが削除される場合があります。例えば、`SourceFilter` を使用して、タイムスタンプでメッセージをフィルタリングします。ただし、CloudTrail ログファイルを受け取る S3 バケットにアクセスするために必要なアクセス権限がありません。必要なアクセス権限がないため、`AmazonServiceException` がスローされます。CloudTrail Processing Library は、これを `CallBackException` で折り返します。 `DefaultExceptionHandler` はこれをログとして記録しますが、必要なアクセス権限がないという根本原因を特定することはありません。メッセージに有効な CloudTrail ログファイルが含まれている場合でも、CloudTrail Processing Library はこれを処理エラーとみなし、メッセージを削除します。メッセージを `SourceFilter` でフィルタリングするには、`ExceptionHandler` がサービスの例外を処理エラーから区別できることを確認します。 ## その他のリソース CloudTrail Processing Library の詳細については、以下を参照してください。 + [CloudTrail Processing Library](https://github.com/aws/aws-cloudtrail-processing-library) の GitHub プロジェクトには、CloudTrail Processing Library アプリケーションの実装方法を示す[サンプル](https://github.com/aws/aws-cloudtrail-processing-library/tree/master/src/sample)コードが含まれます。 + [CloudTrail Processing Library Java パッケージドキュメント](https://docs.aws.amazon.com/awscloudtrail/latest/processinglib/)。