# Como usar o AWS CLI
Esta seção fornece informações sobre uso geral, atributos comuns e opções disponíveis na AWS Command Line Interface (AWS CLI), além do que está descrito na seção [Usar endpoints na AWS CLI](cli-configure-endpoints.md) da Configuração.
Este guia aborda os aspectos fundamentais da escrita de comandos da AWS CLI, incluindo sua estrutura básica, formatação e recursos de filtragem. Ao entender esses elementos principais, você poderá criar comandos que direcionam com precisão os recursos e as ações de que você precisa, sem a necessidade de navegar em consoles complexos baseados na web.
Além disso, isso destaca o conteúdo de ajuda e a documentação disponíveis para a AWS CLI. Da ajuda integrada da linha de comando ao abrangente, [guia de referência da AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/reference/), você terá acesso a informações para ajudá-lo a explorar os atributos e capacidades da AWS CLI.
Para obter exemplos e casos de uso específicos do AWS service (Serviço da AWS), consulte [Exemplo para a AWS CLI](cli-chap-code-examples.md) ou [ a versão 2 do guia de referência da AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/). Eles fornecem informações específicas sobre comandos e demonstram exemplos de como aproveitar a AWS CLI em vários Serviços da AWS.
**nota**
Por padrão, a AWS CLI envia solicitações para os Serviços da AWS usando HTTPS na porta TCP 443. Para usar a AWS CLI com êxito, você deve ser capaz de fazer as conexões de saída nessa porta.
**Topics**
+ [Acesso a ajuda e recursos para a AWS CLI](cli-usage-help.md)
+ [Estrutura do comando na AWS CLI](cli-usage-commandstructure.md)
+ [Especificar valores de parâmetro na AWS CLI](cli-usage-parameters.md)
+ [Habilitar e usar os prompts de comando na AWS CLI](cli-usage-parameters-prompting.md)
+ [Controle de saída do comando na AWS CLI](cli-usage-output.md)
+ [Códigos de retorno da linha de comando na AWS CLI](cli-usage-returncodes.md)
+ [Usar assistentes personalizados para executar comandos interativos na AWS CLI](cli-usage-wizard.md)
+ [Criação e uso de aliases na AWS CLI](cli-usage-alias.md)
+ [Solução de problemas da AWS CLI](cli-chap-troubleshooting.md)
# Acesso a ajuda e recursos para a AWS CLI
Este tópico descreve como acessar o conteúdo da ajuda da AWS Command Line Interface(AWS CLI).
**Topics**
+ [O comando de ajuda integrado da AWS CLI](#cli-usage-help-command)
+ [Guia de referência da AWS CLI](#cli-reference)
+ [Documentação de API](#api-reference)
+ [Solucionar de problemas de erros](#help-tshoot)
+ [Ajuda adicional](#help-additional)
## O comando de ajuda integrado da AWS CLI
Você pode obter ajuda com qualquer comando ao usar a AWS Command Line Interface (AWS CLI). Para fazer isso, basta digitar `help` no final de um nome do comando.
Por exemplo, o comando a seguir exibe a ajuda para as opções gerais da AWS CLI e os comandos de nível superior disponíveis.
```
$ aws help
```
O comando a seguir exibe os comandos específicos do Amazon Elastic Compute Cloud (Amazon EC2) disponíveis.
```
$ aws ec2 help
```
O exemplo a seguir exibe ajuda detalhada para a operação `DescribeInstances` do Amazon EC2. A ajuda inclui descrições de seus parâmetros de entrada, filtros disponíveis, e o que é incluído como saída. Ela também inclui exemplos que mostram como digitar as variações comuns do comando.
```
$ aws ec2 describe-instances help
```
A partir da versão `2.31.0`, a exibição do comando `help` é definida pela configuração `cli_help_output` e tem os seguintes valores:
+ **(padrão)** `terminal`: abra a página do manual no terminal.
+ `browser`: abra a página do manual como um arquivo HTML local em seu navegador padrão. Um aviso é impresso no seu terminal quando o navegador padrão está sendo aberto e uma mensagem de erro será exibida se a AWS CLI não conseguir abrir o navegador.
+ `url`: imprima o URL do “Guia de referência da AWS CLI” on-line da versão da AWS CLI que você instalou. As configurações de paginação do lado do cliente, como a variável de ambiente `AWS_PAGER`, são mantidas.
O conteúdo de ajuda para cada comando está dividido em seis seções:
Nome
O nome do comando.
```
NAME
describe-instances -
```
Descrição
Uma descrição da operação da API que o comando invoca.
```
DESCRIPTION
Describes one or more of your instances.
If you specify one or more instance IDs, Amazon EC2 returns information
for those instances. If you do not specify instance IDs, Amazon EC2
returns information for all relevant instances. If you specify an
instance ID that is not valid, an error is returned. If you specify an
instance that you do not own, it is not included in the returned
results.
...
```
Resumo
A sintaxe básica para usar o comando e suas opções. Se uma opção estiver entre colchetes, significa que ela é opcional, tem um valor padrão ou tem uma opção alternativa que você pode usar.
```
SYNOPSIS
describe-instances
[--dry-run | --no-dry-run]
[--instance-ids ]
[--filters ]
[--cli-input-json ]
[--starting-token ]
[--page-size ]
[--max-items ]
[--generate-cli-skeleton]
```
Por exemplo, `describe-instances` tem um comportamento padrão que descreve ***todas*** as instâncias na conta e na região atuais da AWS. Se preferir, você poderá especificar uma lista de `instance-ids` para descrever uma ou mais instâncias. O `dry-run` é um sinalizador booliano opcional que não tem um valor. Para usar um sinalizador booliano, especifique um valor apresentado, nesse caso `--dry-run` ou `--no-dry-run`. Da mesma forma, `--generate-cli-skeleton` não tem um valor. Se houver condições no uso de uma opção, elas serão descritas na seção `OPTIONS` ou mostradas nos exemplos.
Opções
A descrição de cada uma das opções mostradas na sinopse.
```
OPTIONS
--dry-run | --no-dry-run (boolean)
Checks whether you have the required permissions for the action,
without actually making the request, and provides an error response.
If you have the required permissions, the error response is DryRun-
Operation . Otherwise, it is UnauthorizedOperation .
--instance-ids (list)
One or more instance IDs.
Default: Describes all your instances.
...
```
Exemplos
Os exemplos que mostram o uso do comando e suas opções. Se nenhum exemplo estiver disponível para um comando ou caso de uso que você precisa, solicite um usando o link de comentários nesta página ou na referência de comandos da AWS CLI na página de ajuda para o comando.
```
EXAMPLES
To describe an Amazon EC2 instance
Command:
aws ec2 describe-instances --instance-ids i-5203422c
To describe all instances with the instance type m1.small
Command:
aws ec2 describe-instances --filters "Name=instance-type,Values=m1.small"
To describe all instances with an Owner tag
Command:
aws ec2 describe-instances --filters "Name=tag-key,Values=Owner"
...
```
Output
As descrições de cada um dos campos e os tipos de dados incluídos na resposta da AWS.
Para `describe-instances`, a saída é uma lista de objetos de reserva, cada um com vários campos e objetos que contêm informações sobre as instâncias associadas a ele. Essas informações são provenientes da [documentação da API para o tipo de dados de reserva](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_Reservation.html) usada pelo Amazon EC2.
```
OUTPUT
Reservations -> (list)
One or more reservations.
(structure)
Describes a reservation.
ReservationId -> (string)
The ID of the reservation.
OwnerId -> (string)
The ID of the AWS account that owns the reservation.
RequesterId -> (string)
The ID of the requester that launched the instances on your
behalf (for example, AWS Management Console or Auto Scaling).
Groups -> (list)
One or more security groups.
(structure)
Describes a security group.
GroupName -> (string)
The name of the security group.
GroupId -> (string)
The ID of the security group.
Instances -> (list)
One or more instances.
(structure)
Describes an instance.
InstanceId -> (string)
The ID of the instance.
ImageId -> (string)
The ID of the AMI used to launch the instance.
State -> (structure)
The current state of the instance.
Code -> (integer)
The low byte represents the state. The high byte
is an opaque internal value and should be ignored.
...
```
Quando a AWS CLI renderiza a saída em JSON, ela se torna uma matriz de objetos de reserva, semelhante ao exemplo a seguir.
```
{
"Reservations": [
{
"OwnerId": "012345678901",
"ReservationId": "r-4c58f8a0",
"Groups": [],
"RequesterId": "012345678901",
"Instances": [
{
"Monitoring": {
"State": "disabled"
},
"PublicDnsName": "ec2-52-74-16-12.us-west-2.compute.amazonaws.com",
"State": {
"Code": 16,
"Name": "running"
},
...
```
Cada objeto de reserva contém campos que descrevem a reserva e uma série de objetos de instância, cada um com seus próprios campos (por exemplo, `PublicDnsName`) e objetos (por exemplo, `State`) que os descrevem.
**Usuários do Windows**
Você pode usar *pipe* (\$1) na saída do comando de ajuda do comando `more` para visualizar o arquivo de ajuda uma página por vez. Pressione a barra de espaço ou **PgDn** para visualizar mais detalhes do documento ou **q** se quiser sair.
```
C:\> aws ec2 describe-instances help | more
```
## Guia de referência da AWS CLI
Os arquivos de ajuda contêm links que não podem ser visualizados a partir da linha de comando nem é possível navegar até eles a partir dela. Você pode visualizar e interagir com esses links usando o e o [Guia de referência da AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/reference/index.html) online. A referência também inclui o conteúdo da ajuda para todos os comandos da AWS CLI. As descrições são apresentadas para facilitar a navegação e a visualização em dispositivos móveis, tablets e telas de desktop.
## Documentação de API
Todos os comandos na AWS CLI correspondem a solicitações feitas para uma API pública de serviço do AWS. Cada serviço com uma API pública tem uma referência da API que pode ser encontrada na página inicial do serviço no [site de documentação da AWS](https://docs.aws.amazon.com/). O conteúdo de uma referência da API varia de acordo com a forma como a API é criada e qual protocolo é usado. Normalmente, uma referência da API contém informações detalhadas sobre as operações compatíveis com a API, os dados enviados para e do serviço e qualquer condição de erro que o serviço pode relatar.
**Seções da documentação de API**
+ **Ações**: informações detalhadas sobre cada operação e seus parâmetros (incluindo restrições de tamanho ou conteúdo e valores padrão). Ela lista os erros que podem ocorrer nessa operação. Cada operação corresponde a um subcomando na AWS CLI.
+ **Tipos de dados**: informações detalhadas sobre estruturas que um comando pode exigir como um parâmetro ou retornar em resposta a uma solicitação.
+ **Parâmetros comuns**: informações detalhadas sobre os parâmetros que são compartilhados por toda a ação para o serviço.
+ **Erros comuns**: informações detalhadas sobre erros que podem ser retornados por todas as operações de um serviço.
O nome e a disponibilidade de cada seção podem variar de acordo com o serviço.
**CLIs específicas para o serviço**
Alguns serviços têm uma CLI separado desde antes da criação de uma única AWS CLI que funciona com todos os serviços. Essas CLIs específicas do serviço têm documentação separada vinculada a partir da página de documentação do serviço. A documentação para CLIs específicas de serviço não se aplica à AWS CLI.
## Solucionar de problemas de erros
Para obter ajuda para diagnosticar e corrigir erros da AWS CLI, consulte [Solução de problemas da AWS CLI](cli-chap-troubleshooting.md).
## Ajuda adicional
Para obter ajuda adicional para problemas da AWS CLI, visite a [Comunidade da AWS CLI](https://github.com/aws/aws-cli/issues) no *GitHub*.
# Estrutura do comando na AWS CLI
Este tópico aborda como o comando da AWS Command Line Interface (AWS CLI) é estruturado e como usar comandos de espera.
**Topics**
+ [Estrutura do comando](#cli-usage-commandstructure-structure.title)
+ [Comandos de espera](#cli-usage-commandstructure-wait)
## Estrutura do comando
A AWS CLI usa uma estrutura em várias partes na linha de comando que deve ser especificada nesta ordem:
1. A chamada básica para o programa `aws`.
1. O *comando* de nível superior que normalmente corresponde a um serviço do AWS compatível com a AWS CLI.
1. O *subcomando* que especifica a operação a ser realizada.
1. As opções gerais da AWS CLI ou os parâmetros necessários para a operação. Você pode especificá-los em qualquer ordem, desde que siga as três primeiras partes. Se um parâmetro exclusivo for especificado várias vezes, apenas o *último valor* se aplicará.
```
$ aws [options and parameters]
```
Parâmetros pode levar vários tipos de valores de entrada, como números, sequências de caracteres, listas, mapas e estruturas de JSON. O que é compatível depende do comando e do subcomando que você especificar.
### Exemplos
**Amazon S3**
O exemplo a seguir lista todos os seus buckets do Amazon S3.
```
$ aws s3 ls
2018-12-11 17:08:50 amzn-s3-demo-bucket1
2018-12-14 14:55:44 amzn-s3-demo-bucket2
```
Para obter mais informações sobre os comandos do Amazon S3, consulte [https://docs.aws.amazon.com/cli/latest/reference/s3/index.html](https://docs.aws.amazon.com/cli/latest/reference/s3/index.html) na *Referência de comandos da AWS CLI*.
**AWS CloudFormation**
O exemplo de comando [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/create-change-set.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/create-change-set.html) a seguir altera o nome da pilha cloudformation para *my-change-set*.
```
$ aws cloudformation create-change-set --stack-name my-stack --change-set-name my-change-set
```
Para obter mais informações sobre os comandos AWS CloudFormation, consulte [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/index.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/index.html) na *Referência de comandos da AWS CLI*.
## Comandos de espera
Alguns serviços da AWS contam com comandos `wait`. Qualquer comando que usa `aws wait` normalmente espera até que um comando seja concluído antes de passar para a próxima etapa. Isso é especialmente útil para comandos em várias partes ou scripts, pois você pode usar um comando wait para impedir o avanço para etapas subsequentes se o comando wait falhar.
A AWS CLI usa uma estrutura em várias partes na linha de comando para o comando `wait` que deve ser especificada nesta ordem:
1. A chamada básica para o programa `aws`.
1. O *comando* de nível superior que normalmente corresponde a um serviço do AWS compatível com a AWS CLI.
1. O comando `wait`.
1. O *subcomando* que especifica a operação a ser realizada.
1. As opções gerais da CLI ou os parâmetros necessários para a operação. Você pode especificá-los em qualquer ordem, desde que siga as três primeiras partes. Se um parâmetro exclusivo for especificado várias vezes, apenas o *último valor* se aplicará.
```
$ aws wait [options and parameters]
```
Parâmetros pode levar vários tipos de valores de entrada, como números, sequências de caracteres, listas, mapas e estruturas de JSON. O que é compatível depende do comando e do subcomando que você especificar.
**nota**
Nem todos os serviços da AWS comportam comandos `wait`. Consulte o [AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/reference/index.html) para ver se seu serviço comporta comandos `wait`.
### Exemplos
**AWS CloudFormation**
Os exemplos de comando [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/change-set-create-complete.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/change-set-create-complete.html) a seguir pausam e continuam somente depois que o comando pode confirmar que o conjunto de alterações *my-change-set* na pilha *my-stack* está pronto para ser executado.
```
$ aws cloudformation wait change-set-create-complete --stack-name my-stack --change-set-name my-change-set
```
Para obter mais informações sobre os comandos da AWS CloudFormation `wait`, consulte [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/index.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/index.html) na *Referência de comandos da AWS CLI*.
**AWS CodeDeploy**
Os exemplos de comando [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/change-set-create-complete.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/change-set-create-complete.html) pausam até a implantação de *d-A1B2C3111* ser concluída com êxito.
```
$ aws deploy wait deployment-successful --deployment-id d-A1B2C3111
```
Para obter mais informações sobre os comandos da AWS CodeDeploy `wait`, consulte [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/index.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/index.html) na *Referência de comandos da AWS CLI*.
# Especificar valores de parâmetro na AWS CLI
Muitos parâmetros usados na AWS Command Line Interface (AWS CLI) são strings ou valores numéricos simples, como o nome do par de chaves `my-key-pair` no exemplo de comando `aws ec2 create-key-pair` a seguir.
```
$ aws ec2 create-key-pair --key-name my-key-pair
```
A formatação para comandos pode variar entre os terminais. Por exemplo, a maioria dos terminais faz distinção entre letras maiúsculas e minúsculas, mas não é o caso do Powershell. Isso significa que os dois exemplos de comando a seguir produziriam resultados diferentes para terminais com distinção entre letras maiúsculas e minúsculas, pois eles veem `MyFile*.txt` e `myfile*.txt` como parâmetros **diferentes**.
No entanto, o PowerShell processaria essas solicitações da mesma forma, já que vê `MyFile*.txt` e `myfile*.txt` como os **mesmos** parâmetros. O exemplo de comando a seguir demonstra esses parâmetros usando o comando `aws s3 cp`:
```
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --include "MyFile*.txt"
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --include "myfile*.txt"
```
Para obter mais informações sobre a indistinção de letras maiúsculas e minúsculas do PowerShell, consulte [about\$1Case-Sensitivity](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_case-sensitivity) na *documentação do PowerShell*.
Às vezes, é necessário usar aspas ou literais em strings que incluem caracteres especiais ou de espaço. As regras sobre essa formatação também podem variar entre os terminais. Para obter mais informações sobre como usar aspas em parâmetros complexos, consulte [Usar aspas e literais com strings na AWS CLI](cli-usage-parameters-quoting-strings.md).
Esses tópicos abordam as regras de formatação de terminal mais comuns. Se você estiver tendo problemas em seu terminal com o reconhecimento de valores de parâmetros, revise os tópicos desta seção e também verifique a documentação do seu terminal para ver as regras de sintaxe específicas.
**Topics**
+ [Tipos comuns de parâmetros na AWS CLI](cli-usage-parameters-types.md)
+ [Usar aspas e literais com strings na AWS CLI](cli-usage-parameters-quoting-strings.md)
+ [Carregar um parâmetro de um arquivo na AWS CLI](cli-usage-parameters-file.md)
+ [Esqueletos da AWS CLI e arquivos de entrada na AWS CLI](cli-usage-skeleton.md)
+ [Uso da sintaxe simplificada na AWS CLI](cli-usage-shorthand.md)
# Tipos comuns de parâmetros na AWS CLI
Esta seção descreve alguns dos tipos de parâmetros comuns e o formato típico necessário.
Caso haja problemas com a formatação de um parâmetro para um comando específico, verifique a ajuda inserindo **help** após o nome do comando. A ajuda de cada subcomando inclui o nome e a descrição de uma opção. O tipo de parâmetro da opção está listado entre parênteses. Para obter mais informações sobre a exibição da ajuda, consulte [Acesso a ajuda e recursos para a AWS CLI](cli-usage-help.md).
**Topics**
+ [String](#parameter-type-string)
+ [Timestamp](#parameter-type-timestamp)
+ [Lista](#parameter-type-list)
+ [Booleano](#parameter-type-boolean)
+ [Inteiro](#parameter-type-integer)
+ [Binário/blob (objeto grande binário) e blob de streaming](#parameter-type-blobs)
+ [Mapa](#parameter-type-map)
+ [Documento](#parameter-type-document)
## String
Os parâmetros de string podem conter caracteres alfanuméricos, símbolos e espaço em branco no conjunto de caracteres [ASCII](https://wikipedia.org/wiki/ASCII). Strings com espaço em branco devem ser incluídas entre aspas. Recomendamos que você não use símbolos nem espaços em branco diferentes do caractere de espaço padrão e observe as [regras de aspas](cli-usage-parameters-quoting-strings.md) para evitar resultados inesperados.
Alguns parâmetros de sequência de caracteres pode aceitar dados binários a partir de um arquivo. Para ver um exemplo, consulte [Arquivos binários](cli-usage-parameters-file.md#cli-usage-parameters-file-binary).
## Timestamp
As marcas de tempo são formatadas de acordo com a norma [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html). São geralmente chamados de parâmetros “`DateTime`” ou “`Date`”.
```
$ aws ec2 describe-spot-price-history --start-time 2014-10-13T19:00:00Z
```
Os formatos aceitos incluem:
+ *AAAA*-*MM*-*DD*T*hh*:*mm*:*ss.sss**TZD (UTC)*, por exemplo, 2014-10-01T20:30:00.000Z
+ *AAAA*-*MM*-*DD*T*hh*:*mm*:*ss.sss**TZD (com deslocamento)*, por exemplo, 2014-10-01T12:30:00.000-08:00
+ *AAAA*-*MM*-*DD*, por exemplo, 2014-10-01
+ Tempo do Unix em segundos, por exemplo, 1412195400. Isso às vezes é conhecido como [Tempo epoch Unix](https://wikipedia.org/wiki/Unix_time) e representa o número de segundos desde a meia-noite, 1º de janeiro de 1970 UTC.
Por padrão, a AWS CLI versão 2 converte todos os valores DateTime da ***resposta*** no formato ISO 8601.
Você pode definir o formato do carimbo de data/hora usando a configuração do arquivo `cli\$1timestamp\$1format`.
## Lista
Uma ou mais strings separadas por espaços. Se qualquer um dos itens de string contiver espaços, você deverá colocar esse item entre aspas. Observe as [regras de aspas](cli-usage-parameters-quoting-strings.md) de seu terminal para evitar resultados inesperados
```
$ aws ec2 describe-spot-price-history --instance-types m1.xlarge m1.medium
```
## Booleano
Sinalizador binário que ativa ou desativa uma opção. Por exemplo, `ec2 describe-spot-price-history` tem um parâmetro booleano `--dry-run` que, quando especificado, valida a consulta com o serviço sem realmente executá-la.
```
$ aws ec2 describe-spot-price-history --dry-run
```
A saída indica se o comando foi bem formado. Esse comando também inclui uma versão `--no-dry-run` do parâmetro que você pode usar para indicar explicitamente que o comando deve ser executado normalmente. A inclusão não é necessária, pois esse é o comportamento padrão.
## Inteiro
Um número inteiro não assinado.
```
$ aws ec2 describe-spot-price-history --max-items 5
```
## Binário/blob (objeto grande binário) e blob de streaming
Na AWS CLI, é possível transmitir um valor binário como uma string diretamente na linha de comando. Há dois tipos de blobs:
+ [Blob](#parameter-type-blob)
+ [Blob de streaming](#parameter-type-streaming-blob)
### BLOB
Para transmitir um valor para um parâmetro com o tipo `blob`, é necessário especificar um caminho para um arquivo local que contenha os dados binários usando o prefixo `fileb://`. Arquivos referenciados usando o prefixo `fileb://` são sempre tratados como um binário bruto não codificado. O caminho especificado é interpretado como sendo relativo ao diretório de trabalho atual. Por exemplo, o parâmetro `--plaintext` para `aws kms encrypt` é um blob.
```
$ aws kms encrypt \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--plaintext fileb://ExamplePlaintextFile \
--output text \
--query CiphertextBlob | base64 \
--decode > ExampleEncryptedFile
```
**nota**
Para compatibilidade com versões anteriores, é possível usar o prefixo `file://`. Há dois formatos usados com base na opção da linha de comando `cli\$1binary\$1format` ou `--cli-binary-format` da configuração do arquivo:
Padrão para a AWS CLI versão 2. Se o valor da configuração for `base64`, os arquivos referenciados com o prefixo `file://` serão tratados como texto codificado em base64.
Padrão para a AWS CLI versão 1. Se o valor da configuração for `raw-in-base64-out`, os arquivos referenciados usando o prefixo `file://` serão lidos como texto e, então, a AWS CLI tenta codificá-lo em binário.
Para obter mais informações, consulte a configuração do arquivo `cli\$1binary\$1format` ou a opção `--cli-binary-format` da linha de comando.
### Blob de streaming
Blobs de streaming como `aws cloudsearchdomain upload-documents` não usam prefixos. Em vez disso, os parâmetros de blob de streaming são formatados usando o caminho direto do arquivo. O seguinte exemplo usa o caminho direto do arquivo `document-batch.json` para o comando `aws cloudsearchdomain upload-documents`:
```
$ aws cloudsearchdomain upload-documents \
--endpoint-url https://doc-my-domain.us-west-1.cloudsearch.amazonaws.com \
--content-type application/json \
--documents document-batch.json
```
## Mapa
Um conjunto de pares de chave-valor especificado em JSON ou com a [sintaxe abreviada](cli-usage-shorthand.md) da CLI. O exemplo de JSON a seguir lê um item de uma tabela do Amazon DynamoDB chamada *my-table* com um parâmetro de mapa, `--key`. O parâmetro especifica a chave primária chamada *id* com um valor numérico de *1* em uma estrutura JSON aninhada.
Para uso mais avançado de JSON em uma linha de comando, considere usar um processador JSON de linha de comando, como `jq`, para criar strings JSON. Para obter mais informações sobre o `jq`, consulte o [repositório do jq](http://stedolan.github.io/jq/) no *GitHub*.
```
$ aws dynamodb get-item --table-name my-table --key '{"id": {"N":"1"}}'
{
"Item": {
"name": {
"S": "John"
},
"id": {
"N": "1"
}
}
}
```
## Documento
**nota**
A [sintaxe simplificada](cli-usage-shorthand.md) não é compatível com tipos de documento.
Os tipos de documento são usados para enviar dados sem a necessidade de incorporar JSON dentro de strings. O tipo de documento permite que os serviços forneçam esquemas arbitrários para você usar tipos de dados mais flexíveis.
Isso permite enviar dados JSON sem precisar usar caracteres escape nos valores. Por exemplo, em vez de usar a seguinte entrada JSON com escape:
```
{"document": "{\"key\":true}"}
```
Você pode usar o seguinte tipo de documento:
```
{"document": {"key": true}}
```
### Valores válidos para tipos de documento
Devido à natureza flexível dos tipos de documento, existem vários tipos de valor válidos. Entre os valores válidos estão os seguintes:
**String**
```
--option '"value"'
```
**Número**
```
--option 123
--option 123.456
```
**Booleano**
```
--option true
```
**Null**
```
--option null
```
**Array**
```
--option '["value1", "value2", "value3"]'
--option '["value", 1, true, null, ["key1", 2.34], {"key2": "value2"}]'
```
**Objeto**
```
--option '{"key": "value"}'
--option '{"key1": "value1", "key2": 123, "key3": true, "key4": null, "key5": ["value3", "value4"], "key6": {"value5": "value6"}'
```
# Usar aspas e literais com strings na AWS CLI
Há duas formas principais de usar aspas simples e duplas na AWS CLI.
+ [Uso de aspas em torno de strings que contêm espaços em branco](#cli-usage-parameters-quoting-strings-around)
+ [Uso de aspas dentro de strings](#cli-usage-parameters-quoting-strings-containing)
## Uso de aspas em torno de strings que contêm espaços em branco
Os nomes dos parâmetros e valores são separados por espaços na linha de comando. Se um valor de string contiver um espaço incorporado, você deve fechar a string inteira com aspas para evitar que a AWS CLI interprete mal o espaço como um divisor entre o valor e o próximo nome de parâmetro. O tipo de aspas depende do sistema operacional em que você executa a AWS CLI.
------
#### [ Linux and macOS ]
Uso de aspas simples `' '`
```
$ aws ec2 create-key-pair --key-name 'my key pair'
```
Para obter mais informações sobre como usar aspas, consulte a documentação do usuário para o seu shell preferido.
------
#### [ PowerShell ]
**Aspas simples (recomendado)**
As aspas simples `' '` são chamadas de strings `verbatim`. A string é passada ao comando exatamente como você a digita, o que significa que as variáveis do PowerShell não serão passadas.
```
PS C:\> aws ec2 create-key-pair --key-name 'my key pair'
```
**Aspas duplas**
As aspas duplas `" "` são chamadas de string `expandable`. As variáveis podem ser passadas em strings expansíveis.
```
PS C:\> aws ec2 create-key-pair --key-name "my key pair"
```
Para obter mais informações sobre como usar aspas, consulte [Sobre regras de aspas](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7) na *Documentação do Microsoft PowerShell*.
------
#### [ Windows command prompt ]
Uso de aspas duplas `" "` .
```
C:\> aws ec2 create-key-pair --key-name "my key pair"
```
------
Opcionalmente, você pode separar o nome de parâmetro do valor com um sinal de igual `=`, em vez de um espaço. Isso geralmente é necessário apenas se o valor do parâmetro começa com um hífen.
```
$ aws ec2 delete-key-pair --key-name=-mykey
```
## Uso de aspas dentro de strings
As strings podem conter aspas, e seu shell pode exigir aspas de escape para que funcionem corretamente. Um dos tipos de valor de parâmetro comuns é uma string JSON. Isso é complexo, pois inclui espaços e aspas duplas `" "` em torno de cada nome de elemento e valor na estrutura JSON. A maneira como insere os parâmetros formatados pelo JSON na linha de comando difere dependendo de seu sistema operacional.
Para uso mais avançado de JSON na linha de comando, considere usar um processador JSON de linha de comando, como `jq`, para criar strings JSON. Para obter mais informações sobre o `jq`, consulte o [repositório do jq](http://stedolan.github.io/jq/) no *GitHub*.
------
#### [ Linux and macOS ]
Para que o Linux e o macOS interpretem strings literalmente, use aspas simples `' '` para delimitar estrutura de dados JSON, como no exemplo a seguir. Você não precisa adicionar sequências de escape para as aspas duplas incorporadas na string JSON, pois elas são tratadas literalmente. Como o JSON é delimitado por aspas simples, quaisquer aspas simples na string precisarão utilizar sequências de escape. Isso geralmente é feito usando-se uma barra invertida antes da aspas simples `\'`.
```
$ aws ec2 run-instances \
--image-id ami-12345678 \
--block-device-mappings '[{"DeviceName":"/dev/sdb","Ebs":{"VolumeSize":20,"DeleteOnTermination":false,"VolumeType":"standard"}}]'
```
Para obter mais informações sobre como usar aspas, consulte a documentação do usuário para o seu shell preferido.
------
#### [ PowerShell ]
Use aspas simples `' '` ou aspas duplas`" "`.
**Aspas simples (recomendado)**
As aspas simples `' '` são chamadas de strings `verbatim`. A string é passada ao comando exatamente como você a digita, o que significa que as variáveis do PowerShell não serão passadas.
Como as estruturas de dados JSON incluem aspas duplas, sugerimos utilizar **aspas simples** `' '`para delimitá-las. Se você usar aspas **simples**, não será necessário usar uma sequência de escape para as aspas **duplas** incorporadas na string JSON. No entanto, será necessário usar a sequência de escape para cada uma das aspas **simples**utilizando um apóstrofe ``` dentro da estrutura JSON.
```
PS C:\> aws ec2 run-instances `
--image-id ami-12345678 `
--block-device-mappings '[{"DeviceName":"/dev/sdb","Ebs":{"VolumeSize":20,"DeleteOnTermination":false,"VolumeType":"standard"}}]'
```
**Aspas duplas**
As aspas duplas `" "` são chamadas de string `expandable`. As variáveis podem ser passadas em strings expansíveis.
Se você usar aspas **duplas**, não será necessário usar uma sequência de escape para as aspas **simples** incorporadas na string JSON. No entanto, será necessário usar a sequência de escape para cada uma das aspas **duplas**utilizando um apóstrofe ``` dentro da estrutura JSON, conforme mostrado no exemplo a seguir.
```
PS C:\> aws ec2 run-instances `
--image-id ami-12345678 `
--block-device-mappings "[{`"DeviceName`":`"/dev/sdb`",`"Ebs`":{`"VolumeSize`":20,`"DeleteOnTermination`":false,`"VolumeType`":`"standard`"}}]"
```
Para obter mais informações sobre como usar aspas, consulte [Sobre regras de aspas](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7) na *Documentação do Microsoft PowerShell*.
**Atenção**
Antes que o PowerShell envie um comando para a AWS CLI, ele determina se seu comando é interpretado usando o PowerShell típico ou regras de aspas da `CommandLineToArgvW`. Quando o PowerShell usa `CommandLineToArgvW` no processamento, é necessário escapar dos caracteres com barra invertida `\`.
Para obter mais informações sobre `CommandLineToArgvW` no PowerShell, consulte [O que há com o estranho tratamento de aspas e barras invertidas por CommandlineToArgVW](https://devblogs.microsoft.com/oldnewthing/20100917-00/?p=12833) no *Blog de desenvolvedores da Microsoft*, [Todos delimitam argumentos de linha de comando da maneira errada](https://docs.microsoft.com/en-us/archive/blogs/twistylittlepassagesallalike/everyone-quotes-command-line-arguments-the-wrong-way) no *Blog de documentação da Microsoft* e [Função CommandLineToArGVW](https://docs.microsoft.com/en-us/windows/win32/api/shellapi/nf-shellapi-commandlinetoargvw#remarks) na *Documentação da Microsoft*.
**Aspas simples**
As aspas simples `' '` são chamadas de strings `verbatim`. A string é passada ao comando exatamente como você a digita, o que significa que as variáveis do PowerShell não serão passadas. Caracteres de escape com barra invertida `\`.
```
PS C:\> aws ec2 run-instances `
--image-id ami-12345678 `
--block-device-mappings '[{\"DeviceName\":\"/dev/sdb\",\"Ebs\":{\"VolumeSize\":20,\"DeleteOnTermination\":false,\"VolumeType\":\"standard\"}}]'
```
**Aspas duplas**
As aspas duplas `" "` são chamadas de string `expandable`. As variáveis podem ser passadas em strings expansíveis. Para strings entre aspas duplas, é necessário escapar duas vezes usando*`\$1* para cada aspa, em vez de usar um único backtick. O backtick escapa da barra invertida e, em seguida, a barra invertida é usada como um caractere de escape para o processo `CommandLineToArgvW`.
```
PS C:\> aws ec2 run-instances `
--image-id ami-12345678 `
--block-device-mappings "[{`\"DeviceName`\":`\"/dev/sdb`\",`\"Ebs`\":{`\"VolumeSize`\":20,`\"DeleteOnTermination`\":false,`\"VolumeType`\":`\"standard`\"}}]"
```
**Blobs (recomendados)**
Para ignorar as regras de aspas do PowerShell para entrada de dados JSON, use Blobs para passar seus dados JSON diretamente para a AWS CLI. Para obter mais informações sobre o Blobs, consulte [BLOB](cli-usage-parameters-types.md#parameter-type-blob).
------
#### [ Windows command prompt ]
O prompt de comando do Windows exige aspas duplas `" "` para delimitar a estrutura de dados JSON. Além disso, para evitar que o processador de comando interprete mal as aspas duplas incorporadas no JSON, você também deve usar um caractere de escape (preceder com um caractere de barra invertida `\`) cada uma das aspas duplas `"` dentro da própria estrutura de dados JSON, como no exemplo a seguir.
```
C:\> aws ec2 run-instances ^
--image-id ami-12345678 ^
--block-device-mappings "[{\"DeviceName\":\"/dev/sdb\",\"Ebs\":{\"VolumeSize\":20,\"DeleteOnTermination\":false,\"VolumeType\":\"standard\"}}]"
```
Somente as aspas duplas mais externas não são de escape.
------
# Carregar um parâmetro de um arquivo na AWS CLI
Alguns parâmetros esperam nomes de arquivos como argumentos, dos quais a AWS CLI carrega os dados. Outros parâmetros permitem que você especifique o valor do parâmetro como texto digitado na linha de comando ou lido de um arquivo. Independentemente se um arquivo for obrigatório ou opcional, você deverá codificá-lo corretamente para que a AWS CLI possa entendê-lo. A codificação do arquivo deve corresponder à localidade padrão do sistema de leitura. É possível determinar isso usando o método `locale.getpreferredencoding()` do Python.
Esse método serve para carregar um arquivo para um único parâmetro. Consulte informações sobre como carregar vários parâmetros com um único arquivo em [Esqueletos da AWS CLI e arquivos de entrada na AWS CLI](cli-usage-skeleton.md).
**nota**
Por padrão, o Windows PowerShell gera texto como UTF-16, o que entra em conflito com a codificação UTF-8 usada por arquivos JSON e muitos sistemas Linux. Recomendamos que você use `-Encoding ascii` com os comandos `Out-File` do PowerShell para garantir que a AWS CLI possa ler o arquivo resultante.
**Topics**
+ [Como carregar um parâmetro de um arquivo](#cli-usage-parameters-file-how)
+ [Arquivos binários](#cli-usage-parameters-file-binary)
+ [Carregar um arquivo como um valor de sintaxe abreviada](#cli-usage-parameters-file-shorthand)
## Como carregar um parâmetro de um arquivo
Às vezes é conveniente carregar um valor de parâmetro de um arquivo, em vez de tentar digitá-lo como um valor de parâmetro de linha de comando, por exemplo, quando o parâmetro é uma string JSON complexa. Para especificar um arquivo que contém o valor, especifique um URL de arquivo no formato a seguir.
```
file://complete/path/to/file
```
+ Os dois primeiros caracteres de barra “/” fazem parte da especificação. Se o caminho exigido começar com “/”, o resultado será três caracteres de barra: `file:///folder/file`.
+ O URL fornece o caminho para o arquivo que apresenta o conteúdo real do parâmetro.
+ Ao usar arquivos com espaços ou caracteres especiais, siga as [regras de aspas e escape](cli-usage-parameters-quoting-strings.md) para o terminal.
Os caminhos do arquivo no exemplo a seguir são interpretados como sendo relativos ao diretório de trabalho atual.
------
#### [ Linux or macOS ]
```
// Read from a file in the current directory
$ aws ec2 describe-instances --filters file://filter.json
// Read from a file in /tmp
$ aws ec2 describe-instances --filters file:///tmp/filter.json
// Read from a file with a filename with whitespaces
$ aws ec2 describe-instances --filters 'file://filter content.json'
```
------
#### [ Windows command prompt ]
```
// Read from a file in C:\temp
C:\> aws ec2 describe-instances --filters file://C:\temp\filter.json
// Read from a file with a filename with whitespaces
C:\> aws ec2 describe-instances --filters "file://C:\temp\filter content.json"
```
------
A opção de prefixo `file://` é compatível com as expansões de estilo Unix, inclusive "`~/`", "`./`" e "`../`". No Windows, a expressão "`~/`" se expande para o seu diretório de usuário, armazenado na variável de ambiente `%USERPROFILE%`. Por exemplo, no Windows 10, haveria normalmente um diretório de usuário em `%USERPROFILE%`.
Ainda é necessário inserir um caractere de escape nos documentos JSON que são incorporados como o valor de outro documento JSON.
```
$ aws sqs create-queue --queue-name my-queue --attributes file://attributes.json
```
**attributes.json**
```
{
"RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:us-west-2:0123456789012:deadletter\", \"maxReceiveCount\":\"5\"}"
}
```
## Arquivos binários
Para comandos que incluem dados binários como um parâmetro, especifique que os dados são conteúdo binário usando o prefixo `fileb://`. Comandos que aceitam dados binários incluem:
+ **`aws ec2 run-instances:`** `--user-data` parâmetro .
+ **`aws s3api put-object:`** `--sse-customer-key` parâmetro .
+ **`aws kms decrypt:`** `--ciphertext-blob` parâmetro .
O exemplo a seguir gera uma chave binária AES de 256 bits usando uma ferramenta de linha de comando do Linux e a fornece ao Amazon S3 para criptografar o arquivo enviado no lado do servidor.
```
$ dd if=/dev/urandom bs=1 count=32 > sse.key
32+0 records in
32+0 records out
32 bytes (32 B) copied, 0.000164441 s, 195 kB/s
$ aws s3api put-object \
--bucket amzn-s3-demo-bucket \
--key test.txt \
--body test.txt \
--sse-customer-key fileb://sse.key \
--sse-customer-algorithm AES256
{
"SSECustomerKeyMD5": "iVg8oWa8sy714+FjtesrJg==",
"SSECustomerAlgorithm": "AES256",
"ETag": "\"a6118e84b76cf98bf04bbe14b6045c6c\""
}
```
Para outro exemplo com referência a um arquivo que contém parâmetros formatados pelo JSON, consulte [Associar uma política gerenciada do IAM a um usuário](cli-services-iam.md#cli-services-iam-policy).
## Carregar um arquivo como um valor de sintaxe abreviada
Ao usar a sintaxe abreviada quando um valor é grande ou complexo, geralmente é mais fácil carregar um arquivo como um valor. Ao carregar um arquivo como um valor de sintaxe abreviada, a formatação muda um pouco. Em vez de `key=value`, você usa o operador `@=` no lugar do operador `=`. O `@=` indica à AWS CLI que o valor deve ser lido como um caminho de arquivo e não como uma string. O exemplo a seguir mostra um par de chave-valor carregando um arquivo como seu valor.
------
#### [ Linux or macOS ]
```
--option key@=file://template.txt
```
------
#### [ Windows ]
```
--option "key1@=file://template.txt"
```
------
O exemplo a seguir demonstra o carregamento de um arquivo de certificado para o comando `aws rolesanywhere create-trust-anchor`.
```
$ aws rolesanywhere create-trust-anchor --name TrustAnchor \
--source sourceData={x509CertificateData@=file://root-ca.crt},sourceType="CERTIFICATE_BUNDLE" \
--enabled
```
Consulte mais informações sobre a sintaxe abreviada em [Uso da sintaxe simplificada na AWS CLI](cli-usage-shorthand.md).
# Esqueletos da AWS CLI e arquivos de entrada na AWS CLI
A maioria dos comandos da AWS CLI aceita as entradas de parâmetro importadas de um arquivo. Esses modelos podem ser gerados usando a opção `generate-cli-skeleton` e, depois, ser importados usando os parâmetros `--cli-input-json` e `--cli-input-yaml`.
**Topics**
+ [Sobre esqueletos e arquivos de entrada da AWS CLI](#cli-usage-skeleton-about)
+ [Gerar e importar um esqueleto de comando](#cli-usage-skeleton-generate)
+ [Combinar arquivos de entrada e parâmetros da linha de comandos](#cli-usage-skeleton-combine)
## Sobre esqueletos e arquivos de entrada da AWS CLI
A maioria dos comandos da AWS Command Line Interface (AWS CLI) permite aceitar as entradas de parâmetro usando os parâmetros `--cli-input-json` e `--cli-input-yaml`.
Esses mesmos comandos usam o parâmetro `--generate-cli-skeleton` para gerar um arquivo tanto no formato JSON como YAML com todos os parâmetros que você pode editar e preencher. Depois, é possível executar o comando com o parâmetro `--cli-input-json` ou `--cli-input-yaml` e apontar para o arquivo preenchido.
**Importante**
Comandos personalizados da AWS CLI, como os [comandos `aws s3`](https://docs.aws.amazon.com/cli/latest/reference/s3/index.html) não são compatíveis com os parâmetros `--generate-cli-skeleton` ou `--cli-input-json` e `--cli-input-yaml` descritos neste tópico. Para verificar se um comando específico é compatível com esses parâmetros, execute o [comando `help`](cli-usage-help.md#cli-usage-help-command) para o comando que você deseja usar ou consulte o ou o [Guia de referência da AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/reference/index.html).
O `--generate-cli-skeleton` gera e exibe um modelo de parâmetro que pode ser personalizado e usado como entrada em um comando. O modelo gerado inclui todos os parâmetros compatíveis com o comando.
O parâmetro `--generate-cli-skeleton` aceita um dos seguintes valores:
+ `input`: o modelo gerado inclui todos os parâmetros de entrada formatados como JSON. Este é o valor padrão.
+ `yaml-input`: o modelo gerado inclui todos os parâmetros de entrada formatados como YAML.
+ `output` – o modelo gerado inclui todos os parâmetros de saída formatados como JSON. No momento, não é possível solicitar os parâmetros de saída como YAML.
Como a AWS CLI é essencialmente um “wrapper” em torno da API de serviço, o arquivo de esqueleto espera que você faça referência a todos os parâmetros pelo nome do parâmetro da API subjacente. Isso provavelmente é diferente do nome do parâmetro da AWS CLI. Por exemplo, um parâmetro da AWS CLI chamado `user-name` pode ser mapeado para o parâmetro da API do serviço da AWS chamado `UserName` (observe a capitalização alterada e o traço ausente). Recomendamos usar a opção `--generate-cli-skeleton` para gerar o modelo com os nomes de parâmetro “corretos” a fim de evitar erros. Consulte o Guia de referência da API do serviço para ver os nomes de parâmetro esperados. É possível excluir quaisquer parâmetros do modelo que não sejam necessários e para os quais você não deseja fornecer um valor.
Por exemplo, se você executar o seguinte comando, ele gerará o modelo de parâmetro para o comando do Amazon Elastic Compute Cloud (Amazon EC2) **run-instances**.
------
#### [ JSON ]
O exemplo a seguir mostra como gerar um modelo formatado em JSON usando o valor padrão (`input`) para o `--generate-cli-skeleton` parâmetro.
```
$ aws ec2 run-instances --generate-cli-skeleton
```
```
{
"DryRun": true,
"ImageId": "",
"MinCount": 0,
"MaxCount": 0,
"KeyName": "",
"SecurityGroups": [
""
],
"SecurityGroupIds": [
""
],
"UserData": "",
"InstanceType": "",
"Placement": {
"AvailabilityZone": "",
"GroupName": "",
"Tenancy": ""
},
"KernelId": "",
"RamdiskId": "",
"BlockDeviceMappings": [
{
"VirtualName": "",
"DeviceName": "",
"Ebs": {
"SnapshotId": "",
"VolumeSize": 0,
"DeleteOnTermination": true,
"VolumeType": "",
"Iops": 0,
"Encrypted": true
},
"NoDevice": ""
}
],
"Monitoring": {
"Enabled": true
},
"SubnetId": "",
"DisableApiTermination": true,
"InstanceInitiatedShutdownBehavior": "",
"PrivateIpAddress": "",
"ClientToken": "",
"AdditionalInfo": "",
"NetworkInterfaces": [
{
"NetworkInterfaceId": "",
"DeviceIndex": 0,
"SubnetId": "",
"Description": "",
"PrivateIpAddress": "",
"Groups": [
""
],
"DeleteOnTermination": true,
"PrivateIpAddresses": [
{
"PrivateIpAddress": "",
"Primary": true
}
],
"SecondaryPrivateIpAddressCount": 0,
"AssociatePublicIpAddress": true
}
],
"IamInstanceProfile": {
"Arn": "",
"Name": ""
},
"EbsOptimized": true
}
```
------
#### [ YAML ]
O exemplo a seguir mostra como gerar um modelo formatado em YAML usando o valor `yaml-input` para o parâmetro `--generate-cli-skeleton`.
```
$ aws ec2 run-instances --generate-cli-skeleton yaml-input
```
```
BlockDeviceMappings: # The block device mapping entries.
- DeviceName: '' # The device name (for example, /dev/sdh or xvdh).
VirtualName: '' # The virtual device name (ephemeralN).
Ebs: # Parameters used to automatically set up Amazon EBS volumes when the instance is launched.
DeleteOnTermination: true # Indicates whether the EBS volume is deleted on instance termination.
Iops: 0 # The number of I/O operations per second (IOPS) that the volume supports.
SnapshotId: '' # The ID of the snapshot.
VolumeSize: 0 # The size of the volume, in GiB.
VolumeType: st1 # The volume type. Valid values are: standard, io1, gp2, sc1, st1.
Encrypted: true # Indicates whether the encryption state of an EBS volume is changed while being restored from a backing snapshot.
KmsKeyId: '' # Identifier (key ID, key alias, ID ARN, or alias ARN) for a customer managed KMS key under which the EBS volume is encrypted.
NoDevice: '' # Suppresses the specified device included in the block device mapping of the AMI.
ImageId: '' # The ID of the AMI.
InstanceType: c4.4xlarge # The instance type. Valid values are: t1.micro, t2.nano, t2.micro, t2.small, t2.medium, t2.large, t2.xlarge, t2.2xlarge, t3.nano, t3.micro, t3.small, t3.medium, t3.large, t3.xlarge, t3.2xlarge, t3a.nano, t3a.micro, t3a.small, t3a.medium, t3a.large, t3a.xlarge, t3a.2xlarge, m1.small, m1.medium, m1.large, m1.xlarge, m3.medium, m3.large, m3.xlarge, m3.2xlarge, m4.large, m4.xlarge, m4.2xlarge, m4.4xlarge, m4.10xlarge, m4.16xlarge, m2.xlarge, m2.2xlarge, m2.4xlarge, cr1.8xlarge, r3.large, r3.xlarge, r3.2xlarge, r3.4xlarge, r3.8xlarge, r4.large, r4.xlarge, r4.2xlarge, r4.4xlarge, r4.8xlarge, r4.16xlarge, r5.large, r5.xlarge, r5.2xlarge, r5.4xlarge, r5.8xlarge, r5.12xlarge, r5.16xlarge, r5.24xlarge, r5.metal, r5a.large, r5a.xlarge, r5a.2xlarge, r5a.4xlarge, r5a.8xlarge, r5a.12xlarge, r5a.16xlarge, r5a.24xlarge, r5d.large, r5d.xlarge, r5d.2xlarge, r5d.4xlarge, r5d.8xlarge, r5d.12xlarge, r5d.16xlarge, r5d.24xlarge, r5d.metal, r5ad.large, r5ad.xlarge, r5ad.2xlarge, r5ad.4xlarge, r5ad.8xlarge, r5ad.12xlarge, r5ad.16xlarge, r5ad.24xlarge, x1.16xlarge, x1.32xlarge, x1e.xlarge, x1e.2xlarge, x1e.4xlarge, x1e.8xlarge, x1e.16xlarge, x1e.32xlarge, i2.xlarge, i2.2xlarge, i2.4xlarge, i2.8xlarge, i3.large, i3.xlarge, i3.2xlarge, i3.4xlarge, i3.8xlarge, i3.16xlarge, i3.metal, i3en.large, i3en.xlarge, i3en.2xlarge, i3en.3xlarge, i3en.6xlarge, i3en.12xlarge, i3en.24xlarge, i3en.metal, hi1.4xlarge, hs1.8xlarge, c1.medium, c1.xlarge, c3.large, c3.xlarge, c3.2xlarge, c3.4xlarge, c3.8xlarge, c4.large, c4.xlarge, c4.2xlarge, c4.4xlarge, c4.8xlarge, c5.large, c5.xlarge, c5.2xlarge, c5.4xlarge, c5.9xlarge, c5.12xlarge, c5.18xlarge, c5.24xlarge, c5.metal, c5d.large, c5d.xlarge, c5d.2xlarge, c5d.4xlarge, c5d.9xlarge, c5d.18xlarge, c5n.large, c5n.xlarge, c5n.2xlarge, c5n.4xlarge, c5n.9xlarge, c5n.18xlarge, cc1.4xlarge, cc2.8xlarge, g2.2xlarge, g2.8xlarge, g3.4xlarge, g3.8xlarge, g3.16xlarge, g3s.xlarge, g4dn.xlarge, g4dn.2xlarge, g4dn.4xlarge, g4dn.8xlarge, g4dn.12xlarge, g4dn.16xlarge, cg1.4xlarge, p2.xlarge, p2.8xlarge, p2.16xlarge, p3.2xlarge, p3.8xlarge, p3.16xlarge, p3dn.24xlarge, d2.xlarge, d2.2xlarge, d2.4xlarge, d2.8xlarge, f1.2xlarge, f1.4xlarge, f1.16xlarge, m5.large, m5.xlarge, m5.2xlarge, m5.4xlarge, m5.8xlarge, m5.12xlarge, m5.16xlarge, m5.24xlarge, m5.metal, m5a.large, m5a.xlarge, m5a.2xlarge, m5a.4xlarge, m5a.8xlarge, m5a.12xlarge, m5a.16xlarge, m5a.24xlarge, m5d.large, m5d.xlarge, m5d.2xlarge, m5d.4xlarge, m5d.8xlarge, m5d.12xlarge, m5d.16xlarge, m5d.24xlarge, m5d.metal, m5ad.large, m5ad.xlarge, m5ad.2xlarge, m5ad.4xlarge, m5ad.8xlarge, m5ad.12xlarge, m5ad.16xlarge, m5ad.24xlarge, h1.2xlarge, h1.4xlarge, h1.8xlarge, h1.16xlarge, z1d.large, z1d.xlarge, z1d.2xlarge, z1d.3xlarge, z1d.6xlarge, z1d.12xlarge, z1d.metal, u-6tb1.metal, u-9tb1.metal, u-12tb1.metal, u-18tb1.metal, u-24tb1.metal, a1.medium, a1.large, a1.xlarge, a1.2xlarge, a1.4xlarge, a1.metal, m5dn.large, m5dn.xlarge, m5dn.2xlarge, m5dn.4xlarge, m5dn.8xlarge, m5dn.12xlarge, m5dn.16xlarge, m5dn.24xlarge, m5n.large, m5n.xlarge, m5n.2xlarge, m5n.4xlarge, m5n.8xlarge, m5n.12xlarge, m5n.16xlarge, m5n.24xlarge, r5dn.large, r5dn.xlarge, r5dn.2xlarge, r5dn.4xlarge, r5dn.8xlarge, r5dn.12xlarge, r5dn.16xlarge, r5dn.24xlarge, r5n.large, r5n.xlarge, r5n.2xlarge, r5n.4xlarge, r5n.8xlarge, r5n.12xlarge, r5n.16xlarge, r5n.24xlarge.
Ipv6AddressCount: 0 # [EC2-VPC] The number of IPv6 addresses to associate with the primary network interface.
Ipv6Addresses: # [EC2-VPC] The IPv6 addresses from the range of the subnet to associate with the primary network interface.
- Ipv6Address: '' # The IPv6 address.
KernelId: '' # The ID of the kernel.
KeyName: '' # The name of the key pair.
MaxCount: 0 # [REQUIRED] The maximum number of instances to launch.
MinCount: 0 # [REQUIRED] The minimum number of instances to launch.
Monitoring: # Specifies whether detailed monitoring is enabled for the instance.
Enabled: true # [REQUIRED] Indicates whether detailed monitoring is enabled.
Placement: # The placement for the instance.
AvailabilityZone: '' # The Availability Zone of the instance.
Affinity: '' # The affinity setting for the instance on the Dedicated Host.
GroupName: '' # The name of the placement group the instance is in.
PartitionNumber: 0 # The number of the partition the instance is in.
HostId: '' # The ID of the Dedicated Host on which the instance resides.
Tenancy: dedicated # The tenancy of the instance (if the instance is running in a VPC). Valid values are: default, dedicated, host.
SpreadDomain: '' # Reserved for future use.
RamdiskId: '' # The ID of the RAM disk to select.
SecurityGroupIds: # The IDs of the security groups.
- ''
SecurityGroups: # [default VPC] The names of the security groups.
- ''
SubnetId: '' # [EC2-VPC] The ID of the subnet to launch the instance into.
UserData: '' # The user data to make available to the instance.
AdditionalInfo: '' # Reserved.
ClientToken: '' # Unique, case-sensitive identifier you provide to ensure the idempotency of the request.
DisableApiTermination: true # If you set this parameter to true, you can't terminate the instance using the Amazon EC2 console, CLI, or API; otherwise, you can.
DryRun: true # Checks whether you have the required permissions for the action, without actually making the request, and provides an error response.
EbsOptimized: true # Indicates whether the instance is optimized for Amazon EBS I/O.
IamInstanceProfile: # The IAM instance profile.
Arn: '' # The Amazon Resource Name (ARN) of the instance profile.
Name: '' # The name of the instance profile.
InstanceInitiatedShutdownBehavior: stop # Indicates whether an instance stops or terminates when you initiate shutdown from the instance (using the operating system command for system shutdown). Valid values are: stop, terminate.
NetworkInterfaces: # The network interfaces to associate with the instance.
- AssociatePublicIpAddress: true # Indicates whether to assign a public IPv4 address to an instance you launch in a VPC.
DeleteOnTermination: true # If set to true, the interface is deleted when the instance is terminated.
Description: '' # The description of the network interface.
DeviceIndex: 0 # The position of the network interface in the attachment order.
Groups: # The IDs of the security groups for the network interface.
- ''
Ipv6AddressCount: 0 # A number of IPv6 addresses to assign to the network interface.
Ipv6Addresses: # One or more IPv6 addresses to assign to the network interface.
- Ipv6Address: '' # The IPv6 address.
NetworkInterfaceId: '' # The ID of the network interface.
PrivateIpAddress: '' # The private IPv4 address of the network interface.
PrivateIpAddresses: # One or more private IPv4 addresses to assign to the network interface.
- Primary: true # Indicates whether the private IPv4 address is the primary private IPv4 address.
PrivateIpAddress: '' # The private IPv4 addresses.
SecondaryPrivateIpAddressCount: 0 # The number of secondary private IPv4 addresses.
SubnetId: '' # The ID of the subnet associated with the network interface.
InterfaceType: '' # The type of network interface.
PrivateIpAddress: '' # [EC2-VPC] The primary IPv4 address.
ElasticGpuSpecification: # An elastic GPU to associate with the instance.
- Type: '' # [REQUIRED] The type of Elastic Graphics accelerator.
ElasticInferenceAccelerators: # An elastic inference accelerator to associate with the instance.
- Type: '' # [REQUIRED] The type of elastic inference accelerator.
TagSpecifications: # The tags to apply to the resources during launch.
- ResourceType: network-interface # The type of resource to tag. Valid values are: client-vpn-endpoint, customer-gateway, dedicated-host, dhcp-options, elastic-ip, fleet, fpga-image, host-reservation, image, instance, internet-gateway, launch-template, natgateway, network-acl, network-interface, reserved-instances, route-table, security-group, snapshot, spot-instances-request, subnet, traffic-mirror-filter, traffic-mirror-session, traffic-mirror-target, transit-gateway, transit-gateway-attachment, transit-gateway-route-table, volume, vpc, vpc-peering-connection, vpn-connection, vpn-gateway.
Tags: # The tags to apply to the resource.
- Key: '' # The key of the tag.
Value: '' # The value of the tag.
LaunchTemplate: # The launch template to use to launch the instances.
LaunchTemplateId: '' # The ID of the launch template.
LaunchTemplateName: '' # The name of the launch template.
Version: '' # The version number of the launch template.
InstanceMarketOptions: # The market (purchasing) option for the instances.
MarketType: spot # The market type. Valid values are: spot.
SpotOptions: # The options for Spot Instances.
MaxPrice: '' # The maximum hourly price you're willing to pay for the Spot Instances.
SpotInstanceType: one-time # The Spot Instance request type. Valid values are: one-time, persistent.
BlockDurationMinutes: 0 # The required duration for the Spot Instances (also known as Spot blocks), in minutes.
ValidUntil: 1970-01-01 00:00:00 # The end date of the request.
InstanceInterruptionBehavior: terminate # The behavior when a Spot Instance is interrupted. Valid values are: hibernate, stop, terminate.
CreditSpecification: # The credit option for CPU usage of the T2 or T3 instance.
CpuCredits: '' # [REQUIRED] The credit option for CPU usage of a T2 or T3 instance.
CpuOptions: # The CPU options for the instance.
CoreCount: 0 # The number of CPU cores for the instance.
ThreadsPerCore: 0 # The number of threads per CPU core.
CapacityReservationSpecification: # Information about the Capacity Reservation targeting option.
CapacityReservationPreference: none # Indicates the instance's Capacity Reservation preferences. Valid values are: open, none.
CapacityReservationTarget: # Information about the target Capacity Reservation.
CapacityReservationId: '' # The ID of the Capacity Reservation.
HibernationOptions: # Indicates whether an instance is enabled for hibernation.
Configured: true # If you set this parameter to true, your instance is enabled for hibernation.
LicenseSpecifications: # The license configurations.
- LicenseConfigurationArn: '' # The Amazon Resource Name (ARN) of the license configuration.
```
------
## Gerar e importar um esqueleto de comando
**Para gerar e usar um arquivo de esqueleto de parâmetro**
1. Execute o comando com o parâmetro `--generate-cli-skeleton` para produzir tanto JSON quanto YAML e direcionar a saída a um arquivo para salvá-lo.
------
#### [ JSON ]
```
$ aws ec2 run-instances --generate-cli-skeleton input > ec2runinst.json
```
------
#### [ YAML ]
```
$ aws ec2 run-instances --generate-cli-skeleton yaml-input > ec2runinst.yaml
```
------
1. Abra o arquivo de esqueleto do parâmetro em seu editor de texto e remova os parâmetros que não são mais necessários. Por exemplo, você pode reduzir o modelo ao indicado a seguir. Confirme se o arquivo ainda é JSON ou YAML válido depois de remover os elementos que não são necessários.
------
#### [ JSON ]
```
{
"DryRun": true,
"ImageId": "",
"KeyName": "",
"SecurityGroups": [
""
],
"InstanceType": "",
"Monitoring": {
"Enabled": true
}
}
```
------
#### [ YAML ]
```
DryRun: true
ImageId: ''
KeyName: ''
SecurityGroups:
- ''
InstanceType:
Monitoring:
Enabled: true
```
------
Neste exemplo, deixamos o parâmetro `DryRun` definido como `true` para usar o recurso de simulação do Amazon EC2. Esse recurso permite que você teste com segurança o comando sem realmente criar ou modificar nenhum recursos.
1. Preencha os valores restantes com valores apropriados para seu cenário. Neste exemplo, fornecemos o tipo de instância, o nome da chave, o grupo de segurança e o identificador da imagem de máquina da Amazon (AMI) que devem ser usados. Este exemplo assume a Região da AWS padrão. A AMI `ami-dfc39aef` é uma imagem de 64 bits do hospedada na região `us-west-2`. Se você usar uma região diferente, será necessário [encontrar o ID da AMI correta para usar](https://aws.amazon.com/amazon-linux-ami/).
------
#### [ JSON ]
```
{
"DryRun": true,
"ImageId": "ami-dfc39aef",
"KeyName": "mykey",
"SecurityGroups": [
"my-sg"
],
"InstanceType": "t2.micro",
"Monitoring": {
"Enabled": true
}
}
```
------
#### [ YAML ]
```
DryRun: true
ImageId: 'ami-dfc39aef'
KeyName: 'mykey'
SecurityGroups:
- 'my-sg'
InstanceType: 't2.micro'
Monitoring:
Enabled: true
```
------
1. Execute o comando com os parâmetros concluídos, transmitindo o arquivo do modelo concluído tanto ao parâmetro `--cli-input-json` quanto ao `cli-input-yaml` usando o prefixo `file://`. A AWS CLI interpreta o caminho como sendo relativo ao diretório de trabalho atual. No exemplo a seguir, a AWS CLI procura o arquivo no diretório de trabalho atual.
------
#### [ JSON ]
```
$ aws ec2 run-instances --cli-input-json file://ec2runinst.json
```
```
A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set.
```
------
#### [ YAML ]
```
$ aws ec2 run-instances --cli-input-yaml file://ec2runinst.yaml
```
```
A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set.
```
------
O erro de simulação indica que JSON ou YAML está formado corretamente e os valores de parâmetro são válidos. Se outros problemas forem relatados na saída, corrija-os e repita a etapa anterior até que a mensagem “`Request would have succeeded`“ seja exibida.
1. Agora você pode definir o parâmetro `DryRun` como `false` para desativar a simulação.
------
#### [ JSON ]
```
{
"DryRun": false,
"ImageId": "ami-dfc39aef",
"KeyName": "mykey",
"SecurityGroups": [
"my-sg"
],
"InstanceType": "t2.micro",
"Monitoring": {
"Enabled": true
}
}
```
------
#### [ YAML ]
```
DryRun: false
ImageId: 'ami-dfc39aef'
KeyName: 'mykey'
SecurityGroups:
- 'my-sg'
InstanceType: 't2.micro'
Monitoring:
Enabled: true
```
------
1. Execute o comando, e `run-instances` realmente iniciará uma instância do Amazon EC2 e exibirá os detalhes gerados pelo início bem-sucedido. O formato da saída é controlado pelo parâmetro `--output`, separadamente do formato do modelo de parâmetro de entrada.
------
#### [ JSON ]
```
$ aws ec2 run-instances --cli-input-json file://ec2runinst.json --output json
```
```
{
"OwnerId": "123456789012",
"ReservationId": "r-d94a2b1",
"Groups": [],
"Instances": [
...
```
------
#### [ YAML ]
```
$ aws ec2 run-instances --cli-input-yaml file://ec2runinst.yaml --output yaml
```
```
OwnerId: '123456789012'
ReservationId: 'r-d94a2b1',
Groups":
- ''
Instances:
...
```
------
## Combinar arquivos de entrada e parâmetros da linha de comandos
Um arquivo de entrada pode ser usado para todos os parâmetros ou pode ser combinado com os parâmetros especificados na AWS CLI. É possível usar esse recurso para configurações que você reutiliza com frequência em um arquivo de entrada, mantendo suas configurações individuais no próprio comando.
Os exemplos de `aws ec2 run-instances` a seguir combinam o uso de um arquivo de entrada e parâmetros. Fornecemos o tipo de instância, o nome da chave, o grupo de segurança e o identificador da imagem de máquina da Amazon (AMI) que devem ser usados e assumimos a Região da AWS padrão. A AMI `ami-dfc39aef` é uma imagem de 64 bits do hospedada na região `us-west-2`. Se você usar uma região diferente, será necessário [encontrar o ID da AMI correta para usar](https://aws.amazon.com/amazon-linux-ami/).
------
#### [ JSON ]
Conteúdo do arquivo JSON:
```
{
"ImageId": "ami-dfc39aef",
"KeyName": "mykey",
"SecurityGroups": [
"my-sg"
],
"InstanceType": "t2.micro",
"Monitoring": {
"Enabled": true
}
}
```
------
#### [ YAML ]
Conteúdo do arquivo YAML:
```
ImageId: 'ami-dfc39aef'
KeyName: 'mykey'
SecurityGroups:
- 'my-sg'
InstanceType: 't2.micro'
Monitoring:
Enabled: true
```
------
O exemplo a seguir usa o arquivo de entrada em conjunto com o parâmetro `--dry-run` para executar uma simulação do comando e confirmar se você tem as permissões necessárias e se preencheu o arquivo com valores válidos.
------
#### [ JSON ]
```
$ aws ec2 run-instances --cli-input-json file://ec2runinst.json --dry-run
```
```
A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set.
```
------
#### [ YAML ]
```
$ aws ec2 run-instances --cli-input-yaml file://ec2runinst.yaml --dry-run
```
```
A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set.
```
------
O exemplo a seguir usa o mesmo arquivo de entrada, mas com o parâmetro `--no-dry-run` para executar o comando na íntegra.
------
#### [ JSON ]
```
$ aws ec2 run-instances --cli-input-json file://ec2runinst.json --no-dry-run --output json
```
```
{
"OwnerId": "123456789012",
"ReservationId": "r-d94a2b1",
"Groups": [],
"Instances": [
...
```
------
#### [ YAML ]
```
$ aws ec2 run-instances --cli-input-yaml file://ec2runinst.yaml --no-dry-run --output yaml
```
```
OwnerId: '123456789012'
ReservationId: 'r-d94a2b1',
Groups":
- ''
Instances:
...
```
------
# Uso da sintaxe simplificada na AWS CLI
A AWS Command Line Interface (AWS CLI) pode aceitar muitos de seus parâmetros de opção no formato JSON. No entanto, pode ser entediante inserir grandes estruturas ou listas de JSON na linha de comando. Para tornar isso mais fácil, a AWS CLI também oferece suporte a uma sintaxe abreviada mais simples que permite a representação de seus parâmetros de opção em vez de utilizar o formato JSON completo.
**Topics**
+ [Estruturar parâmetros com pares de chave-valor](#shorthand-structure-parameters)
+ [Carregar um arquivo como um valor de sintaxe abreviada](#shorthand-files)
+ [Usar sintaxe simplificada com a AWS CLI](#shorthand-list-parameters)
## Estruturar parâmetros com pares de chave-valor
A sintaxe abreviada no AWS CLI facilita a inserção de parâmetros simples de entrada pelos usuários (estruturas não aninhadas). O formato é uma lista de pares de chave/valor separados por vírgula. Use as regras de [aspas](cli-usage-parameters-quoting-strings.md) e escape apropriadas para seu terminal, pois a sintaxe abreviada são strings.
------
#### [ Linux or macOS ]
```
--option key1=value1,key2=value2,key3=value3
```
É equivalente ao exemplo a seguir, formatado em JSON.
```
--option '{"key1":"value1","key2":"value2","key3":"value3"}'
```
------
#### [ Windows ]
```
--option "key1=value1,key2=value2,key3=value3"
```
É equivalente ao exemplo a seguir, formatado em JSON.
```
--option '{"key1":"value1","key2":"value2","key3":"value3"}'
```
------
Não pode haver nenhum espaço em branco entre cada par de chave/valor separado por vírgula. Aqui está um exemplo do comando `update-table` do Amazon DynamoDB com a opção `--provisioned-throughput` especificada no formato simplificado.
```
$ aws dynamodb update-table \
--provisioned-throughput ReadCapacityUnits=15,WriteCapacityUnits=10 \
--table-name MyDDBTable
```
Isso é equivalente ao exemplo a seguir formatado em JSON.
```
$ aws dynamodb update-table \
--provisioned-throughput '{"ReadCapacityUnits":15,"WriteCapacityUnits":10}' \
--table-name MyDDBTable
```
## Carregar um arquivo como um valor de sintaxe abreviada
Quando um valor é grande ou complexo, geralmente é mais fácil carregar como um valor. Ao carregar um arquivo como um valor de sintaxe abreviada, a formatação muda um pouco. Em vez de `key=value`, você usa o operador `@=` no lugar do operador `=`. O `@=` indica à AWS CLI que o valor deve ser lido como um caminho de arquivo e não como uma string. Ao carregar arquivos em sintaxe abreviada, [aplicam-se as regras comuns de formatação de arquivos da AWS CLI](cli-usage-parameters-file.md). O exemplo a seguir mostra um par de chave-valor carregando um arquivo como seu valor.
------
#### [ Linux or macOS ]
```
--option key@=file://template.txt
```
------
#### [ Windows ]
```
--option "key1@=file://template.txt"
```
------
O exemplo a seguir demonstra o carregamento de um arquivo de certificado para o comando `aws rolesanywhere create-trust-anchor`.
```
$ aws rolesanywhere create-trust-anchor --name TrustAnchor \
--source sourceData={x509CertificateData@=file://root-ca.crt},sourceType="CERTIFICATE_BUNDLE" \
--enabled
```
## Usar sintaxe simplificada com a AWS CLI
Você pode especificar os parâmetros de entrada em um formulário de lista de duas formas: JSON ou abreviada. A sintaxe abreviada da AWS CLI é projetada para facilitar a inserção de listas com número, sequência de caracteres, estruturas aninhados ou não.
O formato básico é mostrada aqui, onde os valores na lista são separados por um único espaço.
```
--option value1 value2 value3
```
Isso é equivalente ao exemplo a seguir, formatado em JSON.
```
--option '[value1,value2,value3]'
```
Como mencionado anteriormente, é possível especificar uma lista de números, uma lista de strings ou uma lista de estruturas de dados não aninhados em formato abreviado. Veja a seguir um exemplo do comando `stop-instances` do Amazon Elastic Compute Cloud (Amazon EC2), onde o parâmetro de entrada (lista de strings) para a opção `--instance-ids` é especificado no formato simplificado.
```
$ aws ec2 stop-instances \
--instance-ids i-1486157a i-1286157c i-ec3a7e87
```
Isso é equivalente ao exemplo a seguir formatado em JSON.
```
$ aws ec2 stop-instances \
--instance-ids '["i-1486157a","i-1286157c","i-ec3a7e87"]'
```
A seguir está um exemplo do comando `create-tags` do Amazon EC2, que leva uma lista de estruturas não aninhadas para a opção `--tags`. A opção `--resources` especifica o ID da instância a ser marcada.
```
$ aws ec2 create-tags \
--resources i-1286157c \
--tags Key=My1stTag,Value=Value1 Key=My2ndTag,Value=Value2 Key=My3rdTag,Value=Value3
```
Isso é equivalente ao exemplo a seguir, formatado em JSON. O parâmetro JSON é escrito em várias linhas para melhor leitura.
```
$ aws ec2 create-tags \
--resources i-1286157c \
--tags '[
{"Key": "My1stTag", "Value": "Value1"},
{"Key": "My2ndTag", "Value": "Value2"},
{"Key": "My3rdTag", "Value": "Value3"}
]'
```
# Habilitar e usar os prompts de comando na AWS CLI
Você pode fazer com que a AWS CLI versão 2 solicite comandos, parâmetros e recursos quando você executa um comando da `aws`.
**Topics**
+ [Como funciona](#cli-usage-auto-prompt-about)
+ [Recursos do prompt automático](#cli-usage-auto-prompt-features)
+ [Modos de prompt automático](#cli-usage-auto-prompt-modes)
+ [Configurar o prompt automático](#cli-usage-auto-prompt-configure)
## Como funciona
Se estiver habilitado, o prompt automático permitirá usar a tecla **ENTER **para concluir um comando inserido parcialmente. Após pressionar a tecla **ENTER**, comandos, parâmetros e recursos serão sugeridos com base no que você digitar. As sugestões listam o nome do comando, parâmetro ou recurso à esquerda e uma descrição dele à direita. Para selecionar e usar uma sugestão, use as teclas de setas para realçar uma linha e pressione a**Barra de espaço**. Após terminar de inserir seu comando, pressione **ENTER** para executá-lo. O exemplo a seguir demonstra como é a aparência de uma lista sugerida do prompt automático.
```
$ aws
> aws a
accessanalyzer Access Analyzer
acm AWS Certificate Manager
acm-pca AWS Certificate Manager Private Certificate Authority
alexaforbusiness Alexa For Business
amplify AWS Amplify
```
## Recursos do prompt automático
O prompt automático contém os seguintes recursos úteis:
**Painel de documentação**
Fornece a documentação de ajuda para o comando atual. Para abrir a documentação, pressione a tecla **F3**.
**Conclusão de comando**
Sugere comandos da `aws` que podem ser usados. Para ver uma lista, digite parcialmente o comando. O exemplo a seguir está procurando um serviço começando com a letra `a`.
```
$ aws
> aws a
accessanalyzer Access Analyzer
acm AWS Certificate Manager
acm-pca AWS Certificate Manager Private Certificate Authority
alexaforbusiness Alexa For Business
amplify AWS Amplify
```
**Preenchimento automático de parâmetros**
Depois que um comando é digitado, o prompt automático começa a sugerir parâmetros. As descrições dos parâmetros incluem o tipo de valor e uma descrição do que é o parâmetro. Os parâmetros obrigatórios são listados primeiro e rotulados conforme necessário. O exemplo a seguir mostra a lista de parâmetros do `aws dynamodb describe-table`.
```
$ aws dynamodb describe-table
> aws dynamodb describe-table
--table-name (required) [string] The name of the table to describe.
--cli-input-json [string] Reads arguments from the JSON string provided. The JSON string follows the format provide...
--cli-input-yaml [string] Reads arguments from the YAML string provided. The YAML string follows the format provide...
--generate-cli-skeleton [string] Prints a JSON skeleton to standard output without sending an API request. If provided wit...
```
**Preenchimento automático de recursos**
O prompt automático faz chamadas de API da AWS usando propriedades de recursos da AWS disponíveis para sugerir valores de recursos. Isso permite que o prompt automático sugira possíveis recursos pertencentes a você ao inserir parâmetros. No exemplo a seguir, o prompt automático lista seus nomes de tabela ao preencher o parâmetro `--table-name` do comando `aws dynamodb describe-table`.
```
$ aws dynamodb describe-table
> aws dynamodb describe-table --table-name
Table1
Table2
Table3
```
**Preenchimento automático de sintaxe abreviada**
Para parâmetros que usam sintaxe abreviada, o prompt automático sugere valores a serem usados. No exemplo a seguir, o prompt automático lista os valores de sintaxe abreviada para o parâmetro `--placement` no comando `aws ec2 run-instances`.
```
$ aws ec2 run-instances
> aws ec2 run-instances --placement
AvailabilityZone= [string] The Availability Zone of the instance. If not specified, an Availability Zone wil...
Affinity= [string] The affinity setting for the instance on the Dedicated Host. This parameter is no...
GroupName= [string] The name of the placement group the instance is in.
PartitionNumber= [integer] The number of the partition the instance is in. Valid only if the placement grou...
```
**Preenchimento automático de nomes de arquivos**
Ao preencher parâmetros em comandos da `aws`, o preenchimento automático sugere nomes de arquivos locais após o uso dos prefixos `file://` ou `fileb://`. No exemplo a seguir, o prompt automático sugere arquivos locais depois da inserção de `--item file://` para o comando `aws ec2 run-instances`.
```
$ aws ec2 run-instances
> aws ec2 run-instances --item file://
item1.txt
file1.json
file2.json
```
**Preenchimento automático de regiões**
Ao usar o parâmetro global `--region`, o prompt automático lista as possíveis regiões para seleção. No exemplo a seguir, o prompt automático sugere regiões depois da inserção de `--region` para o comando `aws dynamodb list-tables`.
```
$ aws dynamodb list-tables
> aws dynamodb list-tables --region
af-south-1
ap-east-1
ap-northeast-1
ap-northeast-2
```
**Preenchimento automático de perfis**
Quando o parâmetro global `--profile` é usado, o prompt automático lista seus perfis. No exemplo a seguir, o prompt automático sugere seus perfis depois da inserção de `--profile` para o comando `aws dynamodb list-tables`.
```
$ aws dynamodb list-tables
> aws dynamodb list-tables --profile
profile1
profile2
profile3
```
**Pesquisas difusas**
Completa comandos e valores que contêm um conjunto específico de caracteres. No exemplo a seguir, o prompt automático sugere regiões que contêm `eu` depois da inserção de `--region eu` para o comando `aws dynamodb list-tables`.
```
$ aws dynamodb list-tables
> aws dynamodb list-tables --region west
eu-west-1
eu-west-2
eu-west-3
us-west-1
```
**Histórico**
Para visualizar e executar comandos usados anteriormente no modo de prompt automático, pressione **CTRL \$1 R**. O histórico lista os comandos anteriores que você pode selecionar usando as teclas de seta. No exemplo a seguir, o histórico do modo de prompt automático é exibido.
```
$ aws
> aws
dynamodb list-tables
s3 ls
```
## Modos de prompt automático
O prompt automático para a AWS CLI versão 2 oferece 2 modos configuráveis:
+ **Modo completo:** usa o prompt automático cada vez que você tenta executar um comando `aws`, seja quando chamado manualmente via parâmetro `--cli-auto-prompt`, seja quando habilitado permanentemente. Isso inclui pressionar **ENTER** após um comando completo ou um comando incompleto.
+ **Modo parcial:** usa o prompt automático se um comando está incompleto ou não pode ser executado devido a erros de validação no lado do cliente. Esse modo é particularmente útil se você tem scripts pré-existentes, runbooks ou se deseja receber o prompt automático somente para comandos com os quais você não está familiarizado, em vez de ver o prompt para todos os comandos.
## Configurar o prompt automático
Para configurar o prompt automático, você pode usar os seguintes métodos em ordem de precedência:
+ **Opções de linha de comando**: habilite ou desabilite o prompt automático para um único comando. Usar `--cli-auto-prompt` para chamar o prompt automático e `--no-cli-auto-prompt` para desabilitá-lo.
+ **Variáveis de ambiente**: use a variável `aws\$1cli\$1auto\$1prompt`.
+ **Arquivos de configuração compartilhados**: use a configuração `cli\$1auto\$1prompt`.
# Controle de saída do comando na AWS CLI
Esta seção descreve as diferentes maneiras de controlar a saída da AWS Command Line Interface (AWS CLI). Personalizar a saída da AWS CLI em seu terminal pode melhorar a legibilidade, simplificar a automação de scripts e facilitar a navegação em conjuntos de dados maiores.
A AWS CLI aceita vários [formatos de saída](cli-usage-output-format.md), como [`json`](cli-usage-output-format.md#json-output), [`text`](cli-usage-output-format.md#text-output), [`yaml`](cli-usage-output-format.md#yaml-output), [`off`](cli-usage-output-format.md#off-output) e [`table`](cli-usage-output-format.md#table-output). Alguns serviços têm [paginação](cli-usage-pagination.md) do lado do servidor para seus dados e a AWS CLI fornece seus próprios recursos do lado do cliente para opções adicionais de paginação.
Por último, a AWS CLI com [filtragem nos lados do servidor e do cliente](cli-usage-filter.md) que você pode usar individualmente ou em conjunto para filtrar a saída da sua AWS CLI.
**Topics**
+ [Saída confidencial](#cli-usage-output-sensitive)
+ [Opções de saída do lado do servidor e do lado do cliente](#cli-usage-output-server-client)
+ [Definição do formato da saída na AWS CLI](cli-usage-output-format.md)
+ [Saída de erro estruturada na AWS CLI](cli-usage-error-format.md)
+ [Usar as opções de paginação na AWS CLI](cli-usage-pagination.md)
+ [Filtrar a saída na AWS CLI](cli-usage-filter.md)
## Saída confidencial
Algumas operações da AWS CLI podem retornar informações que podem ser consideradas confidenciais, incluindo informações de variáveis de ambiente. A exposição dessas informações pode representar um risco de segurança em determinados cenários; por exemplo, as informações podem ser incluídas nos logs de integração contínua e implantação contínua (CI/CD). Portanto, é importante que você revise quando está incluindo essa saída como parte de seus logs e suprima a saída quando não for necessária.
Para obter informações adicionais sobre a proteção de dados confidenciais, consulte [Proteção de dados no AWS CLI](data-protection.md).
Considere as seguintes práticas recomendadas:
+ Considere recuperar programaticamente seus segredos de um repositório de segredos, como o AWS Secrets Manager.
+ Analise o conteúdo dos seus logs de compilação para garantir que não contenham informações confidenciais. Considere abordagens como canalizar para `/dev/null` ou capturar a saída como uma variável bash ou PowerShell para suprimir as saídas do comando.
Veja a seguir um exemplo de bash para redirecionar a saída, mas não os erros, para `/dev/null`:
```
$ aws s3 ls > /dev/null
```
Para obter detalhes sobre como suprimir a saída do seu terminal, consulte a documentação do usuário do terminal que você usa.
+ Considere o acesso aos seus logs e defina o escopo do acesso de acordo com seu caso de uso.
## Opções de saída do lado do servidor e do lado do cliente
A AWS CLI conta com [filtragem nos lados do servidor e do cliente](cli-usage-filter.md) que você pode usar individualmente ou em conjunto para filtrar sua saída da AWS CLI. A filtragem no lado do servidor é processada primeiro e retorna a saída para a filtragem no lado do cliente. A filtragem no lado do servidor é compatível com a API do serviço. A filtragem no lado do cliente é suportada pelo cliente da AWS CLI com o parâmetro `--query`.
As opções de saída **do lado do servidor** são recursos diretamente compatíveis com a API do AWS service (Serviço da AWS). Os dados filtrados ou paginados não são enviados ao cliente, o que pode acelerar os tempos de resposta HTTP e melhorar a largura de banda para conjuntos de dados maiores.
As opções de saída **do lado do cliente** são recursos criados pela AWS CLI. Todos os dados são enviados ao cliente e, em seguida, a AWS CLI filtra ou realiza a paginação do conteúdo exibido. As operações do lado do cliente não economizam velocidade ou largura de banda para conjuntos de dados maiores.
Quando as opções do lado do servidor e do lado do cliente são usadas juntas, as operações do lado do servidor são concluídas primeiro e depois enviadas ao cliente para operações do lado do cliente. Essa ação usa a economia em potencial de velocidade e largura de banda das opções do lado do servidor, enquanto usa recursos adicionais da AWS CLI para obter a saída desejada.
# Definição do formato da saída na AWS CLI
Este tópico descreve os diferentes formatos de saída para a AWS Command Line Interface (AWS CLI). A AWS CLI oferece suporte aos seguintes formatos de saída:
+ **[`json`](#json-output)**: a saída é formatada como uma string [JSON](https://json.org/).
+ **[`yaml`](#yaml-output)**: a saída é formatada como uma string [YAML](https://yaml.org/).
+ **[`yaml-stream`](#yaml-stream-output)**: a saída é transmitida e formatada como uma string [YAML](https://yaml.org/). A transmissão possibilita um manuseio mais rápido de tipos de dados grandes.
+ **[`text`](#text-output)** – a saída é formatada como várias linhas de valores de string separados por tabulação. Isso pode ser útil para passar a saída para um processador de texto, como `grep`, `sed` ou `awk`.
+ **[`table`](#table-output)** – a saída é formatada como uma tabela usando os caracteres \$1\$1- para formar as bordas da célula. Geralmente, a informação é apresentada em um formato "amigável", que é muito mais fácil de ler do que outros, mas não tão útil programaticamente.
+ **[`off`](#off-output)**: a saída suprime todas as saídas de comando para stdout. Isso é útil em scripts de automação e pipelines de CI/CD em que somente é necessário verificar o código de saída do comando sem processar a saída.
## Como selecionar o formato de saída
Como explicado no tópico sobre [configuração](cli-chap-configure.md), você pode especificar o formato de saída de três maneiras:
+ **Usando a opção `output` em um perfil nomeado no arquivo `config`**: o exemplo a seguir ajusta o formato de saída padrão como `text`.
```
[default]
output=text
```
+ **Usando a variável de ambiente `AWS_DEFAULT_OUTPUT`**: a saída a seguir ajusta o formato como `table` para os comandos nessa sessão de linhas de comandos até que a variável seja alterada ou a sessão encerrada. Usar essa variável de ambiente substitui qualquer valor definido no arquivo `config`.
```
$ export AWS_DEFAULT_OUTPUT="table"
```
+ **Usando a opção `--output` na linha de comando**: o exemplo a seguir define a saída apenas deste comando como `json`. Usar essa opção no comando substitui qualquer variável de ambiente definida atualmente ou o valor no arquivo `config`.
```
$ aws swf list-domains --registration-status REGISTERED --output json
```
**Importante**
O tipo de saída especificado por você modifica a forma de operação da opção `--query`.
Se você especificar `--output text`, a saída será paginada *antes* que o filtro `--query` seja aplicado e a AWS CLI executará a consulta uma vez em *cada página* da saída. Consequentemente, a consulta inclui o primeiro elemento correspondente em cada página, o que pode resultar em uma saída adicional inesperada. Para filtrar ainda mais a saída, é possível usar outras ferramentas da linha de comando, como `head` ou `tail`.
Se você especificar `--output json`, `--output yaml` ou `--output yaml-stream`, a saída será completamente processada como uma única estrutura JSON nativa antes que o filtro `--query` seja aplicado. A AWS CLI executa a consulta apenas uma vez com relação a toda a estrutura, produzindo um resultado filtrado que é, então, a saída.
## Formato de saída JSON
[JSON](https://json.org) é o formato de saída padrão da AWS CLI. A maioria das linguagens de programação pode facilmente decodificar strings JSON usando funções internas ou com bibliotecas disponíveis publicamente. É possível combinar a saída JSON com a [opção --query](cli-usage-filter.md) de maneiras poderosas para filtrar e formatar a saída em formato JSON da AWS CLI.
Para filtragem mais avançada que talvez você não consiga fazer com `--query`, é possível considerar `jq`, um processador JSON da linha de comando. Baixe e localize o tutorial oficial em [http://stedolan.github.io/jq/](http://stedolan.github.io/jq/).
Veja a seguir um exemplo de saída JSON.
```
$ aws iam list-users --output json
```
```
{
"Users": [
{
"Path": "/",
"UserName": "Admin",
"UserId": "AIDA1111111111EXAMPLE",
"Arn": "arn:aws:iam::123456789012:user/Admin",
"CreateDate": "2014-10-16T16:03:09+00:00",
"PasswordLastUsed": "2016-06-03T18:37:29+00:00"
},
{
"Path": "/backup/",
"UserName": "backup-user",
"UserId": "AIDA2222222222EXAMPLE",
"Arn": "arn:aws:iam::123456789012:user/backup/backup-user",
"CreateDate": "2019-09-17T19:30:40+00:00"
},
{
"Path": "/",
"UserName": "cli-user",
"UserId": "AIDA3333333333EXAMPLE",
"Arn": "arn:aws:iam::123456789012:user/cli-user",
"CreateDate": "2019-09-17T19:11:39+00:00"
}
]
}
```
## Formato da saída YAML
O [YAML](https://yaml.org) é uma boa escolha para lidar com a saída programaticamente com serviços e ferramentas que emitem ou consomem strings no formato [YAML](https://yaml.org), como o CloudFormation com suporte para [modelos no formato YAML](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-formats.html).
Para filtragem mais avançada que talvez você não consiga fazer com `--query`, é possível considerar `yq`, um processador YAML da linha de comando. Você pode baixar `yq` no [repositório yq](https://github.com/mikefarah/yq) no *GitHub.*
Veja a seguir um exemplo de saída YAML.
```
$ aws iam list-users --output yaml
```
```
Users:
- Arn: arn:aws:iam::123456789012:user/Admin
CreateDate: '2014-10-16T16:03:09+00:00'
PasswordLastUsed: '2016-06-03T18:37:29+00:00'
Path: /
UserId: AIDA1111111111EXAMPLE
UserName: Admin
- Arn: arn:aws:iam::123456789012:user/backup/backup-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /backup/
UserId: AIDA2222222222EXAMPLE
UserName: arq-45EFD6D1-CE56-459B-B39F-F9C1F78FBE19
- Arn: arn:aws:iam::123456789012:user/cli-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /
UserId: AIDA3333333333EXAMPLE
UserName: cli-user
```
## Formato da saída de fluxo do YAML
O formato `yaml-stream` se beneficia do [YAML](https://yaml.org) e oferece uma visualização mais ágil/rápida de grandes conjuntos de dados ao transmitir os dados para você. Você pode começar a visualizar e usar dados de YAML antes do download de toda a consulta.
Para filtragem mais avançada que talvez você não consiga fazer com `--query`, é possível considerar `yq`, um processador YAML da linha de comando. Você pode baixar `yq` no [repositório yq](https://github.com/mikefarah/yq) no *GitHub.*
A seguir, veja um exemplo de saída `yaml-stream`.
```
$ aws iam list-users --output yaml-stream
```
```
- IsTruncated: false
Users:
- Arn: arn:aws:iam::123456789012:user/Admin
CreateDate: '2014-10-16T16:03:09+00:00'
PasswordLastUsed: '2016-06-03T18:37:29+00:00'
Path: /
UserId: AIDA1111111111EXAMPLE
UserName: Admin
- Arn: arn:aws:iam::123456789012:user/backup/backup-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /backup/
UserId: AIDA2222222222EXAMPLE
UserName: arq-45EFD6D1-CE56-459B-B39F-F9C1F78FBE19
- Arn: arn:aws:iam::123456789012:user/cli-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /
UserId: AIDA3333333333EXAMPLE
UserName: cli-user
```
Veja a seguir um exemplo de saída de `yaml-stream` usando o parâmetro `--page-size` para paginar o conteúdo YAML transmitido.
```
$ aws iam list-users --output yaml-stream --page-size 2
```
```
- IsTruncated: true
Marker: ab1234cdef5ghi67jk8lmo9p/q012rs3t445uv6789w0x1y2z/345a6b78c9d00/1efgh234ij56klmno78pqrstu90vwxyx
Users:
- Arn: arn:aws:iam::123456789012:user/Admin
CreateDate: '2014-10-16T16:03:09+00:00'
PasswordLastUsed: '2016-06-03T18:37:29+00:00'
Path: /
UserId: AIDA1111111111EXAMPLE
UserName: Admin
- Arn: arn:aws:iam::123456789012:user/backup/backup-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /backup/
UserId: AIDA2222222222EXAMPLE
UserName: arq-45EFD6D1-CE56-459B-B39F-F9C1F78FBE19
- IsTruncated: false
Users:
- Arn: arn:aws:iam::123456789012:user/cli-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /
UserId: AIDA3333333333EXAMPLE
UserName: cli-user
```
## Formato de saída de texto
O formato `text` organiza a saída da AWS CLI em linhas delimitadas por tabulação. Isso funciona bem com ferramentas de texto Unix tradicionais, como `grep`, `sed` e `awk`, bem como o processamento de texto executado pelo PowerShell.
O formato de saída `text` segue a estrutura básica mostrada abaixo. As colunas são classificados alfabeticamente por nomes de chaves correspondentes subjacentes do objeto JSON.
```
IDENTIFIER sorted-column1 sorted-column2
IDENTIFIER2 sorted-column1 sorted-column2
```
A seguir, veja um exemplo de saída `text`. Cada campo é separado dos outros por tabulação, com uma guia adicional na qual há um campo vazio.
```
$ aws iam list-users --output text
```
```
USERS arn:aws:iam::123456789012:user/Admin 2014-10-16T16:03:09+00:00 2016-06-03T18:37:29+00:00 / AIDA1111111111EXAMPLE Admin
USERS arn:aws:iam::123456789012:user/backup/backup-user 2019-09-17T19:30:40+00:00 /backup/ AIDA2222222222EXAMPLE backup-user
USERS arn:aws:iam::123456789012:user/cli-user 2019-09-17T19:11:39+00:00 / AIDA3333333333EXAMPLE cli-user
```
A quarta coluna é o campo `PasswordLastUsed` e está vazia nas duas últimas entradas porque esses usuários nunca fazem login no Console de gerenciamento da AWS.
**Importante**
*É altamente recomendável que, se você especificar uma saída `text`, também use sempre a opção [`--query`](cli-usage-filter.md) para garantir um comportamento consistente*.
Isso ocorre porque o formato de texto ordena alfabeticamente as colunas da saída pelo nome da chave do objeto JSON subjacente retornado pelo serviço da AWS, e recursos similares podem não têm os mesmos nomes de chave. Por exemplo, a representação JSON de uma instância do Amazon EC2 baseada em Linux pode ter elementos que não estão presentes na representação JSON de uma instância baseada em Windows ou vice-versa. Além disso, os recursos podem ter elementos de valores de chave adicionados ou removidos em futuras atualizações, alterando a ordem das colunas. Este é o local em que `--query` expande a funcionalidade da saída `text` para fornecer total controle sobre o formato de saída.
No exemplo a seguir, o comando especifica quais elementos devem ser exibidos e *define a ordem* das colunas com a notação da lista `[key1, key2, ...]`. Isso oferece a você a segurança de que os valores de chave corretos sempre serão exibido na coluna esperada. Por fim, observe como a AWS CLI resulta em `None` como os valores para as chaves que não existem.
```
$ aws iam list-users --output text --query 'Users[*].[UserName,Arn,CreateDate,PasswordLastUsed,UserId]'
```
```
Admin arn:aws:iam::123456789012:user/Admin 2014-10-16T16:03:09+00:00 2016-06-03T18:37:29+00:00 AIDA1111111111EXAMPLE
backup-user arn:aws:iam::123456789012:user/backup-user 2019-09-17T19:30:40+00:00 None AIDA2222222222EXAMPLE
cli-user arn:aws:iam::123456789012:user/cli-backup 2019-09-17T19:11:39+00:00 None AIDA3333333333EXAMPLE
```
O exemplo a seguir mostra como você pode usar `grep` e `awk` com a saída `text` do comando `aws ec2 describe-instances`. O primeiro comando exibe a zona de disponibilidade, o estado atual e o ID de cada instância na saída `text`. O segundo comando processa essa saída para exibir somente os IDs de todas as instâncias em execução na Zona de disponibilidade `us-west-2a`.
```
$ aws ec2 describe-instances --query 'Reservations[*].Instances[*].[Placement.AvailabilityZone, State.Name, InstanceId]' --output text
```
```
us-west-2a running i-4b41a37c
us-west-2a stopped i-a071c394
us-west-2b stopped i-97a217a0
us-west-2a running i-3045b007
us-west-2a running i-6fc67758
```
```
$ aws ec2 describe-instances --query 'Reservations[*].Instances[*].[Placement.AvailabilityZone, State.Name, InstanceId]' --output text | grep us-west-2a | grep running | awk '{print $3}'
```
```
i-4b41a37c
i-3045b007
i-6fc67758
```
O exemplo a seguir vai mais longe e mostra não apenas como filtrar a saída, mas como usar essa saída para automatizar a alteração dos tipos de instância para cada instância interrompida.
```
$ aws ec2 describe-instances --query 'Reservations[*].Instances[*].[State.Name, InstanceId]' --output text |
> grep stopped |
> awk '{print $2}' |
> while read line;
> do aws ec2 modify-instance-attribute --instance-id $line --instance-type '{"Value": "m1.medium"}';
> done
```
A saída `text` também pode ser útil no PowerShell. Como as colunas na saída `text` são delimitadas por tabulação, é possível dividir facilmente a saída em uma matriz usando o delimitador ``t` do PowerShell. O comando a seguir exibe o valor da terceira coluna (`InstanceId`) se a primeira coluna (`AvailabilityZone`) corresponder à string `us-west-2a`.
```
PS C:\>aws ec2 describe-instances --query 'Reservations[*].Instances[*].[Placement.AvailabilityZone, State.Name, InstanceId]' --output text |
%{if ($_.split("`t")[0] -match "us-west-2a") { $_.split("`t")[2]; } }
```
```
-4b41a37c
i-a071c394
i-3045b007
i-6fc67758
```
Embora o exemplo anterior mostre como usar o parâmetro `--query` para analisar os objetos JSON subjacentes e extrair a coluna desejada, o PowerShell tem capacidade própria para lidar com o JSON, se a compatibilidade entre as plataformas não for uma preocupação. Em vez de lidar com a saída como texto, o que é exigido pela maioria dos shells de comando, o PowerShell permite que você use o cmdlet `ConvertFrom-JSON` para produzir um objeto estruturado hierarquicamente. Depois, é possível acessar diretamente o membro desejado usando esse objeto.
```
(aws ec2 describe-instances --output json | ConvertFrom-Json).Reservations.Instances.InstanceId
```
**dica**
Se você enviar o texto e filtrar a saída para um único campo usando o parâmetro `--query`, a saída será uma única linha de valores separados por tabulação. Para obter cada valor em uma linha separada, você pode colocar o campo de saída entre colchetes, conforme mostrado nos exemplos a seguir.
Saída de linha única separada por tabulação:
```
$ aws iam list-groups-for-user --user-name susan --output text --query "Groups[].GroupName"
```
```
HRDepartment Developers SpreadsheetUsers LocalAdmins
```
Cada valor em sua própria linha, colocando `[GroupName]` entre colchetes:
```
$ aws iam list-groups-for-user --user-name susan --output text --query "Groups[].[GroupName]"
```
```
HRDepartment
Developers
SpreadsheetUsers
LocalAdmins
```
## Formato de saída de tabela
O formato `table` produz representações legíveis da saída complexa da AWS CLI em um formato tabular.
```
$ aws iam list-users --output table
```
```
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
| ListUsers |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------+
|| Users ||
|+----------------------------------------------------+---------------------------+---------------------------+----------+-----------------------+-------------+|
|| Arn | CreateDate | PasswordLastUsed | Path | UserId | UserName ||
|+----------------------------------------------------+---------------------------+---------------------------+----------+-----------------------+-------------+|
|| arn:aws:iam::123456789012:user/Admin | 2014-10-16T16:03:09+00:00 | 2016-06-03T18:37:29+00:00 | / | AIDA1111111111EXAMPLE | Admin ||
|| arn:aws:iam::123456789012:user/backup/backup-user | 2019-09-17T19:30:40+00:00 | | /backup/ | AIDA2222222222EXAMPLE | backup-user ||
|| arn:aws:iam::123456789012:user/cli-user | 2019-09-17T19:11:39+00:00 | | / | AIDA3333333333EXAMPLE | cli-user ||
+---------------------------------------------------------------------------------------------------------------------------------------------------------------+
```
É possível combinar a opção `--query` com o formato `table` para exibir um conjunto de elementos pré-selecionado na saída bruta. As diferenças das saída entre as notações de lista e dicionário: no primeiro exemplo, os nomes de coluna são ordenados alfabeticamente, e, no segundo, as colunas sem nome são ordenadas conforme definido pelo usuário. Para obter mais informações sobre a opção `--query`, consulte [Filtrar a saída na AWS CLI](cli-usage-filter.md).
```
$ aws ec2 describe-volumes --query 'Volumes[*].{ID:VolumeId,InstanceId:Attachments[0].InstanceId,AZ:AvailabilityZone,Size:Size}' --output table
```
```
------------------------------------------------------
| DescribeVolumes |
+------------+----------------+--------------+-------+
| AZ | ID | InstanceId | Size |
+------------+----------------+--------------+-------+
| us-west-2a| vol-e11a5288 | i-a071c394 | 30 |
| us-west-2a| vol-2e410a47 | i-4b41a37c | 8 |
+------------+----------------+--------------+-------+
```
```
$ aws ec2 describe-volumes --query 'Volumes[*].[VolumeId,Attachments[0].InstanceId,AvailabilityZone,Size]' --output table
```
```
----------------------------------------------------
| DescribeVolumes |
+--------------+--------------+--------------+-----+
| vol-e11a5288| i-a071c394 | us-west-2a | 30 |
| vol-2e410a47| i-4b41a37c | us-west-2a | 8 |
+--------------+--------------+--------------+-----+
```
## Formato de off
O formato `off` suprime todas as saídas de comando para stdout. Isso é útil em scripts de automação e pipelines de CI/CD em que somente é necessário verificar o código de saída do comando sem processar a saída. As mensagens de erro ainda são exibidas em stderr.
O exemplo a seguir mostra como o formato `off` suprime saídas bem-sucedidas. É possível verificar o código de saída para determinar o houve êxito:
```
$ aws s3api list-buckets --output off
$ echo $?
0
```
Isso é particularmente útil em scripts de shell em que se deseja verificar a existência de um recurso sem capturar a saída:
```
#!/bin/bash
if aws s3api head-bucket --bucket my-bucket --output off 2>/dev/null; then
echo "Bucket exists"
else
echo "Bucket does not exist"
fi
```
**nota**
O formato `off` suprime apenas stdout. Os erros ainda são gravados em stderr.
# Saída de erro estruturada na AWS CLI
Este tópico descreve os formatos de saída de erro estruturada para a AWS Command Line Interface (AWS CLI). A CLI grava erros em stderr e aceita os seguintes formatos:
+ **[`enhanced`](#cli-error-format-enhanced)** (padrão): mensagem de erro com detalhes adicionais exibidos em linha. Use para depuração legível por humanos.
+ **[`json`](#cli-error-format-json)**: a saída é formatada como uma string [JSON](https://json.org/) com todos os campos de erro. Use para automação e criação de scripts.
+ **[`yaml`](#cli-error-format-yaml)**: a saída é formatada como uma string [YAML](https://yaml.org/) com todos os campos de erro. Use para automação e criação de scripts.
+ **[`text`](#cli-error-format-text)**: formata erros usando o formatador de texto. Use para verificação visual rápida.
+ **[`table`](#cli-error-format-table)**: formata erros usando o formatador de tabela. Use para verificação visual rápida.
+ **[`legacy`](#cli-error-format-legacy)**: formato de erro original sem detalhes estruturados. Use para compatibilidade com versões anteriores.
## Configurar o formato do erro
É possível configurar o formato do erro usando qualquer um dos seguintes métodos:
Sinalizador da linha de comandos
```
$ aws --cli-error-format json
```
Arquivo de configuração: (`~/.aws/config`)
```
[default]
cli_error_format = json
```
Variável de ambiente
```
$ export AWS_CLI_ERROR_FORMAT=yaml
```
## Formato de saída de erro
As seguintes seções descrevem cada formato.
### Formato aprimorado (padrão)
O formato aprimorado exibe mensagens de erro com detalhes adicionais em linha para valores simples. Para estruturas complexas, o formato fornece uma dica para usar JSON ou YAML.
**Exemplo: configuração de região ausente**
```
aws: [ERROR]: An error occurred (NoRegion): You must specify a region. You can also configure your region by running "aws configure".
```
**Exemplo: bucket do S3 inexistente com campos adicionais**
```
aws: [ERROR]: An error occurred (NoSuchBucket) when calling the GetObject operation: The specified bucket does not exist
Additional error details:
BucketName: amzn-s3-demo-bucket
```
**Exemplo: campos de erro complexos**
```
An error occurred (TransactionCanceledException) when calling the TransactWriteItems operation: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]
Additional error details:
CancellationReasons:
Use "--cli-error-format json" or another error format to see the full details.
```
### Formato JSON
O formato JSON fornece uma representação estruturada com todos os campos de erro.
**Exemplo: configuração de região ausente**
```
{
"Code": "NoRegion",
"Message": "You must specify a region. You can also configure your region by running \"aws configure\"."
}
```
**Exemplo: bucket do S3 inexistente**
```
{
"Code": "NoSuchBucket",
"Message": "The specified bucket does not exist",
"BucketName": "amzn-s3-demo-bucket"
}
```
### Formato YAML
O formato YAML fornece uma representação estruturada com todos os campos de erro.
**Exemplo: configuração de região ausente**
```
Code: NoRegion
Message: You must specify a region. You can also configure your region by running "aws configure".
```
**Exemplo: bucket do S3 inexistente**
```
Code: NoSuchBucket
Message: The specified bucket does not exist
BucketName: amzn-s3-demo-bucket
```
### Formato de texto
O formato de texto usa o mesmo formatador usado para uma saída bem-sucedida do comando.
**Exemplo: bucket do S3 inexistente**
```
amzn-s3-demo-bucket NoSuchBucket The specified bucket does not exist
```
### Formato da tabela
O formato de tabela usa o mesmo formatador usado para uma saída bem-sucedida do comando.
**Exemplo: bucket do S3 inexistente**
```
-------------------------------------------------------------------------------------|
| error |
+---------------------------+---------------+----------------------------------------+
| BucketName | Code | Message |
+---------------------------+---------------+----------------------------------------+
| amzn-s3-demo-bucket | NoSuchBucket | The specified bucket does not exist |
+---------------------------+---------------+----------------------------------------+
```
### Formato legado
O formato legado fornece o formato de erro original sem detalhes estruturados. Esse formato não inclui o prefixo “An error occurred (ErrorCode):” para exceções da CLI.
**Exemplo: configuração de região ausente**
```
aws: [ERROR]: You must specify a region. You can also configure your region by running "aws configure".
```
**Exemplo: bucket do S3 inexistente**
```
An error occurred (NoSuchBucket) when calling the GetObject operation: The specified bucket does not exist
```
**nota**
Agora os erros incluem consistentemente o prefixo `aws: [ERROR]:` para exceções da CLI. As versões anteriores nem sempre incluíam esse prefixo.
As seguintes exceções sempre usam o formato legado, independentemente do formato de erro configurado:
`UnknownArgumentError`: exibe informações de uso.
Interrupções do teclado (`KeyboardInterrupt`)
## Exemplo completo
O seguinte exemplo mostra um comando com a formatação de erro JSON.
```
$ aws s3api get-object \
--bucket amzn-s3-demo-bucket \
--key file.txt out.txt \
--cli-error-format json
```
Saída (stderr):
```
{
"Code": "NoSuchBucket",
"Message": "The specified bucket does not exist",
"BucketName": "amzn-s3-demo-bucket"
}
```
O campo `BucketName` é um membro de erro modelado exibido pelo serviço Amazon S3.
# Usar as opções de paginação na AWS CLI
Este tópico descreve as diferentes maneiras de paginar a saída da AWS Command Line Interface (AWS CLI).
Há duas formas principais de controlar a paginação pela AWS CLI.
+ [Usando os parâmetros de paginação do lado do servidor.](#cli-usage-pagination-serverside)
+ [Usando o programa de paginação do lado do cliente de saída padrão](#cli-usage-pagination-clientside).
Os parâmetros de paginação do lado do servidor são processados primeiro, e qualquer saída é enviada para a paginação do lado do cliente.
## Paginação do lado do servidor
Para a maioria dos comandos que retornam uma extensa lista de itens, a AWS CLI oferece várias opções do lado do servidor para controlar o número de itens incluídos na saída quando a AWS CLI chama a API de um serviço para preencher a lista. A paginação do lado do servidor na AWS CLI é habilitada pela API do serviço da AWS; portanto, essas opções só funcionarão se a API de serviço as habilitar.
**Topics**
+ [--no-paginate](#cli-usage-pagination-nopaginate)
+ [--page-size](#cli-usage-pagination-pagesize)
+ [--max-items](#cli-usage-pagination-maxitems)
+ [--starting-token](#cli-usage-pagination-startingtoken)
Por padrão, a AWS CLI usa um tamanho de página determinado pelo serviço específico e recupera todos os itens disponíveis. Por exemplo, o Amazon S3 tem um tamanho de página padrão de mil. Se você executar `aws s3api list-objects` em um bucket do Amazon S3 que contém 3,5 mil objetos, a AWS CLI fará automaticamente quatro chamadas para o Amazon S3, lidando com a lógica de paginação específica do serviço para você em segundo plano e retornando todos os 3,5 mil objetos na saída final.
Consulte informações sobre se um comando específico oferece paginação do lado do servidor no [Guia de referência da AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/reference/index.html).
### Como usar o parâmetro –no-paginate
A opção `--no-paginate` desabilita os seguintes tokens de paginação no lado do cliente. Ao usar um comando, por padrão a AWS CLI faz várias chamadas automaticamente para retornar todos os resultados possíveis para criar a paginação. Uma chamada para cada página. Desabilitar a paginação faz com que a AWS CLI chame apenas uma vez pela primeira página de resultados do comando.
Por exemplo, se você executar o`aws s3api list-objects` em um bucket do Amazon S3 que contém 3500 objetos, o AWS CLI fará apenas a primeira chamada para o Amazon S3, retornando apenas os primeiros 1000 objetos na saída final.
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--no-paginate
{
"Contents": [
...
```
### Como usar o parâmetro --page-size
Caso haja problemas ao executar os comandos da lista em um grande número de recursos, o tamanho da página padrão poderá ser muito alto. Isso pode fazer com que as chamadas para os serviços do AWS excedam o tempo máximo permitido e gerar um erro de “expiração”. Você pode usar a opção `--page-size` para especificar que a AWS CLI solicite um número menor de itens de cada chamada para o serviço da AWS. A AWS CLI ainda recuperará a lista completa, mas executará um número maior de chamadas de API de serviço em segundo plano e recuperará um número menor de itens em cada chamada. Isso fornece às chamadas individuais chances melhores de sucesso sem um tempo limite. Alterar o tamanho da página não afeta a saída, afeta somente o número de chamadas da API que precisam ser feitas para gerar a saída.
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--page-size 100
{
"Contents": [
...
```
### Como usar o parâmetro --max-items
Para incluir menos itens por vez na saída da AWS CLI, use a opção `--max-items`. A AWS CLI ainda lida com paginação com o serviço conforme descrito anteriormente, mas imprime apenas o número de itens que você especificar de cada vez.
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--max-items 100
{
"NextToken": "eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==",
"Contents": [
...
```
### Como usar o parâmetro --starting-token
Se o número de saída de itens (`--max-items`) for menor do que o número total de itens retornados pelas chamadas de API subjacentes, a saída incluirá um `NextToken` que pode ser passado para um comando subsequente para recuperar o próximo conjunto de itens. O exemplo a seguir mostra como usar o valor `NextToken` retornado pelo exemplo anterior e permite que você recupere os segundos 100 itens.
**nota**
O parâmetro `--starting-token` não pode ser nulo nem vazio. Se o comando anterior não retornar um valor `NextToken`, não haverá mais itens a serem retornados e você não precisará chamar o comando novamente.
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--max-items 100 \
--starting-token eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==
{
"Contents": [
...
```
O serviço da AWS especificado pode não retornar itens na mesma ordem cada vez que você chamá-lo. Se você especificar valores diferentes para `--page-size` e `--max-items`, poderá obter resultados inesperados com itens ausentes ou duplicados. Para evitar que isso aconteça, use o mesmo número para `--page-size` e `--max-items` para sincronizar a paginação da AWS CLI com a paginação do serviço subjacente. Também é possível recuperar a lista completa e executar quaisquer operações necessárias de paginação localmente.
## Paginação do lado do cliente
AWS CLIA versão 2 fornece um programa de paginação do lado do cliente para uso na saída. Por padrão, o atributo retorna toda a saída pelo programa de paginação padrão do sistema operacional.
Em ordem de precedência, você pode especificar a paginação de saída destas duas formas:
+ Usando a configuração `cli_pager` no arquivo `config` no perfil `default` ou nomeado.
+ Usando a variável de ambiente `AWS_PAGER`.
+ Usando a variável de ambiente `PAGER`.
Por ordem de precedência, você pode desabilitar todo o uso de um programa de paginação externo das seguintes maneiras:
+ Usar opção de linha de comando `--no-cli-pager` para desabilitar a paginação para o uso de um único comando.
+ Definir a configuração `cli_pager` ou a variável `AWS_PAGER` como uma string vazia.
**Topics**
+ [cli\$1pager](#cli-usage-pagination-clipager)
+ [AWS\$1PAGER](#cli-usage-pagination-awspager)
+ [--no-cli-pager](#cli-usage-pagination-noclipager)
+ [Sinalizadores de paginação](#cli-usage-pagination-flags)
### Como usar a configuração cli\$1pager
Você pode salvar as definições de configuração usadas com frequência e credenciais em arquivos que são mantidos pela AWS CLI. As configurações em um perfil de nome têm precedência sobre as configurações no perfil `default`. Para obter mais informações sobre as opções de configuração, consulte [Configurações do arquivo de configuração e credenciais na AWS CLI](cli-configure-files.md).
O exemplo a seguir define a paginação de saída padrão para o programa `less`.
```
[default]
cli_pager=less
```
O exemplo abaixo define o padrão para desativar o uso de um paginador.
```
[default]
cli_pager=
```
### Como definir a variável de ambiente AWS\$1PAGER
O exemplo a seguir define a paginação de saída padrão para o programa `less`. Para obter mais informações sobre variáveis de ambiente, consulte [Configurar variáveis de ambiente para a AWS CLI](cli-configure-envvars.md).
------
#### [ Linux and macOS ]
```
$ export AWS_PAGER="less"
```
------
#### [ Windows ]
```
C:\> setx AWS_PAGER "less"
```
------
### Como usar a opção --no-cli-pager
Para desabilitar o uso de uma paginação em um único comando, use a opção `--no-cli-pager`. Para obter mais informações sobre as opções de linha de comando, consulte [Opções da linha de comando na AWS CLI](cli-configure-options.md).
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--no-cli-pager
{
"Contents": [
...
```
### Como usar sinalizadores de paginação
Você pode especificar sinalizadores para usar automaticamente com seu programa de paginação. Os sinalizadores dependem do programa de paginação utilizado. Os exemplos abaixo são referem-se aos padrões típicos de `less` e `more`.
------
#### [ Linux and macOS ]
Se você não especificar o contrário, o paginador que a AWS CLI versão 2 usará por padrão é `less`. Se você não tiver a variável de ambiente `LESS` definida, a AWS CLI versão 2 usará os sinalizadores `FRX`. Você pode combinar sinalizadores especificando-os ao definir a paginação AWS CLI.
O exemplo a seguir usa o sinalizador `S`. Esse sinalizador então se combina aos sinalizadores `FRX` padrão para criar um sinalizador `FRXS`.
```
$ export AWS_PAGER="less -S"
```
Caso não queira usar nenhum dos sinalizadores `FRX`, você poderá negá-los. O exemplo a seguir nega o sinalizador `F` para criar um sinalizador `RX` final.
```
$ export AWS_PAGER="less -+F"
```
Para obter mais informações sobre sinalizadores `less`, consulte [less](http://manpages.org/less/1#options) em *manpages.org*.
------
#### [ Windows ]
Se você não especificar o contrário, o paginador que a AWS CLI versão 2 usará por padrão é `more` sem sinalizadores adicionais.
O exemplo a seguir usa o parâmetro `/c`.
```
C:\> setx AWS_PAGER "more /c"
```
Para obter mais informações sobre sinalizadores `more`, consulte `[more](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/more)` nos *Documentos da Microsoft*.
------
# Filtrar a saída na AWS CLI
A AWS Command Line Interface (AWS CLI) conta com filtragem nos lados do servidor e do cliente que você pode usar individualmente ou em conjunto para filtrar sua saída da AWS CLI. A filtragem no lado do servidor é processada primeiro e retorna a saída para a filtragem no lado do cliente.
+ A filtragem no lado do servidor é suportada pela API, e você geralmente a implementa com um parâmetro `--filter`. O serviço retorna apenas resultados correspondentes que podem acelerar os tempos de resposta de HTTP para conjuntos de dados grandes.
+ A filtragem no lado do cliente é suportada pelo cliente da AWS CLI com o parâmetro `--query`. Esse parâmetro oferece recursos que a filtragem do lado do servidor pode não ter.
**Topics**
+ [Filtragem no lado do servidor](#cli-usage-filter-server-side)
+ [Filtragem no lado do cliente](#cli-usage-filter-client-side)
+ [Combinação das filtragens no lado do servidor e no lado do cliente](#cli-usage-filter-combining)
+ [Recursos adicionais](#cli-usage-filter-resources)
## Filtragem no lado do servidor
A filtragem no lado do servidor na AWS CLI é fornecida pela API do serviço AWS. O serviço da AWS retorna apenas os registros na resposta HTTP que correspondem ao seu filtro, o que pode acelerar os tempos de resposta de HTTP para conjuntos de dados grandes. Como a filtragem no lado do servidor é definida pela API do serviço, os nomes e funções dos parâmetros variam entre os serviços. Alguns nomes de parâmetros comuns usados na filtragem são:
+ `--filter`, como [ses](https://docs.aws.amazon.com/cli/latest/reference/ses/create-receipt-filter.html) e [ce](https://docs.aws.amazon.com/cli/latest/reference/ce/get-cost-and-usage.html).
+ `--filters`, como [ec2](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-volumes.html), [autoscaling](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/describe-tags.html) e [rds](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-instances.html).
+ Nomes que começam com a palavra `filter`; por exemplo, `--filter-expression` para o comando [https://docs.aws.amazon.com/cli/latest/reference/dynamodb/scan.html](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/scan.html).
Para ter informações sobre se um comando específico oferece filtragem no lado do servidor e a respeito das regras de filtragem, consulte o [AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/reference/index.html).
## Filtragem no lado do cliente
A AWS CLI fornece recursos de filtragem integrada baseados em JSON no lado do cliente com o parâmetro`--query`. O parâmetro `--query` é uma ferramenta poderosa que você pode usar para personalizar o conteúdo e estilo da sua saída. O parâmetro `--query` recebe a resposta HTTP retornada pelo servidor e filtra os resultados antes de exibi-los. Como toda a resposta HTTP é enviada para o cliente antes da filtragem, a filtragem no lado do cliente pode ser mais lenta do que a filtragem no lado do servidor para conjuntos de dados grandes.
A consulta usa a [sintaxe JMESPath](https://jmespath.org/) para criar expressões para filtrar sua saída. Para aprender a sintaxe JMESPath, consulte o [Tutorial](https://jmespath.org/tutorial.html) no *site do JMESPath*.
**Importante**
O tipo de saída especificado por você modifica a forma de operação da opção `--query`.
Se você especificar `--output text`, a saída será paginada *antes* que o filtro `--query` seja aplicado e a AWS CLI executará a consulta uma vez em *cada página* da saída. Consequentemente, a consulta inclui o primeiro elemento correspondente em cada página, o que pode resultar em uma saída adicional inesperada. Para filtrar ainda mais a saída, é possível usar outras ferramentas da linha de comando, como `head` ou `tail`.
Se você especificar `--output json`, `--output yaml` ou `--output yaml-stream`, a saída será completamente processada como uma única estrutura JSON nativa antes que o filtro `--query` seja aplicado. A AWS CLI executa a consulta apenas uma vez com relação a toda a estrutura, produzindo um resultado filtrado que é, então, a saída.
**Topics**
+ [Antes de começar](#cli-usage-filter-client-side-output)
+ [Identificadores](#cli-usage-filter-client-side-identifiers)
+ [Como selecionar em uma lista](#cli-usage-filter-client-side-select-list)
+ [Como filtrar dados aninhados](#cli-usage-filter-client-side-nested)
+ [Resultados da simplificação](#cli-usage-filter-client-side-specific-flattening)
+ [Filtragem de valores específicos](#cli-usage-filter-client-side-specific-values)
+ [Encadeamento de expressões](#cli-usage-filter-client-side-pipe)
+ [Filtragem por vários valores de identificador](#cli-usage-filter-client-side-miltiselect-list)
+ [Adição de rótulos a valores de identificador](#cli-usage-filter-client-side-multiselect-hash)
+ [Funções](#cli-usage-filter-client-side-functions)
+ [Exemplos avançados `--query`](#cli-usage-filter-client-side-advanced)
### Antes de começar
**nota**
Esses exemplos de expressão de filtro são escritos para shells básicos do tipo Linux. Ao usar esses exemplos, use as regras de aspas corretas para o shell do terminal. A forma como o terminal interpreta as entradas pode mudar muito o que é enviado à AWS CLI. A forma como o terminal lê aspas simples `'`, aspas duplas `"` ou acentos graves ``` pode alterar a maneira como o conteúdo é lido.
Para obter mais informações, consulte [Usar aspas e literais com strings na AWS CLI](cli-usage-parameters-quoting-strings.md).
A saída JSON a seguir mostra um exemplo do que o parâmetro `--query` pode produzir. A saída descreve três volumes do Amazon EBS anexados a instâncias separadas do Amazon EC2.
#### Exemplo de saída
```
$ aws ec2 describe-volumes
{
"Volumes": [
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-18T20:26:16.000Z",
"InstanceId": "i-4b41a37c",
"VolumeId": "vol-2e410a47",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-2e410a47",
"State": "in-use",
"SnapshotId": "snap-708e8348",
"CreateTime": "2013-09-18T20:26:15.000Z",
"Size": 8
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
}
]
}
```
### Identificadores
Identificadores são rótulos para valores de saída. Ao criar filtros, você usa identificadores para refinar os resultados da consulta. No exemplo de saída a seguir, todos os identificadores como `Volumes`, `AvailabilityZone` e `AttachTime` estão destacados.
```
$ aws ec2 describe-volumes
{
"Volumes": [
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-18T20:26:16.000Z",
"InstanceId": "i-4b41a37c",
"VolumeId": "vol-2e410a47",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-2e410a47",
"State": "in-use",
"SnapshotId": "snap-708e8348",
"CreateTime": "2013-09-18T20:26:15.000Z",
"Size": 8
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
}
]
}
```
Para obter mais informações, consulte [Identificadores](https://jmespath.org/specification.html#identifiers ) no *site do JMESPath*.
### Como selecionar em uma lista
Uma lista ou matriz é um identificador que é seguido por um colchete “`[`“, como `Volumes` e `Attachments` na [Antes de começar](#cli-usage-filter-client-side-output).
**Sintaxe**
```
[ ]
```
Para filtrar toda a saída de uma matriz, você pode usar a notação curinga. Expressões [curinga](http://jmespath.org/specification.html#wildcard-expressions) são expressões usadas para retornar elementos usando a notação `*`.
O exemplo a seguir consulta todo o conteúdo `Volumes`.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*]'
[
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
}
]
```
Para exibir um volume específico na matriz por índice, chame o índice da matriz. Por exemplo, o primeiro item na matriz `Volumes` tem um índice igual a 0, o que resulta na consulta `Volumes[0]`. Para obter mais informações sobre índices de matriz, consulte [Expressões de índice](http://jmespath.org/specification.html#index-expressions) no *site do JMESPath*.
```
$ aws ec2 describe-volumes \
--query 'Volumes[0]'
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
}
```
Para exibir um intervalo específico de volumes por índice, use `slice` com a sintaxe a seguir, em que **start** é o índice da matriz inicial, **stop** é o índice em que o filtro interrompe o processamento e **step** é o intervalo de salto.
**Sintaxe**
```
[::]
```
Se algum deles for omitido da expressão slice, os seguintes valores padrão serão usados:
+ Start: o primeiro índice na lista, 0.
+ Stop: o último índice na lista.
+ Step: sem pular etapas, onde o valor é 1.
Para retornar somente os dois primeiros volumes, use um valor de start igual a 0, um valor de stop igual 2 e um valor de step igual a 1, conforme mostrado no exemplo a seguir.
```
$ aws ec2 describe-volumes \
--query 'Volumes[0:2:1]'
[
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-18T20:26:16.000Z",
"InstanceId": "i-4b41a37c",
"VolumeId": "vol-2e410a47",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-2e410a47",
"State": "in-use",
"SnapshotId": "snap-708e8348",
"CreateTime": "2013-09-18T20:26:15.000Z",
"Size": 8
}
]
```
Como este exemplo contém valores padrão, você pode encurtar o slice de `Volumes[0:2:1]` para `Volumes[:2]`.
O exemplo a seguir omite valores padrão e retorna cada dois volumes em toda a matriz.
```
$ aws ec2 describe-volumes \
--query 'Volumes[::2]'
[
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
}
]
```
Os valores de step também podem ser números negativos, o que resulta na filtragem em ordem inversa de uma matriz, conforme mostrado no exemplo a seguir.
```
$ aws ec2 describe-volumes \
--query 'Volumes[::-2]'
[
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
}
]
```
Para obter mais informações, consulte [Slices](https://jmespath.org/specification.html#slices) no *site do JMESPath*.
### Como filtrar dados aninhados
Para refinar a filtragem de `Volumes[*]` para valores aninhados, use subexpressões anexando um ponto e seus critérios de filtragem.
**Sintaxe**
```
.
```
O exemplo a seguir mostra todas as informações de `Attachments` para todos os volumes.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments'
[
[
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
[
{
"AttachTime": "2013-09-18T20:26:16.000Z",
"InstanceId": "i-4b41a37c",
"VolumeId": "vol-2e410a47",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
[
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
]
]
```
Para filtrar ainda mais os valores aninhados, acrescente a expressão para cada identificador aninhado. O exemplo a seguir lista o `State` para todos os `Volumes`.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[*].State'
[
[
"attached"
],
[
"attached"
],
[
"attached"
]
]
```
### Resultados da simplificação
Para obter mais informações, consulte [Subexpressões](https://jmespath.org/specification.html#subexpressions) no *site do JMESPath*.
Você pode simplificar os resultados para `Volumes[*].Attachments[*].State` removendo a notação curinga, o que resultará na consulta `Volumes[*].Attachments[].State`. A simplificação muitas vezes é útil para melhorar a legibiliade dos resultados.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[].State'
[
"attached",
"attached",
"attached"
]
```
Para obter mais informações, consulte [Simplificação](https://jmespath.org/specification.html#flatten) no *site do JMESPath*.
### Filtragem de valores específicos
Para filtrar valores específicos em uma lista, use uma expressão de filtro como mostrado na sintaxe a seguir.
**Sintaxe**
```
? ]
```
Os comparadores de expressão incluem `==`, `!=`, `<`, `<=`, `>` e `>=`. O exemplo a seguir filtra `VolumeIds` para todos os `Volumes` em um `State` igual a `Attached`.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[?State==`attached`].VolumeId'
[
[
"vol-e11a5288"
],
[
"vol-2e410a47"
],
[
"vol-a1b3c7nd"
]
]
```
Os resultados podem ser simplificados, o que resulta no exemplo a seguir.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[?State==`attached`].VolumeId[]'
[
"vol-e11a5288",
"vol-2e410a47",
"vol-a1b3c7nd"
]
```
O exemplo a seguir filtra `VolumeIds` para todos os `Volumes` com tamanho inferior a 20.
```
$ aws ec2 describe-volumes \
--query 'Volumes[?Size < `20`].VolumeId'
[
"vol-2e410a47",
"vol-a1b3c7nd"
]
```
Para obter mais informações, consulte [Expressões de filtragem](https://jmespath.org/specification.html#filterexpressions) no *site do JMESPath*.
### Encadeamento de expressões
Você pode encadear resultados de um filtro para uma nova lista e, em seguida, filtrar o resultado com outra expressão usando a seguinte sintaxe:
**Sintaxe**
```
| ]
```
O exemplo a seguir leva os resultados do filtro da expressão `Volumes[*].Attachments[].InstanceId` e produz o primeiro resultado na matriz.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[].InstanceId | [0]'
"i-a071c394"
```
Esse exemplo faz isso criando primeiro a matriz a partir da expressão a seguir.
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[].InstanceId'
"i-a071c394",
"i-4b41a37c",
"i-1jd73kv8"
```
Depois, devolva o primeiro elemento para essa matriz.
```
"i-a071c394"
```
Para obter mais informações, consulte [Expressões de encadeamento](https://jmespath.org/specification.html#pipe-expressions) no *site do JMESPath*.
### Filtragem por vários valores de identificador
Para filtrar por vários identificadores, use uma lista de seleção múltipla usando a seguinte sintaxe:
**Sintaxe**
```
[].[, ]
```
No exemplo a seguir, `VolumeId` e `VolumeType` são filtrados na lista `Volumes`, o que resulta na expressão abaixo.
```
$ aws ec2 describe-volumes \
--query 'Volumes[].[VolumeId, VolumeType]'
[
[
"vol-e11a5288",
"standard"
],
[
"vol-2e410a47",
"standard"
],
[
"vol-a1b3c7nd",
"standard"
]
]
```
Para adicionar dados aninhados à lista, adicione outra lista de seleção múltipla. O exemplo a seguir expande o exemplo anterior filtrando também por `InstanceId` e `State` na lista aninhada `Attachments`. Isso resulta na seguinte expressão.
```
$ aws ec2 describe-volumes \
--query 'Volumes[].[VolumeId, VolumeType, Attachments[].[InstanceId, State]]'
[
[
"vol-e11a5288",
"standard",
[
[
"i-a071c394",
"attached"
]
]
],
[
"vol-2e410a47",
"standard",
[
[
"i-4b41a37c",
"attached"
]
]
],
[
"vol-a1b3c7nd",
"standard",
[
[
"i-1jd73kv8",
"attached"
]
]
]
]
```
Para torná-la mais legível, simplifique a expressão conforme mostrado no exemplo a seguir.
```
$ aws ec2 describe-volumes \
--query 'Volumes[].[VolumeId, VolumeType, Attachments[].[InstanceId, State][]][]'
[
"vol-e11a5288",
"standard",
[
"i-a071c394",
"attached"
],
"vol-2e410a47",
"standard",
[
"i-4b41a37c",
"attached"
],
"vol-a1b3c7nd",
"standard",
[
"i-1jd73kv8",
"attached"
]
]
```
Para obter mais informações, consulte [Lista de multisseleção](https://jmespath.org/specification.html#multiselectlist) no *site do JMESPath*.
### Adição de rótulos a valores de identificador
Para tornar essa saída mais fácil de ler, use um hash de seleção múltipla com a sintaxe a seguir.
**Sintaxe**
```
[].{