O AWS SDK para Java 1.x chegou end-of-support em 31 de dezembro de 2025. Recomendamos que você migre para o [AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/home.html) para continuar recebendo novos recursos, melhorias de disponibilidade e atualizações de segurança. 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á. # AWS SDK para Java Code Examples Esta seção fornece tutoriais e exemplos de como usar o AWS SDK para Java v1 para programar os serviços da AWS. Encontre o código-fonte para esses exemplos e outros no [repositório de exemplos de código no GitHub](https://github.com/awsdocs/aws-doc-sdk-examples) da documentação da AWS. Para sugerir um novo exemplo de código para a equipe de documentação da AWS considerar a produção, crie uma solicitação. A equipe está buscando produzir exemplos de código que abrangem cenários e casos de uso mais amplos, em vez de trechos de código simples que abrangem apenas chamadas de API individuais. Para obter instruções, consulte as [Diretrizes de contribuição](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/CONTRIBUTING.md) no repositório de exemplos de código no GitHub. ## AWS SDK para Java 2.x Em 2018, a AWS lançou o [AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/home.html). Este guia contém instruções sobre como usar o SDK para Java mais recente junto com um código de exemplo. **nota** Consulte [Documentação e recursos adicionais](welcome.md#additional-resources) para obter mais exemplos e recursos adicionais disponíveis para desenvolvedores do AWS SDK para Java\$1 **Topics** # Exemplos do CloudWatch usando o AWS SDK para Java Esta seção apresenta exemplos de como programar o [CloudWatch](https://aws.amazon.com/cloudwatch/) usando o [AWS SDK para Java](https://aws.amazon.com/sdk-for-java/). O Amazon CloudWatch monitora os recursos da Amazon Web Services (AWS) e as aplicações que você executa na AWS em tempo real. Você pode usar o CloudWatch para coletar e monitorar métricas, que são as variáveis mensuráveis que ajudam você a avaliar seus recursos e aplicativos. Os alarmes do CloudWatch enviam notificações ou fazem alterações automaticamente nos recursos que você está monitorando com base nas regras definidas. Para obter mais informações sobre o CloudWatch, consulte o [Guia do usuário do Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/). **nota** Entre os exemplos está somente o código necessário para demonstrar cada técnica. O [código de exemplo completo está disponível no GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java). A partir daí, você pode fazer download de um único arquivo de origem ou clonar o repositório de maneira local para obter todos os exemplos para compilação e execução. **Topics** + [Obter métricas do CloudWatch](examples-cloudwatch-get-metrics.md) + [Publicar dados de métrica personalizada](examples-cloudwatch-publish-custom-metrics.md) + [Trabalhar com alarmes do CloudWatch](examples-cloudwatch-create-alarms.md) + [Usar ações de alarme no CloudWatch](examples-cloudwatch-use-alarm-actions.md) + [Enviar eventos do ao CloudWatch](examples-cloudwatch-send-events.md) # Obter métricas do CloudWatch ## Listar métricas Para listar métricas do CloudWatch, crie um [ListMetricsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/ListMetricsRequest.html) e chame o método `listMetrics` do AmazonCloudWatchClient. Você pode usar o `ListMetricsRequest` para filtrar as métricas retornadas por namespace, nome da métrica ou dimensões. **nota** Uma lista de métricas e dimensões publicadas pelos serviços da AWS pode ser encontrada em \$1https---docs-aws-amazon-com-AmazonCloudWatch-Latest-Monitoring-CW-Support-for-AWS-html\$1 [Referência de métricas e dimensões do Amazon CloudWatch] no Guia do usuário do Amazon CloudWatch. **Importações** ``` 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; ``` **Código da** ``` 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; } } ``` As métricas são retornadas em um [ListMetricsResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/ListMetricsResult.html) chamando o método `getMetrics`. Os resultados podem ser *paginados*. Para recuperar o próximo lote de resultados, chame `setNextToken` no objeto de solicitação original com o valor de retorno do método `ListMetricsResult` do objeto `getNextToken` e passe o objeto de solicitação modificado para outra chamada para `listMetrics`. ## Mais informações + [ListMetrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_ListMetrics.html) na Referência de API do Amazon CloudWatch. # Publicar dados de métrica personalizada Vários serviços da AWS publicam [as próprias métricas](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/aws-namespaces.html) em namespaces que começam com “`AWS`”. Também é possível publicar dados de métricas personalizadas usando seu próprio namespace (contanto que não comece com “`AWS`”). ## Publicar dados de métrica personalizada Para publicar os próprios dados de métrica, chame o método `putMetricData` do AmazonCloudWatchClient com um [PutMetricDataRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/PutMetricDataRequest.html). O `PutMetricDataRequest` deve incluir o namespace personalizado a ser usado para os dados e as informações sobre o próprio ponto de dados em um objeto [MetricDatum](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/MetricDatum.html). **nota** Você não pode especificar um namespace que começa com “`AWS`”. Namespaces que começam com “`AWS`” são reservados para serem usados por produtos da Amazon Web Services. **Importações** ``` 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; ``` **Código da** ``` 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); ``` ## Mais informações + [Usar métricas do Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) no Guia do usuário do Amazon CloudWatch. + [Namespaces da AWS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/aws-namespaces.html) no Guia do usuário Amazon CloudWatch. + [PutMetricData](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html) na Referência de API do Amazon CloudWatch. # Trabalhar com alarmes do CloudWatch ## Criar um alarme Para criar um alarme com base em uma métrica do CloudWatch, chame o método `putMetricAlarm` do AmazonCloudWatchClient com um [PutMetricAlarmRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/PutMetricAlarmRequest.html) preenchido com as condições de alarme. **Importações** ``` 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; ``` **Código da** ``` 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); ``` ## Listar alarmes Para listar os alarmes do CloudWatch criados por você, chame o método `describeAlarms` do AmazonCloudWatchClient com um [DescribeAlarmsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/DescribeAlarmsRequest.html) que pode ser usado para definir opções para o resultado. **Importações** ``` 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; ``` **Código da** ``` 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; } } ``` A lista de alarmes pode ser obtida chamando `getMetricAlarms` no [DescribeAlarmsResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/DescribeAlarmsResult.html) retornado por `describeAlarms`. Os resultados podem ser *paginados*. Para recuperar o próximo lote de resultados, chame `setNextToken` no objeto de solicitação original com o valor de retorno do método `DescribeAlarmsResult` do objeto `getNextToken` e passe o objeto de solicitação modificado para outra chamada para `describeAlarms`. **nota** Você também pode recuperar alarmes para uma métrica específica usando o método `describeAlarmsForMetric` do AmazonCloudWatchClient. O uso é semelhante a `describeAlarms`. ## Excluir alarmes Para excluir os alarmes do CloudWatch, chame o método `deleteAlarms` do AmazonCloudWatchClient com um [DeleteAlarmsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/DeleteAlarmsRequest.html) contendo um ou mais nomes de alarmes que você deseja excluir. **Importações** ``` 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; ``` **Código da** ``` final AmazonCloudWatch cw = AmazonCloudWatchClientBuilder.defaultClient(); DeleteAlarmsRequest request = new DeleteAlarmsRequest() .withAlarmNames(alarm_name); DeleteAlarmsResult response = cw.deleteAlarms(request); ``` ## Mais informações + [Criar alarmes do Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html), no Guia do usuário do Amazon CloudWatch + [PutMetricAlarm](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricAlarm.html) na Referência de API do Amazon CloudWatch + [DescribeAlarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_DescribeAlarms.html) na Referência de API do Amazon CloudWatch + [DeleteAlarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_DeleteAlarms.html) na Referência de API do Amazon CloudWatch # Usar ações de alarme no CloudWatch Usando ações de alarme do CloudWatch, é possível criar alarmes que realizam ações como interromper, encerrar, reinicializar ou recuperar automaticamente instâncias do Amazon EC2. **nota** As ações de alarme podem ser adicionadas a um alarme usando-se o método [ de ](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/PutMetricAlarmRequest.html)PutMetricAlarmRequest`setAlarmActions` quando se [cria um alarme](examples-cloudwatch-create-alarms.md). ## Habilitar ações de alarme Para habilitar ações de um alarme do CloudWatch, chame o `enableAlarmActions` do AmazonCloudWatchClient com um [EnableAlarmActionsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/EnableAlarmActionsRequest.html) que contém um ou mais nomes de alarmes cujas ações você deseja habilitar. **Importações** ``` 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; ``` **Código da** ``` final AmazonCloudWatch cw = AmazonCloudWatchClientBuilder.defaultClient(); EnableAlarmActionsRequest request = new EnableAlarmActionsRequest() .withAlarmNames(alarm); EnableAlarmActionsResult response = cw.enableAlarmActions(request); ``` ## Desabilitar ações de alarme Para desabilitar ações de um alarme do CloudWatch, chame o `disableAlarmActions` do AmazonCloudWatchClient com um [DisableAlarmActionsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatch/model/DisableAlarmActionsRequest.html) que contém um ou mais nomes de alarmes cujas ações você deseja desabilitar. **Importações** ``` 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; ``` **Código da** ``` final AmazonCloudWatch cw = AmazonCloudWatchClientBuilder.defaultClient(); DisableAlarmActionsRequest request = new DisableAlarmActionsRequest() .withAlarmNames(alarmName); DisableAlarmActionsResult response = cw.disableAlarmActions(request); ``` ## Mais informações + [Criar alarmes para interromper, encerrar, reinicializar ou recuperar uma instância](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/UsingAlarmActions.html) no Guia do Usuário do Amazon CloudWatch + [PutMetricAlarm](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricAlarm.html) na Referência de API do Amazon CloudWatch + [EnableAlarmActions](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_EnableAlarmActions.html) na Referência de API do Amazon CloudWatch + [DisableAlarmActions](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_DisableAlarmActions.html) na Referência de API do Amazon CloudWatch # Enviar eventos do ao CloudWatch O CloudWatch Events distribui um fluxo quase em tempo real de eventos do sistema que descrevem alterações feitas em recursos da AWS para instâncias do Amazon EC2, funções do Lambda, fluxos do Kinesis, tarefas do Amazon ECS, máquinas de estado do Step Functions, tópicos do Amazon SNS, filas do Amazon SQS ou destinos internos. Você pode comparar eventos e roteá-los para um ou mais fluxos ou funções de destino usando regras simples. ## Adicionar eventos Para adicionar eventos do CloudWatch personalizados, chame o método `putEvents` do AmazonCloudWatchEventsClient com um objeto [PutEventsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatchevents/model/PutEventsRequest.html) que contenha um ou mais objetos [PutEventsRequestEntry](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatchevents/model/PutEventsRequestEntry.html) que fornecem detalhes sobre cada evento. Você pode especificar vários parâmetros para a entrada, como a origem e o tipo do evento, recursos associados ao evento e assim por diante. **nota** Você pode especificar um máximo de dez eventos por chamada para `putEvents`. **Importações** ``` 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; ``` **Código da** ``` 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); ``` ## Adicionar regras Para criar ou atualizar uma regra, chame o método `putRule` do AmazonCloudWatchEventsClient com um [PutRuleRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatchevents/model/PutRuleRequest.html) com o nome da regra e os parâmetros opcionais, como o [padrão de evento](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/CloudWatchEventsandEventPatterns.html), o perfil do IAM a ser associado à regra e uma [expressão de programação](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html) que descreva com que frequência a regra é executada. **Importações** ``` 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; ``` **Código da** ``` 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); ``` ## Adicionar destinos Destinos são os recursos invocados quando uma regra é disparada. Entre os destinos de exemplo estão instâncias do Amazon EC2, funções do Lambda, streamings do Kinesis, tarefas do Amazon ECS, máquinas de estado do Step Functions e destinos integrados. Para adicionar um destino a uma regra, chame o método `putTargets` do AmazonCloudWatchEventsClient com um [PutTargetsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/cloudwatchevents/model/PutTargetsRequest.html) que contenha a regra a ser atualizada e uma lista de destinos a serem adicionados à regra. **Importações** ``` 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; ``` **Código da** ``` 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); ``` ## Mais informações + [Adicionar eventos com PutEvents](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/AddEventsPutEvents.html) no Guia do Usuário do Amazon CloudWatch Events + [Programar expressões para regras](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html) no Guia do Usuário do Amazon CloudWatch Events + [Tipos de eventos para o CloudWatch Events](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/EventTypes.html) no Guia do usuário do Amazon CloudWatch Events + [Eventos e padrões de evento](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/CloudWatchEventsandEventPatterns.html) no Guia do Usuário do Amazon CloudWatch Events + [PutEvents](https://docs.aws.amazon.com/AmazonCloudWatchEvents/latest/APIReference/API_PutEvents.html) na Referência de API do Amazon CloudWatch Events + [PutTargets](https://docs.aws.amazon.com/AmazonCloudWatchEvents/latest/APIReference/API_PutTargets.html) na Referência de API do Amazon CloudWatch Events + [PutRule](https://docs.aws.amazon.com/AmazonCloudWatchEvents/latest/APIReference/API_PutRule.html) na Referência de API do Amazon CloudWatch Events # DynamoDB Exemplos de usando a AWS SDK para Java Esta seção apresenta exemplos de como programar o [DynamoDB](https://aws.amazon.com/dynamodb/) usando o [AWS SDK para Java](https://aws.amazon.com/sdk-for-java/). **nota** Entre os exemplos está somente o código necessário para demonstrar cada técnica. O [código de exemplo completo está disponível no GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java). A partir daí, você pode fazer download de um único arquivo de origem ou clonar o repositório de maneira local para obter todos os exemplos para compilação e execução. **Topics** + [Usar endpoints baseados em conta da AWS](#account-based-endpoint-routing) + [Trabalho com tabelas no DynamoDB](examples-dynamodb-tables.md) + [Trabalho com itens no DynamoDB](examples-dynamodb-items.md) ## Usar endpoints baseados em conta da AWS O DynamoDB oferece [endpoints baseados em contas da AWS](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.SDKOverview.html#Programming.SDKs.endpoints) que podem melhorar o desempenho usando seu ID de conta da AWS para simplificar o roteamento de solicitações. Para aproveitar esse recurso, use a versão 1.12.771 ou posterior da versão 1 do AWS SDK para Java. É possível encontrar a versão mais recente do SDK listado no[repositório central do Maven](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom). Depois que uma versão compatível do SDK está ativa, os novos endpoints são usados automaticamente. Se quiser optar por não utilizar o roteamento baseado em contas, você terá quatro opções: + Configurar um cliente de serviço do DynamoDB com o `AccountIdEndpointMode` definido como `DISABLED`. + Definir uma variável de ambiente. + Definir uma propriedade do sistema da JVM. + Atualizar a definição do arquivo de configuração compartilhado AWS. O seguinte trecho é um exemplo de como desabilitar o roteamento baseado em contas configurando um cliente de serviço do 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(); ``` O Guia de referência e ferramentas de AWS SDKs fornece mais informações sobre as últimas [três opções de configuração](https://docs.aws.amazon.com/sdkref/latest/guide/feature-account-endpoints.html). # Trabalho com tabelas no DynamoDB Tabelas são os contêineres de todos os itens em um banco de dados do DynamoDB. Para adicionar ou remover dados do DynamoDB, você deve criar uma tabela. Para cada tabela, você deve definir: + Um *nome* de tabela é exclusivo para a conta e a região. + Uma *chave primária* para a qual cada valor deve ser único; dois itens na tabela não podem ter o mesmo valor de chave primária. Uma chave primária pode ser *simples*, consistindo em uma única chave de partição (HASH) ou *composta*, que consiste em uma partição e uma chave de classificação (RANGE). Cada valor de chave tem um *tipo de dados* associado, enumerados pela classe [ScalarAttributeType](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/ScalarAttributeType.html). O valor da chave pode ser binário (B), numérico (N) ou uma string (S). Para obter mais informações, consulte [Regras de nomenclatura e tipos de dados](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html) no Guia do desenvolvedor do Amazon DynamoDB. + Valores de *throughput provisionado* que definem o número de unidades de capacidade de leitura/gravação reservadas para a tabela. **nota** A [definição de preço do Amazon DynamoDB](https://aws.amazon.com/dynamodb/pricing/) se baseia nos valores de throughput provisionados definidos por você nas tabelas. Dessa forma, reserve somente a capacidade máxima de que você imagina precisar para a tabela. O throughput provisionado para uma tabela pode ser modificado a qualquer momento. Dessa forma, você poderá ajustar a capacidade se as necessidades mudarem. ## Criar uma tabela Use o método `createTable` do [cliente do DynamoDB](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/AmazonDynamoDB.html) para criar uma nova tabela do DynamoDB. Você precisa construir atributos de tabela e um esquema de tabela, ambos usados para identificar a chave primária da tabela. Você também deve fornecer valores de throughput provisionado iniciais e um nome de tabela. Defina atributos de tabela de chaves apenas ao criar sua tabela de DynamoDB. **nota** Se uma tabela com o nome escolhido por você já existir, um [AmazonServiceException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/AmazonServiceException.html) será lançado. **Importações** ``` 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; ``` ### Criar uma tabela com uma chave primária simples Este código cria uma tabela com uma chave primária simples ("Name"). **Código da** ``` 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); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/CreateTable.java) no GitHub. ### Criar uma tabela com uma chave primária composta Adicione outro [AttributeDefinition](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/AttributeDefinition.html) e [KeySchemaElement](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/KeySchemaElement.html) a [CreateTableRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/CreateTableRequest.html). **Código da** ``` 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); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/CreateTableCompositeKey.java) no GitHub. ## Listar tabelas Você pode listar as tabelas em uma determinada região chamando o método `listTables` do [cliente do DynamoDB](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/AmazonDynamoDB.html). **nota** Se a tabela nomeada não existir para a conta e a região, um [ResourceNotFoundException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/ResourceNotFoundException.html) será lançado. **Importações** ``` 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; ``` **Código da** ``` 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; } ``` Por padrão, até 100 tabelas são retornadas por chamada. Use `getLastEvaluatedTableName` no objeto [ListTablesResult](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/model/ListTablesResult.html) retornado para obter a tabela mais recentemente avaliada. Você pode usar esse valor para iniciar a listagem depois do último valor retornado da listagem anterior. Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/ListTables.java) no GitHub. ## Descrever (obter informações sobre) uma tabela Chame o método `describeTable` do [cliente do DynamoDB](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/AmazonDynamoDB.html). **nota** Se a tabela nomeada não existir para a conta e a região, um [ResourceNotFoundException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/ResourceNotFoundException.html) será lançado. **Importações** ``` 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; ``` **Código da** ``` 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); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/DescribeTable.java) no GitHub. ## Modificar (atualizar) uma tabela Você pode modificar os valores de throughput provisionado da tabela a qualquer momento chamando o método `updateTable` do [cliente do DynamoDB](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/AmazonDynamoDB.html). **nota** Se a tabela nomeada não existir para a conta e a região, um [ResourceNotFoundException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/ResourceNotFoundException.html) será lançado. **Importações** ``` import com.amazonaws.services.dynamodbv2.AmazonDynamoDB; import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder; import com.amazonaws.services.dynamodbv2.model.ProvisionedThroughput; import com.amazonaws.AmazonServiceException; ``` **Código da** ``` 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); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/UpdateTable.java) no GitHub. ## Excluir uma tabela Chame o método `deleteTable` do [cliente do DynamoDB](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/AmazonDynamoDB.html) e passe o nome da tabela para ele. **nota** Se a tabela nomeada não existir para a conta e a região, um [ResourceNotFoundException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/ResourceNotFoundException.html) será lançado. **Importações** ``` import com.amazonaws.AmazonServiceException; import com.amazonaws.services.dynamodbv2.AmazonDynamoDB; import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder; ``` **Código da** ``` final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient(); try { ddb.deleteTable(table_name); } catch (AmazonServiceException e) { System.err.println(e.getErrorMessage()); System.exit(1); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/DeleteTable.java) no GitHub. ## Mais informações + [Diretrizes para trabalhar com tabelas](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GuidelinesForTables.html) no Guia do desenvolvedor do Amazon DynamoDB + [Trabalhar com tabelas no DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.html) no Guia do Desenvolvedor do Amazon DynamoDB # Trabalho com itens no DynamoDB No DynamoDB, um item é um conjunto de *atributos*, e cada um tem um *nome* e um *valor*. Um valor de atributo pode ser uma escalar, um conjunto ou um tipo de documento. Para obter mais informações, consulte [Regras de nomenclatura e tipos de dados](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html) no Guia do desenvolvedor do Amazon DynamoDB. ## Recuperar (obter) um item de uma tabela Chame o método `getItem` do AmazonDynamoDB e passe um objeto [GetItemRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/GetItemRequest.html) para ele com o nome da tabela e o valor da chave primária do item desejado. Ele retorna um objeto [GetItemResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/GetItemResult.html). Você pode usar o método `getItem()` do objeto `GetItemResult` retornado para recuperar um [Mapa](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/Map.html) dos pares de chave (String) e valor ([AttributeValue](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/AttributeValue.html)) associados ao item. **Importações** ``` 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; ``` **Código da** ``` 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); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/GetItem.java) no GitHub. ## Adicionar um novo item a uma tabela Crie um [Mapa](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/Map.html) de pares de chave/valor que representem os atributos do item. Eles devem incluir valores para os campos de chave primária da tabela. Se o item identificado pela chave primária já existir, os campos serão *atualizados* pela requisição. **nota** Se a tabela nomeada não existir para a conta e a região, um [ResourceNotFoundException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/ResourceNotFoundException.html) será lançado. **Importações** ``` 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; ``` **Código da** ``` 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); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/PutItem.java) no GitHub. ## Atualizar um item existente em uma tabela Você pode atualizar um atributo para um item já existente em uma tabela usando o método `updateItem` do AmazonDynamoDB, fornecendo um nome de tabela, o valor da chave primária e um mapa de campos a ser atualizado. **nota** Se a tabela nomeada não existir para a conta e a região, ou se o item identificado pela chave primária passada não existir, uma [ResourceNotFoundException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/model/ResourceNotFoundException.html) será lançada. **Importações** ``` 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; ``` **Código da** ``` 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); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/UpdateItem.java) no GitHub. ## Usar a classe DynamoDBMapper O [AWS SDK para Java](https://aws.amazon.com/sdk-for-java/) fornece uma classe [DynamoDBMapper](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html), permitindo mapear classes no lado do cliente para tabelas do Amazon DynamoDB. Para usar a classe [DynamoDBMapper](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html), defina o relacionamento entre itens em uma tabela do DynamoDB e suas instâncias de objeto correspondentes no código usando anotações (conforme mostrado no exemplo de código a seguir). A classe [DynamoDBMapper](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html) permite acessar tabelas, realizar várias operações de criação, leitura, atualização e exclusão (CRUD) e executar consultas. **nota** A classe [DynamoDBMapper](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html) não permite criar, atualizar ou excluir tabelas. **Importações** ``` 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; ``` **Código da** O exemplo de código Java a seguir demonstra como adicionar conteúdo à tabela *Music (Música)* usando a classe [DynamoDBMapper](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html). Depois que o conteúdo é adicionado à tabela, observe que um item é carregado usando as teclas *Partition* e *Sort* . Depois disso, o item *Awards (Prêmios)* é atualizado. Para obter informações sobre como criar a tabela *Música*, consulte [Criar uma tabela](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/getting-started-step-1.html) no Guia do desenvolvedor do Amazon DynamoDB. ``` 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; } } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/dynamodb/src/main/java/aws/example/dynamodb/UseDynamoMapping.java) no GitHub. ## Mais informações + [Diretrizes para trabalhar com itens](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GuidelinesForItems.html) no Guia do desenvolvedor do Amazon DynamoDB + [Trabalho com itens no DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html) no Guia do Desenvolvedor do Amazon DynamoDB # Amazon EC2 Exemplos de usando a AWS SDK para Java Esta seção apresenta exemplos de como programar o [Amazon EC2](https://aws.amazon.com/ec2/) com o AWS SDK para Java. **Topics** + [Tutorial: iniciar uma instância do EC2](how-to-ec2.md) + [Usar perfis do IAM para conceder acesso a recursos da AWS no Amazon EC2](java-dg-roles.md) + [Tutorial: instâncias spot do Amazon EC2](tutorial-spot-instances-java.md) + [Tutorial: gerenciamento de requisições spot do Amazon EC2 avançado](tutorial-spot-adv-java.md) + [Gerenciar instâncias do Amazon EC2](examples-ec2-instances.md) + [Usar endereços IP elásticos no Amazon EC2](examples-ec2-elastic-ip.md) + [Usar regiões e zonas de disponibilidade](examples-ec2-regions-zones.md) + [Trabalhar com pares de chaves do Amazon EC2](examples-ec2-key-pairs.md) + [Como trabalhar com grupos de segurança no Amazon EC2](examples-ec2-security-groups.md) # Tutorial: iniciar uma instância do EC2 Este tutorial demonstra como usar o AWS SDK para Java para iniciar uma instância do EC2. **Topics** + [Pré-requisitos](#prerequisitesec2) + [Criar um security group do Amazon EC2](create-security-group.md) + [Criar um par de chaves](create-key-pair.md) + [Executar uma instância do Amazon EC2](run-instance.md) ## Pré-requisitos Antes de começar, verifique se você criou uma Conta da AWS e configurou as credenciais da AWS. Para obter mais informações, consulte [Conceitos básicos](getting-started.md). # Criar um security group do Amazon EC2 ## O EC2-Classic será descontinuado **Atenção** Estamos aposentando o EC2-Classic em 15 de agosto de 2022. É recomendável migrar do EC2-Classic para uma VPC. Consulte mais informações na publicação de blog [EC2-Classic Networking is Retiring – Here's How to Prepare](https://aws.amazon.com/blogs/aws/ec2-classic-is-retiring-heres-how-to-prepare/). Crie um *security group*, que funciona como um firewall virtual que controla o tráfego de rede para uma ou mais instâncias do EC2. Por padrão, o Amazon EC2 associa as instâncias a um security group que não permite tráfego de entrada. Você pode criar um security group que permita que as instâncias do EC2 aceitem um determinado tráfego. Por exemplo, se precisar se conectar a uma instância do Linux, você deverá configurar o security group para permitir tráfego SSH. Você pode criar um grupo de segurança usando o console do Amazon EC2 ou o AWS SDK para Java. Um security group é criado para seu usado no EC2-Classic e EC2-VPC. Para obter mais informações sobre o EC2-Classic e o EC2-VPC, consulte [Plataformas compatíveis](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-supported-platforms.html) no Manual do usuário do Amazon EC2 para instâncias do Linux. Para obter mais informações sobre como criar um grupo de segurança usando o console do Amazon EC2, consulte [Grupos de segurança do Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html) no Guia do usuário do Amazon EC2 para instâncias Linux. 1. Crie e inicialize uma instância [CreateSecurityGroupRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateSecurityGroupRequest.html). Use o método [withGroupName](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateSecurityGroupRequest.html#withGroupName-java.lang.String-) para definir o nome do grupo de segurança e o método [withDescription](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateSecurityGroupRequest.html#withDescription-java.lang.String-) para definir a descrição do grupo de segurança da seguinte maneira: ``` CreateSecurityGroupRequest csgr = new CreateSecurityGroupRequest(); csgr.withGroupName("JavaSecurityGroup").withDescription("My security group"); ``` O nome do grupo de segurança deve ser exclusivo dentro da região da AWS na qual você inicializa o cliente do Amazon EC2. Você deve usar caracteres US-ASCII para o nome e a descrição do security group. 1. Passe o objeto de requisição como um parâmetro para o método [createSecurityGroup](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/AmazonEC2.html#createSecurityGroup-com.amazonaws.services.ec2.model.CreateSecurityGroupRequest-). O método retorna um objeto [CreateSecurityGroupResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateSecurityGroupResult.html), conforme mostrado a seguir: ``` CreateSecurityGroupResult createSecurityGroupResult = amazonEC2Client.createSecurityGroup(csgr); ``` Se você tentar criar um security group com o mesmo nome de um security group existente, `createSecurityGroup` lançará uma exceção. Por padrão, um novo security group não permite tráfego de entrada para a instância do Amazon EC2. Para permitir o tráfego de entrada, você deve autorizar explicitamente a entrada no security group. Você pode autorizar a entrada para endereços IP individuais, para um intervalo de endereços IP, para um protocolo específico e para portas TCP/UDP. 1. Crie e inicialize uma instância [IpPermission](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/IpPermission.html). Use o método [withIpv4Ranges](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/IpPermission.html#withIpv4Ranges-java.util.Collection-) a fim definir o intervalo de endereços IP para autorizar a entrada, e use o método [withIpProtocol](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/IpPermission.html#withIpProtocol-java.lang.String-) para definir o protocolo IP. Use os métodos [withFromPort](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/IpPermission.html#withFromPort-java.lang.Integer-) e [withToPort](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/IpPermission.html#withToPort-java.lang.Integer-) para especificar um intervalo de portas para autorizar a entrada da seguinte maneira: ``` 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); ``` Todas as condições especificadas por você no objeto `IpPermission` devem ser atendidas para que a entrada seja permitida. Especifique o endereço IP usando notação CIDR. Se especificar o protocolo como TCP/UDP, você deverá fornecer uma porta de origem e uma porta de destino. Você poderá autorizar portas somente se especificar TCP ou UDP. 1. Crie e inicialize uma instância [AuthorizeSecurityGroupIngressRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AuthorizeSecurityGroupEgressRequest.html). Use o método `withGroupName` para especificar o nome do grupo de segurança e transmita o objeto `IpPermission` inicializado anteriormente para o método [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…​-) da seguinte maneira: ``` AuthorizeSecurityGroupIngressRequest authorizeSecurityGroupIngressRequest = new AuthorizeSecurityGroupIngressRequest(); authorizeSecurityGroupIngressRequest.withGroupName("JavaSecurityGroup") .withIpPermissions(ipPermission); ``` 1. Transmita o objeto de requisição para o método [authorizeSecurityGroupIngress](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/AmazonEC2Client.html#authorizeSecurityGroupIngress-com.amazonaws.services.ec2.model.AuthorizeSecurityGroupIngressRequest-) da seguinte maneira: ``` amazonEC2Client.authorizeSecurityGroupIngress(authorizeSecurityGroupIngressRequest); ``` Se você chamar `authorizeSecurityGroupIngress` com endereços IP para os quais a entrada já esteja autorizada, o método lançará uma exceção. Crie e inicialize um novo objeto `IpPermission` para autorizar a entrada para IPs, portas e protocolos diferentes antes de chamar `AuthorizeSecurityGroupIngress`. Sempre que você chama os métodos [authorizeSecurityGroupIngress](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/AmazonEC2Client.html#authorizeSecurityGroupIngress-com.amazonaws.services.ec2.model.AuthorizeSecurityGroupIngressRequest-) ou [authorizeSecurityGroupEgress](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/AmazonEC2Client.html#authorizeSecurityGroupEgress-com.amazonaws.services.ec2.model.AuthorizeSecurityGroupEgressRequest-), uma regra é adicionada ao grupo de segurança. # Criar um par de chaves Você deve especificar um par de chaves ao executar uma instância do EC2 e, em seguida, especificar a chave privada do par de chaves ao se conectar à instância. É possível criar um par de chaves ou usar um par de chaves existente que você usou ao iniciar outras instâncias. Para obter mais informações, consulte [Pares de chaves do Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) no Guia do Usuário do Amazon EC2 para instâncias do Linux. 1. Crie e inicialize uma instância [CreateKeyPairRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateKeyPairRequest.html). Use o método [withKeyName](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateKeyPairRequest.html#withKeyName-java.lang.String-) para definir o nome do par de chaves da seguinte maneira: ``` CreateKeyPairRequest createKeyPairRequest = new CreateKeyPairRequest(); createKeyPairRequest.withKeyName(keyName); ``` **Importante** Os nomes do par de chaves devem ser exclusivos. Se tentar criar um par de chaves com o mesmo nome de chave como um par de chaves existente, você receberá uma exceção. 1. Passe o objeto de requisição para o método [createKeyPair](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/AmazonEC2.html#createKeyPair-com.amazonaws.services.ec2.model.CreateKeyPairRequest--). O método retorna uma instância [CreateKeyPairResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateKeyPairResult.html) da seguinte maneira: ``` CreateKeyPairResult createKeyPairResult = amazonEC2Client.createKeyPair(createKeyPairRequest); ``` 1. Chame o método [getKeyPair](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateKeyPairResult.html#getKeyPair--) do objeto resultante para obter um objeto [KeyPair](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/KeyPair.html). Chame o método [getKeyMaterial](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/KeyPair.html#getKeyMaterial--) do objeto `KeyPair` para obter a chave privada codificada por PEM da seguinte maneira: ``` KeyPair keyPair = new KeyPair(); keyPair = createKeyPairResult.getKeyPair(); String privateKey = keyPair.getKeyMaterial(); ``` # Executar uma instância do Amazon EC2 Use o procedimento a seguir para executar uma ou mais instâncias do EC2 configuradas de maneira idêntica na mesma Amazon Machine Image (AMI – Imagem de máquina da Amazon). Depois de criar as instâncias do EC2, você poderá verificar o status. Depois que as instâncias do EC2 estiverem em execução, você poderá se conectar a elas. 1. Crie e inicialize uma instância de [RunInstancesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RunInstancesRequest.html). Verifique se a AMI, o par de chaves e o security group especificados por você existem na região especificada quando criou o objeto de cliente. ``` 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-) + O ID da AMI. Para saber como encontrar AMIs públicas fornecidas pela Amazon ou criar sua própria, consulte [Imagem de máquina da Amazon (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-) + Um tipo de instância compatível com a AMI especificada. Para obter mais informações, consulte [Tipos de instância](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html) no Guia do usuário do Amazon EC2 para instâncias do Linux. [withMinCount](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RunInstancesRequest.html#withMinCount-java.lang.Integer-) + O número mínimo de instâncias do EC2 a serem executadas. Se isso for mais instâncias do que o Amazon EC2 pode executar na zona de disponibilidade de destino, o Amazon EC2 não executará nenhuma instância. [withMaxCount](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RunInstancesRequest.html#withMaxCount-java.lang.Integer-) + O número máximo de instâncias do EC2 a serem executadas. Se isso for mais instâncias do que o Amazon EC2 pode executar na zona de disponibilidade de destino, o Amazon EC2 executará o maior número possível de instâncias acima de `MinCount`. É possível executar entre 1 e o número máximo de instâncias às quais você tem permissão para o tipo de instância. Para obter mais informações, consulte Quantas instâncias posso executar no Amazon EC2 nas perguntas frequentes do Amazon EC2. [withKeyName](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RunInstancesRequest.html#withKeyName-java.lang.String-) + O nome do par de chaves do EC2. Se você iniciar uma instância sem especificar um par de chaves, não poderá se conectar a ela. Para obter mais informações, consulte [Criar um par de chaves](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-) + Um ou mais security groups. Para obter mais informações, consulte [Criar um grupo de segurança do Amazon EC2](create-security-group.md). 1. Execute as instâncias passando o objeto de requisição para o método [runInstances](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/AmazonEC2Client.html#runInstances-com.amazonaws.services.ec2.model.RunInstancesRequest-). O método retorna um objeto [RunInstancesResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RunInstancesResult.html) da seguinte forma: ``` RunInstancesResult result = amazonEC2Client.runInstances( runInstancesRequest); ``` Depois que a instância estiver em execução, você poderá se conectar a ela usando o par de chaves. Para obter mais informações, consulte [Conectar-se à sua instância do Linux](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstances.html) no Guia do usuário do Amazon EC2 para instâncias do Linux. # Usar perfis do IAM para conceder acesso a recursos da AWS no Amazon EC2 Todas as solicitações à Amazon Web Services (AWS) devem ser assinadas criptograficamente usando as credenciais emitidas pela AWS. Você pode usar *perfis do IAM* para conceder acesso seguro de maneira prática a recursos da AWS a partir das instâncias do Amazon EC2. Este tópico fornece informações sobre como usar os perfis do IAM com aplicativos do Java SDK em execução no Amazon EC2. Para obter mais informações sobre instâncias do IAM, consulte [Perfis do IAM para Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) no Guia do usuário do Amazon EC2 para instâncias do Linux. ## A cadeia de fornecedores padrão e os perfis de instância do EC2 Se o aplicativo criar um cliente da AWS usando o construtor padrão, o cliente vai procurar credenciais usando a *cadeia de fornecedores de credenciais padrão*, na seguinte ordem: 1. Nas propriedades do sistema Java: `aws.accessKeyId` e `aws.secretKey`. 1. Em variáveis de ambiente do sistema: `AWS_ACCESS_KEY_ID` e `AWS_SECRET_ACCESS_KEY`. 1. No arquivo de credenciais padrão (o local desse arquivo varia de acordo com a plataforma). 1. Credenciais entregues por meio do serviço de contêiner do Amazon EC2 se a variável de ambiente `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` estiver definida e o gerente de segurança tiver permissão para acessar a variável. 1. Nas *credenciais de perfil de instância*, que existem dentro dos metadados da instância associados ao perfil do IAM para a instância do EC2. 1. Credenciais do token de identidade da web do ambiente ou contêiner. A etapa *credenciais de perfil de instância* na cadeia de fornecedores padrão está disponível somente durante a execução do aplicativo em uma instância do Amazon EC2, mas proporciona a maior facilidade de uso e a melhor segurança durante o trabalho com instâncias do Amazon EC2. Você também pode passar uma instância [InstanceProfileCredentialsProvider](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/InstanceProfileCredentialsProvider.html) diretamente para o construtor cliente para obter as credenciais do perfil de instância sem avançar em toda a cadeia de fornecedores padrão. Por exemplo: ``` AmazonS3 s3 = AmazonS3ClientBuilder.standard() .withCredentials(new InstanceProfileCredentialsProvider(false)) .build(); ``` Usando essa abordagem, o SDK recupera credenciais da AWS temporárias que tenham as mesmas permissões das associadas ao perfil do IAM ligada à instância do Amazon EC2 no perfil de instância. Embora essas credenciais sejam temporárias e acabem expirando, o `InstanceProfileCredentialsProvider` as atualiza periodicamente para você, de maneira que as credenciais obtidas continuem permitindo o acesso à AWS. **Importante** A atualização de credenciais automática acontece *somente* quando você usa o construtor de cliente padrão, que cria o próprio `InstanceProfileCredentialsProvider` como parte da cadeia de fornecedores padrão, ou quando passa uma instância `InstanceProfileCredentialsProvider` diretamente para o construtor de cliente. Se usar outro método para obter ou passar credenciais de perfil de instância, você será responsável por verificar e atualizar as credenciais expiradas. Se não conseguir encontrar credenciais usando a cadeia de fornecedores de credenciais, o construtor de cliente lançará um [AmazonClientException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/AmazonClientException.html). ## Demonstração: usar funções do IAM em instâncias do EC2 A demonstração a seguir mostra como recuperar um objeto do Amazon S3 usando um perfil do IAM para gerenciar acesso. ### Criar um perfil do IAM Crie um perfil do IAM que conceda acesso somente leitura ao Amazon S3. 1. Abra o [console do IAM](https://console.aws.amazon.com/iam/home). 1. No painel de navegação, selecione **Roles** e **Create New Role**. 1. Insira um nome para a função e selecione **Next Step (Próxima etapa)**. Lembre-se desse nome, porque será necessário quando você executar a instância do Amazon EC2. 1. Na página **Selecionar tipo de função**, em **Funções do AWS service (Serviço da AWS)**, selecione **Amazon EC2**. 1. Na página **Definir permissões**, em **Selecionar modelo de política**, selecione **Acesso somente leitura do Amazon S3** e, em seguida, **Próxima etapa**. 1. Na página **Review**, selecione **Create Role**. ### Iniciar uma instância do EC2 e especificar o perfil do IAM Você pode iniciar uma instância do Amazon EC2 com um perfil do IAM usando o console do Amazon EC2 ou o AWS SDK para Java. + Para ativar uma instância do Amazon EC2 usando o console, siga as orientações em [Conceitos básicos das instâncias do Linux do Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html) no Guia do usuário do Amazon EC2 para instâncias do Linux. Quando você chegar à página **Review Instance Launch (Revisar ativação da instância)**, selecione **Edit instance details (Editar detalhes da instância)**. Em **Perfil do IAM**, escolha o perfil do IAM criado por você anteriormente. Conclua o procedimento conforme indicado. **nota** Será necessário criar ou usar um grupo de segurança existente e um par de chaves para se conectar à instância. + Para iniciar uma instância do Amazon EC2 com um perfil do IAM usando o AWS SDK para Java, consulte [Executar uma instância do Amazon EC2](run-instance.md). ### Criar o aplicativo Vamos criar o aplicativo de exemplo a ser executado na instância do EC2. Primeiro, crie um diretório que você possa usar para manter os arquivos de tutorial (por exemplo, `GetS3ObjectApp`). Em seguida, copie as bibliotecas do AWS SDK para Java no diretório recém-criado. Se tiver obtido por download o AWS SDK para Java para o diretório `~/Downloads`, você poderá copiá-lo usando os seguintes comandos: ``` cp -r ~/Downloads/aws-java-sdk-{1.7.5}/lib . cp -r ~/Downloads/aws-java-sdk-{1.7.5}/third-party . ``` Abra um novo arquivo, chame-o de `GetS3Object.java` e adicione o seguinte código: ``` 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(); } } ``` Abra um novo arquivo, chame-o de `build.xml` e adicione as seguintes linhas: ``` ``` Compile e execute o programa modificado. Não há credenciais armazenadas no programa. Por isso, a menos que você tenha as credenciais da AWS já especificadas, o código lançará `AmazonServiceException`. Por exemplo: ``` $ 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 ``` ### Transferir o programa compilado para a instância do EC2 Transfira o programa para a instância do Amazon EC2 usando uma cópia segura (** `` **), com as bibliotecas do AWS SDK para Java. A sequência de comandos é semelhante à sequência a seguir. ``` 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 ``` **nota** Dependendo da distribuição do Linux usada por você, o *nome de usuário* pode ser "ec2-user", "root" ou "ubuntu". Para obter o nome DNS público da instância, abra o [console do EC2](https://console.aws.amazon.com/ec2/home) e procure o valor **Public DNS (DNS público)** na guia **Description (Descrição)** (por exemplo, `ec2-198-51-100-1.compute-1.amazonaws.com`). Nos comandos anteriores: + `GetS3Object.class` é o programa compilado + `build.xml` é o arquivo ant usado para compilar e executar o programa + os diretórios `lib` e `third-party` são as pastas da biblioteca correspondente do AWS SDK para Java. + A opção `-r` indica que `scp` deve fazer uma cópia recursiva de todo o conteúdo dos diretórios `library` e `third-party` na distribuição do AWS SDK para Java. + A opção `-p` indica que `scp` deverá preservar as permissões dos arquivos de código-fonte quando copiá-los para o destino. **nota** A opção `-p` funciona somente no Linux, macOS ou Unix. Se estiver copiando arquivos do Windows, você precisará corrigir as permissões de arquivo na instância usando o seguinte comando: ``` chmod -R u+rwx GetS3Object.class build.xml lib third-party ``` ### Executar o programa de exemplo na instância do EC2 Para executar o programa, conecte-se à instância do Amazon EC2. Para obter mais informações, consulte [Conectar-se à sua instância do Linux](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstances.html) no Guia do usuário do Amazon EC2 para instâncias do Linux. Se ** ` ant ` ** não estiver disponível na instância, instale-o usando o seguinte comando: ``` sudo yum install ant ``` Em seguida, execute o programa usando `ant` da seguinte maneira: ``` ant run ``` O programa gravará o conteúdo do objeto do Amazon S3 na janela de comando. # Tutorial: instâncias spot do Amazon EC2 ## Visão geral As instâncias spot permitem que você faça ofertas pela capacidade não utilizada do Amazon Elastic Compute Cloud (Amazon EC2) em até 90% com relação ao preço de instância sob demanda e execute as instâncias adquiridas desde que seu lance exceda o *Preço spot* atual. O Amazon EC2 altera o preço spot periodicamente com base na oferta e na demanda e os clientes cujos lances alcancem ou excedam o preço ganham acesso às instâncias spot disponíveis. Assim como instâncias sob demanda e instâncias reservadas, as instâncias spot são outra opção para obter mais capacidade computacional. As instâncias spot podem reduzir significativamente os custos do Amazon EC2 para processamento em lote, pesquisa científica, processamento de imagens, codificação de vídeos, crawling de dados e web, análise financeira e testes. Além disso, as instâncias spot dão acesso a grandes quantidades de capacidade adicional em situações nas quais a necessidade dessa capacidade não é urgente. Para usar instâncias spot, faça uma solicitação de instância spot especificando o preço máximo que você está disposto a pagar por hora de instância; esse é seu lance. Se seu lance exceder o preço spot atual, sua solicitação será cumprida e as instâncias serão executadas até que você opte por encerrá-las ou até que o preço spot exceda seu lance (o que ocorrer primeiro). É importante observar: + Você frequentemente pagará menos por hora que seu lance. O Amazon EC2 ajusta o preço spot periodicamente, à medida que as requisições entram e a oferta disponível se altera. Todos pagam o mesmo preço spot por esse período, independente de o lance ter sido maior. Portanto, você pode pagar menos que seu lance, mas jamais pagará mais. + Se você estiver executando instâncias spot e o seu lance não atender mais ou ultrapassar o preço spot atual, suas instâncias serão encerradas. Isto significa que você precisará se certificar de que as suas cargas de trabalho e aplicativos sejam suficientemente flexíveis para se beneficiarem desta capacidade oportunista. As instâncias spot funcionam exatamente como outras instâncias do Amazon EC2 durante a execução e, como outras instâncias do Amazon EC2, as instâncias spot poderão ser encerradas quando não forem mais necessárias. Se você finalizar sua instância, pagará por qualquer hora parcial usada (como para instâncias sob demanda ou reservadas). Entretanto, se o preço spot for além do lance e a instância for encerrada pelo Amazon EC2, você não será cobrado em relação a qualquer hora parcial de uso. Este tutorial mostra como usar o AWS SDK para Java para fazer o seguinte. + Enviar uma requisição spot + Determinar quando a requisição spot é atendida + Cancelar a requisição spot + Encerrar as instâncias associadas ## Pré-requisitos Para usar este tutorial, você deve ter o AWS SDK para Java instalado, bem como ter atendido aos pré-requisitos de instalação básicos. Consulte [Configurar o AWS SDK para Java](setup-install.md) para obter mais informações. ## Etapa 1: configurar as credenciais Para começar a usar esse exemplo de código, é preciso configurar credenciais da AWS. Consulte [Configurar credenciais e a região da AWS para desenvolvimento](setup-credentials.md) para obter instruções sobre como fazer isso. **nota** Recomendamos usar as credenciais de um usuário do IAM para fornecer esses valores. Para obter mais informações, consulte [Cadastrar-se na AWS e criar um usuário do IAM](signup-create-iam-user.md). Agora que definiu as configurações, você pode começar a usar o código no exemplo. ## Etapa 2: configurar um security group Um *security group* funciona como um firewall que controla o tráfego permitido de entrada e saída de um grupo de instâncias. Por padrão, uma instância é iniciada sem nenhum security group, o que significa que todo o tráfego IP recebido, em qualquer porta TCP, será negado. Por isso, antes de enviar a requisição spot, vamos configurar um security group que permite o tráfego de rede necessário. Para os fins deste tutorial, criaremos um novo security group chamado "GettingStarted" que permite o tráfego Secure Shell (SSH) do endereço IP em que está executando o aplicativo. Para configurar um novo security group, você precisa incluir ou executar o exemplo de código a seguir que configura o security group de maneira programática. Depois que criarmos um objeto de cliente `AmazonEC2`, criaremos um objeto `CreateSecurityGroupRequest` com o nome, "GettingStarted", e uma descrição do security group. Em seguida, chamaremos a API `ec2.createSecurityGroup` para criar o grupo. Para permitir acesso ao grupo, criaremos um objeto `ipPermission` com o intervalo de endereços IP definido como a representação CIDR da sub-rede para o computador local; o sufixo "/10" no endereço IP indica a sub-rede do endereço IP especificado. Também configuramos o objeto `ipPermission` com o protocolo TCP e a porta 22 (SSH). A etapa final é chamar `ec2.authorizeSecurityGroupIngress` com o nome do security group e o objeto `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()); } ``` Você precisa somente executar esse aplicativo uma vez para criar um novo security group. Você também pode criar o security group usando o AWS Toolkit for Eclipse. Consulte [Gerenciar grupos de segurança do AWS Cost Explorer](https://docs.aws.amazon.com/toolkit-for-eclipse/v1/user-guide/tke-sg.html) para obter mais informações. ## Etapa 3: enviar a requisição spot Para enviar uma requisição spot, é preciso primeiro determinar o tipo de instância, a imagem de máquina da Amazon (AMI) e o preço máximo do lance que você deseja usar. Você também deve incluir o security group que configuramos anteriormente, de maneira que possa fazer logon na instância, se desejado. Há vários tipos de instância a escolher; acesse Tipos de instância do Amazon EC2 para ver a lista completa. Para este tutorial, usaremos t1.micro, o tipo de instância mais barata disponível. Em seguida, determinaremos o tipo de AMI que gostaríamos de usar. Usaremos ami-a9d09ed1, a AMI do Amazon Linux mais atualizada disponível quando elaboramos este tutorial. A AMI mais recente pode mudar ao longo do tempo, mas você pode sempre determinar a AMI da versão mais recente seguindo estas etapas: 1. Abra o [console de Amazon EC2](https://console.aws.amazon.com/ec2/home). 1. Selecione o botão **Launch Instance (Iniciar instância)**. 1. A primeira janela exibe as AMIs disponíveis. O ID da AMI é exibido ao lado de cada título de AMI. Você também pode usar a API `DescribeImages`, mas aproveitar esse comando está fora do escopo deste tutorial. Existem muitas maneiras de abordar lances para instâncias spot. Para obter uma visão geral ampla das diversas abordagens, assista ao vídeo [Bidding for Spot Instances](https://www.youtube.com/watch?v=WD9N73F3Fao&feature=player_embedded). No entanto, para começar, descreveremos três estratégias comuns: lance para garantir que o custo seja menor que a definição de preço sob demanda, lance baseado no valor do cálculo resultante e lance para adquirir capacidade computacional o mais rápido possível. + *Reduzir custo abaixo da demanda* Você tem um job de processamento em lote que modera determinado número de horas ou dias para ser executado. Contudo, você tem flexibilidade em relação ao início e ao fim quando terminar. Você quer ver se pode o concluído por um custo inferior ao das instâncias sob demanda. Você examina o histórico de preços spot para tipos de instância usando o Console de gerenciamento da AWS ou a API do Amazon EC2. Para obter mais informações, acesse [Exibir histórico de preços spot](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-spot-instances-history.html). Depois de analisar o histórico de preços do tipo de instância desejado em determinada zona de disponibilidade, há duas abordagens alternativas para seu lance: + Você pode oferecer um lance na extremidade superior do intervalo de preços spot (que ainda estão abaixo do preço sob demanda), prevendo que sua solicitação spot única provavelmente seria cumprida e executada pelo tempo de computação consecutivo suficiente para concluir o trabalho. + Ou você pode especificar o valor que está disposto a pagar pelas instâncias spot como uma porcentagem do preço das instâncias sob demanda e planejar combinar muitas instâncias executadas ao longo do tempo por meio de uma requisição persistente. Se o preço especificado for excedido, a instância spot será encerrada. (Explicaremos como automatizar essa tarefa ainda neste tutorial.) + *Não pagar a mais pelo valor do resultado* Você tem um trabalho de processamento de dados a ser executado. Você entende o valor dos resultados do trabalho bem o suficiente para saber o quanto valem em termos de custos computacionais. Após analisar o histórico de preços spot para seu tipo de instância, escolha o preço de lance no qual o custo do tempo computacional não é mais que o valor dos resultados do trabalho. Você cria um lance persistente e o deixa ser executado de forma intermitente, à medida que o preço spot flutua acima ou abaixo do seu lance. + *Adquirir capacidade computacional rapidamente* Você tem a necessidade imprevista e de curto prazo por capacidade adicional indisponível pelas instâncias sob demanda. Depois de analisar o histórico de preços spot para seu tipo de instância, faça um lance acima do preço histórico mais alto para indicar uma maior probabilidade de sua solicitação ser atendida com rapidez e continuar a computação até a conclusão. Depois de escolher o preço do lance, você já estará pronto para solicitar uma instância spot. Para os fins deste tutorial, daremos uma sugestão de preço sob demanda (USD 0,03) para maximizar as chances de o lance ser cumprido. Você pode determinar os tipos de instâncias disponíveis e os preços sob demanda para instâncias indo à página de definição de preços do Amazon EC2. Enquanto as instâncias spot estão em execução, você paga o preço spot em vigor pelo período da execução das instâncias. Os preços de instância spot são definidos pelo Amazon EC2 e são ajustados gradualmente de acordo com tendências de longo prazo da oferta e da demanda pela capacidade de instâncias spot. Também é possível especificar o valor que você está disposto a pagar por uma instância spot como uma porcentagem do preço de instância sob demanda. Para solicitar uma instância spot, basta criar sua requisição com os parâmetros escolhidos anteriormente. Começamos criando um objeto `RequestSpotInstanceRequest`. O objeto de solicitação exige o número de instâncias que você deseja para começar e o preço do lance. Além disso, você precisa definir o `LaunchSpecification` para a solicitação, que inclui o tipo de instância, o ID do AMI e o security group que deseja usar. Depois que a solicitação for preenchida, você chamará o método `requestSpotInstances` no objeto `AmazonEC2Client`. O exemplo a seguir mostra como solicitar uma instância 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); ``` Executar esse código iniciará uma nova solicitação de instância spot. Há outras opções que você pode usar para configurar suas solicitações spot. Para saber mais, visite [Tutorial: gerenciamento de requisições spot do Amazon EC2 avançado](tutorial-spot-adv-java.md) ou a classe [RequestSpotInstances](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RequestSpotInstancesRequest.html) na Referência de API do AWS SDK para Java. **nota** Você será cobrado por todas as instâncias spot que forem efetivamente iniciadas, por isso cancele as solicitações e encerre todas as instâncias que iniciar para reduzir os encargos associados. ## Etapa 4: determinar o estado da solicitação spot Em seguida, queremos criar um código para esperar até que a solicitação spot alcance o estado "ativo" antes de continuar para a última etapa. Para determinar o estado da solicitação spot, faremos uma sondagem do método [describeSpotInstanceRequests](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/AmazonEC2Client.html#describeSpotInstanceRequests) para obter o estado do ID da solicitação spot que queremos monitorar. O ID da solicitação criado na Etapa 2 é integrado na resposta à solicitação `requestSpotInstances`. O código de exemplo a seguir mostra como coletar IDs de solicitação da resposta `requestSpotInstances` e usá-los para preencher um `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()); } ``` Para monitorar o ID da solicitação, chame o método `describeSpotInstanceRequests` para determinar o estado da solicitação. Em seguida, mantenha em loop até que a solicitação não esteja no estado "aberto". Monitoramos um estado de não "aberto", em vez de um estado de, digamos, "ativo", porque a solicitação poderá ir diretamente para "fechado" se houver um problema com os argumentos da solicitação. O código de exemplo a seguir apresenta os detalhes de como realizar essa tarefa. ``` // 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); ``` Depois de executar esse código, a solicitação da instância spot terá sido concluída ou falhado com um erro que será produzido para a tela. Em ambos os casos, podemos avançar à próxima etapa para limpar todas as solicitações ativas e encerrar as instâncias em execução. ## Etapa 5: limpar as solicitações spot e instâncias Por fim, precisamos limpar as solicitações e as instâncias. É importante cancelar todas as solicitações pendentes *e* encerrar as instâncias. Simplesmente cancelar as solicitações não encerrará as instâncias, o que significa que você continuará pagando por elas. Se você encerrar suas instâncias, suas solicitações spot poderão ser canceladas, mas há algumas situações, como se você usar lances persistentes, nas quais encerrar suas instâncias não basta para impedir que a solicitação seja cumprida novamente. Portanto, é uma prática recomendada cancelar todos os lances ativos e encerrar as usar instâncias em execução. O código a seguir demonstra como cancelar as solicitações. ``` 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()); } ``` Para encerrar todas as instâncias pendentes, você precisará do ID da instância associada à solicitação que as iniciou. O exemplo de código a seguir utiliza o código original para monitorar as instâncias e adiciona um `ArrayList` no qual armazenamos o ID da instância associado à resposta `describeInstance`. ``` // 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); ``` Usando os IDs de instância, armazenados no `ArrayList`, encerre todas as instâncias em execução usando o trecho de código a seguir. ``` 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()); } ``` ## Resumir Para resumir, fornecemos uma abordagem mais orientada ao objeto que integra as etapas anteriores que mostramos: inicializar o EC2 Client, enviar a solicitação spot, determinar quando as solicitações spot não estão mais no estado aberto e limpar eventuais solicitações spot e instâncias associadas. Criamos uma classe chamada `Requests` que realiza essas ações. Também criamos uma classe `GettingStartedApp`, que tem um método principal em que realizamos as chamadas à função de alto nível. Mais especificamente, inicializaremos o objeto `Requests` descrito anteriormente. Enviaremos a solicitação da instância spot. Em seguida, aguarde a solicitação spot chegar ao estado "ativo". Por fim, limpamos as solicitações e as instâncias. O código-fonte completo desse exemplo pode ser visualizado ou obtido por download no [GitHub](https://github.com/aws/aws-sdk-java/tree/master/src/samples/AmazonEC2SpotInstances-GettingStarted). Parabéns\$1 Você acabou de concluir o tutorial de conceitos básicos para desenvolver software de instância spot com o AWS SDK para Java. ## Próximas etapas Avance para [Tutorial: gerenciamento de solicitações spot do Amazon EC2 avançado](tutorial-spot-adv-java.md). # Tutorial: gerenciamento de requisições spot do Amazon EC2 avançado Instâncias spot do Amazon EC2 permitem que você ofereça a capacidade não utilizada do Amazon EC2 e execute essas instâncias desde que a oferta ultrapasse o *preço spot* atual. O Amazon EC2 altera o preço spot periodicamente com base na oferta e na demanda. Para obter mais informações sobre instâncias spot, consulte [Instâncias spot](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-spot-instances.html) no Guia do usuário do Amazon EC2 para instâncias do Linux. ## Pré-requisitos Para usar este tutorial, você deve ter o AWS SDK para Java instalado, bem como ter atendido aos pré-requisitos de instalação básicos. Consulte [Configurar o AWS SDK para Java](setup-install.md) para obter mais informações. ## Configurar as credenciais Para começar a usar esse exemplo de código, é preciso configurar credenciais da AWS. Consulte [Configurar credenciais e a região da AWS para desenvolvimento](setup-credentials.md) para obter instruções sobre como fazer isso. **nota** Recomendamos usar as credenciais de um usuário do IAM para fornecer esses valores. Para obter mais informações, consulte [Cadastrar-se na AWS e criar um usuário do IAM](signup-create-iam-user.md). Agora que definiu as configurações, você pode começar a usar o código no exemplo. ## Configurar um security group Um security group funciona como um firewall que controla o tráfego permitido de entrada e saída de um grupo de instâncias. Por padrão, uma instância é iniciada sem nenhum security group, o que significa que todo o tráfego IP recebido, em qualquer porta TCP, será negado. Por isso, antes de enviar a requisição spot, vamos configurar um security group que permite o tráfego de rede necessário. Para os fins deste tutorial, criaremos um novo security group chamado "GettingStarted" que permite o tráfego Secure Shell (SSH) do endereço IP em que está executando o aplicativo. Para configurar um novo security group, você precisa incluir ou executar o exemplo de código a seguir que configura o security group de maneira programática. Depois que criarmos um objeto de cliente `AmazonEC2`, criaremos um objeto `CreateSecurityGroupRequest` com o nome, "GettingStarted", e uma descrição do security group. Em seguida, chamaremos a API `ec2.createSecurityGroup` para criar o grupo. Para permitir acesso ao grupo, criaremos um objeto `ipPermission` com o intervalo de endereços IP definido como a representação CIDR da sub-rede para o computador local; o sufixo "/10" no endereço IP indica a sub-rede do endereço IP especificado. Também configuramos o objeto `ipPermission` com o protocolo TCP e a porta 22 (SSH). A etapa final é chamar `ec2 .authorizeSecurityGroupIngress` com o nome do security group e o objeto `ipPermission`. (O código a seguir é o mesmo que usamos no primeiro tutorial.) ``` // 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()); } ``` Você pode visualizar todo esse exemplo de código em `advanced.CreateSecurityGroupApp.java`. Você precisa somente executar esse aplicativo uma vez para criar um novo security group. **nota** Você também pode criar o security group usando o AWS Toolkit for Eclipse. Consulte [Gerenciar grupos de segurança do AWS Cost Explorer](https://docs.aws.amazon.com/toolkit-for-eclipse/v1/user-guide/tke-sg.html) no Guia do usuário do AWS Toolkit for Eclipse para obter mais informações. ## Opções de criação da requisição da instância spot detalhadas Como explicamos no [Tutorial: instâncias spot do Amazon EC2](tutorial-spot-instances-java.md), você precisa compilar a requisição com um tipo de instância, uma Imagem de máquina da Amazon (AMI) e um preço de sugestão de preço máximo. Vamos começar criando um objeto `RequestSpotInstanceRequest`. O objeto de requisição exige o número de instâncias que você deseja e o preço da sugestão. Além disso, precisamos definir o `LaunchSpecification` da requisição, que inclui o tipo de instância, o ID de AMI e o security group que você deseja usar. Depois que a requisição for preenchida, chamaremos o método `requestSpotInstances` no objeto `AmazonEC2Client`. Veja a seguir um exemplo de como solicitar uma instância spot. (O código a seguir é o mesmo que usamos no primeiro tutorial.) ``` // 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); ``` ## Requisições persistentes x ocasionais Ao compilar uma requisição spot, você pode especificar diversos parâmetros opcionais. O primeiro é se a requisição é somente ocasional ou persistente. Por padrão, trata-se de uma requisição ocasional. A requisição ocasional pode ser atendida somente uma vez e, depois que as instâncias solicitadas forem encerradas, a requisição será fechada. Uma requisição persistente é considerada para o cumprimento sempre que não há instância spot em execução para a mesma requisição. Para especificar o tipo de requisição, basta definir o tipo na requisição spot. Isso pode ser feito com o código a seguir. ``` // 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); ``` ## Limitar a duração de uma requisição Você também pode especificar o tempo em que a requisição permanecerá válida. Você pode especificar horários de início e término para esse período. Por padrão, uma requisição spot será considerada para o cumprimento a partir do momento em que é criada até ser atendida ou cancelada por você. No entanto, você poderá restringir o período de validade, se precisar. Um exemplo de como especificar esse período é mostrado no código a seguir. ``` // 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); ``` ## Agrupar as requisições de instância spot do Amazon EC2 Você tem a opção de agrupar as requisições de instância spot de diversas maneiras diferentes. Veremos os benefícios de usar grupos de inicialização, grupos de zonas de disponibilidade e grupos de colocações. Se quiser garantir que as instâncias spot sejam todas executadas e encerradas juntas, você terá a opção de aproveitar um grupo de inicialização. Grupo de inicialização é um rótulo que agrupa um conjunto de sugestões de preço. Todas as instâncias em um grupo de execução são iniciadas e encerradas juntas. Se instâncias em um grupo de inicialização já tiverem sido atendidas, não haverá garantia de que novas instâncias executadas com o mesmo grupo de inicialização também serão atendidas. Um exemplo de como definir um grupo de inicialização é mostrado no exemplo de código a seguir. ``` // 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); ``` Se quiser garantir que todas as instâncias dentro de uma solicitação sejam iniciadas na mesma zona de disponibilidade e não se preocupar com qual delas, será possível aproveitar os grupos de zonas de disponibilidade. Grupo de zonas de disponibilidade é um rótulo que agrupa um conjunto de instâncias na mesma zona de disponibilidade. Todas as instâncias que compartilham um grupo de zonas de disponibilidade e são atendidas simultaneamente começarão na mesma zona de disponibilidade. Um exemplo de como definir um grupo de zonas de disponibilidade está a seguir. ``` // 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); ``` Você pode especificar uma zona de disponibilidade desejada para as instâncias spot. O código de exemplo a seguir mostra como definir uma zona de disponibilidade. ``` // 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); ``` Por fim, será possível especificar um *grupo de colocações* se estiver usando instâncias spot High Performance Computing (HPC – Computação de Alto Desempenho), como instâncias de computação em cluster ou de GPU de cluster. Os grupos de colocações oferecem latência mais baixa e alta conectividade de largura de banda entre as instâncias. Um exemplo de como definir um grupo de colocações está a seguir. ``` // 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); ``` Todos os parâmetros mostrados nesta seção são opcionais. Também é importante perceber que a maioria desses parâmetros (com exceção da sugestão de preço ser ocasional ou persistente) pode reduzir a probabilidade de cumprimento da sugestão de preço. Por isso, será importante aproveitar essas opções somente se você precisar delas. Todos os exemplos de código anteriores são integrados a um exemplo longo, que pode ser encontrado na classe `com.amazonaws.codesamples.advanced.InlineGettingStartedCodeSampleApp.java`. ## Como manter uma partição raiz após a interrupção ou o encerramento Uma das maneiras mais fáceis de gerenciar a interrupção das instâncias spot é garantir que os dados sejam verificados em um volume do Amazon Elastic Block Store (Amazon Amazon EBS) em um ritmo regular. Verificando periodicamente, se houver uma interrupção, você perderá somente os dados criados desde o ponto de verificação mais recente (pressupondo-se que não haja outras ações não idempotentes realizadas entre essas duas situações). Para facilitar ainda mais esse processo, você pode configurar a requisição spot para garantir que a partição raiz não seja excluída na interrupção ou no encerramento. Inserimos um novo código no exemplo a seguir que mostra como habilitar esse cenário. No código adicionado, criamos um objeto `BlockDeviceMapping` e definimos o Amazon Elastic Block Store (Amazon EBS) associado como um objeto Amazon EBS que configuramos como `not` caso a instância spot seja encerrada. Em seguida, adicionaremos o `BlockDeviceMapping` a ArrayList de mapeamentos que incluímos na especificação de inicialização. ``` // 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); ``` Pressupondo-se que queira reanexar esse volume à instância na inicialização, você também pode usar as configurações de mapeamento de dispositivos de blocos. Como alternativa, se você tiver anexado uma partição não raiz, será possível especificar os volumes do Amazon Amazon EBS que queira anexar à instância spot após o reinício. Você pode fazer isso simplesmente especificando um ID de snapshot no `EbsBlockDevice` e um nome de dispositivo alternativo nos objetos `BlockDeviceMapping`. Utilizando-se mapeamentos de dispositivos de blocos, pode ser mais fácil inicializar a instância. Usar a partição raiz no ponto de verificação dos dados críticos é uma ótima maneira de gerenciar o potencial de interrupção das instâncias. Para obter mais métodos para gerenciar o potencial de interrupção, assista ao vídeo [Gerenciar interrupções](https://www.youtube.com/watch?feature=player_embedded&v=wcPNnUo60pc). ## Como marcar as requisições spot e as instâncias Adicionar tags a recursos do Amazon EC2 pode simplificar a administração da infraestrutura em nuvem. Uma forma de metadados, as tags podem ser usadas para criar nomes amigáveis ao usuário, aprimorar a capacidade de pesquisa e melhorar a coordenação entre vários usuários. Você também pode usar tags para automatizar scripts e partes dos processos. Para ler mais sobre como marcar recursos do Amazon EC2, acesse [Usar tags](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html) no Guia do usuário do Amazon EC2 para instâncias do Linux. ### Marcar requisições Para adicionar tags às requisições spot, você precisará marcá-las *depois* que tiverem sido solicitadas. O valor de retorno de `requestSpotInstances()` fornece um objeto [RequestSpotInstancesResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RequestSpotInstancesResult.html) que você pode usar para obter os IDs de requisição spot para marcar: ``` // 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()); } ``` Assim que você tiver os IDs, será possível marcar as solicitações adicionando os IDs a um [CreateTagsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateTagsRequest.html) e chamando o método `createTags()` do cliente do Amazon EC2: ``` // 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()); } ``` ### Marcar instâncias De maneira semelhante a requisições spot, você poderá marcar somente uma instância depois que ela tiver sido criada, o que acontecerá assim que a requisição spot tiver sido atendida (deixa de estar no estado *aberto*). É possível verificar o status das solicitações chamando o método `describeSpotInstanceRequests()` do cliente do Amazon EC2 com um objeto [DescribeSpotInstanceRequestsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeSpotInstanceRequestsRequest.html). O objeto [DescribeSpotInstanceRequestsResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeSpotInstanceRequestsResult.html) retornado contém uma lista de objetos [SpotInstanceRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/SpotInstanceRequest.html) que você pode usar para consultar o status das requisições spot e obter os IDs de instância assim que elas não estiverem mais no estado *aberto*. Assim que a requisição spot não estiver mais aberta, você poderá recuperar o ID de instância do objeto `SpotInstanceRequest` chamando o método `getInstanceId()`. ``` 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); ``` Você já pode marcar as instâncias retornadas: ``` // 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()); } ``` ## Cancelar requisições spot e encerrar instâncias ### Cancelar uma requisição spot Para cancelar uma requisição de instância spot, chame `cancelSpotInstanceRequests` no cliente do Amazon EC2 com um objeto [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()); } ``` ### Encerrar instâncias spot É possível encerrar todas as instâncias spot em execução passando os IDs para o método `terminateInstances()` do cliente do Amazon EC2. ``` 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()); } ``` ## Resumir Para resumir, fornecemos uma abordagem mais orientada a objeto que integra as etapas que mostramos neste tutorial em uma única classe fácil de usar. Instanciamos uma classe chamada `Requests` que realiza essas ações. Também criamos uma classe `GettingStartedApp`, que tem um método principal em que realizamos as chamadas à função de alto nível. O código-fonte completo desse exemplo pode ser visualizado ou obtido por download no [GitHub](https://github.com/aws/aws-sdk-java/tree/master/src/samples/AmazonEC2SpotInstances-Advanced). Parabéns\$1 Você concluiu o tutorial Recursos de solicitação avançados para desenvolver o software de instância spot com o AWS SDK para Java. # Gerenciar instâncias do Amazon EC2 ## Criar uma instância Crie uma instância do Amazon EC2 chamando o método `runInstances` do AmazonEC2Client, fornecendo um [RunInstancesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RunInstancesRequest.html) contendo a [imagem de máquina da Amazon (AMI)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) a ser usada e um [tipo de instância](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html). **Importações** ``` 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; ``` **Código da** ``` 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(); ``` Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/CreateInstance.java). ## Iniciar uma instância Para iniciar uma instância do Amazon EC2, chame o método `startInstances` do AmazonEC2Client, fornecendo um [StartInstancesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/StartInstancesRequest.html) contendo o ID da instância para iniciar. **Importações** ``` import com.amazonaws.services.ec2.AmazonEC2; import com.amazonaws.services.ec2.AmazonEC2ClientBuilder; import com.amazonaws.services.ec2.model.StartInstancesRequest; ``` **Código da** ``` final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient(); StartInstancesRequest request = new StartInstancesRequest() .withInstanceIds(instance_id); ec2.startInstances(request); ``` Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/StartStopInstance.java). ## Interromper uma instância Para interromper uma instância do Amazon EC2, chame o método `stopInstances` do AmazonEC2Client, fornecendo um [StopInstancesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/StopInstancesRequest.html) contendo o ID da instância para interromper. **Importações** ``` import com.amazonaws.services.ec2.AmazonEC2; import com.amazonaws.services.ec2.AmazonEC2ClientBuilder; import com.amazonaws.services.ec2.model.StopInstancesRequest; ``` **Código da** ``` final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient(); StopInstancesRequest request = new StopInstancesRequest() .withInstanceIds(instance_id); ec2.stopInstances(request); ``` Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/StartStopInstance.java). ## Como reinicializar uma instância Para reinicializar uma instância do Amazon EC2, chame o método `rebootInstances` do AmazonEC2Client, fornecendo um [RebootInstancesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/RebootInstancesRequest.html) contendo o ID da instância para reinicializar. **Importações** ``` 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; ``` **Código da** ``` final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient(); RebootInstancesRequest request = new RebootInstancesRequest() .withInstanceIds(instance_id); RebootInstancesResult response = ec2.rebootInstances(request); ``` Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/RebootInstance.java). ## Descrever instâncias Para listar as instâncias, crie um [DescribeInstancesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeInstancesRequest.html) e chame o método `describeInstances` do AmazonEC2Client. Isso retornará um objeto [DescribeInstancesResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeInstancesResult.html) que você pode usar para listar as instâncias do Amazon EC2 para a conta e a região. As instâncias são agrupadas por *reserva*. Cada reserva corresponde à chamada a `startInstances` que iniciou a instância. Para listar as instâncias, você deve primeiro chamar a classe `DescribeInstancesResult` `getReservations' method, and then call `getInstances` em cada objeto [Reservation](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/Reservation.html) retornado. **Importações** ``` 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; ``` **Código da** ``` 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; } } ``` Os resultados são paginados. É possível obter mais resultados passando o valor retornado do método `getNextToken` do objeto resultante para o método `setNextToken` do objeto de solicitação original e usando o mesmo objeto de solicitação na próxima chamada para `describeInstances`. Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DescribeInstances.java). ## Monitorar uma instância Você pode monitorar diversos aspectos das instâncias do Amazon EC2, como utilização de CPU e rede, memória disponível e espaço em disco restante. Para saber mais sobre monitoramento de instância, consulte [Monitoramento do Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/monitoring_ec2.html) no Guia do Usuário do Amazon EC2 para instâncias do Linux. Para iniciar o monitoramento de uma instância, você deve criar um [MonitorInstancesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/MonitorInstancesRequest.html) com o ID da instância para monitorar e passá-lo para o método `monitorInstances` do AmazonEC2Client. **Importações** ``` import com.amazonaws.services.ec2.AmazonEC2; import com.amazonaws.services.ec2.AmazonEC2ClientBuilder; import com.amazonaws.services.ec2.model.MonitorInstancesRequest; ``` **Código da** ``` final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient(); MonitorInstancesRequest request = new MonitorInstancesRequest() .withInstanceIds(instance_id); ec2.monitorInstances(request); ``` Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/MonitorInstance.java). ## Interromper monitoramento de instâncias Para interromper o monitoramento de uma instância, crie um [UnmonitorInstancesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/UnmonitorInstancesRequest.html) com o ID da instância para interromper o monitoramento e passá-lo para o método `unmonitorInstances` do AmazonEC2Client. **Importações** ``` import com.amazonaws.services.ec2.AmazonEC2; import com.amazonaws.services.ec2.AmazonEC2ClientBuilder; import com.amazonaws.services.ec2.model.UnmonitorInstancesRequest; ``` **Código da** ``` final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient(); UnmonitorInstancesRequest request = new UnmonitorInstancesRequest() .withInstanceIds(instance_id); ec2.unmonitorInstances(request); ``` Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/MonitorInstance.java). ## Mais informações + [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) na Referência de API do Amazon EC2 + [DescribeInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html) na Referência de API do Amazon EC2 + [StartInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_StartInstances.html) na Referência de API do Amazon EC2 + [StopInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_StopInstances.html) na Referência de API do Amazon EC2 + [RebootInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RebootInstances.html) na Referência de API do Amazon EC2 + [MonitorInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_MonitorInstances.html) na referência de API do Amazon EC2 + [UnmonitorInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_UnmonitorInstances.html) na referência de API do Amazon EC2 # Usar endereços IP elásticos no Amazon EC2 ## O EC2-Classic será descontinuado **Atenção** Estamos aposentando o EC2-Classic em 15 de agosto de 2022. É recomendável migrar do EC2-Classic para uma VPC. Consulte mais informações na publicação de blog [EC2-Classic Networking is Retiring – Here's How to Prepare](https://aws.amazon.com/blogs/aws/ec2-classic-is-retiring-heres-how-to-prepare/). ## Como alocar um endereço IP elástico Para usar um endereço IP elástico, você primeiro aloca um para sua conta e o associa à instância ou a uma interface de rede. Para alocar um endereço IP elástico, chame o método `allocateAddress` do AmazonEC2Client com um objeto [AllocateAddressRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AllocateAddressRequest.html) contendo o tipo de rede (EC2 ou VPC clássico). O [AllocateAddressResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AllocateAddressResult.html) retornado contém um ID de alocação que é possível usar para associar o endereço a uma instância, passando o ID de alocação e o ID de instância em um [AssociateAddressRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AssociateAddressRequest.html) para o método `associateAddress` do AmazonEC2Client. **Importações** ``` 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; ``` **Código da** ``` 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); ``` Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/AllocateAddress.java). ## Descrever endereços IP elásticos Para listar os endereços IP elásticos atribuídos à conta, chame o método `describeAddresses` do AmazonEC2Client. Ele retorna um [DescribeAddressesResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeAddressesResult.html) que você pode usar para obter uma lista de objetos [Address](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/Address.html) que representam os endereços IP elásticos na conta. **Importações** ``` 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; ``` **Código da** ``` 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()); } ``` Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DescribeAddresses.java). ## Como liberar um endereço IP elástico Para liberar um endereço IP elástico, chame o método `releaseAddress` do AmazonEC2Client, passando um [ReleaseAddressRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/ReleaseAddressRequest.html) contendo o ID de alocação do endereço IP elástico que você deseja liberar. **Importações** ``` 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; ``` **Código da** ``` final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient(); ReleaseAddressRequest request = new ReleaseAddressRequest() .withAllocationId(alloc_id); ReleaseAddressResult response = ec2.releaseAddress(request); ``` Depois que você liberar um endereço IP elástico, ele será liberado para o grupo de endereços IP da AWS e poderá estar indisponível em seguida. Não se esqueça de atualizar os registros DNS e todos os servidores ou dispositivos que se comunicam com o endereço. Se tentar liberar um endereço IP elástico já liberado, você receberá um erro *AuthFailure* se o endereço já estiver alocado para outra Conta da AWS. Se você estiver usando o *EC2-Classic* ou uma *VPC padrão*, liberar um endereço IP elástico o desassociará automaticamente de qualquer instância a qual esteja associada. Para desassociar um endereço IP elástico sem liberá-lo, use o método `disassociateAddress` do AmazonEC2Client. Se estiver usando uma VPC não padrão, você *deverá* usar `disassociateAddress` para desassociar o endereço IP elástico antes de tentar liberá-lo. Do contrário, o Amazon EC2 retornará um erro (*InvalidIPAddress.InUse*). Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/ReleaseAddress.java). ## Mais informações + [Endereços IP elásticos](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html) no Guia do Usuário do Amazon EC2 para instâncias Linux + [AllocateAddress](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_AllocateAddress.html) na Referência de API do Amazon EC2 + [DescribeAddresses](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeAddresses.html) na Referência de API do Amazon EC2 + [ReleaseAddress](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ReleaseAddress.html) na Referência de API do Amazon EC2 # Usar regiões e zonas de disponibilidade ## Descrever regiões Para listar as regiões disponíveis para a conta, chame o método `describeRegions` do AmazonEC2Client. Ele retorna um [DescribeRegionsResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeRegionsResult.html). Chame o método `getRegions` do objeto retornado para obter uma lista de objetos [Region](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/Region.html) que representam cada região. **Importações** ``` 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; ``` **Código da** ``` DescribeRegionsResult regions_response = ec2.describeRegions(); for(Region region : regions_response.getRegions()) { System.out.printf( "Found region %s " + "with endpoint %s", region.getRegionName(), region.getEndpoint()); } ``` Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DescribeRegionsAndZones.java). ## Descrever zonas de disponibilidade Para listar cada zona de disponibilidade disponível para a conta, chame o método `describeAvailabilityZones` do AmazonEC2Client. Ele retorna um [DescribeAvailabilityZonesResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeAvailabilityZonesResult.html). Chame o método `getAvailabilityZones` para obter uma lista de objetos [AvailabilityZone](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AvailabilityZone.html) que representam cada zona de disponibilidade. **Importações** ``` 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; ``` **Código da** ``` 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()); } ``` Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DescribeRegionsAndZones.java). ## Descrever contas Para descrever a conta, chame o método `describeAccountAttributes` do AmazonEC2Client. Esse método retorna um objeto [DescribeAccountAttributesResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeAccountAttributesResult.html). Invoque o método `getAccountAttributes` desses objetos para obter uma lista de objetos [AccountAttribute](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AccountAttribute.html). É possível percorrer a lista para recuperar um objeto [AccountAttribute](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AccountAttribute.html). Você pode obter os valores dos atributos da sua conta invocando o método `getAttributeValues` do objeto [AccountAttribute](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AccountAttribute.html). Esse método retorna uma lista de objetos [AccountAttributeValue](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AccountAttributeValue.html). É possível percorrer essa segunda lista para exibir o valor dos atributos (veja o exemplo de código a seguir). **Importações** ``` 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; ``` **Código da** ``` 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(); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DescribeAccount.java) no GitHub. ## Mais informações + [Regiões e zonas de disponibilidade](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) no Guia do Usuário do Amazon EC2 para Instâncias do Linux + [DescribeRegions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeRegions.html) na Referência de API do Amazon EC2 + [DescribeAvailabilityZones](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeAvailabilityZones.html) na Referência de API do Amazon EC2 # Trabalhar com pares de chaves do Amazon EC2 ## Criação de um par de chaves Para criar um par de chaves, chame o método `createKeyPair` do AmazonEC2Client com um [CreateKeyPairRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateKeyPairRequest.html) que contenha o nome da chave. **Importações** ``` 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; ``` **Código da** ``` final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient(); CreateKeyPairRequest request = new CreateKeyPairRequest() .withKeyName(key_name); CreateKeyPairResult response = ec2.createKeyPair(request); ``` Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/CreateKeyPair.java). ## Descrever pares de chaves Para listar os pares de chaves ou obter informações sobre eles, chame o método `describeKeyPairs` do AmazonEC2Client. Ele retorna um [DescribeKeyPairsResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeKeyPairsResult.html) que você pode usar para acessar a lista de pares de chaves chamando o método `getKeyPairs`, que retorna uma lista de objetos [KeyPairInfo](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/KeyPairInfo.html). **Importações** ``` 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; ``` **Código da** ``` 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()); } ``` Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DescribeKeyPairs.java). ## Excluir um par de chaves Para excluir um par de chaves, chame o método `deleteKeyPair` do AmazonEC2Client, passando um [DeleteKeyPairRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DeleteKeyPairRequest.html) que contenha o nome do par de chaves a ser excluído. **Importações** ``` 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; ``` **Código da** ``` final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient(); DeleteKeyPairRequest request = new DeleteKeyPairRequest() .withKeyName(key_name); DeleteKeyPairResult response = ec2.deleteKeyPair(request); ``` Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DeleteKeyPair.java). ## Mais informações + [Pares de chaves do Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) no Guia do Usuário do Amazon EC2 para instâncias do Linux + [CreateKeyPair](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CreateKeyPair.html) na Referência de API do Amazon EC2 + [DescribeKeyPairs](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeKeyPairs.html) na Referência de API do Amazon EC2 + [DeleteKeyPair](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DeleteKeyPair.html) na Referência de API do Amazon EC2 # Como trabalhar com grupos de segurança no Amazon EC2 ## Criar um grupo de segurança Para criar um grupo de segurança, chame o método `createSecurityGroup` do AmazonEC2Client com um [CreateSecurityGroupRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/CreateSecurityGroupRequest.html) que contenha o nome da chave. **Importações** ``` 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; ``` **Código da** ``` 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); ``` Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/CreateSecurityGroup.java). ## Configurar um grupo de segurança Um grupo de segurança pode controlar os tráfegos de entrada e saída para as instâncias do Amazon EC2. Para adicionar regras de entrada ao grupo de segurança, use o método `authorizeSecurityGroupIngress` do AmazonEC2Client, fornecendo o nome do grupo de segurança e as regras de acesso ([IpPermission](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/IpPermission.html)) que você deseja atribuir a ele dentro de um objeto [AuthorizeSecurityGroupIngressRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AuthorizeSecurityGroupIngressRequest.html). O exemplo a seguir mostra como adicionar permissões de IP a um grupo de segurança. **Importações** ``` 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; ``` **Código da** ``` 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); ``` Para adicionar uma regra de saída ao grupo de segurança, forneça dados semelhantes em um [AuthorizeSecurityGroupEgressRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/AuthorizeSecurityGroupEgressRequest.html) ao método `authorizeSecurityGroupEgress` do AmazonEC2Client. Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/CreateSecurityGroup.java). ## Descrever grupos de segurança Para descrever os grupos de segurança ou obter informações sobre eles, chame o método `describeSecurityGroups` do AmazonEC2Client. Ele retorna um [DescribeSecurityGroupsResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DescribeSecurityGroupsResult.html) que você pode usar para acessar a lista de grupos de segurança chamando o método `getSecurityGroups`, que retorna uma lista de objetos [SecurityGroup](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/ec2/model/SecurityGroup.html). **Importações** ``` 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; ``` **Código da** ``` 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]; ``` Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DescribeSecurityGroups.java). ## Excluir um grupo de segurança Para excluir um grupo de segurança, chame o método `deleteSecurityGroup` do AmazonEC2Client, passando um [DeleteSecurityGroupRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/ec2/model/DeleteSecurityGroupRequest.html) que contenha o ID do grupo de segurança a ser excluído. **Importações** ``` 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; ``` **Código da** ``` final AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient(); DeleteSecurityGroupRequest request = new DeleteSecurityGroupRequest() .withGroupId(group_id); DeleteSecurityGroupResult response = ec2.deleteSecurityGroup(request); ``` Consulte o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/ec2/src/main/java/aws/example/ec2/DeleteSecurityGroup.java). ## Mais informações + [Grupos de segurança do Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) no Guia do Usuário Amazon EC2 para Instâncias do Linux + [Autorização de tráfego de entrada para suas instâncias Linux](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/authorizing-access-to-an-instance.html) no Guia do Usuário Amazon EC2 para Instâncias do Linux + [CreateSecurityGroup](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CreateSecurityGroup.html), na Referência de API do Amazon EC2 + [DescribeSecurityGroups](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSecurityGroups.html), na Referência de API do Amazon EC2 + [DeleteSecurityGroup](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DeleteSecurityGroup.html) na Referência de API do Amazon EC2 + [AuthorizeSecurityGroupIngress](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_AuthorizeSecurityGroupIngress.html) na Referência de API do Amazon EC2 # Exemplos do IAM usando o AWS SDK para Java Esta seção fornece exemplos de como programar o [IAM](https://aws.amazon.com/iam/) usando o [AWS SDK para Java](https://aws.amazon.com/sdk-for-java/). O AWS Identity and Access Management (IAM) permite que você controle com segurança o acesso aos serviços e recursos da AWS para seus usuários. Usando o IAM, você pode criar e gerenciar usuários e grupos da AWS e usar permissões para permitir e negar o acesso deles aos recursos da AWS. Para obter um guia completo do IAM, visite o [Guia do usuário do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/). **nota** Entre os exemplos está somente o código necessário para demonstrar cada técnica. O [código de exemplo completo está disponível no GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java). A partir daí, você pode fazer download de um único arquivo de origem ou clonar o repositório de maneira local para obter todos os exemplos para compilação e execução. **Topics** + [Gerenciar chaves de acesso do IAM](examples-iam-access-keys.md) + [Gerenciar usuários do IAM](examples-iam-users.md) + [Usar aliases de conta do IAM](examples-iam-account-aliases.md) + [Trabalhar com políticas do IAM](examples-iam-policies.md) + [Trabalhar com certificados de servidor do IAM](examples-iam-server-certificates.md) # Gerenciar chaves de acesso do IAM ## Criar uma chave de acesso Para criar uma chave de acesso do IAM, chame o método `createAccessKey` do AmazonIdentityManagementClient com um objeto [CreateAccessKeyRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/CreateAccessKeyRequest.html). `CreateAccessKeyRequest` tem dois construtores: um que utiliza um nome de usuário e outro sem parâmetros. Se usar a versão que não utiliza parâmetros, você deverá definir o nome de usuário usando o método setter `withUserName` para passá-lo ao método `createAccessKey`. **Importações** ``` 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; ``` **Código da** ``` final AmazonIdentityManagement iam = AmazonIdentityManagementClientBuilder.defaultClient(); CreateAccessKeyRequest request = new CreateAccessKeyRequest() .withUserName(user); CreateAccessKeyResult response = iam.createAccessKey(request); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/CreateAccessKey.java) no GitHub. ## Listar chave de acesso Para listar as chaves de acesso de um determinado usuário, crie um objeto [ListAccessKeysRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/ListAccessKeysRequest.html) que contenha o nome de usuário cujas chaves listar e passe para o método `listAccessKeys` do AmazonIdentityManagementClient. **nota** Se você não fornecer um nome de usuário para `listAccessKeys`, ele tentará listar chaves de acesso associadas à Conta da AWS que assinou a solicitação. **Importações** ``` 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; ``` **Código da** ``` 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; } } ``` Os resultados de `listAccessKeys` são paginados (com um máximo de 100 registros por chamada). Você pode chamar `getIsTruncated` no objeto [ListAccessKeysResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/ListAccessKeysResult.html) retornado para ver se a consulta retornou menos resultados então disponíveis. Dessa forma, chame `setMarker` no `ListAccessKeysRequest` e repasse para a próxima invocação de `listAccessKeys`. Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/ListAccessKeys.java) no GitHub. ## Recuperar a hora do uso mais recente de uma chave de acesso Para obter a hora em que uma chave de acesso foi usada pela última vez, chame o método `getAccessKeyLastUsed` do AmazonIdentityManagementClient com o ID da chave de acesso, que pode ser passado usando um objeto [GetAccessKeyLastUsedRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/GetAccessKeyLastUsedRequest.html) ou diretamente para a sobrecarga que utiliza o ID de chave de acesso diretamente. Depois disso, é possível usar o objeto [GetAccessKeyLastUsedResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/GetAccessKeyLastUsedResult.html) retornado para recuperar a hora em que a chave foi usada mais recentemente. **Importações** ``` 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; ``` **Código da** ``` 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()); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/AccessKeyLastUsed.java) no GitHub. ## Ativar ou desativar chaves de acesso É possível ativar ou desativar uma chave de acesso criando um objeto [UpdateAccessKeyRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/UpdateAccessKeyRequest.html), fornecendo o ID de chave de acesso, como opção o nome do usuário e o [Status](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/StatusType.html) desejado e passando o objeto de solicitação para o método `updateAccessKey` do AmazonIdentityManagementClient. **Importações** ``` 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; ``` **Código da** ``` final AmazonIdentityManagement iam = AmazonIdentityManagementClientBuilder.defaultClient(); UpdateAccessKeyRequest request = new UpdateAccessKeyRequest() .withAccessKeyId(access_id) .withUserName(username) .withStatus(status); UpdateAccessKeyResult response = iam.updateAccessKey(request); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/UpdateAccessKey.java) no GitHub. ## Excluir uma chave de acesso Para excluir permanentemente uma chave de acesso, chame o método `deleteKey` do AmazonIdentityManagementClient, fornecendo um [DeleteAccessKeyRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/DeleteAccessKeyRequest.html) que contenha o ID e o nome de usuário da chave de acesso. **nota** Depois de excluída, uma chave não poderá mais ser recuperada ou usada. Para desativar temporariamente uma chave de maneira que ela possa ser reativado mais tarde, use o método [updateAccessKey](#iam-access-keys-update) em seu lugar. **Importações** ``` 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; ``` **Código da** ``` final AmazonIdentityManagement iam = AmazonIdentityManagementClientBuilder.defaultClient(); DeleteAccessKeyRequest request = new DeleteAccessKeyRequest() .withAccessKeyId(access_key) .withUserName(username); DeleteAccessKeyResult response = iam.deleteAccessKey(request); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/DeleteAccessKey.java) no GitHub. ## Mais informações + [CreateAccessKey](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateAccessKey.html) na Referência de API do IAM + [ListAccessKeys](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListAccessKeys.html) na Referência de API do IAM + [GetAccessKeyLastUsed](https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetAccessKeyLastUsed.html) na Referência de API do IAM + [UpdateAccessKey](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateAccessKey.html) na Referência de API do IAM + [DeleteAccessKey](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteAccessKey.html) na Referência de API do IAM # Gerenciar usuários do IAM ## Criação de um usuário Crie um usuário do IAM fornecendo o nome de usuário para o método `createUser` do AmazonIdentityManagementClient, diretamente ou usando um objeto [CreateUserRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/CreateUserRequest.html) que contém o nome do usuário. **Importações** ``` 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; ``` **Código da** ``` final AmazonIdentityManagement iam = AmazonIdentityManagementClientBuilder.defaultClient(); CreateUserRequest request = new CreateUserRequest() .withUserName(username); CreateUserResult response = iam.createUser(request); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/CreateUser.java) no GitHub. ## Listar usuários Para listar os usuários do IAM da conta, crie um [ListUsersRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/ListUsersRequest.html) e passe para o método `listUsers` do AmazonIdentityManagementClient. Você pode recuperar a lista de usuários chamando `getUsers` no objeto [ListUsersResult](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/identitymanagement/model/ListUsersResult.html) retornado. A lista de usuários retornados por `listUsers` é paginada. Você pode verificar se há mais resultados a serem recuperados chamando o método `getIsTruncated` do objeto de resposta. Se ele retornar `true`, chame o método `setMarker()` do objeto da solicitação, passando o valor de retorno do método `getMarker()` do objeto de resposta. **Importações** ``` 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; ``` **Código da** ``` 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; } } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/ListUsers.java) no GitHub. ## Atualizar um usuário Para atualizar um usuário, chame o método `updateUser` do objeto do AmazonIdentityManagementClient, que utiliza um objeto [UpdateUserRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/UpdateUserRequest.html) que pode ser usado por você para alterar o *nome* ou o *caminho* do usuário. **Importações** ``` 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; ``` **Código da** ``` final AmazonIdentityManagement iam = AmazonIdentityManagementClientBuilder.defaultClient(); UpdateUserRequest request = new UpdateUserRequest() .withUserName(cur_name) .withNewUserName(new_name); UpdateUserResult response = iam.updateUser(request); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/UpdateUser.java) no GitHub. ## Excluir um usuário Para excluir um usuário, chame a solicitação `deleteUser` do AmazonIdentityManagementClient com um objeto [UpdateUserRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/UpdateUserRequest.html) definido com o nome de usuário a ser excluído. **Importações** ``` 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; ``` **Código da** ``` 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; } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/DeleteUser.java) no GitHub. ## Mais informações + [Usuários do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html) no Guia do usuário do IAM + [Gerenciar usuários do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_manage.html) no Guia do usuário do IAM + [CreateUser](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateUser.html) na Referência de API do IAM + [ListUsers](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListUsers.html) na Referência de API do IAM + [UpdateUser](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateUser.html) na Referência de API do IAM + [DeleteUser](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteUser.html) na Referência de API do IAM # Usar aliases de conta do IAM Se deseja que o URL para sua página de login contenha o nome da sua empresa (ou outro identificador amigável) em vez do ID da sua Conta da AWS, você pode criar um alias para o Conta da AWS. **nota** A AWS dá suporte a exatamente um alias por conta. ## Criar um alias da conta Para criar um alias de conta, chame o método `createAccountAlias` do AmazonIdentityManagementClient com um objeto [CreateAccountAliasRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/CreateAccountAliasRequest.html) que contém o nome de alias. **Importações** ``` 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; ``` **Código da** ``` final AmazonIdentityManagement iam = AmazonIdentityManagementClientBuilder.defaultClient(); CreateAccountAliasRequest request = new CreateAccountAliasRequest() .withAccountAlias(alias); CreateAccountAliasResult response = iam.createAccountAlias(request); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/CreateAccountAlias.java) no GitHub. ## Listar aliases de conta Para listar o alias da conta, se houver, chame o método `listAccountAliases` do AmazonIdentityManagementClient. **nota** O [ListAccountAliasesResult](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/identitymanagement/model/ListAccountAliasesResult.html) retornado dá suporte aos mesmos métodos `getIsTruncated` e `getMarker` como outros métodos *list* do AWS SDK para Java, mas uma Conta da AWS pode ter somente *um* alias de conta. **importações** ``` import com.amazonaws.services.identitymanagement.AmazonIdentityManagement; import com.amazonaws.services.identitymanagement.AmazonIdentityManagementClientBuilder; import com.amazonaws.services.identitymanagement.model.ListAccountAliasesResult; ``` **código** ``` final AmazonIdentityManagement iam = AmazonIdentityManagementClientBuilder.defaultClient(); ListAccountAliasesResult response = iam.listAccountAliases(); for (String alias : response.getAccountAliases()) { System.out.printf("Retrieved account alias %s", alias); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/ListAccountAliases.java) no GitHub. ## Excluir um alias de conta Para excluir o alias da sua conta, chame o método `deleteAccountAlias` do AmazonIdentityManagementClient. Ao excluir um alias de conta, você deve fornecer o nome usando um objeto [DeleteAccountAliasRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/DeleteAccountAliasRequest.html). **importações** ``` 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; ``` **Código da** ``` final AmazonIdentityManagement iam = AmazonIdentityManagementClientBuilder.defaultClient(); DeleteAccountAliasRequest request = new DeleteAccountAliasRequest() .withAccountAlias(alias); DeleteAccountAliasResult response = iam.deleteAccountAlias(request); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/DeleteAccountAlias.java) no GitHub. ## Mais informações + [ID da sua conta da AWS e o alias](https://docs.aws.amazon.com/IAM/latest/UserGuide/console_account-alias.html) no Guia do Usuário do IAM + [CreateAccountAlias](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateAccountAlias.html) na Referência de API do IAM + [ListAccountAliases](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListAccountAliases.html) na Referência de API do IAM + [DeleteAccountAlias](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteAccountAlias.html) na Referência de API do IAM # Trabalhar com políticas do IAM ## Criar uma política Para criar uma política, forneça o nome da política e um documento de política em formato JSON em um [CreatePolicyRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/CreatePolicyRequest.html) para o método `createPolicy` do AmazonIdentityManagementClient. **Importações** ``` 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; ``` **Código da** ``` final AmazonIdentityManagement iam = AmazonIdentityManagementClientBuilder.defaultClient(); CreatePolicyRequest request = new CreatePolicyRequest() .withPolicyName(policy_name) .withPolicyDocument(POLICY_DOCUMENT); CreatePolicyResult response = iam.createPolicy(request); ``` Os documentos de política do IAM; são strings JSON com uma [sintaxe bem documentada](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_grammar.html). Veja a seguir um exemplo que fornece acesso para fazer solicitações específicas ao 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\"" + " }" + " ]" + "}"; ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/CreatePolicy.java) no GitHub. ## Obter uma política Para recuperar uma política existente, chame o método `getPolicy` do AmazonIdentityManagementClient fornecendo o ARN da política em um objeto [GetPolicyRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/GetPolicyRequest.html). **Importações** ``` 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; ``` **Código da** ``` final AmazonIdentityManagement iam = AmazonIdentityManagementClientBuilder.defaultClient(); GetPolicyRequest request = new GetPolicyRequest() .withPolicyArn(policy_arn); GetPolicyResult response = iam.getPolicy(request); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/GetPolicy.java) no GitHub. ## Anexar uma política de função [Você pode anexar uma política a um perfil do IAM [http://docs.aws.amazon.com/IAM/latest/UserGuide/id\$1roles.html] chamando o método `attachRolePolicy` do AmazonIdentityManagementClient, fornecendo a ele o nome do perfil e o ARN da política em um AttachRolePolicyRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/AttachRolePolicyRequest.html). **Importações** ``` 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; ``` **Código da** ``` final AmazonIdentityManagement iam = AmazonIdentityManagementClientBuilder.defaultClient(); AttachRolePolicyRequest attach_request = new AttachRolePolicyRequest() .withRoleName(role_name) .withPolicyArn(POLICY_ARN); iam.attachRolePolicy(attach_request); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/AttachRolePolicy.java) no GitHub. ## Listar políticas de função anexadas Liste as políticas anexadas em um perfil chamando o método `listAttachedRolePolicies` do AmazonIdentityManagementClient. Ele utiliza um objeto [ListAttachedRolePoliciesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/ListAttachedRolePoliciesRequest.html) que contém o nome da função para listar as políticas. Chame `getAttachedPolicies` no objeto [ListAttachedRolePoliciesResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/ListAttachedRolePoliciesResult.html) retornado para obter a lista de políticas anexadas. Os resultados podem ser truncados. Se o método `ListAttachedRolePoliciesResult` do objeto `getIsTruncated` retornar `true`, chame o método `ListAttachedRolePoliciesRequest` do objeto `setMarker` e o use para chamar `listAttachedRolePolicies` novamente a fim de obter o próximo lote de resultados. **Importações** ``` 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; ``` **Código da** ``` 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()); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/AttachRolePolicy.java) no GitHub. ## Desanexar uma política de função Para desanexar uma política de uma função, chame o método `detachRolePolicy` do AmazonIdentityManagementClient fornecendo o nome da função e o ARN da política em um [DetachRolePolicyRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/DetachRolePolicyRequest.html). **Importações** ``` 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; ``` **Código da** ``` final AmazonIdentityManagement iam = AmazonIdentityManagementClientBuilder.defaultClient(); DetachRolePolicyRequest request = new DetachRolePolicyRequest() .withRoleName(role_name) .withPolicyArn(policy_arn); DetachRolePolicyResult response = iam.detachRolePolicy(request); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/DetachRolePolicy.java) no GitHub. ## Mais informações + [Visão geral de políticas do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) no Guia do usuário do IAM. + [Referência da política do IAM da AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) no Guia do usuário do IAM. + [CreatePolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreatePolicy.html) na Referência de API do IAM + [GetPolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetPolicy.html) na Referência de API do IAM + [AttachRolePolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_AttachRolePolicy.html) na Referência de API do IAM + [ListAttachedRolePolicies](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListAttachedRolePolicies.html) na Referência de API do IAM + [DetachRolePolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DetachRolePolicy.html) na Referência de API do IAM # Trabalhar com certificados de servidor do IAM Para habilitar conexões HTTPS para o seu site ou aplicativo na AWS, você precisa de um *certificado de servidor* SSL/TLS. Você pode usar um certificado de servidor fornecido pelo AWS Certificate Manager ou um obtido junto a um provedor externo. Recomendamos que você use o ACM para provisionar, gerenciar e implantar seus certificados de servidor. Com o ACM; você pode solicitar um certificado, implantá-lo nos seus recursos da AWS e deixar o ACM processar renovações de certificado para você. Os certificados fornecidos pelo ACM são gratuitos. Para obter mais informações sobre o ACM, consulte o [Guia do usuário do ACM](https://docs.aws.amazon.com/acm/latest/userguide/). ## Obter um certificado de servidor Você pode recuperar um certificado de servidor chamando o método `getServerCertificate` do AmazonIdentityManagementClient, passando um [GetServerCertificateRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/GetServerCertificateRequest.html) com o nome do certificado. **Importações** ``` 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; ``` **Código da** ``` final AmazonIdentityManagement iam = AmazonIdentityManagementClientBuilder.defaultClient(); GetServerCertificateRequest request = new GetServerCertificateRequest() .withServerCertificateName(cert_name); GetServerCertificateResult response = iam.getServerCertificate(request); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/GetServerCertificate.java) no GitHub. ## Listar certificados de servidor Para listar os certificados de servidor, chame o método `listServerCertificates` do AmazonIdentityManagementClient com um [ListServerCertificatesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/ListServerCertificatesRequest.html). Ele retorna um [ListServerCertificatesResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/ListServerCertificatesResult.html). Chame o método `getServerCertificateMetadataList` do objeto `ListServerCertificateResult` para obter uma lista de objetos [ServerCertificateMetadata](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/ServerCertificateMetadata.html) usados por você para obter informações sobre cada certificado. Os resultados podem ser truncados. Se o método `ListServerCertificateResult` do objeto `getIsTruncated` retornar `true`, chame o método `ListServerCertificatesRequest` do objeto `setMarker` e o use para chamar `listServerCertificates` novamente a fim de obter o próximo lote de resultados. **Importações** ``` 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; ``` **Código da** ``` 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; } } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/ListServerCertificates.java) no GitHub. ## Atualizar um certificado de servidor Você pode atualizar o nome ou o caminho de um certificado de servidor chamando o método `updateServerCertificate` do AmazonIdentityManagementClient. Ele utiliza um objeto [UpdateServerCertificateRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/UpdateServerCertificateRequest.html) definido com o nome atual do certificado de servidor e um novo nome ou caminho a ser usado. **Importações** ``` 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; ``` **Código da** ``` final AmazonIdentityManagement iam = AmazonIdentityManagementClientBuilder.defaultClient(); UpdateServerCertificateRequest request = new UpdateServerCertificateRequest() .withServerCertificateName(cur_name) .withNewServerCertificateName(new_name); UpdateServerCertificateResult response = iam.updateServerCertificate(request); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/UpdateServerCertificate.java) no GitHub. ## Excluir um certificado de servidor Para excluir um certificado de servidor, chame o método `deleteServerCertificate` do AmazonIdentityManagementClient com um [DeleteServerCertificateRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/identitymanagement/model/DeleteServerCertificateRequest.html) contendo o nome do certificado. **Importações** ``` 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; ``` **Código da** ``` final AmazonIdentityManagement iam = AmazonIdentityManagementClientBuilder.defaultClient(); DeleteServerCertificateRequest request = new DeleteServerCertificateRequest() .withServerCertificateName(cert_name); DeleteServerCertificateResult response = iam.deleteServerCertificate(request); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/iam/src/main/java/aws/example/iam/DeleteServerCertificate.java) no GitHub. ## Mais informações + [Trabalhar com certificados de servidor](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_server-certs.html) no Guia do Usuário do IAM + [GetServerCertificate](https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetServerCertificate.html) na Referência de API do IAM + [ListServerCertificates](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListServerCertificates.html) na Referência de API do IAM + [UpdateServerCertificate](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateServerCertificate.html) na Referência de API do IAM + [DeleteServerCertificate](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteServerCertificate.html) na Referência de API do IAM + [Guia do usuário do ACM](https://docs.aws.amazon.com/acm/latest/userguide/) # Lambda Exemplos de usando a AWS SDK para Java Esta seção apresenta exemplos de como programar o Lambda usando o AWS SDK para Java. **nota** Entre os exemplos está somente o código necessário para demonstrar cada técnica. O [código de exemplo completo está disponível no GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java). A partir daí, você pode fazer download de um único arquivo de origem ou clonar o repositório de maneira local para obter todos os exemplos para compilação e execução. **Topics** + [Operações de serviço](examples-lambda.md) # Invocar, listar e excluir funções do Lambda Esta seção fornece exemplos de programação com o cliente de serviço do Lambda usando o AWS SDK para Java. Para saber como criar uma função do Lambda, consulte [Como criar funções do AWS Lambda](https://docs.aws.amazon.com/toolkit-for-eclipse/v1/user-guide/lambda-tutorial.html). **Topics** + [Invocar uma função](#invoke-function) + [Listar as funções](#list-function) + [Excluir uma função](#delete-function) ## Invocar uma função É possível invocar uma função do Lambda criando um objeto [AWSLambda](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/AWSLambda.html) e invocando seu método `invoke`. Crie um objeto [InvokeRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/model/InvokeRequest.html) para especificar informações adicionais, como o nome da função e a carga útil a serem transmitidas para a função do Lambda. Os nomes de função aparecem como *arn:aws:lambda:us-east-1:555556330391:function:HelloFunction*. É possível recuperar o valor examinando a função no Console de gerenciamento da AWS. Para transmitir dados de carga para uma função, invoque o método `withPayload` do objeto [InvokeRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/model/InvokeRequest.html) e especifique uma String no formato JSON, conforme mostrado no exemplo de código a seguir. **Importações** ``` 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; ``` **Código da** O exemplo de código a seguir demonstra como invocar uma função do 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()); ``` Veja o exemplo completo no [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/lambda/src/main/java/com/example/lambda/LambdaInvokeFunction.java). ## Listar as funções Crie um objeto [AWSLambda](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/AWSLambda.html) e invoque seu método `listFunctions`. Este método retorna um objeto [ListFunctionsResult](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/model/ListFunctionsResult.html). É possível invocar o método `getFunctions` desse objeto para retornar uma lista de objetos [FunctionConfiguration](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/model/FunctionConfiguration.html). É possível percorrer a lista para recuperar informações sobre as funções. Por exemplo, o exemplo de código Java a seguir mostra como obter cada nome de função. **Importações** ``` 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; ``` **Código da** O exemplo de código Java a seguir demonstra como recuperar uma lista de nomes de função do 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); } ``` Veja o exemplo completo no [GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/lambda/src/main/java/com/example/lambda/ListFunctions.java). ## Excluir uma função Crie um objeto [AWSLambda](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/AWSLambda.html) e invoque seu método `deleteFunction`. Crie um objeto [DeleteFunctionRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/model/DeleteFunctionRequest.html) e transmita-o ao método `deleteFunction`. Esse objeto contém informações como o nome da função a ser excluída. Os nomes de função aparecem como *arn:aws:lambda:us-east-1:555556330391:function:HelloFunction*. É possível recuperar o valor examinando a função no Console de gerenciamento da AWS. **Importações** ``` 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; ``` **Código da** O seguinte código Java demonstra como excluir uma função do 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); } ``` Veja o exemplo completo no [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 Exemplos de usando a AWS SDK para Java Esta seção apresenta exemplos de como programar o [Amazon Pinpoint](https://aws.amazon.com/pinpoint/) usando o [AWS SDK para Java](https://aws.amazon.com/sdk-for-java/). **nota** Entre os exemplos está somente o código necessário para demonstrar cada técnica. O [código de exemplo completo está disponível no GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java). A partir daí, você pode fazer download de um único arquivo de origem ou clonar o repositório de maneira local para obter todos os exemplos para compilação e execução. **Topics** + [Criar e excluir aplicativos no Amazon Pinpoint](examples-pinpoint-create-app.md) + [Criar endpoints no Amazon Pinpoint](examples-pinpoint-create-endpoint.md) + [Criar segmentos no Amazon Pinpoint](examples-pinpoint-create-segment.md) + [Criar campanhas no Amazon Pinpoint](examples-pinpoint-create-campaign.md) + [Atualizar canais no Amazon Pinpoint](examples-pinpoint-update-channel.md) # Criar e excluir aplicativos no Amazon Pinpoint Um aplicativo é um projeto do Amazon Pinpoint no qual você define o público para um aplicativo distinto e envolve esse público com mensagens personalizadas. Os exemplos nesta página demonstram como criar um novo aplicativo ou excluir um existente. ## Criar um aplicativo Crie um aplicativo no Amazon Pinpoint fornecendo um nome de aplicativo ao objeto [CreateAppRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/CreateAppRequest.html) e passando esse objeto para o método `createApp` do AmazonPinpointClient. **Importações** ``` 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; ``` **Código da** ``` CreateApplicationRequest appRequest = new CreateApplicationRequest() .withName(appName); CreateAppRequest request = new CreateAppRequest(); request.withCreateApplicationRequest(appRequest); CreateAppResult result = pinpoint.createApp(request); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/pinpoint/src/main/java/com/example/pinpoint/CreateApp.java) no GitHub. ## Excluir um aplicativo Para excluir um aplicativo, chame a solicitação `deleteApp` do AmazonPinpointClient com um objeto [DeleteAppRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/DeleteAppRequest.html), que é definido com o nome do aplicativo a ser excluído. **Importações** ``` import com.amazonaws.services.pinpoint.AmazonPinpoint; import com.amazonaws.services.pinpoint.AmazonPinpointClientBuilder; ``` **Código da** ``` DeleteAppRequest deleteRequest = new DeleteAppRequest() .withApplicationId(appID); pinpoint.deleteApp(deleteRequest); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/pinpoint/src/main/java/com/example/pinpoint/DeleteApp.java) no GitHub. ## Mais informações + [Apps](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-apps.html) na Referência de API do Amazon Pinpoint + [App](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-app.html) na Referência de API do Amazon Pinpoint # Criar endpoints no Amazon Pinpoint Um endpoint identifica exclusivamente um dispositivo de usuário ao qual você pode enviar notificações por push com o Amazon Pinpoint. Se o seu aplicativo tem suporte ao Amazon Pinpoint ativado, ele registra automaticamente um endpoint com esse Amazon Pinpoint quando um novo usuário o abre. O exemplo a seguir demonstra como adicionar um novo endpoint de maneira programática. ## Criar um endpoint Crie um endpoint no Amazon Pinpoint fornecendo os dados do endpoint em um objeto [EndpointRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/EndpointRequest.html). **Importações** ``` 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; ``` **Código da** ``` 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); ``` Em seguida, crie um objeto [UpdateEndpointRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/UpdateEndpointRequest.html) com o objeto EndpointRequest. Por fim, passe o objeto UpdateEndpointRequest para o método `updateEndpoint` do AmazonPinpointClient. **Código da** ``` UpdateEndpointRequest updateEndpointRequest = new UpdateEndpointRequest() .withApplicationId(appId) .withEndpointId(endpointId) .withEndpointRequest(endpointRequest); UpdateEndpointResult updateEndpointResponse = client.updateEndpoint(updateEndpointRequest); System.out.println("Update Endpoint Response: " + updateEndpointResponse.getMessageBody()); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/pinpoint/src/main/java/com/example/pinpoint/CreateEndpoint.java) no GitHub. ## Mais informações + [Adicionar endpoint](https://docs.aws.amazon.com/pinpoint/latest/developerguide/endpoints.html) no Guia do desenvolvedor do Amazon Pinpoint + [Endpoint](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-endpoint.html) na Referência de API do Amazon Pinpoint # Criar segmentos no Amazon Pinpoint Um segmento de usuário representa um subconjunto de seus usuários com base em características compartilhadas, como a última vez em que os usuários abriram seu aplicativo ou qual dispositivo usam. O exemplo a seguir demonstra como definir um segmento dos usuários. ## Criar um segmento Crie um segmento no Amazon Pinpoint definindo dimensões do segmento em um objeto [SegmentDimensions](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/SegmentDimensions.html). **Importações** ``` 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; ``` **Código da** ``` 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); ``` Em seguida, defina o objeto [SegmentDimensions](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/SegmentDimensions.html) em um [WriteSegmentRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/WriteSegmentRequest.html) usado para criar um objeto [CreateSegmentRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/CreateSegmentRequest.html). Depois disso, passe o objeto CreateSegmentRequest para o método `createSegment` do AmazonPinpointClient. **Código da** ``` WriteSegmentRequest writeSegmentRequest = new WriteSegmentRequest() .withName("MySegment").withDimensions(dimensions); CreateSegmentRequest createSegmentRequest = new CreateSegmentRequest() .withApplicationId(appId).withWriteSegmentRequest(writeSegmentRequest); CreateSegmentResult createSegmentResult = client.createSegment(createSegmentRequest); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/pinpoint/src/main/java/com/example/pinpoint/CreateSegment.java) no GitHub. ## Mais informações + [Segmentos do Amazon Pinpoint](https://docs.aws.amazon.com/pinpoint/latest/userguide/segments.html) no Guia do usuário do Amazon Pinpoint + [Criar segmentos](https://docs.aws.amazon.com/pinpoint/latest/developerguide/segments.html), no Guia do desenvolvedor do Amazon Pinpoint + [Segmentos](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-segments.html) na Referência de API do Amazon Pinpoint + [Segmento](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-segment.html) na Referência de API do Amazon Pinpoint # Criar campanhas no Amazon Pinpoint Você pode usar campanhas para ajudar a aumentar o envolvimento entre seu aplicativo e seus usuários. Você pode criar uma campanha para alcançar um segmento específico dos seus usuários com mensagens personalizadas ou promoções especiais. Este exemplo demonstra como criar uma nova campanha padrão que envia uma notificação push personalizada para um segmento especificado. ## Criar uma campanha Antes de criar uma nova campanha, você deve definir uma [programação](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/Schedule.html) e uma [mensagem](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/Message.html) e, em seguida, definir esses valores em um objeto [WriteCampaignRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/WriteCampaignRequest.html). **Importações** ``` 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; ``` **Código da** ``` 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); ``` Em seguida, crie uma nova campanha no Amazon Pinpoint fornecendo o [WriteCampaignRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/WriteCampaignRequest.html) com a configuração da campanha para um objeto [CreateCampaignRequest](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/pinpoint/model/CreateCampaignRequest.html). Por fim, passe o objeto CreateCampaignRequest para o método `createCampaign` do AmazonPinpointClient. **Código da** ``` CreateCampaignRequest createCampaignRequest = new CreateCampaignRequest() .withApplicationId(appId).withWriteCampaignRequest(request); CreateCampaignResult result = client.createCampaign(createCampaignRequest); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/pinpoint/src/main/java/com/example/pinpoint/CreateApp.java) no GitHub. ## Mais informações + [Campanhas do Amazon Pinpoint](https://docs.aws.amazon.com/pinpoint/latest/userguide/campaigns.html) no Guia do usuário do Amazon Pinpoint + [Criar campanhas](https://docs.aws.amazon.com/pinpoint/latest/developerguide/campaigns.html) no Guia do desenvolvedor do Amazon Pinpoint + [Campanhas](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-campaigns.html) na Referência de API do Amazon Pinpoint + [Campanha](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-campaign.html) na Referência de API do Amazon Pinpoint + [Atividades de campanha](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-campaign-activities.html) na Referência de API do Amazon Pinpoint + [Versões da campanha](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-campaign-versions.html) na Referência de API do Amazon Pinpoint + [Versão da campanha](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-campaign-version.html) na Referência de API do Amazon Pinpoint # Atualizar canais no Amazon Pinpoint Um canal define os tipos de plataformas para as quais você pode entregar mensagens. Este exemplo mostra como usar o canal APNs para enviar uma mensagem. ## Atualizar um canal Ativar um canal no Amazon Pinpoint fornecendo um ID de aplicativo e um objeto de solicitação do tipo de canal que você quer atualizar. Este exemplo atualiza o canal APNs, que requer o objeto [APNSChannelRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/APNSChannelRequest.html). Defina-os em [UpdateApnsChannelRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/pinpoint/model/UpdateApnsChannelRequest.html) e passe o objeto para o método `updateApnsChannel` do AmazonPinpointClient. **Importações** ``` 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; ``` **Código da** ``` APNSChannelRequest request = new APNSChannelRequest() .withEnabled(enabled); UpdateApnsChannelRequest updateRequest = new UpdateApnsChannelRequest() .withAPNSChannelRequest(request) .withApplicationId(appId); UpdateApnsChannelResult result = client.updateApnsChannel(updateRequest); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/pinpoint/src/main/java/com/example/pinpoint/UpdateChannel.java) no GitHub. ## Mais informações + [Canais do Amazon Pinpoint](https://docs.aws.amazon.com/pinpoint/latest/userguide/channels.html) no Guia do usuário do Amazon Pinpoint + [Canal ADM](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-adm-channel.html) na Referência de API do Amazon Pinpoint + [Canal do APNs](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-apns-channel.html) na Referência de API do Amazon Pinpoint + [Canal Sandbox de APNs](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-apns-sandbox-channel.html) na Referência de API do Amazon Pinpoint + [Canal VoIP de APNs](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-apns-voip-channel.html) na Referência de API do Amazon Pinpoint + [Canal APNs VoIP Sandbox](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-apns-voip-sandbox-channel.html) na Referência de API do Amazon Pinpoint + [Canal Baidu](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-baidu-channel.html) na Referência de API do Amazon Pinpoint + [Canal de e-mail](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-email-channel.html) na Referência de API do Amazon Pinpoint + [Canal GCM](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-gcm-channel.html) na Referência de API do Amazon Pinpoint + [Canal SMS](https://docs.aws.amazon.com/pinpoint/latest/apireference/rest-api-sms-channel.html) na Referência de API do Amazon Pinpoint # Amazon S3 Exemplos de usando a AWS SDK para Java Esta seção apresenta exemplos de como programar o [Amazon S3](https://aws.amazon.com/s3/) usando o [AWS SDK para Java](https://aws.amazon.com/sdk-for-java/). **nota** Entre os exemplos está somente o código necessário para demonstrar cada técnica. O [código de exemplo completo está disponível no GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java). A partir daí, você pode fazer download de um único arquivo de origem ou clonar o repositório de maneira local para obter todos os exemplos para compilação e execução. **Topics** + [Criar, listar e excluir buckets do Amazon S3](examples-s3-buckets.md) + [Realizar operações em objetos do Amazon S3](examples-s3-objects.md) + [Gerenciar permissões de acesso ao Amazon S3 para buckets e objetos](examples-s3-access-permissions.md) + [Gerenciar acesso a buckets do Amazon S3 usando políticas de bucket](examples-s3-bucket-policies.md) + [Usar o TransferManager em operações do Amazon S3](examples-s3-transfermanager.md) + [Configurar um bucket do Amazon S3 como um site](examples-s3-website-configuration.md) + [Usar criptografia do lado do cliente do Amazon S3](examples-crypto.md) # Criar, listar e excluir buckets do Amazon S3 Cada objeto (arquivo) no Amazon S3 deve residir em um *bucket*, que representa um conjunto (contêiner) de objetos. Cada bucket é conhecido por uma *chave* (nome), que deve ser exclusiva. Para obter informações detalhadas sobre os buckets e suas configurações, consulte [Trabalhar com buckets do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html) Guia do usuário do Amazon Simple Storage Service. **nota** Melhor prática Recomendamos habilitar a regra de ciclo de vida [AbortIncompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTlifecycle.html) nos buckets do Amazon S3. Essa regra leva o Amazon S3 a anular multipart uploads que não sejam concluídos dentro de um número específico de dias depois de serem iniciados. Quando o limite de tempo definido é excedido, o Amazon S3 anula o upload e exclui os dados de uploads incompletos. Para obter mais informações, consulte [Configuração do ciclo de vida de um bucket com versionamento](https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-configuration-bucket-with-versioning.html) no Guia do usuário do Amazon S3. **nota** Esses exemplos de código pressupõem que você entenda o material em [Usar o AWS SDK para Java](basics.md) e tenha configurado credenciais da AWS padrão usando as informações em [Configurar credenciais e região da AWS para desenvolvimento](setup-credentials.md). ## Criar um bucket Use o método `createBucket` do cliente AmazonS3. O novo [bucket](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Bucket.html) é retornado. O método `createBucket` lançará uma exceção se o bucket já existir. **nota** Para verificar se um bucket já existe antes de tentar criar um com o mesmo nome, chame o método `doesBucketExist`. Isso retornará `true` se o bucket existir e, do contrário, `false`. **Importações** ``` 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; ``` **Código da** ``` 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; ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/CreateBucket.java) no GitHub. ## Listar buckets Use o método `listBucket` do cliente AmazonS3. Se for bem-sucedido, uma lista de [buckets](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Bucket.html) será retornada. **Importações** ``` 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; ``` **Código da** ``` List buckets = s3.listBuckets(); System.out.println("Your {S3} buckets are:"); for (Bucket b : buckets) { System.out.println("* " + b.getName()); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/ListBuckets.java) no GitHub. ## Excluir um Bucket Para excluir um bucket do Amazon S3, você deve verificar se o bucket está vazio, ou isso resultará em um erro. Se tiver um [bucket versionado](https://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html), você também deverá excluir todos os objetos versionados associados ao bucket. **nota** O [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java) inclui todas essas etapas em ordem, fornecendo uma solução completa para excluir um bucket do Amazon S3 e o conteúdo. **Topics** + [Remover objetos de um bucket não versionado antes de excluí-lo](#remove-objects-from-an-unversioned-bucket-before-deleting-it) + [Remover objetos de um bucket versionado antes de excluí-lo](#remove-objects-from-a-versioned-bucket-before-deleting-it) + [Excluir um bucket vazio](#delete-an-empty-bucket) ### Remover objetos de um bucket não versionado antes de excluí-lo Use o método `listObjects` de cliente do AmazonS3 para recuperar a lista de objetos e `deleteObject` para excluir cada um. **Importações** ``` 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; ``` **Código da** ``` 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; } } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java) no GitHub. ### Remover objetos de um bucket versionado antes de excluí-lo Se estiver usando um [bucket versionado](https://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html), também será necessário remover todas as versões armazenadas dos objetos no bucket para o bucket ser excluído. Usando um padrão semelhante ao usado ao remover objetos dentro de um bucket, remova objetos versionados usando o método `listVersions` de cliente do AmazonS3 para listar todos os objetos versionados e `deleteVersion` para excluir cada um. **Importações** ``` 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; ``` **Código da** ``` 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; } } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java) no GitHub. ### Excluir um bucket vazio Assim que remover os objetos de um bucket (inclusive todos os objetos versionados), será possível excluir o bucket em si usando o método `deleteBucket` de cliente do AmazonS3. **Importações** ``` 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; ``` **Código da** ``` System.out.println(" OK, bucket ready to delete!"); s3.deleteBucket(bucket_name); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java) no GitHub. # Realizar operações em objetos do Amazon S3 Um objeto do Amazon S3 representa um *arquivo* ou um conjunto de dados. Cada objeto deve residir em um [bucket](examples-s3-buckets.md). **nota** Esses exemplos de código pressupõem que você entenda o material em [Usar o AWS SDK para Java](basics.md) e tenha configurado credenciais da AWS padrão usando as informações em [Configurar credenciais e região da AWS para desenvolvimento](setup-credentials.md). **Topics** + [Fazer upload de um objeto](#upload-object) + [Listar objetos](#list-objects) + [Fazer download de um objeto](#download-object) + [Copiar, mover ou renomear objetos](#copy-object) + [Excluir um objeto](#delete-object) + [Excluir vários objetos de uma só vez](#delete-objects) ## Fazer upload de um objeto Use o método `putObject` de cliente do AmazonS3 fornecendo um nome de bucket, um nome de chave e um arquivo para upload. *O bucket deve existir ou isso resultará em um erro*. **Importações** ``` import com.amazonaws.AmazonServiceException; import com.amazonaws.regions.Regions; import com.amazonaws.services.s3.AmazonS3; ``` **Código da** ``` 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); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/PutObject.java) no GitHub. ## Listar objetos Para obter uma lista de objetos em um bucket, use o método `listObjects` de cliente do AmazonS3 fornecendo o nome de um bucket. O método `listObjects` retorna um objeto [ObjectListing](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/ObjectListing.html) que fornece informações sobre os objetos no bucket. Para listar os nomes de objeto (chaves), use o método `getObjectSummaries` para obter uma lista de objetos [S3ObjectSummary](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/S3ObjectSummary.html), cada um dos quais representa um único objeto no bucket. Depois disso, chame o método `getKey` para recuperar o nome do objeto. **Importações** ``` 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; ``` **Código da** ``` 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()); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/ListObjects.java) no GitHub. ## Fazer download de um objeto Use o método `getObject` de cliente do AmazonS3 passando o nome de um bucket e o objeto para fazer download. Se bem-sucedido, o método retornará um [S3Object](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/S3Object.html). *O bucket especificado e a chave de objeto devem existir ou isso resultará em um erro*. É possível obter o conteúdo do objeto chamando `getObjectContent` no `S3Object`. Isso retorna um [S3ObjectInputStream](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/S3ObjectInputStream.html) que se comporta como um objeto `InputStream` do Java padrão. O exemplo a seguir faz download de um objeto do S3 e salva o conteúdo em um arquivo (usando o mesmo nome da chave do objeto). **Importações** ``` 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; ``` **Código da** ``` 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); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/GetObject.java) no GitHub. ## Copiar, mover ou renomear objetos É possível copiar um objeto de um bucket para outro usando o método `copyObject` de cliente do AmazonS3. Ele utiliza o nome do bucket do qual será feita a cópia, o objeto a ser copiado e o nome do bucket de destino. **Importações** ``` import com.amazonaws.AmazonServiceException; import com.amazonaws.regions.Regions; ``` **Código da** ``` 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!"); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/CopyObject.java) no GitHub. **nota** Você pode usar `copyObject` com [deleteObject](#delete-object) para **migrar** ou **renomear** um objeto copiando primeiro o objeto para um novo nome (é possível usar o mesmo bucket na origem e no destino) e excluindo o objeto do local anterior. ## Excluir um objeto Use o método `deleteObject` de cliente do AmazonS3, passando o nome de um bucket e o objeto a ser excluído. *O bucket especificado e a chave de objeto devem existir ou isso resultará em um erro*. **Importações** ``` import com.amazonaws.AmazonServiceException; import com.amazonaws.regions.Regions; ``` **Código da** ``` 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); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteObject.java) no GitHub. ## Excluir vários objetos de uma só vez Usando o método `deleteObjects` de cliente do AmazonS3, você pode excluir vários objetos do mesmo bucket passando seus nomes para o método link:sdk-for-java/v1/reference/com/amazonaws/services/s3/model/DeleteObjectsRequest.html``. **Importações** ``` import com.amazonaws.AmazonServiceException; import com.amazonaws.regions.Regions; import com.amazonaws.services.s3.AmazonS3; ``` **Código da** ``` 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); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteObjects.java) no GitHub. # Gerenciar permissões de acesso ao Amazon S3 para buckets e objetos É possível usar listas de controle de acesso (ACLs) para objetos e buckets do Amazon S3 para controle refinado sobre os recursos do Amazon S3. **nota** Esses exemplos de código pressupõem que você entenda o material em [Usar o AWS SDK para Java](basics.md) e tenha configurado credenciais da AWS padrão usando as informações em [Configurar credenciais e região da AWS para desenvolvimento](setup-credentials.md). ## Obter a lista de controle de acesso para um bucket Para obter a ACL atual de um bucket, chame o método `getBucketAcl` do AmazonS3 passando o *nome do bucket* para consulta. Esse método retorna um objeto [AccessControlList](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/AccessControlList.html). Para obter cada concessão de acesso na lista, chame o método `getGrantsAsList`, que retornará uma lista de objetos [Grant](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Grant.html) do Java padrão. **Importações** ``` 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; ``` **Código da** ``` 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); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/GetAcl.java) no GitHub. ## Definir a lista de controle de acesso para um bucket Para adicionar ou modificar permissões para uma ACL de um bucket, chame o método `setBucketAcl` do AmazonS3. Ele utiliza um objeto [AccessControlList](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/AccessControlList.html) que contém uma lista de favorecidos e níveis de acesso a serem definidos. **Importações** ``` 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; ``` **Código da** ``` 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); } ``` **nota** É possível fornecer o identificador exclusivo do favorecido diretamente usando a classe [Grantee](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Grantee.html) ou usar a classe [EmailAddressGrantee](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/EmailAddressGrantee.html) para definir o favorecido por e-mail, como fizemos aqui. Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/SetAcl.java) no GitHub. ## Obter a lista de controle de acesso para um objeto Para obter a ACL atual de um objeto, chame o método `getObjectAcl` do AmazonS3, passando o *nome do bucket* e o *nome do objeto* para consulta. Assim como `getBucketAcl`, esse método retorna um objeto [AccessControlList](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/AccessControlList.html) que você pode usar para examinar cada [Grant](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Grant.html). **Importações** ``` 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; ``` **Código da** ``` 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); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/GetAcl.java) no GitHub. ## Definir a lista de controle de acesso para um objeto Para adicionar ou modificar permissões para uma ACL de um objeto, chame o método `setObjectAcl` do AmazonS3. Ele utiliza um objeto [AccessControlList](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/AccessControlList.html) que contém uma lista de favorecidos e níveis de acesso a serem definidos. **Importações** ``` 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; ``` **Código da** ``` 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); } } ``` **nota** É possível fornecer o identificador exclusivo do favorecido diretamente usando a classe [Grantee](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/Grantee.html) ou usar a classe [EmailAddressGrantee](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/EmailAddressGrantee.html) para definir o favorecido por e-mail, como fizemos aqui. Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/SetAcl.java) no GitHub. ## Mais informações + [GET Bucket acl](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketGETacl.html) na Referência de API do Amazon S3 + [PUT Bucket acl](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTacl.html) na Referência de API do Amazon S3 + [GET Object acl](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGETacl.html) na Referência de API do Amazon S3 + [PUT Object acl](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUTacl.html) na Referência de API do Amazon S3 # Gerenciar acesso a buckets do Amazon S3 usando políticas de bucket Você pode definir, obter ou excluir uma *política de bucket* para gerenciar o acesso aos buckets do Amazon S3. ## Definir uma política de bucket Você pode definir a política de bucket para um determinado bucket do S3 ao: + Chamar o `setBucketPolicy` de cliente do AmazonS3 e fornecer um [SetBucketPolicyRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/SetBucketPolicyRequest.html) + Definir a política diretamente usando a sobrecarga `setBucketPolicy` que utiliza um nome de bucket e o texto da política (em formato JSON) **Importações** ``` import com.amazonaws.AmazonServiceException; import com.amazonaws.auth.policy.Policy; import com.amazonaws.auth.policy.Principal; ``` **Código da** ``` s3.setBucketPolicy(bucket_name, policy_text); } catch (AmazonServiceException e) { System.err.println(e.getErrorMessage()); System.exit(1); } ``` ### Usar a classe Policy para gerar ou validar uma política Ao fornecer uma política de bucket para `setBucketPolicy`, você pode fazer o seguinte: + Especificar a política diretamente como uma string de texto formatado em JSON + Compilar a política usando a classe [Policy](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/auth/policy/Policy.html) Usando a classe `Policy`, não é necessário se preocupar com a formatação correta da string de texto. Para obter o texto da política JSON da classe `Policy`, use o método `toJson`. **Importações** ``` 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; ``` **Código da** ``` new Statement(Statement.Effect.Allow) .withPrincipals(Principal.AllUsers) .withActions(S3Actions.GetObject) .withResources(new Resource( "{region-arn}s3:::" + bucket_name + "/*"))); return bucket_policy.toJson(); ``` A classe `Policy` também oferece um método `fromJson` que pode tentar compilar uma política usando uma string JSON passada. O método a valida para garantir que o texto possa ser transformado em uma estrutura de política válida e falhará com um `IllegalArgumentException` se o texto da política for inválido. ``` 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()); } ``` Você pode usar essa técnica para pré-validar uma política lida de um arquivo ou outros meios. Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/SetBucketPolicy.java) no GitHub. ## Obter uma política de bucket Para recuperar a política de um bucket do Amazon S3, chame o método `getBucketPolicy` de cliente do AmazonS3, passando o nome do bucket do qual obter a política. **Importações** ``` import com.amazonaws.AmazonServiceException; import com.amazonaws.regions.Regions; import com.amazonaws.services.s3.AmazonS3; import com.amazonaws.services.s3.AmazonS3ClientBuilder; ``` **Código da** ``` try { BucketPolicy bucket_policy = s3.getBucketPolicy(bucket_name); policy_text = bucket_policy.getPolicyText(); } catch (AmazonServiceException e) { System.err.println(e.getErrorMessage()); System.exit(1); } ``` Se o bucket nomeado não existir, se você não tiver acesso a ele, ou se ele não tiver uma política de bucket, um `AmazonServiceException` será lançado. Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/GetBucketPolicy.java) no GitHub. ## Excluir uma política de bucket Para excluir uma política de bucket, chame o `deleteBucketPolicy` de cliente do AmazonS3, fornecendo o nome do bucket. **Importações** ``` import com.amazonaws.AmazonServiceException; import com.amazonaws.regions.Regions; import com.amazonaws.services.s3.AmazonS3; ``` **Código da** ``` try { s3.deleteBucketPolicy(bucket_name); } catch (AmazonServiceException e) { System.err.println(e.getErrorMessage()); System.exit(1); } ``` Esse método será bem-sucedido, mesmo se o bucket ainda não tiver uma política. Se você especificar um nome de bucket não existente ou se não tiver acesso ao bucket, um `AmazonServiceException` será lançado. Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteBucketPolicy.java) no GitHub. ## Mais informações + [Visão geral da linguagem de políticas de acesso](https://docs.aws.amazon.com/AmazonS3/latest/dev/access-policy-language-overview.html) no Guia do usuário do Amazon Simple Storage Service + [Exemplos de políticas de bucket](https://docs.aws.amazon.com/AmazonS3/latest/dev/example-bucket-policies.html) no Guia do usuário do Amazon Simple Storage Service # Usar o TransferManager em operações do Amazon S3 Você pode usar a classe TransferManager do AWS SDK para Java para transferir arquivos de maneira confiável do ambiente local para Amazon S3 e copiar objetos de um local do S3 para outro. O `TransferManager` pode saber o andamento de uma transferência e pausar ou retomar uploads e downloads. **nota** Melhor prática Recomendamos habilitar a regra de ciclo de vida [AbortIncompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTlifecycle.html) nos buckets do Amazon S3. Essa regra leva o Amazon S3 a anular multipart uploads que não sejam concluídos dentro de um número específico de dias depois de serem iniciados. Quando o limite de tempo definido é excedido, o Amazon S3 anula o upload e exclui os dados de uploads incompletos. Para obter mais informações, consulte [Configuração do ciclo de vida de um bucket com versionamento](https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-configuration-bucket-with-versioning.html) no Guia do usuário do Amazon S3. **nota** Esses exemplos de código pressupõem que você entenda o material em [Usar o AWS SDK para Java](basics.md) e tenha configurado credenciais da AWS padrão usando as informações em [Configurar credenciais e região da AWS para desenvolvimento](setup-credentials.md). ## Fazer upload de arquivos e diretórios O TransferManager pode fazer upload de arquivos, listas de arquivos e diretórios para todos os buckets do Amazon S3 [criados anteriormente](examples-s3-buckets.md#create-bucket). **Topics** + [Fazer upload de um único arquivo](#transfermanager-upload-file) + [Fazer upload de uma lista de arquivos](#transfermanager-upload-file-list) + [Fazer upload de um diretório](#transfermanager-upload-directory) ### Fazer upload de um único arquivo Chame o método `upload` do TransferManager, fornecendo um nome de bucket do Amazon S3, um nome de chave (objeto) e um objeto [File](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html) do Java padrão que represente o arquivo para upload. **Importações** ``` 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; ``` **Código da** ``` 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(); ``` O método `upload` retorna *imediatamente*, fornecendo um objeto `Upload` a ser usado para verificar o estado de transferência ou aguardar a conclusão. Consulte [Aguardar a conclusão de uma transferência](#transfermanager-wait-for-completion) para obter informações sobre como usar `waitForCompletion` para concluir com êxito uma transferência antes de chamar o método `shutdownNow` do TransferManager. Enquanto aguarda a conclusão da transferência, você pode sondar ou escutar atualizações sobre o status e o progresso. Consulte [Obter status de transferência e progresso](#transfermanager-get-status-and-progress) para obter mais informações. Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrUpload.java) no GitHub. ### Fazer upload de uma lista de arquivos Para fazer upload de vários arquivos em uma única operação, chame o método `uploadFileList` do TransferManager, fornecendo o seguinte: + Um nome do bucket do Amazon S3 + Um *prefixo de chaves* a ser acrescentado aos nomes dos objetos criados (o caminho dentro do bucket no qual colocar os objetos) + Um objeto [File](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html) que representa o diretório relativo do qual criar caminhos de arquivo + Um objeto [List](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/List.html) contendo um conjunto de objetos [File](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html) para upload **Importações** ``` 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; ``` **Código da** ``` 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(); ``` Consulte [Aguardar a conclusão de uma transferência](#transfermanager-wait-for-completion) para obter informações sobre como usar `waitForCompletion` para concluir com êxito uma transferência antes de chamar o método `shutdownNow` do TransferManager. Enquanto aguarda a conclusão da transferência, você pode sondar ou escutar atualizações sobre o status e o progresso. Consulte [Obter status de transferência e progresso](#transfermanager-get-status-and-progress) para obter mais informações. O objeto [MultipleFileUpload](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/MultipleFileUpload.html) retornado por `uploadFileList` pode ser usado para consultar o estado da transferência ou o progresso. Consulte [Sondar o progresso atual de uma transferência](#transfermanager-get-progress-polling) e [Obter o progresso da transferência com um ProgressListener](#transfermanager-progress-listener) para obter mais informações. Você também pode usar o método `MultipleFileUpload` de `getSubTransfers` para obter os objetos `Upload` individuais de cada arquivo transferido. Para obter mais informações, consulte [Obter o progresso de subtransferências](#transfermanager-get-subtransfer-progress). Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrUpload.java) no GitHub. ### Fazer upload de um diretório É possível usar o método `uploadDirectory` do TransferManager para fazer upload de um diretório de arquivos inteiro, com a opção de copiar arquivos em subdiretórios de maneira recursiva. Você fornece um nome de bucket do Amazon S3, um prefixo de chaves do S3, um objeto [File](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html) representando o diretório local para cópia e um valor `boolean` que indica se deseja copiar subdiretórios de maneira recursiva (*verdadeiro* ou *falso*). **Importações** ``` 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; ``` **Código da** ``` 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(); ``` Consulte [Aguardar a conclusão de uma transferência](#transfermanager-wait-for-completion) para obter informações sobre como usar `waitForCompletion` para concluir com êxito uma transferência antes de chamar o método `shutdownNow` do TransferManager. Enquanto aguarda a conclusão da transferência, você pode sondar ou escutar atualizações sobre o status e o progresso. Consulte [Obter status de transferência e progresso](#transfermanager-get-status-and-progress) para obter mais informações. O objeto [MultipleFileUpload](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/MultipleFileUpload.html) retornado por `uploadFileList` pode ser usado para consultar o estado da transferência ou o progresso. Consulte [Sondar o progresso atual de uma transferência](#transfermanager-get-progress-polling) e [Obter o progresso da transferência com um ProgressListener](#transfermanager-progress-listener) para obter mais informações. Você também pode usar o método `MultipleFileUpload` de `getSubTransfers` para obter os objetos `Upload` individuais de cada arquivo transferido. Para obter mais informações, consulte [Obter o progresso de subtransferências](#transfermanager-get-subtransfer-progress). Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrUpload.java) no GitHub. ## Fazer download de arquivos ou diretórios Use a classe TransferManager para fazer download de um único arquivo (objeto do Amazon S3) ou de um diretório (um nome de bucket do Amazon S3 seguido de um prefixo de objeto) do Amazon S3. **Topics** + [Fazer download de um único arquivo](#transfermanager-download-file) + [Fazer download de um diretório](#tranfermanager-download-directory) ### Fazer download de um único arquivo Use o método `download` do TransferManager, fornecendo o nome de bucket do Amazon S3 que contém o objeto cujo download você deseja fazer, o nome da chave (objeto) e um objeto [File](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html) que representa o arquivo a ser criado no sistema local. **Importações** ``` 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; ``` **Código da** ``` 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(); ``` Consulte [Aguardar a conclusão de uma transferência](#transfermanager-wait-for-completion) para obter informações sobre como usar `waitForCompletion` para concluir com êxito uma transferência antes de chamar o método `shutdownNow` do TransferManager. Enquanto aguarda a conclusão da transferência, você pode sondar ou escutar atualizações sobre o status e o progresso. Consulte [Obter status de transferência e progresso](#transfermanager-get-status-and-progress) para obter mais informações. Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrDownload.java) no GitHub. ### Fazer download de um diretório Para fazer download de um conjunto de arquivos que compartilham um mesmo prefixo de chaves (semelhante a um diretório em um sistema de arquivos) do Amazon S3, use o método `downloadDirectory` do TransferManager. O método utiliza o nome de bucket do Amazon S3 que contém os objetos cujo download você deseja fazer, o prefixo do objeto compartilhado por todos os objetos e um objeto [File](https://docs.oracle.com/javase/8/docs/api/index.html?java/io/File.html) que representa o diretório para fazer download dos arquivos no sistema local. Se ainda não existir, o diretório nomeado será criado. **Importações** ``` 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; ``` **Código da** ``` 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(); ``` Consulte [Aguardar a conclusão de uma transferência](#transfermanager-wait-for-completion) para obter informações sobre como usar `waitForCompletion` para concluir com êxito uma transferência antes de chamar o método `shutdownNow` do TransferManager. Enquanto aguarda a conclusão da transferência, você pode sondar ou escutar atualizações sobre o status e o progresso. Consulte [Obter status de transferência e progresso](#transfermanager-get-status-and-progress) para obter mais informações. Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrDownload.java) no GitHub. ## Copiar objetos Para copiar um objeto de um bucket do S3 para outro, use o método `copy` do TransferManager. **Importações** ``` 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; ``` **Código da** ``` 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(); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrCopy.java) no GitHub. ## Aguardar a conclusão de uma transferência Se o aplicativo (ou thread) puder bloquear até a conclusão da transferência, você poderá usar o método `waitForCompletion` da interface [Transfer](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Transfer.html) para bloquear até a transferência estar concluída ou ocorrer uma exceção. ``` 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); } ``` Você obterá o progresso de transferências se sondar eventos *antes* de chamar `waitForCompletion`, implementar um mecanismo de sondagem em um thread separado ou receber atualizações de progresso de maneira assíncrona usando um [ProgressListener](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/event/ProgressListener.html). Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java) no GitHub. ## Obter status da transferência e progresso Cada uma das classes retornadas pelos métodos `upload*`, `download*` e `copy` do TransferManager retorna uma instância de uma das classes a seguir, dependendo da operação ser de arquivo único ou de vários arquivos. **​** | Classe | Retornado por | | --- | --- | | [Copiar](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Copy.html) | `copy` | | [Baixar](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` | | [Carregar](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` | Todas essas classes implementam a interface [Transfer](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Transfer.html). O `Transfer` oferece métodos úteis para obter o progresso de uma transferência, pausar ou retomar a transferência, além de obter o status atual ou final da transferência. **Topics** + [Sondar o progresso atual de uma transferência](#transfermanager-get-progress-polling) + [Obter o progresso da transferência com um ProgressListener](#transfermanager-progress-listener) + [Obter o progresso de subtransferências](#transfermanager-get-subtransfer-progress) ### Sondar o progresso atual de uma transferência Este loop imprime o progresso de uma transferência, examina o progresso atual durante a execução e, quando concluído, imprime o estado final. **Importações** ``` 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; ``` **Código da** ``` // 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); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java) no GitHub. ### Obter o progresso da transferência com um ProgressListener Você pode anexar um [ProgressListener](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/event/ProgressListener.html) a qualquer transferência usando o método `addProgressListener` da interface [Transfer](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Transfer.html). Um [ProgressListener](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/event/ProgressListener.html) exige somente um método, `progressChanged`, que utiliza um objeto [ProgressEvent](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/event/ProgressEvent.html). Você pode usar o objeto para obter o total de bytes da operação chamando o método `getBytes` e o número de bytes transferidos até o momento chamando `getBytesTransferred`. **Importações** ``` 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; ``` **Código da** ``` 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(); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java) no GitHub. ### Obter o progresso de subtransferências A classe [MultipleFileUpload](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/MultipleFileUpload.html) pode retornar informações sobre as subtransferências chamando o método `getSubTransfers`. Isso retorna um [Conjunto](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/Collection.html) de objetos [Upload](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/transfer/Upload.html) que fornecem o status de transferência individual e o progresso de cada subtransferência. **Importações** ``` 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; ``` **Código da** ``` 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); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/XferMgrProgress.java) no GitHub. ## Mais informações + [Chaves de objeto](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html) no Guia do usuário do Amazon Simple Storage Service # Configurar um bucket do Amazon S3 como um site É possível configurar um bucket do Amazon S3 para se comportar como um site. Para isso, você precisa definir a configuração do site. **nota** Esses exemplos de código pressupõem que você entenda o material em [Usar o AWS SDK para Java](basics.md) e tenha configurado credenciais da AWS padrão usando as informações em [Configurar credenciais e região da AWS para desenvolvimento](setup-credentials.md). ## Definir uma configuração do site de um bucket Para definir a configuração do site de um bucket do Amazon S3, chame o método `setWebsiteConfiguration` do AmazonS3 com o nome do bucket para definir a configuração e um objeto [BucketWebsiteConfiguration](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/BucketWebsiteConfiguration.html) contendo a configuração do site do bucket. Configurar um documento de índice é *obrigatório*; todos os outros parâmetros são opcionais. **Importações** ``` 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; ``` **Código da** ``` 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); } ``` **nota** Definir a configuração de um site não modifica as permissões de acesso do bucket. Para tornar os arquivos visíveis na web, você também precisa definir uma *política de bucket* que permite acesso de leitura público aos arquivos no bucket. Para obter mais informações, consulte [Gerenciar acesso aos buckets do Amazon S3 usando políticas de bucket](examples-s3-bucket-policies.md). Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/SetWebsiteConfiguration.java) no GitHub. ## Obter uma configuração do site de um bucket Para obter a configuração do site de um bucket do Amazon S3, chame o método `getWebsiteConfiguration` do AmazonS3 com o nome do bucket cuja configuração recuperar. A configuração será retornada como um objeto [BucketWebsiteConfiguration](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/BucketWebsiteConfiguration.html). Se não houver configuração de site para o bucket, `null` será retornado. **Importações** ``` 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; ``` **Código da** ``` 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); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/GetWebsiteConfiguration.java) no GitHub. ## Excluir uma configuração do site de um bucket Para excluir a configuração do site de um bucket do Amazon S3, chame o método `deleteWebsiteConfiguration` do AmazonS3 com o nome do bucket cuja configuração será excluída. **Importações** ``` import com.amazonaws.AmazonServiceException; import com.amazonaws.regions.Regions; import com.amazonaws.services.s3.AmazonS3; import com.amazonaws.services.s3.AmazonS3ClientBuilder; ``` **Código da** ``` 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); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/DeleteWebsiteConfiguration.java) no GitHub. ## Mais informações + [PUT Bucket website](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTwebsite.html) na Referência de API do Amazon S3 + [GET Bucket website](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketGETwebsite.html) na Referência de API do Amazon S3 + [DELETE Bucket website](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketDELETEwebsite.html) na Referência de API do Amazon S3 # Usar criptografia do lado do cliente do Amazon S3 Criptografar dados usando o cliente de criptografia do Amazon S3 é uma maneira de fornecer uma camada adicional de proteção para informações confidenciais armazenadas no Amazon S3. Os exemplos nesta seção demonstram como criar e configurar o cliente de criptografia do Amazon S3 para seu aplicativo. Se você for novo em criptografia, consulte [Conceitos básicos de criptografia](https://docs.aws.amazon.com/kms/latest/developerguide/crypto-intro.html) no Guia do desenvolvedor do AWS KMS para uma visão geral básica dos termos e algoritmos de criptografia. Para obter informações sobre suporte à criptografia em todos os SDKs da AWS, consulte [Suporte do AWS SDK à criptografia do lado do cliente do Amazon S3](https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html) na Referência geral da Amazon Web Services. **nota** Esses exemplos de código pressupõem que você entenda o material em [Usar o AWS SDK para Java](basics.md) e tenha configurado credenciais da AWS padrão usando as informações em [Configurar credenciais e região da AWS para desenvolvimento](setup-credentials.md). Se você estiver usando a versão 1.11.836 ou anterior do AWS SDK para Java, consulte [Migração do cliente de criptografia do Amazon S3](s3-encryption-migration.md) para obter informações sobre como migrar seus aplicativos para versões posteriores. Se você não conseguir migrar, consulte [este exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/S3Encrypt.java) no GitHub. Caso contrário, se você estiver usando a versão 1.11.837 ou posterior do AWS SDK para Java, explore os tópicos de exemplo listados abaixo para usar a criptografia do lado do cliente do Amazon S3. **Topics** + [Criptografia do lado do cliente do Amazon S3 com chaves mestras do lado do cliente](examples-crypto-masterkey.md) + [Criptografia do lado do cliente do Amazon S3 com chaves gerenciadas do AWS KMS](examples-crypto-kms.md) # Criptografia do lado do cliente do Amazon S3 com chaves mestras do lado do cliente Os exemplos a seguir usam a classe [AmazonS3EncryptionClientV2Builder](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/AmazonS3EncryptionClientV2Builder.html) para criar um cliente do Amazon S3 com criptografia do lado do cliente ativada. Uma vez ativado, todo objeto que você enviar para o Amazon S3 usando este cliente será criptografado. Todos os objetos obtidos no Amazon S3 por meio deste cliente são automaticamente descriptografados. **nota** Os exemplos a seguir demonstram como usar a criptografia do lado do cliente do Amazon S3 com as chaves mestres clientes gerenciadas do cliente. Para aprender a usar criptografia com chaves gerenciadas pelo AWS KMS, consulte [Criptografia do lado do cliente do Amazon S3 com chaves gerenciadas do AWS KMS](examples-crypto-kms.md). Você pode escolher um dos dois modos de criptografia ao ativar a criptografia do lado do cliente do Amazon S3: rigorosa autenticada ou autenticada. As seções a seguir mostram como ativar cada tipo. Para saber quais algoritmos cada modo usa, consulte a definição [CryptoMode](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/CryptoMode.html). ## Requer importações Importe as seguintes classes para esses exemplos. **Importações** ``` 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; ``` ## Criptografia rigorosa autenticada A criptografia rigorosa autenticada é o modo padrão se nenhum `CryptoMode` for especificado. Para ativar explicitamente este modo, especifique o valor `StrictAuthenticatedEncryption` no método `withCryptoConfiguration`. **nota** Para usar criptografia autenticada do lado do cliente, você precisa incluir o arquivo [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) mais recente no caminho de classe do seu aplicativo. **Código da** ``` 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"); ``` ## Modo de criptografia autenticada Quando você usa o modo `AuthenticatedEncryption`, um algoritmo de encapsulamento de chave aprimorado é aplicado durante a criptografia. Ao descriptografar nesse modo, o algoritmo verifica a integridade do objeto descriptografado e lança uma exceção se a verificação falhar. Para obter mais detalhes sobre como a criptografia autenticada funciona, consulte a postagem do blog [Criptografia autenticada no lado do cliente do Amazon S3](https://aws.amazon.com/blogs/developer/amazon-s3-client-side-authenticated-encryption). **nota** Para usar criptografia autenticada do lado do cliente, você precisa incluir o arquivo [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) mais recente no caminho de classe do seu aplicativo. Para ativar este modo, especifique o valor `AuthenticatedEncryption` no método `withCryptoConfiguration`. **Código da** ``` 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"); ``` # Criptografia do lado do cliente do Amazon S3 com chaves gerenciadas do AWS KMS Os exemplos a seguir usam a classe [AmazonS3EncryptionClientV2Builder](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/AmazonS3EncryptionClientV2Builder.html) para criar um cliente do Amazon S3 com criptografia do lado do cliente ativada. Uma vez configurado, todo objeto que você enviar para o Amazon S3 usando este cliente será criptografado. Todos os objetos obtidos no Amazon S3 por meio deste cliente são automaticamente descriptografados. **nota** Os exemplos a seguir demonstram como usar a criptografia do lado do cliente do Amazon S3 com as chaves gerenciadas do AWS KMS. Para aprender a usar criptografia com suas próprias chaves, consulte [Criptografia do lado do cliente do Amazon S3 com chaves mestras de cliente](examples-crypto-masterkey.md). Você pode escolher um dos dois modos de criptografia ao ativar a criptografia do lado do cliente do Amazon S3: rigorosa autenticada ou autenticada. As seções a seguir mostram como ativar cada tipo. Para saber quais algoritmos cada modo usa, consulte a definição [CryptoMode](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/CryptoMode.html). ## Requer importações Importe as seguintes classes para esses exemplos. **Importações** ``` 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; ``` ## Criptografia rigorosa autenticada A criptografia rigorosa autenticada é o modo padrão se nenhum `CryptoMode` for especificado. Para ativar explicitamente este modo, especifique o valor `StrictAuthenticatedEncryption` no método `withCryptoConfiguration`. **nota** Para usar criptografia autenticada do lado do cliente, você precisa incluir o arquivo [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) mais recente no caminho de classe do seu aplicativo. **Código da** ``` 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)); ``` Chame o método `putObject` no cliente de criptografia do Amazon S3 para os objetos de upload. **Código da** ``` s3Encryption.putObject(bucket_name, ENCRYPTED_KEY3, "This is the 3rd content to encrypt with a key created in the {console}"); ``` Você pode recuperar o objeto usando o mesmo cliente. Este exemplo chama o método `getObjectAsString` para recuperar a string que foi armazenada. **Código da** ``` System.out.println(s3Encryption.getObjectAsString(bucket_name, ENCRYPTED_KEY3)); ``` ## Modo de criptografia autenticada Quando você usa o modo `AuthenticatedEncryption`, um algoritmo de encapsulamento de chave aprimorado é aplicado durante a criptografia. Ao descriptografar nesse modo, o algoritmo verifica a integridade do objeto descriptografado e lança uma exceção se a verificação falhar. Para obter mais detalhes sobre como a criptografia autenticada funciona, consulte a postagem do blog [Criptografia autenticada no lado do cliente do Amazon S3](https://aws.amazon.com/blogs/developer/amazon-s3-client-side-authenticated-encryption). **nota** Para usar criptografia autenticada do lado do cliente, você precisa incluir o arquivo [Bouncy Castle jar](https://www.bouncycastle.org/download/bouncy-castle-java/) mais recente no caminho de classe do seu aplicativo. Para ativar este modo, especifique o valor `AuthenticatedEncryption` no método `withCryptoConfiguration`. **Código da** ``` AmazonS3EncryptionV2 s3Encryption = AmazonS3EncryptionClientV2Builder.standard() .withRegion(Regions.US_WEST_2) .withCryptoConfiguration(new CryptoConfigurationV2().withCryptoMode((CryptoMode.AuthenticatedEncryption))) .withEncryptionMaterialsProvider(new KMSEncryptionMaterialsProvider(keyId)) .build(); ``` ## Configurar o cliente do AWS KMS O cliente de criptografia do Amazon S3 cria um cliente do AWS KMS por padrão, a menos que um seja explicitamente especificado. Para definir a região desse cliente do AWS KMS criado automaticamente, defina a`awsKmsRegion`. **Código da** ``` 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(); ``` Se preferir, pode usar seu próprio cliente do AWS KMS para inicializar o cliente de criptografia. **Código da** ``` 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 Exemplos de usando a AWS SDK para Java Esta seção apresenta exemplos de como programar o [Amazon SQS](https://aws.amazon.com/sqs/) usando o [AWS SDK para Java](https://aws.amazon.com/sdk-for-java/). **nota** Entre os exemplos está somente o código necessário para demonstrar cada técnica. O [código de exemplo completo está disponível no GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java). A partir daí, você pode fazer download de um único arquivo de origem ou clonar o repositório de maneira local para obter todos os exemplos para compilação e execução. **Topics** + [Trabalhar com filas de mensagens do Amazon SQS](examples-sqs-message-queues.md) + [Enviar, receber e excluir mensagens do Amazon SQS](examples-sqs-messages.md) + [Habilitar sondagem longa para filas de mensagens do Amazon SQS](examples-sqs-long-polling.md) + [Definir tempo limite de visibilidade no Amazon SQS](examples-sqs-visibility-timeout.md) + [Usar fila de mensagens mortas no Amazon SQS](examples-sqs-dead-letter-queues.md) # Trabalhar com filas de mensagens do Amazon SQS Uma *fila de mensagens* é o contêiner lógico usado para enviar mensagens de maneira confiável no Amazon SQS. Existem dois tipos de filas: *padrão* e *First-In, First-Out* (FIFO – Primeiro a entrar, primeiro a sair). Para saber mais sobre as filas e as diferenças entre esses tipos, consulte o [Guia do desenvolvedor do Amazon SQS](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/). Este tópico descreve como criar, listar, excluir e obter o URL de uma fila do Amazon SQS usando o AWS SDK para Java. ## Criar uma fila Use o método `createQueue` do cliente do AmazonSQS fornecendo um objeto [CreateQueueRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/CreateQueueRequest.html) que descreve os parâmetros de fila. **Importações** ``` 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; ``` **Código da** ``` 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; } } ``` Você pode usar a forma simplificada de `createQueue`, que precisa somente do nome de uma fila, para criar uma fila padrão. ``` sqs.createQueue("MyQueue" + new Date().getTime()); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java) no GitHub. ## Listar filas Para listar as filas do Amazon SQS da conta, chame o método `listQueues` do cliente do AmazonSQS. **Importações** ``` import com.amazonaws.services.sqs.AmazonSQS; import com.amazonaws.services.sqs.AmazonSQSClientBuilder; import com.amazonaws.services.sqs.model.ListQueuesResult; ``` **Código da** ``` 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); } ``` Usar a sobrecarga `listQueues` sem parâmetros retorna *todas as filas*. Você pode filtrar os resultados retornados passando um objeto `ListQueuesRequest`. **Importações** ``` import com.amazonaws.services.sqs.AmazonSQS; import com.amazonaws.services.sqs.AmazonSQSClientBuilder; import com.amazonaws.services.sqs.model.ListQueuesRequest; ``` **Código da** ``` 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); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java) no GitHub. ## Obter o URL de uma fila Chame o método `getQueueUrl` do cliente do AmazonSQS. **Importações** ``` import com.amazonaws.services.sqs.AmazonSQS; import com.amazonaws.services.sqs.AmazonSQSClientBuilder; ``` **Código da** ``` AmazonSQS sqs = AmazonSQSClientBuilder.defaultClient(); String queue_url = sqs.getQueueUrl(QUEUE_NAME).getQueueUrl(); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java) no GitHub. ## Excluir uma fila Forneça o [URL](#sqs-get-queue-url) da fila para o método `deleteQueue` do cliente do AmazonSQS. **Importações** ``` import com.amazonaws.services.sqs.AmazonSQS; import com.amazonaws.services.sqs.AmazonSQSClientBuilder; ``` **Código da** ``` AmazonSQS sqs = AmazonSQSClientBuilder.defaultClient(); sqs.deleteQueue(queue_url); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/UsingQueues.java) no GitHub. ## Mais informações + [Como as filas do Amazon SQS funcionam](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-how-it-works.html) no Guia do Desenvolvedor do Amazon SQS + [CreateQueue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_CreateQueue.html) na Referência de API do Amazon SQS + [GetQueueUrl](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_GetQueueUrl.html) na Referência de API do Amazon SQS + [ListQueues](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ListQueues.html) na Referência de API do Amazon SQS + [DeleteQueues](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteQueues.html) na Referência de API do Amazon SQS # Enviar, receber e excluir mensagens do Amazon SQS Este tópico descreve como enviar, receber e excluir mensagens do Amazon SQS. As mensagens são sempre entregues usando-se uma [fila do SQS](examples-sqs-message-queues.md). ## Enviar uma mensagem Adicione uma mensagem única a uma fila do Amazon SQS chamando o método `sendMessage` do cliente do AmazonSQS. Forneça um objeto [SendMessageRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/SendMessageRequest.html) que contenha o [URL](examples-sqs-message-queues.md#sqs-get-queue-url) da fila, o corpo da mensagem e o valor de atraso opcional (em segundos). **Importações** ``` import com.amazonaws.services.sqs.AmazonSQS; import com.amazonaws.services.sqs.AmazonSQSClientBuilder; import com.amazonaws.services.sqs.model.SendMessageRequest; ``` **Código da** ``` SendMessageRequest send_msg_request = new SendMessageRequest() .withQueueUrl(queueUrl) .withMessageBody("hello world") .withDelaySeconds(5); sqs.sendMessage(send_msg_request); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/SendReceiveMessages.java) no GitHub. ### Enviar várias mensagens de uma só vez Você pode enviar mais de uma mensagem em uma única solicitação. Para enviar várias mensagens, use o método `sendMessageBatch` do cliente do AmazonSQS, que utiliza um [SendMessageBatchRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/SendMessageBatchRequest.html) que contém o URL da fila e uma lista de mensagens (cada uma sendo um [SendMessageBatchRequestEntry](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/SendMessageBatchRequestEntry.html)) a serem enviadas. Você também pode definir um valor de atraso opcional por mensagem. **Importações** ``` import com.amazonaws.services.sqs.model.SendMessageBatchRequest; import com.amazonaws.services.sqs.model.SendMessageBatchRequestEntry; ``` **Código da** ``` 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); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/SendReceiveMessages.java) no GitHub. ## Receber mensagens Recupere todas as mensagens que estejam atualmente na fila chamando o método `receiveMessage` do cliente do AmazonSQS, passando o URL da fila. As mensagens são retornadas como uma lista de objetos [Message](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/Message.html). **Importações** ``` import com.amazonaws.services.sqs.AmazonSQSClientBuilder; import com.amazonaws.services.sqs.model.AmazonSQSException; import com.amazonaws.services.sqs.model.SendMessageBatchRequest; ``` **Código da** ``` List messages = sqs.receiveMessage(queueUrl).getMessages(); ``` ## Excluir mensagens depois do recebimento Após receber uma mensagem e processar o conteúdo, exclua a mensagem da fila enviando o identificador de recebimento da mensagem e o URL da fila para o método `deleteMessage` de cliente do AmazonSQS. **Código da** ``` for (Message m : messages) { sqs.deleteMessage(queueUrl, m.getReceiptHandle()); } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/SendReceiveMessages.java) no GitHub. ## Mais informações + [Como as filas do Amazon SQS funcionam](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-how-it-works.html) no Guia do Desenvolvedor do Amazon SQS + [SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html) na Referência de API do Amazon SQS + [SendMessageBatch](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html) na Referência de API do Amazon SQS + [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) na Referência de API do Amazon SQS + [DeleteMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html) na Referência de API do Amazon SQS # Habilitar sondagem longa para filas de mensagens do Amazon SQS Por padrão, o Amazon SQS usa a *sondagem curta*, consultando apenas um subconjunto dos servidores (com base na distribuição aleatória ponderada) para determinar se as mensagens estão disponíveis para inclusão na resposta. A sondagem longa ajuda a reduzir o custo de usar o Amazon SQS reduzindo o número de respostas vazias quando não há mensagens disponíveis para serem retornadas em resposta a uma solicitação ReceiveMessage enviada para uma fila do Amazon SQS e eliminando respostas vazias falsas. **nota** Você pode definir uma frequência de sondagem longa de *1 a 20 segundos*. ## Habilitar sondagem longa ao criar uma fila Para habilitar a sondagem longa ao criar uma fila do Amazon SQS, defina o atributo `ReceiveMessageWaitTimeSeconds` no objeto [CreateQueueRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/CreateQueueRequest.html) antes de chamar o método `createQueue` de classe do AmazonSQS. **Importações** ``` 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; ``` **Código da** ``` 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; } } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/LongPolling.java) no GitHub. ## Habilitar sondagem longa em uma fila existente Além de habilitar a sondagem longa ao criar uma fila, você também pode habilitá-la em uma fila existente definindo `ReceiveMessageWaitTimeSeconds` no [SetQueueAttributesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/SetQueueAttributesRequest.html) antes de chamar o método `setQueueAttributes` de classe do AmazonSQS. **Importações** ``` import com.amazonaws.services.sqs.model.SetQueueAttributesRequest; ``` **Código da** ``` SetQueueAttributesRequest set_attrs_request = new SetQueueAttributesRequest() .withQueueUrl(queue_url) .addAttributesEntry("ReceiveMessageWaitTimeSeconds", "20"); sqs.setQueueAttributes(set_attrs_request); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/LongPolling.java) no GitHub. ## Habilitar sondagem longa no recebimento da mensagem Você pode habilitar a sondagem longa ao receber uma mensagem definindo o tempo de espera em segundos no [ReceiveMessageRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/ReceiveMessageRequest.html) fornecido por você ao método `receiveMessage` de classe do AmazonSQS. **nota** É necessário verificar se o tempo limite da solicitação do cliente da AWS é maior que o tempo de sondagem longa máximo (20 segundos), de forma que as solicitações `receiveMessage` não expirem enquanto esperam o próximo evento de sondagem. **Importações** ``` import com.amazonaws.services.sqs.model.ReceiveMessageRequest; ``` **Código da** ``` ReceiveMessageRequest receive_request = new ReceiveMessageRequest() .withQueueUrl(queue_url) .withWaitTimeSeconds(20); sqs.receiveMessage(receive_request); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/LongPolling.java) no GitHub. ## Mais informações + [Sondagem longa do Amazon SQS](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-long-polling.html) no Guia do desenvolvedor do Amazon SQS + [CreateQueue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_CreateQueue.html) na Referência de API do Amazon SQS + [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) na Referência de API do Amazon SQS + [SetQueueAttributes](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SetQueueAttributes.html) na Referência de API do Amazon SQS # Definir tempo limite de visibilidade no Amazon SQS Quando for recebida no Amazon SQS, uma mensagem permanecerá na fila até ser excluída para garantir o recebimento. Uma mensagem que foi recebida, mas não excluída, estará disponível em requisições subsequentes depois de um determinado *tempo limite de visibilidade* para ajudar a evitar que a mensagem seja recebida mais de uma vez antes de ser processada e excluída. **nota** Ao usar [filas padrão](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/standard-queues.html), o tempo limite de visibilidade não é uma garantia em relação ao recebimento de uma mensagem duas vezes. Se você estiver usando uma fila padrão, verifique se o código pode processar o caso em que a mesma mensagem foi entregue mais de uma vez. ## Definir o tempo limite de visibilidade da mensagem para uma única mensagem Quando tiver recebido uma mensagem, você poderá modificar o tempo limite de visibilidade passando o identificador de recebimento em um [ChangeMessageVisibilityRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/ChangeMessageVisibilityRequest.html) passado para o método `changeMessageVisibility` da classe do AmazonSQS. **Importações** ``` import com.amazonaws.services.sqs.AmazonSQS; import com.amazonaws.services.sqs.AmazonSQSClientBuilder; ``` **Código da** ``` 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); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/VisibilityTimeout.java) no GitHub. ## Definir o tempo limite de visibilidade da mensagem para várias mensagens de uma só vez Para definir o tempo limite de visibilidade da mensagem para várias mensagens de uma só vez, crie uma lista de objetos [ChangeMessageVisibilityBatchRequestEntry](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/ChangeMessageVisibilityBatchRequestEntry.html), cada um contendo uma string de ID exclusiva e um identificador de recebimento. Em seguida, passe a lista para o método Amazon SQS da classe de cliente do `changeMessageVisibilityBatch`. **Importações** ``` 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; ``` **Código da** ``` 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); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/VisibilityTimeout.java) no GitHub. ## Mais informações + [Tempo limite de visibilidade](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html) no Guia do desenvolvedor do Amazon SQS + [SetQueueAttributes](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SetQueueAttributes.html) na Referência de API do Amazon SQS + [GetQueueAttributes](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_GetQueueAttributes.html) na Referência de API do Amazon SQS + [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) na Referência de API do Amazon SQS + [ChangeMessageVisibility](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ChangeMessageVisibility.html) na Referência de API do Amazon SQS + [ChangeMessageVisibilityBatch](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ChangeMessageVisibilityBatch.html) na Referência de API do Amazon SQS # Usar fila de mensagens mortas no Amazon SQS O Amazon SQS fornece suporte para *filas de mensagens mortas*. Uma fila de mensagens mortas é uma fila para a qual outras filas (de origem) podem enviar as mensagens que não são processadas com êxito. Você pode separar e isolar essas mensagens na dead letter queue para determinar por que o processamento não teve sucesso. ## Criar uma dead letter queue Uma dead letter queue é criada da mesma maneira que uma fila regular, mas tem as seguintes restrições: + Uma dead letter queue deve ter o mesmo tipo de fila (FIFO ou padrão) da fila de origem. + Uma fila de mensagens não entregues deve ser criada usando-se a mesma Conta da AWS e região da fila de origem. Criamos aqui duas filas do Amazon SQS idênticas, uma que funcionará como a dead letter queue: **Importações** ``` import com.amazonaws.services.sqs.AmazonSQS; import com.amazonaws.services.sqs.AmazonSQSClientBuilder; import com.amazonaws.services.sqs.model.AmazonSQSException; ``` **Código da** ``` 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; } } ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/DeadLetterQueues.java) no GitHub. ## Designar uma dead letter queue para uma fila de origem Para designar uma fila de mensagens mortas, é necessário criar primeiro uma *política de redirecionamento* e definir a política nos atributos da fila. Uma política de redirecionamento é especificada em JSON e determina o ARN da fila de mensagens mortas, além do número máximo de vezes em que a mensagem pode ser recebida e não processada antes ser enviada para a fila de mensagens mortas. Para definir a política de redirecionamento para a fila de origem, chame o método `setQueueAttributes` da classe do AmazonSQS com um objeto [SetQueueAttributesRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/sqs/model/SetQueueAttributesRequest.html) para o qual você definiu o atributo `RedrivePolicy` com a política de redirecionamento JSON. **Importações** ``` import com.amazonaws.services.sqs.model.GetQueueAttributesRequest; import com.amazonaws.services.sqs.model.GetQueueAttributesResult; import com.amazonaws.services.sqs.model.SetQueueAttributesRequest; ``` **Código da** ``` 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); ``` Veja o [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/sqs/src/main/java/aws/example/sqs/DeadLetterQueues.java) no GitHub. ## Mais informações + [Usar filas de mensagens não entregues doAmazon SQS](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html) no Guia do desenvolvedor do Amazon SQS + [SetQueueAttributes](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SetQueueAttributes.html) na Referência de API do Amazon SQS # Amazon SWF Exemplos de usando a AWS SDK para Java O[Amazon SWF](https://aws.amazon.com/swf/) é um serviço de gerenciamento de fluxo de trabalho que ajuda desenvolvedores a compilar e escalar fluxos de trabalho distribuídos que tenham etapas paralelas ou sequenciais que consistem em atividades, fluxos de trabalho filho ou até mesmo tarefas [Lambda](https://aws.amazon.com/lambda/). Existem duas maneiras de trabalhar com o Amazon SWF usando o AWS SDK para Java: com o objeto *client* do SWF ou usando o AWS Flow Framework para Java. O AWS Flow Framework para Java é mais difícil de configurar inicialmente, porque ele usa muitas anotações e conta com bibliotecas adicionais, como AspectJ e Spring Framework. No entanto, para projetos grandes ou complexos, você economizará tempo de codificação usando o AWS Flow Framework para Java. Para obter mais informações, consulte o [Guia do desenvolvedor do AWS Flow Framework para Java](https://docs.aws.amazon.com/amazonswf/latest/awsflowguide/). Esta seção apresenta exemplos de como programar o Amazon SWF usando o cliente do AWS SDK para Java diretamente. **Topics** + [Conceitos básicos do SWF](swf-basics.md) + [Compilar um aplicativo do Amazon SWF simples](swf-hello.md) + [LambdaTarefas do](swf-lambda-task.md) + [Desligar operadores de atividade e de fluxo de trabalho de maneira tranquila](swf-graceful-shutdown.md) + [Registro de domínios](prog-services-swf-register-domain.md) + [Listar domínios](prog-services-swf-list-domains.md) # Conceitos básicos do SWF Esses são padrões gerais para trabalhar com o Amazon SWF usando o AWS SDK para Java. Ele foi desenvolvido principalmente para referência. Para obter um tutorial introdutório mais completo, consulte [Compilar um aplicativo do Amazon SWF simples](swf-hello.md). ## Dependências Os aplicativos do Amazon SWF básicos exigem as seguintes dependências, incluídas com o AWS SDK para Java: + 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 **nota** Os números da versão desses pacotes serão diferentes dependendo da versão do SDK que você tiver, mas as versões fornecidas com o SDK foram testadas em termos de compatibilidade e são as que deve usar. Os aplicativos do AWS Flow Framework para Java exigem configuração adicional *e* dependências adicionais. Consulte o [Guia do desenvolvedor do AWS Flow Framework para Java](https://docs.aws.amazon.com/amazonswf/latest/awsflowguide/) para obter mais informações sobre como usar a estrutura. ## Importações Em geral, você pode usar as seguintes importações no desenvolvimento de código: ``` import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflowClientBuilder; import com.amazonaws.services.simpleworkflow.model.*; ``` Porém, é uma boa prática importar somente as classes necessárias. Você provavelmente acabará especificando determinadas classes no espaço de trabalho `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; ``` Se estiver usando o AWS Flow Framework para Java, você importará classes do espaço de trabalho `com.amazonaws.services.simpleworkflow.flow`. Por exemplo: ``` import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflow; import com.amazonaws.services.simpleworkflow.flow.ActivityWorker; ``` **nota** O AWS Flow Framework para Java tem requisitos adicionais além dos AWS SDK para Java base. Para obter mais informações, consulte o [Guia do desenvolvedor do AWS Flow Framework para Java](https://docs.aws.amazon.com/amazonswf/latest/awsflowguide/). ## Usar a classe de cliente do SWF A interface básica do Amazon SWF é por meio das classes [AmazonSimpleWorkflowClient](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/AmazonSimpleWorkflowClient.html) ou [AmazonSimpleWorkflowAsyncClient](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/AmazonSimpleWorkflowAsyncClient.html). A principal diferença entre elas é que a classe `\*AsyncClient` retorna objetos [Future](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/concurrent/Future.html) para programação simultânea (assíncrona). ``` AmazonSimpleWorkflowClient swf = AmazonSimpleWorkflowClientBuilder.defaultClient(); ``` # Compilar um aplicativo do Amazon SWF simples Este tópico apresentará você à programação de aplicativos do [Amazon SWF](https://aws.amazon.com/swf/) com o AWS SDK para Java, ao mesmo tempo em que apresenta alguns conceitos importantes. ## Sobre o exemplo O projeto de exemplo criará um fluxo de trabalho com uma única atividade que aceita dados do fluxo de trabalho passados pela Nuvem AWS (na tradição de HelloWorld, ele será o nome de alguém a ser cumprimentado) e imprimir um cumprimento em resposta. Embora isso pareça muito simples superficialmente, os aplicativos do Amazon SWF consistem em várias partes funcionando juntas: + Um **domínio**, usado como um contêiner lógico para os dados de execução do fluxo de trabalho. + Um ou mais **fluxos de trabalho** que representam os componentes de código que definem a ordem lógica de execução das atividades do fluxo de trabalho e dos fluxos de trabalho filhos. + Um **operador de fluxo de trabalho**, também conhecido como *administrador*, que faça uma sondagem de tarefas de decisão e programe atividades ou fluxos de trabalho filhos em resposta. + Uma ou mais **atividades**, cada uma delas representando uma unidade de trabalho no fluxo de trabalho. + Um **operador de atividade** que faz uma sondagem de tarefas de atividade e executa métodos de atividade em resposta. + Uma ou mais **listas de tarefas**, que são filas mantidas pelo Amazon SWF usadas a fim de emitir requisições para os operadores de fluxo de trabalho e atividade. As tarefas em uma lista indicadas para operadores de fluxo de trabalho são chamadas de *tarefas de decisão*. As destinadas a operadores de atividade são chamadas de *tarefas de atividade*. + Um **início de fluxo de trabalho** que inicia a execução do fluxo de trabalho. Nos bastidores, o Amazon SWF orquestra a operação desses componentes, coordenando o fluxo da Nuvem AWS, passando dados entre eles, processando tempos limite e notificações de pulsação, além de registrar em log o histórico de execuções do fluxo de trabalho. ## Pré-requisitos ### Ambiente de desenvolvimento O ambiente de desenvolvimento usado neste tutorial consiste em: + O [AWS SDK para Java](https://aws.amazon.com/sdk-for-java/). + [Apache Maven](http://maven.apache.org/) (3.3.1). + JDK 1.7 ou posterior. Este tutorial foi desenvolvido e testado usando-se o JDK 1.8.0. + Um bom editor de textos do Java (sua escolha). **nota** Se usar um sistema de compilação diferente de Maven, você ainda poderá criar um projeto usando as etapas apropriadas ao ambiente e usar os conceitos fornecidos aqui para acompanhar. Mais informações sobre como configurar e usar o AWS SDK para Java com diversos sistemas de compilação são fornecidas em [Conceitos básicos](getting-started.md). Da mesma forma, mas com mais esforço, as etapas mostradas aqui podem ser implementadas usando-se qualquer um dos SDKs da AWS compatíveis com o Amazon SWF. Todas as dependências externas necessárias estão incluídas com o AWS SDK para Java. Dessa maneira, não há mais nada para fazer download. ### Acesso da AWS Para trabalhar com sucesso neste tutorial, você deve ter acesso ao portal de acesso da AWS, conforme [descrito na seção de configuração básica](signup-create-iam-user.md#signup-create-iam-user-overview) deste guia. As instruções descrevem como acessar as credenciais temporárias que você copia e cola no arquivo compartilhado local de `credentials`. As credenciais temporárias que você cola devem estar associadas a um perfil do IAM no Centro de Identidade do AWS IAM que tenha permissões para acessar o Amazon SWF. Depois de colar as credenciais temporárias, o arquivo `credentials` será semelhante ao seguinte. ``` [default] aws_access_key_id=AKIAIOSFODNN7EXAMPLE aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY aws_session_token=IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE ``` Essas credenciais temporárias estão associadas ao perfil `default`. ## Criar um projeto SWF 1. Inicie um novo projeto com o Maven: ``` mvn archetype:generate -DartifactId=helloswf \ -DgroupId=aws.example.helloswf -DinteractiveMode=false ``` Isso criará um novo projeto com uma estrutura de projeto maven padrão: ``` helloswf ├── pom.xml └── src ├── main │   └── java │   └── aws │   └── example │   └── helloswf │   └── App.java └── test └── ... ``` É possível ignorar ou excluir o diretório `test` e tudo o que ele contiver, e não usaremos isso neste tutorial. Também é possível excluir `App.java`, porque o substituiremos por novas classes. 1. Edite o arquivo `pom.xml` do projeto e adicione o módulo **aws-java-sdk-simpleworkflow** incluindo uma dependência para ele dentro do bloco ``. ``` com.amazonaws aws-java-sdk-simpleworkflow 1.11.1000 ``` 1. *Verifique se o Maven compila o projeto com suporte ao JDK 1.7\$1*. Adicione o seguinte ao projeto (antes ou depois do bloco ``) em `pom.xml`: ``` maven-compiler-plugin 3.6.1 1.8 1.8 ``` ## Codificar o projeto O projeto de exemplo consistirá em quatro aplicativos separados, que analisaremos um por um: + **HelloTypes.java**: contém o domínio do projeto, a atividade e os dados do tipo de fluxo de trabalho, compartilhados com os outros componentes. Ele também processa como registrar esses tipos com SWF. + **ActivityWorker.java**: contém o operador de atividade, que faz uma sondagem de tarefas de atividade e executa atividades em resposta. + **WorkflowWorker.java**: contém o operador de fluxo de trabalho (administrador), que faz uma sondagem de tarefas de administração e programa novas atividades. + **WorkflowStarter.java**: contém o início do fluxo de trabalho, que inicia uma nova execução de fluxo de trabalho, o que fará o SWF começar a gerar tarefas de decisão e fluxo de trabalho para consumo pelos operadores. ### Etapas comuns a todos os arquivos de origem Todos os arquivos criados por você para hospedar as classes do Java terão algumas coisas em comum. Pensando no tempo, essas etapas *serão implícitas sempre que você adicionar um novo arquivo ao projeto*: 1. Crie o arquivo no diretório `src/main/java/aws/example/helloswf/` do projeto. 1. Adicione uma declaração `package` ao início de cada arquivo para declarar o namespace. O projeto de exemplo usa: ``` package aws.example.helloswf; ``` 1. Adicione declarações `import` para a classe [AmazonSimpleWorkflowClient](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/AmazonSimpleWorkflowClient.html) e para várias classes no namespace `com.amazonaws.services.simpleworkflow.model`. Para simplificar, usaremos: ``` import com.amazonaws.regions.Regions; import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflow; import com.amazonaws.services.simpleworkflow.AmazonSimpleWorkflowClientBuilder; import com.amazonaws.services.simpleworkflow.model.*; ``` ### Registrar um domínio, tipos de fluxo de trabalho e de atividade Começaremos criando uma classe executável, `HelloTypes.java`. Este arquivo conterá dados compartilhados que partes diferentes do fluxo de trabalho precisarão conhecer, como o nome e a versão dos tipos de atividade e de fluxo de trabalho, o nome de domínio e o nome da lista de tarefas. 1. Abra o editor de textos e crie o arquivo `HelloTypes.java`, adicionando uma declaração de pacote e importações de acordo com as [etapas comuns](#swf-hello-common). 1. Declare a classe `HelloTypes` e atribua a ela valores a serem usados nos tipos de atividade e fluxo de trabalho registrados: ``` 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"; ``` Esses valores serão usados em todo o código. 1. Após as declarações String, crie uma instância da classe [AmazonSimpleWorkflowClient](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/AmazonSimpleWorkflowClient.html). Trata-se da interface básica para os métodos do Amazon SWF fornecidos pelo AWS SDK para Java. ``` private static final AmazonSimpleWorkflow swf = AmazonSimpleWorkflowClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build(); ``` O trecho anterior pressupõe que as credenciais temporárias estejam associadas ao perfil `default`. Se você usar um perfil diferente, modifique o código acima da seguinte forma e substitua *profile\$1name* pelo verdadeiro nome do perfil. ``` private static final AmazonSimpleWorkflow swf = AmazonSimpleWorkflowClientBuilder .standard() .withCredentials(new ProfileCredentialsProvider("profile_name")) .withRegion(Regions.DEFAULT_REGION) .build(); ``` 1. Adicione uma nova função para registrar um domínio do SWF. *Domínio* é um contêiner lógico para uma série de tipos de atividade e de fluxo de trabalho do SWF relacionados. Os componentes do SWF só poderão se comunicar entre si se estiverem no mesmo domínio. ``` 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!"); } ``` Ao registrar um domínio, você dá a ele um *nome* (qualquer conjunto de 1 a 256 caracteres, exceto `:`, `/`, `|`, caracteres de controle ou a string literal “arn”) e um *período de retenção*, que é o número de dias por que o Amazon SWF manterá os dados do histórico de execução do fluxo de trabalho depois que uma execução do fluxo de trabalho tiver sido concluída. O período de retenção da execução do fluxo de trabalho máximo é 90 dias. Consulte [RegisterDomainRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/RegisterDomainRequest.html) para obter informações. Se já houver um domínio com esse nome, um [DomainAlreadyExistsException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/DomainAlreadyExistsException.html) será lançado. Como não estamos preocupados se o domínio já foi criado, podemos ignorar a exceção. **nota** Esse código demonstra um padrão comum durante o trabalho com métodos do AWS SDK para Java, e os dados do método são fornecidos por uma classe no namespace `simpleworkflow.model`, que você instancia e preenche usando os métodos `–0—with*` em cadeia. 1. Adicione uma função para registrar um novo tipo de atividade. Uma *atividade* representa uma unidade de trabalho no fluxo de trabalho. ``` 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!"); } ``` Um tipo de atividade é identificado por um *nome* e uma *versão*, usados para identificar com exclusividade a atividade em quaisquer outros no domínio em que esteja registrado. As atividades também contêm alguns parâmetros opcionais, como a task-list padrão usada para receber tarefas e dados do SWF e alguns tempos limite diferentes que podem ser usados por você para impor restrições ao tempo em que partes diferentes da execução da atividade podem demorar. Consulte [RegisterActivityTypeRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/RegisterActivityTypeRequest.html) para obter mais informações. **nota** Todos os valores de tempo limite estão especificados em *segundos*. Consulte [Tipos de tempo limite do Amazon SWF](https://docs.aws.amazon.com/amazonswf/latest/developerguide/swf-timeout-types.html) para obter uma descrição completa de como tempos limite afetam as execuções de fluxo de trabalho. Se o tipo de atividade que você estiver tentando registrar já existir, um [TypeAlreadyExistsException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/TypeAlreadyExistsException.html) será lançado. Adicione uma função para registrar um novo tipo de fluxo de trabalho. Um *fluxo de trabalho*, também conhecido como um *administrador*, representa a lógica de execução do fluxo de trabalho. \$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 Semelhantes a tipos de atividade, os tipos de fluxo de trabalho são identificados por um *nome* e uma *versão*, além de ter tempos limite configuráveis. Consulte [RegisterWorkflowTypeRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/RegisterWorkflowTypeRequest.html) para obter mais informações. \$1 Se o tipo de fluxo de trabalho que você estiver tentando registrar já existir, um [TypeAlreadyExistsException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/TypeAlreadyExistsException.html) será lançado. Por fim, torne a classe executável fornecendo a ela um método `main`, que registrará o domínio, o tipo de atividade e o tipo de fluxo de trabalho por vez: \$1 ``` registerDomain(); registerWorkflowType(); registerActivityType(); ``` Você já pode [compilar](#swf-hello-build) e [executar](#swf-hello-run-register) o aplicativo para executar o script de registro ou continuar codificando os operadores de atividade e de fluxo de trabalho. Assim que o domínio, o fluxo de trabalho e a atividade tiverem sido registrados, você não precisará reexecutá-los. Esses tipos persistirão até você torná-los obsoletos por conta própria. ### Implementar o operador de atividade Uma *atividade* é a unidade de trabalho básica em um fluxo de trabalho. Um fluxo de trabalho fornece a lógica, programando atividades a serem executadas (ou outras ações a serem tomadas) em resposta a tarefas de decisão. Um fluxo de trabalho típico normalmente consiste em várias atividades que podem ser executadas de maneira síncrona, assíncrona ou uma combinação de ambas. O *operador de atividade* é o bit de código que faz uma sondagem de tarefas de atividade geradas pelo Amazon SWF em resposta a decisões de fluxo de trabalho. Ao receber uma tarefa de atividade, ele executa a atividade correspondente e retorna uma resposta de êxito/falha para o fluxo de trabalho. Implementaremos um operador de atividade simples que realiza uma única atividade. 1. Abra o editor de textos e crie o arquivo `ActivityWorker.java`, adicionando uma declaração de pacote e importações de acordo com as [etapas comuns](#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. Adicione a classe `ActivityWorker` ao arquivo e atribua a ele um membro de dados para manter um cliente do SWF que usaremos para interagir com o Amazon SWF: ``` private static final AmazonSimpleWorkflow swf = AmazonSimpleWorkflowClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build(); ``` 1. Adicione o método que usaremos como uma atividade: ``` private static String sayHello(String input) throws Throwable { return "Hello, " + input + "!"; } ``` A atividade simplesmente utiliza uma string, integra a um cumprimento e retorna o resultado. Embora não seja muito provável que essa atividade crie uma exceção, é uma boa ideia criar atividades que possam lançar um erro se algo der errado. 1. Adicione um método `main` que usaremos como o método de sondagem da tarefa de atividade. Nós o iniciaremos adicionando alguns códigos para fazer uma sondagem à lista de tarefas para tarefas de atividade: ``` 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(); ``` A atividade recebe tarefas do Amazon SWF chamando o método `pollForActivityTask` do cliente do SWF, especificando o domínio e a lista de tarefas a serem usados no [PollForActivityTaskRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/PollForActivityTaskRequest.html) passado. Assim que uma tarefa for recebida, recuperaremos um identificador exclusivo para ela, chamando o método `getTaskToken` da tarefa. 1. Em seguida, escreva um código para processar as tarefas recebidas. Adicione o seguinte ao método `main`, logo depois do código que faz uma sondagem à tarefa e recupera o token da tarefa. ``` 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())); } } ``` Se o token da tarefa não for `null`, poderemos começar executando o método de atividade (`sayHello`), fornecendo a ele os dados de entrada enviados com a tarefa. Se a tarefa for *bem-sucedida* (sem erro gerado), o operador responderá ao SWF chamando o método `respondActivityTaskCompleted` do cliente do SWF com um objeto [RespondActivityTaskCompletedRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/RespondActivityTaskCompletedRequest.html) que contém o token da tarefa e os dados resultantes da atividade. Por outro lado, se a tarefa tiver *falhado*, responderemos chamando o método `respondActivityTaskFailed` com um objeto [RespondActivityTaskFailedRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/RespondActivityTaskFailedRequest.html), passando a ela o token da tarefas e as informações sobre o erro. **nota** Essa atividade não será desligada de maneira tranquila, se eliminada. Embora esteja além do escopo deste tutorial, uma implementação alternativa desse operador de atividade é apresentada no tópico complementar, [Desligar operadores de atividade e fluxo de trabalho de maneira tranquila](swf-graceful-shutdown.md). ### Implementar o operador de fluxo de trabalho A lógica do fluxo de trabalho reside em um código conhecido como um **operador de fluxo de trabalho**. O operador de fluxo de trabalho faz uma sondagem para tarefas de decisão enviadas pelo Amazon SWF no domínio e na lista de tarefas padrão com que o tipo de fluxo de trabalho foi registrado. Quando recebe uma tarefa, o operador de fluxo de trabalho toma algum tipo de decisão (normalmente se deve programar uma nova atividade ou não) e utiliza uma ação apropriada (como programar a atividade). 1. Abra o editor de textos e crie o arquivo `WorkflowWorker.java`, adicionando uma declaração de pacote e importações de acordo com as [etapas comuns](#swf-hello-common). 1. Adicione algumas importações adicionais ao arquivo: ``` 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. Declare a classe `WorkflowWorker` e crie uma instância da classe [AmazonSimpleWorkflowClient](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/AmazonSimpleWorkflowClient.html) usada para acessar os métodos SWF. ``` private static final AmazonSimpleWorkflow swf = AmazonSimpleWorkflowClientBuilder.standard().withRegion(Regions.DEFAULT_REGION).build(); ``` 1. Adicione o método `main`. O método fica em loop continuamente, fazendo uma sondagem de tarefas de decisão usando o método `pollForDecisionTask` do cliente do SWF. O [PollForDecisionTaskRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/PollForDecisionTaskRequest.html) apresenta os detalhes. ``` 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(); } } } ``` Assim que uma tarefa for recebida, chamaremos o método `getTaskToken`, que retornará uma string que poderá ser usada para identificar a tarefa. Se o token retornado não for `null`, processaremos ainda mais no método `executeDecisionTask`, passando o token da tarefa e a lista de objetos [HistoryEvent](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/HistoryEvent.html) enviados com a tarefa. 1. Adicione o método `executeDecisionTask`, utilizando o token da tarefa (uma `String`) e a lista `HistoryEvent`. ``` List decisions = new ArrayList(); String workflow_input = null; int scheduled_activities = 0; int open_activities = 0; boolean activity_completed = false; String result = null; ``` Também configuramos alguns membros de dados para acompanhar coisas como: + Uma lista de objetos [Decisão](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/Decision.html) usados para relatar os resultados do processamento da tarefa. + Uma string para armazenar a entrada do fluxo de trabalho fornecida pelo evento "WorkflowExecutionStarted" + uma contagem das atividades programadas e abertas (em execução) para evitar programar a mesma atividade quando ela já tiver sido programada ou estiver em execução no momento. + um booliano para indicar que a atividade foi concluída. + Uma string para manter os resultados da atividade, a fim de retorná-los como o resultado do fluxo de trabalho. 1. Em seguida, adicione um código a `executeDecisionTask` para processar os objetos `HistoryEvent` que foram enviados com a tarefa, com base no tipo de evento informado pelo método `getEventType`. ``` 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("]"); ``` Tendo em vista o fluxo de trabalho, estamos mais interessados: + no evento "WorkflowExecutionStarted", que indica que a execução do fluxo de trabalho foi iniciada (normalmente isso significa que você deve executar a primeira atividade no fluxo de trabalho) e apresenta a entrada inicial fornecida para o fluxo de trabalho. Nesse caso, trata-se da parte do nome do cumprimento. Por isso, ela é salva em uma string para ser usada durante a programação da atividade a ser executada. + no evento "ActivityTaskCompleted", enviado assim que a atividade programada é concluída. Os dados do evento também incluem o valor de retorno da atividade concluída. Como temos somente uma atividade, usaremos esse valor como o resultado de todo o fluxo de trabalho. Os outros tipos de evento poderão ser usados se o fluxo de trabalho precisar deles. Consulte a descrição da classe [HistoryEvent](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/HistoryEvent.html) para obter informações sobre cada tipo de evento. \$1 OBSERVAÇÃO: as strings em instruções `switch` foram introduzidas no Java 7. Se estiver usando uma versão anterior do Java, será possível usar a classe [EventType](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/model/EventType.html) para converter a `String` retornado por `history_event.getType()` em um valor enum e novamente em uma `String`, se necessário: ``` EventType et = EventType.fromValue(event.getEventType()); ``` 1. Depois da instrução `switch`, adicione mais código para responder com uma *decisão* apropriada com base na tarefa que foi recebida. ``` 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); ``` + Se a atividade ainda não tiver sido programada, responderemos com uma decisão `ScheduleActivityTask`, que fornecerá informações em uma estrutura [ScheduleActivityTaskDecisionAttributes](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/ScheduleActivityTaskDecisionAttributes.html) sobre a atividade que o Amazon SWF deve programar em seguida, incluindo também todos os dados que o Amazon SWF deve enviar para a atividade. + Se a atividade tiver sido concluída, vamos considerar todo o fluxo de trabalho concluído e responder com uma decisão `CompletedWorkflowExecution`, preenchendo uma estrutura [CompleteWorkflowExecutionDecisionAttributes](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/CompleteWorkflowExecutionDecisionAttributes.html) para fornecer detalhes sobre o fluxo de trabalho concluído. Neste caso, retornamos o resultado da atividade. Em qualquer um dos casos, as informações sobre a decisão são adicionadas à lista `Decision` que foi declarada na parte superior do método. 1. Conclua a tarefa de decisão retornando a lista de objetos `Decision` coletados durante o processamento da tarefa. Adicione esse código ao final do método `executeDecisionTask` que estávamos escrevendo: ``` swf.respondDecisionTaskCompleted( new RespondDecisionTaskCompletedRequest() .withTaskToken(taskToken) .withDecisions(decisions)); ``` O método `respondDecisionTaskCompleted` do cliente do SWF utiliza o token da tarefa que identifica a tarefa, bem como a lista de objetos `Decision`. ### Implementar o início do fluxo de trabalho Por fim, escreveremos um código para iniciar a execução do fluxo de trabalho. 1. Abra o editor de textos e crie o arquivo `WorkflowStarter.java`, adicionando uma declaração de pacote e importações de acordo com as [etapas comuns](#swf-hello-common). 1. Adicione a classe `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() + "'."); } } ``` A classe `WorkflowStarter` consiste em um único método `main`, que utiliza um argumento opcional passado na linha de comando como dados de entrada para o fluxo de trabalho. O método de cliente do SWF, `startWorkflowExecution`, utiliza um objeto [StartWorkflowExecutionRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/StartWorkflowExecutionRequest.html) como entrada. Aqui, além de especificar o domínio e o tipo de fluxo de trabalho para execução, fornecemos: + um nome de execução do fluxo de trabalho legível por humanos + dados de entrada do fluxo de trabalho (fornecidos na linha de comando no exemplo) + um valor de tempo limite que representa por quanto tempo, em segundos, todo o fluxo de trabalho deve ser executado. O objeto [Executar](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/Run.html) que `startWorkflowExecution` retorna fornece um *ID de execução*, um valor que pode ser usado para identificar a execução desse fluxo de trabalho em especial no histórico do Amazon SWF das execuções de fluxo de trabalho. \$1 OBSERVAÇÃO: o ID de execução é gerado pelo Amazon SWF e *não* tem o mesmo nome de execução do fluxo de trabalho passado por você ao iniciar a execução do fluxo de trabalho. ## Compilar o exemplo Para compilar o projeto de exemplo com o Maven, vá até o diretório `helloswf` e digite: ``` mvn package ``` O `helloswf-1.0.jar` resultante será gerado no diretório `target`. ## Executar o exemplo O exemplo consiste em quatro classes executáveis separadas, executadas de maneira independente entre si. **nota** Se estiver usando um sistema Linux, macOS ou Unix, você poderá executar todas, uma depois da outra, em uma única janela do terminal. Se estiver executando o Windows, você deverá abrir duas instâncias de linha de comando adicionais e navegar até o diretório `helloswf` em cada uma delas. ### Configurar o classpath do Java Embora o Maven tenha processado as dependências para você, para executar o exemplo, será necessário fornecer a biblioteca de SDK da AWS e as dependências no classpath do Java. Você pode definir a variável de ambiente `CLASSPATH` como o local das bibliotecas do SDK da AWS e o diretório `third-party/lib` no SDK, que inclui as dependências necessárias: ``` export CLASSPATH='target/helloswf-1.0.jar:/path/to/sdk/lib/*:/path/to/sdk/third-party/lib/*' java example.swf.hello.HelloTypes ``` ou usar a opção `-cp` do comando **` java `** para definir o classpath, ao mesmo tempo em que executa todos os aplicativos. ``` java -cp target/helloswf-1.0.jar:/path/to/sdk/lib/*:/path/to/sdk/third-party/lib/* \ example.swf.hello.HelloTypes ``` O estilo usado cabe a você. Se você não teve problemas ao compilar o código, tentou executar os exemplos e obteve uma série de erros "NoClassDefFound", provavelmente será porque o classpath estava definido de maneira incorreta. ### Registrar o domínio, tipos de fluxo de trabalho e de atividade Para executar os operadores e o início do fluxo de trabalho, será necessário registrar o domínio e os tipos de fluxo de trabalho e de atividade. O código para fazer isso foi implementado em [Registrar um fluxo de trabalho de domínio e tipos de atividade](#swf-hello-hellotypes). Depois da criação, se você [definiu o CLASSPATH](#swf-hello-set-classpath), será possível executar o código de registro executando o comando: ``` echo 'Supply the name of one of the example classes as an argument.' ``` ### Iniciar os operadores de atividade e de fluxo de trabalho Agora que os tipos foram registrados, você poderá iniciar os operadores de atividade e de fluxo de trabalho. Eles continuarão sendo executados e sondando tarefas até serem eliminados. Dessa maneira, é necessário executá-los em janelas de terminal separadas ou, se estiver executando no Linux, no macOS ou no Unix, será possível usar o operador `&` para fazer cada um deles gerar um processo separado quando executado. ``` echo 'If there are arguments to the class, put them in quotes after the class name.' exit 1 ``` Se você estiver executando esses comandos em janelas separadas, omita o operador `&` final de cada linha. ### Iniciar a execução de fluxo de trabalho Agora que os operadores de atividade e de fluxo de trabalho estão fazendo uma sondagem, você pode começar a execução do fluxo de trabalho. Esse processo será executado até o fluxo de trabalho retornar um status concluído. Você deve executá-lo em uma nova janela do terminal (a menos que tenha executado os operadores como novos processos gerados usando o operador `&`). ``` fi ``` **nota** Se você quiser fornecer os próprios dados de entrada, que serão passados primeiro para o fluxo de trabalho e, em seguida, para a atividade, adicione-os à linha de comando. Por exemplo: ``` echo "## Running $className..." ``` Assim que começar a execução do fluxo de trabalho, você deverá começar a ver a saída entregue por ambos os operadores e pela própria execução do fluxo de trabalho. Quando o fluxo de trabalho for finalmente concluído, a saída será impressa na tela. ## Fonte completa deste exemplo Você pode procurar a [origem completa](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/java/example_code/swf) desse exemplo no Github no repositório *aws-java-developer-guide*. ## Para obter mais informações + Os operadores apresentados aqui poderão resultar em tarefas perdidas, se forem desligados enquanto a sondagem de um fluxo de trabalho estiver acontecendo. Para saber como desligar operadores de maneira tranquila, consulte [Desligar operadores de atividade e fluxo de trabalho de maneira tranquila](swf-graceful-shutdown.md). + Para saber mais sobre o Amazon SWF, visite a página inicial do [Amazon SWF](https://aws.amazon.com/swf/) ou consulte o [Guia do desenvolvedor do Amazon SWF](https://docs.aws.amazon.com/amazonswf/latest/developerguide/). + Você pode usar o AWS Flow Framework para Java para escrever fluxos de trabalho mais complexos em um estilo Java elegante usando anotações. Para saber mais, consulte o [Guia do desenvolvedor do AWS Flow Framework para Java](https://docs.aws.amazon.com/amazonswf/latest/awsflowguide/). # LambdaTarefas do Como alternativa às atividades do Amazon SWF ou em conjunto com elas, você pode usar funções [Lambda](https://aws.amazon.com/lambda/) para representar unidades de trabalho nos fluxos de trabalho e programá-las de maneira semelhante a atividades. Este tópico descreve como implementar tarefas Lambda do Amazon SWF usando o AWS SDK para Java. Para obter mais informações sobre tarefas do Lambda em geral, consulte [Tarefas do AWS Lambda](https://docs.aws.amazon.com/amazonswf/latest/developerguide/lambda-task.html) em Guia do desenvolvedor do Amazon SWF. ## Configurar um perfil do IAM entre serviços para executar a função Lambda Para o Amazon SWF executar a função do Lambda, você precisa configurar um perfil do IAM para dar ao Amazon SWF permissão para executar funções do Lambda em seu nome. Para obter informações completas sobre como fazer isso, consulte [Tarefas do AWS Lambda](https://docs.aws.amazon.com/amazonswf/latest/developerguide/lambda-task.html). Será necessário o nome do recurso da Amazon (ARN) desse perfil do IAM ao registrar um fluxo de trabalho que usará tarefas do Lambda. ## Criar uma função do Lambda Você pode escrever funções Lambda em várias linguagens diferentes, inclusive Java. Para obter informações completas sobre como criar, implantar e usar funções do Lambda, consulte o [Guia do desenvolvedor do AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/). **nota** Não importa a linguagem usada para escrever a função do Lambda, pois ela pode ser programada e executada por *qualquer* fluxo de trabalho do Amazon SWF, independentemente da linguagem na qual o código de fluxo de trabalho foi escrito. O Amazon SWF processa os detalhes de como executar a função e passar os dados de e para ele. Veja a seguir uma função do Lambda simples que pode ser usada no lugar da atividade em [Criar um aplicativo do Amazon SWF simples](swf-hello.md). + Essa versão foi escrita em JavaScript, que pode ser inserido diretamente usando-se o [Console de gerenciamento da AWS](https://console.aws.amazon.com/console/home): ``` exports.handler = function(event, context) { context.succeed("Hello, " + event.who + "!"); }; ``` + Aqui está a mesma função escrita em Java, que você também pode implantar e executar no 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 + "!"); } } ``` **nota** Para saber mais sobre como implantar funções do Java no Lambda, consulte [Criar um pacote de implantação (Java)](https://docs.aws.amazon.com/lambda/latest/dg/lambda-java-how-to-create-deployment-package.html) no Guia do desenvolvedor do AWS Lambda. Você também deve observar a seção intitulada [Programar modelo para criar funções do Lambda no Java](https://docs.aws.amazon.com/lambda/latest/dg/java-programming-model.html). As funções do Lambda utilizam um objeto *event* ou *input* como o primeiro parâmetro e um objeto *context* como o segundo, o que fornece informações sobre a solicitação para executar a função do Lambda. Essa função em especial espera que a entrada esteja em JSON, com um campo `who` definido como o nome usado para criar o cumprimento. ## Registrar um fluxo de trabalho a ser usado com o Lambda Para um fluxo de trabalho programar uma função do Lambda, você deve fornecer o nome do perfil do IAM que dá ao Amazon SWF permissão para invocar funções Lambda. Você pode definir isso durante o registro do fluxo de trabalho usando os métodos `withDefaultLambdaRole` ou `setDefaultLambdaRole` de [RegisterWorkflowTypeRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/RegisterWorkflowTypeRequest.html). ``` 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) { ``` ## Programar uma tarefa do Lambda Programar uma tarefa do Lambda é semelhante a programar uma atividade. Você fornece uma [Decisão](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/Decision.html) com um [DecisionType](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/DecisionType.html) “ScheduleLambdaFunction” e com [ScheduleLambdaFunctionDecisionAttributes](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/ScheduleLambdaFunctionDecisionAttributes.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( ``` Em `ScheduleLambdaFuntionDecisionAttributes`, você deve fornecer um *nome*, que é o ARN da função do Lambda a ser chamada, e um *id*, que é o nome que o Amazon SWF usará para identificar a função do Lambda em logs do histórico. Você também pode fornecer *input* opcional para a função do Lambda e definir o valor *começar para encerrar tempo limte*, que é o número de segundos em que a função do Lambda tem permissão para ser executada antes de gerar um evento `LambdaFunctionTimedOut`. **nota** Esse código usa o [AWSLambdaClient](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/lambda/AWSLambdaClient.html) para recuperar o ARN da função do Lambda, dado o nome da função. Você pode usar essa técnica para evitar realizar a codificação rígida do ARN completo (o que inclui o ID de Conta da AWS) no código. ## Processar eventos de função do Lambda no administrador As tarefas do Lambda vão gerar vários eventos em que você pode atuar ao fazer uma sondagem de tarefas de decisão no operador de fluxo de trabalho, correspondente ao ciclo de vida da tarefa do Lambda, com valores [EventType](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/EventType.html) como `LambdaFunctionScheduled`, `LambdaFunctionStarted` e `LambdaFunctionCompleted`. Se a função do Lambda falhar ou demorar mais do que o valor de tempo limite definido, você receberá um tipo de evento `LambdaFunctionFailed` ou `LambdaFunctionTimedOut`, respectivamente. ``` 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; ``` ## Receber a saída da função do Lambda Você pode receber um `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` no [HistoryEvent](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/HistoryEvent.html) para obter um objeto [LambdaFunctionCompletedEventAttributes](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/LambdaFunctionCompletedEventAttributes.html) e chamar o método `getResult` para recuperar a saída da função do Lambda: ``` LambdaFunctionCompleted: running_functions--; ``` ## Fonte completa deste exemplo Você pode procurar a *origem completa :github:`* desse exemplo no Github no repositório *aws-java-developer-guide*. # Desligar operadores de atividade e de fluxo de trabalho de maneira tranquila O tópico [Compilar um aplicativo Amazon SWF simples](swf-hello.md) apresentou uma implementação completa de um aplicativo de fluxo de trabalho simples que consiste em um aplicativo de registro, um operador de atividade e de fluxo de trabalho, além de um início de fluxo de trabalho. As classes de operador foram projetadas para serem executadas continuamente, sondando tarefas enviadas pelo Amazon SWF para executar atividades ou retornar decisões. Assim que uma requisição de sondagem for feita, o Amazon SWF vai registrar quem fez a sondagem e tentar atribuir uma tarefa. Se o operador de fluxo de trabalho for encerrado durante uma sondagem longa, o Amazon SWF ainda poderá tentar enviar uma tarefa para o operador encerrado, resultando em uma tarefa perdida (até a tarefa expirar). Uma maneira de processar essa situação é aguardar todas as requisições de sondagem longa retornarem antes do operador terminar. Neste tópico, vamos reescrever o operador de atividade de `helloswf`, usando ganchos de desligamento do Java para fazer um desligamento normal do operador de atividade. Aqui está o código completo: ``` 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())); } } } } } ``` Nesta versão, o código de sondagem que estava na função `main` na versão original foi migrado para o próprio método, `pollAndExecute`. Agora a função `main` usa um [CountDownLatch](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/concurrent/CountDownLatch.html) com um [hook de desligamento](https://docs.oracle.com/javase/8/docs/api/index.html?java/lang/Runtime.html) para fazer o thread aguardar até 60 segundos após o término ser solicitado antes de permitir o desligamento do thread. # Registro de domínios Cada fluxo de trabalho e atividade no [Amazon SWF](https://aws.amazon.com/swf/) precisa de um *domínio* para execução. 1. Crie um novo objeto [RegisterDomainRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/RegisterDomainRequest.html), fornecendo pelo menos o nome de domínio e o período de retenção da execução do fluxo de trabalho (ambos os parâmetros são obrigatórios). 1. Chame o método [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-) com o objeto *RegisterDomainRequest*. 1. Intercepte [DomainAlreadyExistsException](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/DomainAlreadyExistsException.html) se o domínio que você estiver solicitando já existir (nesse caso, geralmente nenhuma ação é necessária). O código a seguir demonstra este procedimento: ``` 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!"); } } ``` # Listar domínios Você pode listar os domínios do [Amazon SWF](https://aws.amazon.com/swf/) associados à conta e à região da AWS por tipo de registro. 1. Crie um objeto [ListDomainsRequest](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/ListDomainsRequest.html) e especifique o status de registro dos domínios nos quais você tenha interesse. Isso é obrigatório. 1. Chame [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-) com o objeto *ListDomainRequest*. Os resultados são fornecidos em um objeto [DomainInfos](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/DomainInfos.html). 1. Chame [getDomainInfos](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/DomainInfos.html#getDomainInfos--) no objeto retornado para obter uma lista de objetos [DomainInfo](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/DomainInfo.html). 1. Chame [getName](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/simpleworkflow/model/DomainInfo.html#getName--) em cada objeto *DomainInfo* para obter o nome. O código a seguir demonstra este procedimento: ``` 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()); } } ``` # Amostras de código incluídas no SDK O AWS SDK para Java acompanha exemplos de código que demonstram muitos dos recursos do SDK nos programas executáveis, compiláveis. Você pode estudar ou modificá-los para implementar as próprias soluções da AWS usando o AWS SDK para Java. ## Como obter os exemplos Os exemplos de código do AWS SDK para Java são fornecidos no diretório de *exemplos* do SDK. Se tiver obtido por download e instalado o SDK usando as informações em [Configurar o AWS SDK para Java](setup-install.md), você já terá os exemplos no sistema. Você também pode visualizar os exemplos mais recentes no repositório GitHub do AWS SDK para Java, no diretório [src/samples](https://github.com/aws/aws-sdk-java/tree/master/src/samples). ## Compilar e executar os exemplos usando a linha de comando Entre os exemplos estão scripts de compilação [Ant](http://ant.apache.org/), de maneira que você possa compilar e executá-los facilmente na linha de comando. Todo exemplo também contém um arquivo README em formato HTML com informações específicas de cada exemplo. **nota** Se você estiver procurando o código de exemplo no GitHub, clique no botão **Raw** na exibição do código-fonte ao visualizar o arquivo README.html do exemplo. Em modo bruto, o HTML será renderizado conforme desejado no navegador. ### Pré-requisitos Para executar qualquer um dos exemplos do AWS SDK para Java, você precisa definir as credenciais da AWS no ambiente ou com a AWS CLI, conforme especificado em [Configurar credenciais e região da AWS para desenvolvimento](setup-credentials.md). Os exemplos usam a cadeia de fornecedores de credencial padrão sempre que possível. Dessa forma, definindo as credenciais assim, você pode evitar a prática arriscada de inserir as credenciais da AWS em arquivos dentro do diretório de código-fonte (onde o check-in deles pode ser feito inadvertidamente, além de compartilhados publicamente). ### Executar os exemplos 1. Mude para o diretório que contém o código de exemplo. Por exemplo, se você está no diretório raiz do download do SDK da AWS e deseja executar o exemplo `AwsConsoleApp`, digite: ``` cd samples/AwsConsoleApp ``` 1. Compile e execute o exemplo com Ant. O alvo da compilação padrão realiza ambas as ações. Dessa forma, basta você inserir: ``` ant ``` As informações de impressões de exemplo para a saída padrão, por exemplo: ``` =========================================== 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. ``` ## Compilar e executar os exemplos usando o IDE do Eclipse Se usar o AWS Toolkit for Eclipse, você também poderá iniciar um novo projeto no Eclipse com base no AWS SDK para Java ou adicionar o SDK a um projeto do Java existente. ### Pré-requisitos Após a instalação do AWS Toolkit for Eclipse, recomendamos configurar o Toolkit com as credenciais de segurança. Você pode fazer isso a qualquer momento escolhendo **Preferências** no menu **Janela** do Eclipse e a seção **Kit de ferramentas da AWS**. ### Executar os exemplos 1. Abra o Eclipse. 1. Criar um novo projeto da AWS em Java. No Eclipse, no menu **File**, escolha **New** e clique em **Project**. O assistente **New Project** é aberto. 1. Expanda a categoria **AWS** e escolha **AWS Java Project**. 1. Escolha **Próximo**. A página de configurações do projeto é exibida. 1. Insira um nome na caixa **Project Name**. O grupo de exemplos do AWS SDK para Java exibe os exemplos disponíveis no SDK, conforme descrito anteriormente. 1. Selecione os exemplos que você deseja incluir no projeto marcando cada caixa de seleção. 1. Insira credenciais de usuário da AWS. Se você já configurou o AWS Toolkit for Eclipse com as credenciais, ele será preenchido automaticamente. 1. Escolha **Terminar**. O projeto é criado e adicionado ao **Project Explorer**. 1. Escolha o arquivo de exemplo `.java` que você deseja executar. Por exemplo, para o exemplo do Amazon S3, escolha `S3Sample.java`. 1. Escolha **Run** no menu **Run**. 1. Clique com o botão direito do mouse no projeto em **Project Explorer**, aponte para **Build Path** e escolha **Add Libraries**. 1. Escolha **AWS SDK para Java**, selecione **Avançar** e siga as instruções na tela restantes.