# Como acessar o Object Storage usando o protocolo S3

O **Object Storage** da Azion é totalmente compatível com o protocolo S3. Isso permite que você gerencie seus dados utilizando o ecossistema de ferramentas, SDKs e bibliotecas que você já conhece. Essa compatibilidade facilita a migração de outros provedores de nuvem para a Azion, aproveitando a nossa rede global para reduzir a latência e eliminar custos de **Data Transfer Out (DTO)**.

O acesso é realizado através de credenciais HMAC (access key e secret key), que garantem segurança e controle granular sobre as operações.

---

## 1. Criar credenciais de acesso (HMAC) via API

Para utilizar ferramentas S3-compatible, você deve gerar uma credencial que define o nível de permissão (*capabilities*).

1. Execute a seguinte requisição `POST` no seu terminal, substituindo `[TOKEN VALUE]` pelo seu [personal token](/pt-br/documentacao/produtos/guias/personal-tokens/):

```bash
curl --request POST \
  --url [https://api.azion.com/v4/workspace/storage/credentials](https://api.azion.com/v4/workspace/storage/credentials) \
  --header 'Accept: application/json' \
  --header 'Authorization: Token [TOKEN VALUE]' \
  --header 'Content-Type: application/json' \
  --data '{
     "name": "Credencial Full Access",
     "capabilities": [
        "listFiles", 
        "readFiles", 
        "writeFiles", 
        "deleteFiles", 
        "listAllBucketNames", 
        "listBuckets"
  ],
  "buckets": [
    "meu-bucket-estatico"
  ],
  "expiration_date": "2026-12-31T23:59:59Z"
}'

```

| Chave | Descrição |
| --- | --- |
| `name` | Identificador amigável para a credencial. |
| `capabilities` | Lista de permissões (ex: `readFiles` para GET, `writeFiles` para PUT). |
| `buckets` | Opcional. Restringe o acesso apenas aos buckets listados. |
| `expiration_date` | Data de expiração no formato UTC ISO 8601. |

2. Na resposta, salve os valores de `access_key` e `secret_key`.

:::caution
Por segurança, a `secret_key` é exibida apenas uma vez no momento da criação. Caso a perca, será necessário criar uma nova credencial, pois não é possível recuperá-la ou modificá-la posteriormente.
:::

---

## 2. Configurações Globais de Conexão

Para configurar qualquer ferramenta, utilize os seguintes parâmetros padrão:

* **Endpoint:** `s3.us-east-005.azionstorage.net`.
* **Região:** `us-east-005`.

---

## 3. Exemplos de Integração

### Usando Python (Boto3)

O Boto3 é a biblioteca padrão para desenvolvedores Python interagirem com storage S3.

```python
import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="[https://s3.us-east-005.azionstorage.net](https://s3.us-east-005.azionstorage.net)",
    aws_access_key_id="<SUA_ACCESS_KEY>",
    aws_secret_access_key="<SUA_SECRET_KEY>",
    region_name="us-east-005",
)

# Exemplo: Listar objetos no bucket
response = s3.list_objects_v2(Bucket="meu-bucket-estatico")
for obj in response.get("Contents", []):
    print(f"Objeto encontrado: {obj['Key']}")

```

### Usando s3cmd (CLI)

O [s3cmd](https://s3cmd.org) é uma ferramenta de linha de comando para gerenciar serviços S3.

1. Instale o pacote `s3cmd` e certifique-se de que ele esteja no seu PATH.
2. Execute `s3cmd --configure` e siga o prompt interativo:
* **Access Key / Secret Key:** Insira as chaves geradas no passo 1.
* **Default Region:** `us-east`.
* **S3 Endpoint:** `s3.us-east-005.azionstorage.net`.
* **DNS template:** `%(bucket).s3.us-east-005.azionstorage.net`.
* **Encryption password / GPG program path:** Opcional (GPG adiciona camada de privacidade).
* **Use HTTPS protocol:** `true`.
* **HTTP Proxy server:** Deixe em branco, a menos que utilize um proxy.


3. Pressione `y` para testar o acesso. Se bem-sucedido, você verá: `Success. Your access key and secret key worked fine :-)`.

#### Comandos comuns:

| Comando | Descrição |
| --- | --- |
| `s3cmd ls` | Lista todos os buckets da conta. |
| `s3cmd put arquivo.png s3://meu-bucket/` | Faz upload de um objeto. |
| `s3cmd get s3://meu-bucket/arquivo.png` | Faz download de um objeto. |
| `s3cmd del s3://meu-bucket/arquivo.png` | Exclui um objeto. |

:::note
A exclusão de buckets (`rb`) só é permitida se o bucket estiver vazio. Se arquivos foram deletados recentemente, pode haver um período de espera de até 24 horas antes que a exclusão do bucket seja permitida.
:::