As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Usando a Biblioteca CloudTrail de Processamento A Biblioteca CloudTrail de Processamento é uma biblioteca Java que fornece uma maneira fácil de processar AWS CloudTrail registros. Você fornece detalhes de configuração sobre sua fila CloudTrail SQS e grava código para processar eventos. A Biblioteca CloudTrail de Processamento faz o resto. Ele pesquisa sua fila do Amazon SQS, lê e analisa mensagens da fila, CloudTrail baixa arquivos de log, analisa eventos nos arquivos de log e passa os eventos para seu código como objetos Java. A Biblioteca CloudTrail de Processamento é altamente escalável e tolerante a falhas. Ela lida com processamento paralelo de arquivos de log para que você possa processar quantos logs precisar. Ela lida com falhas de rede relacionadas a limites de tempo da rede e recursos inacessíveis. O tópico a seguir mostra como usar a Biblioteca CloudTrail de Processamento para processar CloudTrail registros em seus projetos Java. A biblioteca é fornecida como um projeto de código aberto licenciado pela Apache, disponível em:. GitHub [https://github.com/aws/aws-cloudtrail-processing-library](https://github.com/aws/aws-cloudtrail-processing-library) O código-fonte da biblioteca inclui código de exemplo que você pode usar como base para os seus próprios projetos. **Topics** + [Requisitos mínimos](#use-the-cloudtrail-processing-library-prerequisites) + [CloudTrail Registros de processamento](#use-the-cloudtrail-processing-library-how-to) + [Tópicos avançados](#use-the-cloudtrail-processing-library-advanced) + [Recursos adicionais do](#UsingProcessingLib-ar) ## Requisitos mínimos Para usar a Biblioteca CloudTrail de Processamento, você deve ter o seguinte: + [AWS SDK para 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 Registros de processamento Para processar CloudTrail registros em seu aplicativo Java: 1. [Adicionando a Biblioteca CloudTrail de Processamento ao seu projeto](#use-the-cloudtrail-processing-library-add-to-project) 1. [Configurando a biblioteca de CloudTrail processamento](#use-the-cloudtrail-processing-library-configure) 1. [Implementar o processador de eventos](#use-the-cloudtrail-processing-library-implement-events-processor) 1. [Instalar e executar o executor de processamento](#use-the-cloudtrail-processing-library-instantiate-and-run-executor) ### Adicionando a Biblioteca CloudTrail de Processamento ao seu projeto Para usar a Biblioteca CloudTrail de Processamento, adicione-a ao classpath do seu projeto Java. **Contents** + [Adicionar a biblioteca a um projeto Apache Ant](#use-the-cloudtrail-processing-library-add-to-project-apache-ant) + [Adicionar a biblioteca a um projeto Apache Maven](#use-the-cloudtrail-processing-library-add-to-project-apache-maven) + [Adicionar a biblioteca a um projeto Eclipse](#use-the-cloudtrail-processing-library-add-to-project-eclipse) + [Adicionar a biblioteca a um projeto IntelliJ](#use-the-cloudtrail-processing-library-add-to-intellij-project) #### Adicionar a biblioteca a um projeto Apache Ant **Para adicionar a Biblioteca CloudTrail de Processamento a um projeto Apache Ant** 1. Baixe ou clone o código-fonte da Biblioteca de CloudTrail Processamento em: GitHub + [https://github.com/aws/aws-cloudtrail-processing-library](https://github.com/aws/aws-cloudtrail-processing-library) 1. Crie o arquivo .jar a partir do código-fonte, conforme descrito na seção [README](https://github.com/aws/aws-cloudtrail-processing-library/blob/master/README.rst) (LEIA-ME): ``` mvn clean install -Dgpg.skip=true ``` 1. Copie o arquivo .jar resultante para o seu projeto e adicione-o ao arquivo `build.xml` do projeto. Por exemplo: ``` ``` #### Adicionar a biblioteca a um projeto Apache Maven A Biblioteca CloudTrail de Processamento está disponível para o [Apache Maven](https://maven.apache.org/). Você pode adicioná-la ao seu projeto escrevendo uma única dependência no arquivo `pom.xml` do seu projeto. **Para adicionar a Biblioteca CloudTrail de Processamento a um projeto Maven** + Abra o arquivo `pom.xml` do seu projeto Maven e adicione a seguinte dependência: ``` com.amazonaws aws-cloudtrail-processing-library 1.6.1 ``` #### Adicionar a biblioteca a um projeto Eclipse **Para adicionar a Biblioteca CloudTrail de Processamento a um projeto Eclipse** 1. Baixe ou clone o código-fonte da Biblioteca de CloudTrail Processamento em: GitHub + [https://github.com/aws/aws-cloudtrail-processing-library](https://github.com/aws/aws-cloudtrail-processing-library) 1. Crie o arquivo .jar a partir do código-fonte, conforme descrito na seção [README](https://github.com/aws/aws-cloudtrail-processing-library/blob/master/README.rst) (LEIA-ME): ``` mvn clean install -Dgpg.skip=true ``` 1. Copie o aws-cloudtrail-processing-library -1.6.1.jar construído para um diretório em seu projeto (normalmente). `lib` 1. Clique com o botão direito do mouse no nome do projeto no **Project Explorer (Explorador de projetos)** do Eclipse, escolha **Build Path (Caminho do build)** e escolha **Configure (Configurar)** 1. Na janela **Java Build Path (Caminho de build Java)**, escolha a guia **Libraries (Bibliotecas)**. 1. Escolha **Adicionar JARs...** e navegue até o caminho em que você copiou aws-cloudtrail-processing-library -1.6.1.jar. 1. Escolha **OK** para concluir a adição do `.jar` ao seu projeto. #### Adicionar a biblioteca a um projeto IntelliJ **Para adicionar a Biblioteca CloudTrail de Processamento a um projeto IntelliJ** 1. Baixe ou clone o código-fonte da Biblioteca de CloudTrail Processamento em: GitHub + [https://github.com/aws/aws-cloudtrail-processing-library](https://github.com/aws/aws-cloudtrail-processing-library) 1. Crie o arquivo .jar a partir do código-fonte, conforme descrito na seção [README](https://github.com/aws/aws-cloudtrail-processing-library/blob/master/README.rst) (LEIAME): ``` mvn clean install -Dgpg.skip=true ``` 1. Em **File**, escolha **Project Structure**. 1. Escolha **Modules (Módulos)** e escolha **Dependencies (Dependências)**. 1. Escolha **\$1 JARS or Directories (\$1 JARS ou diretórios)** e acesse o caminho em que você criou o `aws-cloudtrail-processing-library-1.6.1.jar`. 1. Escolha **Apply (Aplicar)** e escolha **OK** para concluir a adição do `.jar` ao seu projeto. ### Configurando a biblioteca de CloudTrail processamento Você pode configurar a Biblioteca CloudTrail de Processamento criando um arquivo de propriedades do caminho de classe que é carregado em tempo de execução ou criando um `ClientConfiguration` objeto e definindo as opções manualmente. #### Fornecer um arquivo de propriedades Você pode criar um arquivo de propriedades classpath que fornece opções de configuração ao seu aplicativo. O seguinte exemplo de arquivo mostra as opções que você pode definir: ``` # 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 ``` Os seguintes parâmetros são obrigatórios: + `sqsUrl`— Fornece o URL do qual extrair suas CloudTrail notificações. Se você não especificar esse valor, o `AWSCloudTrailProcessingExecutor` lança uma `IllegalStateException`. + `accessKey` - Um identificador exclusivo para a sua conta, como AKIAIOSFODNN7EXAMPLE. + `secretKey` - Um identificador exclusivo para a sua conta, como wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY. Os `secretKey` parâmetros `accessKey` e fornecem suas AWS credenciais à biblioteca para que ela possa acessar AWS em seu nome. O padrão para os outros parâmetros são definidos pela biblioteca. Para obter mais informações, consulte a [Referência da Biblioteca de Processamento do AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/processinglib/). #### Criando um ClientConfiguration Em vez de definir opções nas propriedades do classpath, você pode fornecer opções ao `AWSCloudTrailProcessingExecutor` inicializando e definindo opções em um objeto `ClientConfiguration`, como mostra este exemplo: ``` ClientConfiguration basicConfig = new ClientConfiguration( "http://sqs.us-east-1.amazonaws.com/123456789012/queue2", new DefaultAWSCredentialsProviderChain()); basicConfig.setEnableRawEventInfo(true); basicConfig.setThreadCount(4); basicConfig.setnEventsPerEmit(20); ``` ### Implementar o processador de eventos Para processar CloudTrail registros, você deve implementar um `EventsProcessor` que receba os dados do CloudTrail registro. Este é um exemplo de nome de implementação: ``` 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())); } } } ``` Ao implementar um`EventsProcessor`, você implementa o `process()` retorno de chamada que ele `AWSCloudTrailProcessingExecutor` usa para enviar CloudTrail eventos a você. Os eventos são fornecidos em uma lista de objetos `CloudTrailClientEvent`. O `CloudTrailClientEvent` objeto fornece um `CloudTrailEvent` e `CloudTrailEventMetadata` que você pode usar para ler as informações do CloudTrail evento e da entrega. Esse exemplo simples imprime as informações de cada evento transmitido ao `SampleEventsProcessor`. Em sua própria implementação, você pode processar logs de acordo com a sua necessidade. O `AWSCloudTrailProcessingExecutor` continua enviando eventos ao seu `EventsProcessor`, desde que tenha eventos para enviar e ainda esteja em execução. ### Instalar e executar o executor de processamento Depois de escrever `EventsProcessor` e definir valores de configuração para a Biblioteca de CloudTrail Processamento (em um arquivo de propriedades ou usando a `ClientConfiguration` classe), você pode usar esses elementos para inicializar e usar um`AWSCloudTrailProcessingExecutor`. **Para usar `AWSCloudTrailProcessingExecutor` para processar CloudTrail eventos** 1. Instanciar um objeto `AWSCloudTrailProcessingExecutor.Builder`. O construtor do `Builder` usa um objeto `EventsProcessor` e o nome de um arquivo de propriedades do caminho de classe. 1. Chame o método de fábrica `build()` do `Builder` para configurar e obter um objeto `AWSCloudTrailProcessingExecutor`. 1. Use os `AWSCloudTrailProcessingExecutor` `stop()` métodos `start()` e para iniciar e finalizar o processamento de CloudTrail eventos. ``` 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 } } ``` ## Tópicos avançados **Topics** + [Filtrar os eventos a serem processados](#use-the-cloudtrail-processing-library-advanced-filter-events) + [Processar eventos de dados](#use-the-cpl-advanced-integers-floats) + [Informar o progresso](#use-the-cloudtrail-processing-library-advanced-report-progress) + [Tratamento de erros](#use-the-cloudtrail-processing-library-advanced-handle-errors) ### Filtrar os eventos a serem processados Por padrão, todos os logs no bucket do S3 da sua fila do Amazon SQS e todos os eventos que eles contêm são enviados para o `EventsProcessor`. A Biblioteca CloudTrail de Processamento fornece interfaces opcionais que você pode implementar para filtrar as fontes usadas para obter CloudTrail registros e filtrar os eventos que você tem interesse em processar. `SourceFilter` Você pode implementar a interface `SourceFilter` para escolher se deseja processar os logs de uma origem fornecida. `SourceFilter` declara um único método de retorno de chamada, `filterSource()`, que recebe um objeto `CloudTrailSource`. Para impedir que os eventos de uma origem sejam processados, retorne `false` de `filterSource()`. A Biblioteca CloudTrail de processamento chama o `filterSource()` método depois que a biblioteca pesquisa os registros na fila do Amazon SQS. Isso ocorre antes de a biblioteca começar a filtragem de eventos ou o processamento de logs. Este é um exemplo de nome de implementação: ``` 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); } } ``` Se você não fornecer seu próprio `SourceFilter`, `DefaultSourceFilter` será usado, o que permite que todas as origens sejam processadas (o valor retornado é sempre `true`). `EventFilter` Você pode implementar a interface `EventFilter` para escolher se um evento CloudTrail é enviado para o seu `EventsProcessor`. `EventFilter` declara um único método de retorno de chamada`filterEvent()`, que recebe um objeto `CloudTrailEvent`. Para impedir que o evento seja processado, retorne `false` de `filterEvent()`. A Biblioteca CloudTrail de processamento chama o `filterEvent()` método depois que a biblioteca pesquisa os registros na fila do Amazon SQS e após a filtragem da fonte. Isso ocorre antes de a biblioteca começar o processamento de eventos para os logs. Veja este exemplo de implementação: ``` 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"); } } ``` Se você não fornecer seu próprio `EventFilter`, `DefaultEventFilter` será usado, o que permite que todos os eventos sejam processados (o valor retornado é sempre `true`). ### Processar eventos de dados Ao CloudTrail processar eventos de dados, ele preserva os números em seu formato original, seja um inteiro (`int`) ou um `float` (um número que contém um decimal). Em eventos que têm números inteiros nos campos de um evento de dados, CloudTrail historicamente processou esses números como flutuantes. Atualmente, CloudTrail processa números nesses campos mantendo o formato original. Como prática recomendada, para evitar a quebra de suas automações, seja flexível em qualquer código ou automação que você esteja usando para processar ou filtrar eventos de CloudTrail dados e permita ambos `int` e números `float` formatados. Para obter melhores resultados, use a versão 1.4.0 ou superior da Biblioteca de CloudTrail Processamento. O snippet de exemplo a seguir mostra um número formatado `float` (`2.0`) para o parâmetro `desiredCount` no bloco de evento de dados `ResponseParameters`. ``` "eventName": "CreateService", "awsRegion": "us-east-1", "sourceIPAddress": "000.00.00.00", "userAgent": "console.amazonaws.com", "requestParameters": { "clientToken": "EXAMPLE", "cluster": "default", "desiredCount": 2.0 ... ``` O snippet de exemplo a seguir mostra um número formatado `int` (`2`) para o parâmetro `desiredCount` no bloco de evento de dados `ResponseParameters`. ``` "eventName": "CreateService", "awsRegion": "us-east-1", "sourceIPAddress": "000.00.00.00", "userAgent": "console.amazonaws.com", "requestParameters": { "clientToken": "EXAMPLE", "cluster": "default", "desiredCount": 2 ... ``` ### Informar o progresso Implemente a `ProgressReporter` interface para personalizar os relatórios do progresso da Biblioteca de CloudTrail Processamento. `ProgressReporter`declara dois métodos: `reportStart()` e`reportEnd()`, que são chamados no início e no final das seguintes operações: + Consultar mensagens do Amazon SQS + Analisar mensagens do Amazon SQS + Processando uma fonte do Amazon SQS para registros CloudTrail + Excluir mensagens do Amazon SQS + Baixando um arquivo CloudTrail de log + Processando um arquivo CloudTrail de log Os dois métodos recebem um objeto `ProgressStatus` que contém informações sobre a operação executada. O membro `progressState` contém um membro da enumeração `ProgressState` que identifica a operação atual. Esse membro pode conter informações adicionais no membro `progressInfo`. Além disso, qualquer objeto que você retornar de `reportStart()` será transmitido para `reportEnd()`, a fim de que você possa fornecer informações contextuais, como o horário em que o evento começou a ser processado. Veja a seguir um exemplo de implementação que fornece informações sobre quanto tempo uma operação levou para ser concluída: ``` 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."); } } ``` Se você não implementar seu próprio `ProgressReporter`, `DefaultExceptionHandler`, que imprime o nome do estado que está em execução, será usado. ### Tratamento de erros A interface `ExceptionHandler` permite que você dê um tratamento especial quando ocorre uma exceção durante o processamento de log. `ExceptionHandler` declara um único método de retorno de chamada, `handleException()`, que recebe um objeto `ProcessingLibraryException` com contexto sobre a exceção que ocorreu. Você pode usar o método de `ProcessingLibraryException`, `getStatus()`, transferido para descobrir qual operação foi executada quando a exceção ocorreu e obter informações adicionais sobre o status da operação. `ProcessingLibraryException` deriva-se da classe padrão `Exception` de Java, portanto, você também pode recuperar informações sobre a exceção chamando qualquer um dos métodos de exceção. Veja este exemplo de implementação: ``` 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)); } } ``` Se você não fornecer seu próprio `ExceptionHandler`, `DefaultExceptionHandler`, que imprime uma mensagem de erro padrão, será usado. **nota** Se o `deleteMessageUponFailure` parâmetro for`true`, a Biblioteca CloudTrail de Processamento não distingue exceções gerais de erros de processamento e poderá excluir mensagens da fila. Por exemplo, você usa o `SourceFilter` para filtrar mensagens por data e hora. No entanto, você não tem as permissões necessárias para acessar o bucket do S3 que recebe os arquivos de CloudTrail log. Como você não tem as permissões necessárias, uma `AmazonServiceException` é lançada. A Biblioteca CloudTrail de Processamento envolve isso em um`CallBackException`. O `DefaultExceptionHandler` registra isso como um erro, mas não identifica a causa-raiz, que é o fato de você não ter as permissões necessárias. A Biblioteca CloudTrail de Processamento considera isso um erro de processamento e exclui a mensagem, mesmo que a mensagem inclua um arquivo de CloudTrail log válido. Se você quiser filtrar mensagens com `SourceFilter`, verifique se o seu `ExceptionHandler` pode diferenciar exceções de serviço de erros de processamento. ## Recursos adicionais do Para obter mais informações sobre a Biblioteca CloudTrail de Processamento, consulte o seguinte: + CloudTrail GitHub Projeto [de biblioteca de processamento](https://github.com/aws/aws-cloudtrail-processing-library), que inclui código de [amostra](https://github.com/aws/aws-cloudtrail-processing-library/tree/master/src/sample) que demonstra como implementar um aplicativo CloudTrail de biblioteca de processamento. + [CloudTrail Documentação do Pacote Java da Biblioteca de Processamento](https://docs.aws.amazon.com/awscloudtrail/latest/processinglib/).