--- name: azion-use-ferramentas-compativeis-com-s3-com-o-object-storage description: >- Crie uma credencial S3 para Object Storage, configure o s3cmd ou um SDK com ela e gerencie os objetos dos seus buckets pelas ferramentas que você já usa. --- # Use ferramentas compatíveis com S3 com o Object Storage [Object Storage](/pt-br/documentacao/plataforma/object-storage/) responde ao protocolo S3, então você gerencia objetos com as ferramentas que já usa, como o s3cmd e a biblioteca boto3. Cada ferramenta se autentica com uma credencial S3 e depois lista, faz upload, faz download e exclui os objetos dos buckets que essa credencial alcança. --- ## Pré-requisitos - Um bucket para a credencial alcançar. Consulte [Criar um bucket](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/criar-e-modificar-um-bucket/). - Acesso ao Azion Console, para o procedimento pelo Console. Consulte [Como acessar o Azion Console](/pt-br/documentacao/guias/plataforma/conta-e-billing/como-acessar-o-azion-console/). - Um [personal token](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/), para o procedimento pela API. - Um cliente S3: o s3cmd para os procedimentos de linha de comando, ou Python com a biblioteca boto3 para o exemplo com SDK. --- ## Crie uma credencial no Azion Console Uma credencial carrega um conjunto de capabilities e cada capability é um checkbox no formulário de criação. | Rótulo no Console | Valor na API | O que a credencial pode fazer | | ------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | **List Files** | `listFiles` | Ver os arquivos armazenados no bucket: `ListObjects` e `ListObjectsV2`. | | **Read Files** | `readFiles` | Acessar arquivos e fazer download deles: `GetObject` e `HeadObject`. | | **Write Files** | `writeFiles` | Fazer upload de arquivos ou modificá-los: `PutObject`, `CopyObject`, `CreateMultipartUpload`, `UploadPart` e `CompleteMultipartUpload`. | | **Delete Files** | `deleteFiles` | Remover arquivos: `DeleteObject`, `DeleteObjects` e `AbortMultipartUpload`. Exige **Write Files**. | | **List All Bucket Names** | `listAllBucketNames` | Recuperar os nomes dos buckets disponíveis: `ListBuckets`. | | **List Buckets** | `listBuckets` | Ver os detalhes dos buckets, incluindo metadados e configurações: `HeadBucket`, `ListMultipartUploads` e `ListParts`. | Para criar a credencial: 1. **Abra Object Storage no Azion Console** Acesse [Azion Console](https://console.azion.com/) > **Object Storage**. 2. **Inicie a credencial** Selecione **Create Credential**, o controle que configura uma nova credencial para alcançar o seu bucket do Object Storage. 3. **Nomeie a credencial** Em **General**, em **Name**, insira um nome que diga o que usa a credencial, como `ci-upload`. 4. **Defina a data de expiração** Insira a data em que a credencial para de funcionar. 5. **Selecione as capabilities** Selecione um checkbox por operação que a credencial permite, entre as seis da tabela acima. 6. **Copie o secret key** Azion Console informa "Credential has been created" e mostra o secret key uma única vez, em um diálogo de cópia. Copie o secret key antes de fechar o diálogo. A credencial existe na sua conta e você guarda a única cópia do secret key dela. --- ## Crie uma credencial pela API `POST /v4/workspace/storage/credentials` cria a credencial e retorna o par de chaves. O corpo aceita quatro campos: | Campo | Obrigatório | O que define | | ----------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `name` | Sim | Identifica a credencial na sua conta. | | `capabilities` | Sim | As operações que a credencial permite: `listFiles`, `readFiles`, `writeFiles`, `deleteFiles`, `listAllBucketNames` e `listBuckets`. | | `buckets` | Não | Um array com os nomes dos buckets que a credencial alcança. Omita o campo e a credencial alcança todos os buckets da conta. | | `expiration_date` | Não | O momento em que a credencial para de funcionar, em UTC ISO 8601. O campo é `null` quando você o omite. | O campo é o plural `buckets` e aceita um array. Um campo `bucket` no singular é aceito e ignorado, e a credencial que ele cria alcança toda a conta. Para as operações S3 que cada capability cobre, consulte [Compatibilidade com S3](/pt-br/documentacao/plataforma/object-storage/compatibilidade-s3/). Para criar a credencial: 1. **Envie a requisição de criação** Substitua `[TOKEN VALUE]` pelo seu personal token e `my-static-bucket` pelo bucket que a credencial alcança: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/storage/credentials \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' \ --header 'Content-Type: application/json' \ --data '{ "name": "full-access", "capabilities": [ "listFiles", "readFiles", "writeFiles", "deleteFiles", "listAllBucketNames", "listBuckets" ], "buckets": [ "my-static-bucket" ], "expiration_date": "2026-12-31T23:59:59Z" }' ``` 2. **Leia a resposta** Um `201` carrega a credencial, com o access key e o secret key de que o seu cliente S3 precisa: ```json { "state": "executed", "data": { "id": 1234, "name": "full-access", "access_key": "[ACCESS KEY]", "secret_key": "[SECRET KEY]", "capabilities": [ "listFiles", "readFiles", "writeFiles", "deleteFiles", "listAllBucketNames", "listBuckets" ], "buckets": [ "my-static-bucket" ], "expiration_date": "2026-12-31T23:59:59Z", "last_editor": "user@example.com", "created_at": "2026-01-01T12:00:00.000000Z", "last_modified": "2026-01-01T12:00:00.000000Z" } } ``` 3. **Salve o par de chaves** Copie `data.access_key` e `data.secret_key` para a ferramenta que você configura em seguida. A credencial alcança os buckets em `data.buckets` e `DELETE /v4/workspace/storage/credentials/{id}` a remove. > **Atenção** > > Esta chamada é a única que retorna `secret_key`. Azion não consegue recuperá-lo e um `GET` posterior no endpoint de credenciais nunca o retorna. Substitua um secret key perdido criando outra credencial. --- ## Configure o s3cmd O [s3cmd](https://s3tools.org/s3cmd) é uma ferramenta de linha de comando para S3 e outros serviços de armazenamento em nuvem, e `s3cmd --configure` pergunta cada configuração de conexão, uma de cada vez. Para configurá-lo: 1. **Instale o s3cmd** Instale o pacote s3cmd na máquina que gerencia os objetos. 2. **Adicione o s3cmd ao seu PATH** Confirme que o PATH do seu sistema contém `s3cmd`, para que o comando rode a partir de qualquer diretório. 3. **Inicie a configuração** ```bash s3cmd --configure ``` 4. **Insira o access key e o secret key** Insira o `access_key` e o `secret_key` da credencial que você criou. 5. **Insira a região** Insira `us-east-005`, a região que dá nome ao endpoint do Object Storage. 6. **Insira o endpoint** Insira `s3.us-east-005.azionstorage.net`. 7. **Insira o template de DNS** Insira `%(bucket).s3.us-east-005.azionstorage.net`, que endereça cada bucket como um subdomínio do endpoint. 8. **(Opcional) Insira uma senha de criptografia** Insira uma senha de criptografia e o caminho para o seu programa GPG. Gnu Privacy Guard é um software de criptografia livre e de código aberto, e adiciona uma camada de privacidade criptográfica e de autenticação à comunicação S3. 9. **Ative o HTTPS** Insira `true`. 10. **(Opcional) Insira um servidor proxy HTTP** Deixe a resposta em branco quando a sua máquina se conecta diretamente. 11. **Pressione y para testar as configurações** O s3cmd assina uma requisição com as chaves que você inseriu e informa o resultado: ```text Please wait, attempting to list all buckets... Success. Your access key and secret key worked fine :-) ``` O s3cmd agora alcança os seus buckets com essa credencial. Você pode salvar as respostas em um arquivo `.s3cfg` e rodar `s3cmd --configure` de novo para mudá-las. --- ## Gerencie objetos com o s3cmd Cada comando endereça um bucket ou um objeto pela sua URL `s3://`. | Comando | O que faz | | ---------------------------------------------- | ------------------------------------------------------------------------------ | | `s3cmd ls` | Lista todos os buckets da conta. | | `s3cmd ls s3://my-bucket` | Lista o conteúdo do bucket. | | `s3cmd put file.xml s3://my-bucket/file.xml` | Faz upload de um arquivo para o bucket. | | `s3cmd get s3://my-bucket/file.xml file-2.xml` | Faz download do objeto para um arquivo local, que você compara com o original. | | `s3cmd del s3://my-bucket/addrbook.xml` | Exclui um objeto. | | `s3cmd info s3://my-bucket/file.xml` | Retorna os metadados de um objeto sem baixá-lo. | > **Atenção** > > O endpoint S3 gerencia objetos, não buckets. `s3cmd mb` e `s3cmd rb` são recusados com `403 AccessDenied` e a mensagem `not entitled`, quaisquer que sejam as capabilities da credencial. Crie e exclua buckets pelo Azion Console, pela API da Azion ou pela Azion CLI, como [Criar um bucket](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/criar-e-modificar-um-bucket/) mostra. Rode `s3cmd --help` para listar todos os comandos que a ferramenta aceita. --- ## Conecte-se com um SDK Qualquer SDK S3 alcança o mesmo endpoint com a mesma credencial. boto3 é a biblioteca que a maioria dos projetos Python usa para armazenamento S3, e o seu client recebe o endpoint, a região e o par de chaves: ```python import boto3 s3 = boto3.client( "s3", endpoint_url="https://s3.us-east-005.azionstorage.net", aws_access_key_id="[ACCESS KEY]", aws_secret_access_key="[SECRET KEY]", region_name="us-east-005", ) response = s3.list_objects_v2(Bucket="my-static-bucket") for obj in response.get("Contents", []): print(f"Object found: {obj['Key']}") ``` O script imprime uma linha por objeto armazenado no bucket: ```text Object found: images/logo.png ``` O endpoint assina requisições com SigV4 e também responde a um endereço no estilo path, `s3.us-east-005.azionstorage.net//`. Ele serve o gerenciamento de objetos, não a entrega a usuários finais: uma aplicação apoiada por um connector é o que responde a uma requisição vinda da internet. --- ## Próximos passos - [Compatibilidade com S3](/pt-br/documentacao/plataforma/object-storage/compatibilidade-s3.md): Todas as capabilities, as operações S3 que Azion responde e o que o endpoint retorna. - [Upload e download de objetos](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/upload-e-download-de-objetos-do-bucket.md): Mova os mesmos objetos com a API da Azion e a Azion CLI. - [Criar um bucket](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/criar-e-modificar-um-bucket.md): Crie o bucket que uma credencial alcança e defina o nível de acesso que a plataforma usa. - [Use um bucket como origem de uma aplicação](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/bucket-como-connector.md): Sirva os objetos ao público, o que o endpoint S3 não faz.