# Criação e uso de aliases na AWS CLI
<a name="cli-usage-alias"></a>

Os aliases são atalhos que você pode criar na AWS Command Line Interface (AWS CLI) para encurtar comandos ou scripts que utiliza com frequência. Os aliases são criados no arquivo `alias` localizado em sua pasta de configuração.

**Topics**
+ [Pré-requisitos](#cli-usage-alias-prepreqs)
+ [Etapa 1: Criação do arquivo de alias](#cli-usage-alias-create-file)
+ [Etapa 2: Criação de um alias](#cli-usage-alias-create-alias)
+ [Passo 3: Como chamar um alias](#cli-usage-alias-call-alias)
+ [Exemplos de repositório de alias](#cli-usage-alias-examples)
+ [Recursos](#cli-usage-alias-references)

## Pré-requisitos
<a name="cli-usage-alias-prepreqs"></a>

Para usar comandos de alias, é necessário fazer o seguinte:
+ Instale e configure a AWS CLI. Para ter mais informações, consulte [Instalar ou atualizar a versão mais recente da AWS CLI](getting-started-install.md) e [Autenticação e credenciais de acesso para a AWS CLI](cli-chap-authentication.md).
+ Usar, no mínimo, a AWS CLI versão 1.11.24 ou 2.0.0.
+ (Opcional) Para usar scripts bash em alias da AWS CLI, é necessário usar um terminal compatível com bash.

## Etapa 1: Criação do arquivo de alias
<a name="cli-usage-alias-create-file"></a>

Para criar o arquivo `alias`, você pode utilizar a navegação de arquivos e um editor de texto ou utilizar o terminal preferido seguindo o procedimento passo a passo. Para criar rapidamente seu arquivo de alias, use o seguinte bloco de comandos.

------
#### [ Linux and macOS ]

```
$ mkdir -p ~/.aws/cli
$ echo '[toplevel]' > ~/.aws/cli/alias
```

------
#### [ Windows ]

```
C:\> md %USERPROFILE%\.aws\cli
C:\> echo [toplevel] > %USERPROFILE%/.aws/cli/alias
```

------

**Para criar o arquivo de alias**

1. Crie uma pasta chamada `cli` na pasta de configuração da AWS CLI. Por padrão, a pasta de configuração é `~/.aws/` no Linux ou no macOS e `%USERPROFILE%\.aws\` no Windows. Você pode criar isso via sua navegação de arquivos ou usando o comando a seguir.

------
#### [ Linux and macOS ]

   ```
   $ mkdir -p ~/.aws/cli
   ```

------
#### [ Windows ]

   ```
   C:\> md %USERPROFILE%\.aws\cli
   ```

------

   O caminho padrão da pasta `cli` resultante é `~/.aws/cli/` no Linux ou no macOS e `%USERPROFILE%\.aws\cli` no Windows.

1. Na pasta `cli`, crie um arquivo de texto chamado `alias`sem extensão e adicione `[toplevel]` à primeira linha. Você pode criar esse arquivo com seu editor de texto preferido ou usar o comando a seguir.

------
#### [ Linux and macOS ]

   ```
   $ echo '[toplevel]' > ~/.aws/cli/alias
   ```

------
#### [ Windows ]

   ```
   C:\> echo [toplevel] > %USERPROFILE%/.aws/cli/alias
   ```

------

## Etapa 2: Criação de um alias
<a name="cli-usage-alias-create-alias"></a>

Você pode criar um alias usando comandos básicos ou scripts bash.

### Criação um alias de comando básico
<a name="cli-usage-alias-create-alias-basic"></a>

Você pode criar seu alias ao adicionar um comando usando a seguinte sintaxe no arquivo `alias` criado na etapa anterior. 

**Sintaxe**

```
aliasname = command [--options]
```

*aliasname* é o que você atribui ao seu alias. *command* é o comando que você deseja chamar, o qual pode incluir outros aliases. Você pode incluir opções ou parâmetros em seu alias ou adicioná-los ao chamar seu alias.

O exemplo a seguir cria um alias chamado [https://docs.aws.amazon.com/cli/latest/reference/sts/get-caller-identity.html](https://docs.aws.amazon.com/cli/latest/reference/sts/get-caller-identity.html). Como esse alias chama um comando da AWS CLI existente, você pode escrever o comando sem usar o prefixo `aws`.

```
whoami = sts get-caller-identity
```

O exemplo a seguir usa o exemplo `whoami` anterior e adiciona o filtro `Account` e as opções `output` de texto.

```
whoami2 = sts get-caller-identity --query Account --output text
```

### Criar um alias de subcomando
<a name="cli-usage-alias-create-alias-sub-command"></a>

**nota**  
O recurso de alias do subcomando requer, no mínimo, a versão da AWS CLI 1.11.24 ou 2.0.0

É possível criar um alias para subcomandos adicionando um comando usando a seguinte sintaxe no arquivo `alias` criado na etapa anterior. 

**Sintaxe**

```
[command commandGroup]
aliasname = command [--options]
```

O *commandGroup* é o namespace do comando, por exemplo, o comando `aws ec2 describe-regions` está sob o grupo do comando `ec2`. *aliasname* é o que você atribui ao seu alias. *command* é o comando que você deseja chamar, o qual pode incluir outros aliases. Você pode incluir opções ou parâmetros em seu alias ou adicioná-los ao chamar seu alias.

O exemplo a seguir cria um alias chamado [https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-regions.html](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-regions.html). Como esse alias chama um comando da AWS CLI existente sob o namespace do comando `ec2`, é possível escrever o comando sem usar o prefixo `aws ec2`.

```
[command ec2]
regions = describe-regions --query Regions[].RegionName
```

Para criar aliases de comandos fora do namespace do comando, use um ponto de exclamação como prefixo do comando completo. O exemplo a seguir cria um alias chamado [https://docs.aws.amazon.com/cli/latest/reference/iam/list-instance-profiles.html](https://docs.aws.amazon.com/cli/latest/reference/iam/list-instance-profiles.html).

```
[command ec2]
instance-profiles = !aws iam list-instance-profiles
```

**nota**  
Os aliases usam apenas namespaces de comandos existentes e não é possível criar outros. Por exemplo, você não pode criar um alias com a seção `[command johnsmith]`, pois o namespace do comando `johnsmith` ainda não existe.

### Criação de um alias de script bash
<a name="cli-usage-alias-create-alias-scripting"></a>

**Atenção**  
Para usar scripts bash em alias da AWS CLI, é necessário usar um terminal compatível com bash.

Você pode criar um alias usando scripts bash para processos mais avançados usando a sintaxe a seguir.

**Sintaxe**

```
aliasname = 
    !f() {
        script content
}; f
```

*aliasname* é o nome do seu alias e *script content* é o script que você deseja executar ao chamar o alias.

O exemplo a seguir usa `opendns` para mostrar seu endereço IP atual. Como você pode usar aliases em outros aliases, o alias `myip` a seguir é útil para permitir ou revogar o acesso ao seu endereço IP de dentro de outros aliases. 

```
myip =
  !f() {
    dig +short myip.opendns.com @resolver1.opendns.com
  }; f
```

Os exemplos de script a seguir chamam o alias `aws myip` anterior para autorizar seu endereço IP para ingresso em um grupo de segurança do Amazon EC2.

```
authorize-my-ip =
  !f() {
    ip=$(aws myip)
    aws ec2 authorize-security-group-ingress --group-id ${1} --cidr $ip/32 --protocol tcp --port 22
  }; f
```

Quando você chama aliases que usam scripts bash, as variáveis são sempre passadas na ordem em que você as inseriu. Nos scripts bash, os nomes das variáveis não são levados em consideração, apenas a ordem em que aparecem. No exemplo de alias `textalert` a seguir, a variável para a opção `--message` é a primeira e para a opção `--phone-number` é a segunda.

```
textalert =
  !f() {
    aws sns publish --message "${1}" --phone-number ${2}
  }; f
```

## Passo 3: Como chamar um alias
<a name="cli-usage-alias-call-alias"></a>

Para executar o alias que você criou em seu arquivo `alias`, use a sintaxe a seguir. Você pode adicionar opções extras ao chamar seu alias.

**Sintaxe**

```
$ aws aliasname
```

O exemplo a seguir usa o alias do comando `aws whoami`.

```
$ aws whoami
{
    "UserId": "A12BCD34E5FGHI6JKLM",
    "Account": "1234567890987",
    "Arn": "arn:aws:iam::1234567890987:user/userName"
}
```

O exemplo a seguir usa o alias `aws whoami` com opções adicionais para retornar somente o número `Account` na saída de `text`.

```
$ aws whoami --query Account --output text
1234567890987
```

O exemplo a seguir usa o [alias do subcomando](#cli-usage-alias-create-alias-sub-command) `aws ec2 regions`.

```
$ aws ec2 regions
[
    "ap-south-1",
    "eu-north-1",
    "eu-west-3",
    "eu-west-2",
...
```

### Como chamar um alias usando variáveis de script bash
<a name="cli-usage-alias-call-alias-variables"></a>

Quando você chama aliases que usam scripts bash, as variáveis são passadas na ordem em que foram inseridas. Nos scripts bash, os nomes das variáveis não são levados em consideração, apenas a ordem em que aparecem. Por exemplo, no alias `textalert` a seguir, a variável para a opção `--message` é a primeira e para a opção `--phone-number` é a segunda.

```
textalert =
  !f() {
    aws sns publish --message "${1}" --phone-number ${2}
  }; f
```

Ao chamar o alias `textalert`, você precisa passar variáveis na mesma ordem em que elas são executadas no alias. No exemplo a seguir usamos as variáveis `$message` e `$phone`. A variável `$message` é passada como `${1}` para a opção `--message` e a variável `$phone`é passada como `${2}` para a opção `--phone-number`. Isso faz com que o alias `textalert` seja chamado com êxito para enviar uma mensagem.

```
$ aws textalert $message $phone
{
    "MessageId": "1ab2cd3e4-fg56-7h89-i01j-2klmn34567"
}
```

No exemplo a seguir, a ordem é invertida quando o alias é chamado para `$phone` e `$message`. A variável `$phone` é passada como `${1}` para a opção `--message` e a variável `$message`é passada como `${2}` para a opção `--phone-number`. Como as variáveis estão fora de ordem, o alias passa as variáveis incorretamente. Isso causa um erro porque o conteúdo de `$message` não corresponde aos requisitos de formatação de número de telefone para a opção `--phone-number`.

```
$ aws textalert $phone $message
usage: aws [options] <command> <subcommand> [<subcommand> ...] [parameters]
To see help text, you can run:

  aws help
  aws <command> help
  aws <command> <subcommand> help

Unknown options: text
```

## Exemplos de repositório de alias
<a name="cli-usage-alias-examples"></a>

O [repositório de alias da AWS CLI](https://github.com/awslabs/awscli-aliases) no *GitHub* contém exemplos de alias da AWS CLI criados pela equipe de desenvolvedores da AWS CLI e pela comunidade. Você pode usar todo o arquivo de exemplo de `alias` ou use aliases individuais para seu próprio uso.

**Atenção**  
A execução dos comandos nesta seção exclui seu arquivo `alias`. Para evitar que o arquivo de alias existente seja sobrescrito, altere o local de download.

**Para usar aliases do repositório**

1. Instale o Git. Para obter instruções de instalação, consulte [Introdução: Instalação do Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) na *Documentação do Git*.

1. Instale o comando `jp`. O comando `jp` é usado no alias `tostring`. Para obter instruções de instalação, consulte [JMESPath (jp) Readme.md](https://github.com/jmespath/jp) no *GitHub*.

1. Instale o comando `jq`. O comando `jq` é usado no alias `tostring-with-jq`. Para obter instruções de instalação, consulte [Processador JSON (jq)](https://stedolan.github.io/jq/download/) no *GitHub*.

1. Baixe o `alias` de uma das seguintes formas:
   + Execute os seguintes comandos que são baixados do repositório e copiam o arquivo `alias` para sua pasta de configuração.

------
#### [ Linux and macOS ]

     ```
     $ git clone https://github.com/awslabs/awscli-aliases.git
     $ mkdir -p ~/.aws/cli
     $ cp awscli-aliases/alias ~/.aws/cli/alias
     ```

------
#### [ Windows ]

     ```
     C:\> git clone https://github.com/awslabs/awscli-aliases.git
     C:\> md %USERPROFILE%\.aws\cli
     C:\> copy awscli-aliases\alias %USERPROFILE%\.aws\cli
     ```

------
   + Baixe diretamente o repositório e salve na pasta `cli` em sua pasta de configuração da AWS CLI. Por padrão, a pasta de configuração é `~/.aws/` no Linux ou no macOS e `%USERPROFILE%\.aws\` no Windows. 

1. Para verificar se os aliases estão funcionando, execute o alias a seguir.

   ```
   $ aws whoami
   ```

   Isso exibe a mesma resposta que o comando `aws sts get-caller-identity`:

   ```
   {
       "Account": "012345678901",
       "UserId": "AIUAINBADX2VEG2TC6HD6",
       "Arn": "arn:aws:iam::012345678901:user/myuser"
   }
   ```

## Recursos
<a name="cli-usage-alias-references"></a>
+ O [repositório de alias da AWS CLI](https://github.com/awslabs/awscli-aliases) no *GitHub* contém exemplos de alias da AWS CLI criados pela equipe de desenvolvedores da AWS CLI e contribuições da comunidade da AWS CLI.
+ The alias feature announcement from [AWS re:Invent 2016: The Effective AWS CLI User](https://www.youtube.com/watch?t=1590&v=Xc1dHtWa9-Q) no *YouTube*. 
+ [https://docs.aws.amazon.com/cli/latest/reference/sts/get-caller-identity.html](https://docs.aws.amazon.com/cli/latest/reference/sts/get-caller-identity.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html)
+ [https://docs.aws.amazon.com/cli/latest/reference/sns/publish.html](https://docs.aws.amazon.com/cli/latest/reference/sns/publish.html)