# Compatibilidade com S3 [Object Storage](/pt-br/documentacao/plataforma/object-storage/) responde a requisições S3 em seu próprio endpoint, então uma ferramenta, um SDK ou uma biblioteca que fala o protocolo S3 alcança os mesmos buckets e os mesmos objetos que a API da Azion v4 alcança. O que muda é a credencial: a API v4 carrega um personal token, e o endpoint S3 carrega uma requisição assinada com Signature Version 4 (SigV4) usando um access key e um secret key. Esta página lista a credencial que guarda esse par de chaves, as capabilities que ela concede, as configurações de conexão e as operações S3 que Azion suporta. Para os passos que configuram um cliente, consulte [Usar ferramentas compatíveis com S3](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/protocolo-s3-para-object-storage/). --- ## Configurações de conexão Um cliente S3 precisa do endpoint, da região e do par de chaves de uma credencial. | Configuração | Valor | | ------------ | --------------------------------------- | | Endpoint | `s3.us-east-005.azionstorage.net` | | Região | `us-east-005` | | Access key | O `access_key` que a credencial retorna | | Secret key | O `secret_key` que a credencial retorna | Um cliente que monta seus próprios host names usa o template no estilo DNS `%(bucket).s3.us-east-005.azionstorage.net`. As duas formas de endereço alcançam o mesmo objeto. O estilo virtual-host carrega o bucket no host name, e o estilo path carrega o bucket no primeiro segmento do caminho: ```text my-bucket-ro.s3.us-east-005.azionstorage.net/file.txt s3.us-east-005.azionstorage.net/my-bucket-ro/file.txt ``` O endpoint gerencia objetos; ele não os entrega a usuários finais. Um bucket alcança o público por meio de um [Connector](/pt-br/documentacao/plataforma/connectors/) que aponta para ele e de uma regra que envia requisições para o connector, à frente de uma [aplicação](/pt-br/documentacao/plataforma/applications/). --- ## Credenciais Uma credencial guarda o par de chaves com que um cliente S3 assina, as operações que esse par de chaves pode executar e os buckets que ele pode alcançar. Crie uma em Azion Console, em **Create Credential**, ou pela API da Azion v4 em `https://api.azion.com/v4/workspace/storage/credentials`. Esta página documenta a API; Azion Console apresenta as mesmas capabilities como checkboxes, com os rótulos **List Files**, **Read Files**, **Write Files**, **Delete Files**, **List All Bucket Names** e **List Buckets**. Uma credencial é independente do nível de acesso do bucket: `workloads_access` governa o que a plataforma da Azion pode fazer com um bucket, e uma credencial que carrega `writeFiles` grava em um bucket definido como `read_only`. Para os níveis de acesso, consulte [Buckets e objetos](/pt-br/documentacao/plataforma/object-storage/buckets-e-objetos/). | Campo | Tipo | Obrigatório | Padrão | Descrição | | ----------------- | ------------------------ | ----------- | ------------------------- | --------------------------------------------------------------------------------------------------- | | `name` | string | Sim | — | O nome da credencial | | `capabilities` | array de strings | Sim | — | As operações que a credencial pode executar, entre os seis valores em [Capabilities](#capabilities) | | `buckets` | array de nomes de bucket | Não | Todos os buckets da conta | Os buckets que a credencial alcança | | `expiration_date` | date-time, UTC ISO 8601 | Não | `null` | Quando a credencial expira. O campo retorna `null` quando a requisição o omite | > **Atenção** > > `buckets` é plural, aceita um array e é o campo que limita o escopo de uma credencial. Uma requisição de criação que o omite produz uma credencial que alcança todos os buckets da conta. ### Criar uma credencial Crie a credencial com o personal token da conta que é dona dos buckets: ```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": "my-credential", "capabilities": ["listFiles", "readFiles", "writeFiles", "deleteFiles", "listAllBucketNames", "listBuckets"], "buckets": ["my-bucket-ro"], "expiration_date": "2026-12-31T23:59:59Z" }' ``` A resposta carrega `201` e a credencial, com as duas chaves: ```json { "state": "executed", "data": { "id": 1236, "name": "my-credential", "access_key": "[ACCESS KEY]", "secret_key": "[SECRET KEY]", "capabilities": [ "listAllBucketNames", "listBuckets", "listFiles", "readFiles", "writeFiles", "deleteFiles" ], "buckets": ["my-bucket-ro"], "expiration_date": "2026-12-31T23:59:59Z", "last_editor": "user@example.com", "created_at": "2026-01-01T12:03:16.829681Z", "last_modified": "2026-01-01T12:03:16.829695Z" } } ``` `secret_key` é retornado por esta resposta e por nenhuma outra chamada. Guarde-o quando a credencial for criada; para substituir um secret key que não foi guardado, crie outra credencial. ### Listar credenciais ```bash curl --request GET \ --url https://api.azion.com/v4/workspace/storage/credentials \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` A resposta é paginada e carrega todos os campos de cada credencial, exceto o secret key: ```json { "count": 1, "total_pages": 1, "page": 1, "page_size": 10, "next": null, "previous": null, "results": [ { "id": 1236, "name": "ci-upload", "access_key": "[ACCESS KEY]", "capabilities": ["listFiles", "readFiles", "writeFiles"], "buckets": ["my-bucket-ro"], "expiration_date": "2027-01-31T23:59:59Z", "created_at": "2026-01-01T12:03:16.829681Z", "last_modified": "2026-01-01T12:03:16.829695Z", "last_editor": "user@example.com" } ] } ``` Uma credencial nunca é retornada com seu `secret_key`, e o valor não pode ser recuperado depois da requisição de criação. Substitua um secret key perdido criando outra credencial e excluindo a antiga. ### Excluir uma credencial Exclua uma credencial pelo `id` que a resposta de criação retornou: ```bash curl --request DELETE \ --url https://api.azion.com/v4/workspace/storage/credentials/ \ --header 'Accept: application/json' \ --header 'Authorization: Token [TOKEN VALUE]' ``` A resposta carrega `200`. O par de chaves deixa de assinar requisições válidas. --- ## Capabilities Uma capability nomeia as operações S3 que uma credencial pode executar. O array `capabilities` aceita estes seis valores e nenhum outro. | Capability | Operações S3 | | -------------------- | --------------------------------------------------------------------------------- | | `listFiles` | ListObjects, ListObjectsV2 | | `readFiles` | GetObject, HeadObject | | `writeFiles` | PutObject, CreateMultipartUpload, UploadPart, CompleteMultipartUpload, CopyObject | | `deleteFiles` | DeleteObject, DeleteObjects, AbortMultipartUpload | | `listAllBucketNames` | ListBuckets | | `listBuckets` | HeadBucket, ListMultipartUploads, ListParts | `deleteFiles` exige `writeFiles` na mesma credencial. Um valor fora dos seis retorna `17008`, e `listBuckets` também muda o status que uma requisição por um objeto ausente recebe, como descrito em [Erros](#erros). --- ## Operações suportadas A Azion suporta as dezesseis operações S3 abaixo. Cada uma pertence a uma classe de cobrança que os [Termos de Serviço](/pt-br/documentacao/contratos/tds/) definem: Class A, Class B ou Class C. As operações de Class C são incluídas em todos os planos. Para o uso que cada plano inclui, consulte [Limites do Object Storage](/pt-br/documentacao/plataforma/object-storage/limites/), e para as tarifas, consulte [Preços](/pt-br/documentacao/fundamentos/precos/#object-storage). A última coluna traz a forma [s3cmd](https://s3tools.org/s3cmd) de cada operação, como exemplo de como um cliente a expressa. | Operação | Classe | O que ela faz | Comando s3cmd | | ----------------------- | ------ | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | | ListBuckets | A | Lista os buckets da conta | `s3cmd ls` | | HeadBucket | A | Verifica se um bucket existe e se a credencial o alcança, retornando `200 OK` ou `404 Not Found` | `s3cmd info s3://BUCKET` | | ListMultipartUploads | A | Lista os multipart uploads em andamento em um bucket | `s3cmd multipart s3://BUCKET` | | ListObjects | A | Lista até 1.000 objetos em um bucket, ordenados por chave | `s3cmd ls s3://BUCKET` | | ListObjectsV2 | A | Lista até 1.000 objetos em um bucket e pagina além disso com um continuation token | `s3cmd ls s3://BUCKET` | | CopyObject | A | Copia um objeto que já está armazenado | `s3cmd cp s3://BUCKET1/OBJECT1 s3://BUCKET2/OBJECT2` | | GetObject | B | Retorna um objeto | `s3cmd get s3://BUCKET/OBJECT LOCAL_FILE` | | HeadObject | B | Retorna os metadados de um objeto, sem o objeto em si | `s3cmd info s3://BUCKET/OBJECT` | | DeleteObject | C | Remove um objeto de um bucket | `s3cmd del s3://BUCKET/OBJECT` | | DeleteObjects | C | Remove vários objetos em uma requisição, com as chaves no corpo XML | `s3cmd del s3://BUCKET/PREFIX --recursive` | | AbortMultipartUpload | C | Encerra um multipart upload sem montá-lo | `s3cmd abortmp s3://BUCKET/OBJECT Id` | | CompleteMultipartUpload | C | Monta no objeto as partes enviadas | Chamada por `s3cmd put` | | CreateMultipartUpload | C | Inicia um multipart upload e retorna o `uploadId` que agrupa suas partes | Chamada por `s3cmd put` | | ListParts | A | Lista as partes enviadas para um multipart upload | `s3cmd listmp s3://BUCKET/OBJECT Id` | | PutObject | C | Faz upload de um objeto | `s3cmd put FILE s3://BUCKET/OBJECT` | | UploadPart | C | Faz upload de uma parte de um multipart upload | Chamada por `s3cmd put` | `ListObjectsV2` é a operação de listagem a usar além de 1.000 objetos: ela define `IsTruncated` como true e retorna um `NextContinuationToken`, que a próxima requisição envia como o parâmetro de consulta `continuation-token`. `ListParts` pagina da mesma forma, com `NextPartNumberMarker` e o parâmetro `part-number-marker`. As seis operações de multipart carregam um upload grande em partes. `CreateMultipartUpload` abre o upload, `UploadPart` envia cada parte, `CompleteMultipartUpload` as monta e `AbortMultipartUpload` encerra um upload que não foi concluído; `ListParts` e `ListMultipartUploads` informam o que está em andamento. Um cliente que divide arquivos grandes as chama a partir do seu próprio comando de upload, então elas raramente são chamadas diretamente. ### Status da resposta Uma requisição assinada ao endpoint retorna estes status: | Operação | Requisição assinada | Status | | ------------- | --------------------------- | ------ | | ListBuckets | `GET /` | `200` | | ListObjectsV2 | `GET /?list-type=2` | `200` | | PutObject | `PUT //` | `200` | | GetObject | `GET //` | `200` | | HeadObject | `HEAD //` | `200` | | DeleteObject | `DELETE //` | `204` | As duas operações de listagem respondem em XML: `ListBuckets` retorna um documento `ListAllMyBucketsResult`, e `ListObjectsV2` retorna um documento `ListBucketResult` que carrega um `Key` e um `ETag` para cada objeto. --- ## Autenticação Uma requisição a `s3.us-east-005.azionstorage.net` é assinada com Signature Version 4. A assinatura é calculada a partir do `access_key` da credencial, do seu `secret_key` e da região `us-east-005`. Um cliente S3 assina cada requisição assim que tem as configurações de conexão. Esta não é a autenticação que a API da Azion v4 usa. Uma chamada a `https://api.azion.com/v4/workspace/storage` carrega um [personal token](/pt-br/documentacao/guias/plataforma/conta-e-billing/personal-tokens/) em um header `Authorization`, e o que a chamada pode fazer vem das permissões da conta. Uma requisição S3 assinada não carrega token, e o que ela pode fazer vem das `capabilities` da credencial e do seu escopo de `buckets`. As duas se encontram em um ponto: criar, listar e excluir uma credencial são chamadas da API v4, então elas carregam o personal token. Tudo o que o endpoint S3 responde é assinado com o par de chaves que a chamada de criação retornou. --- ## Erros Uma requisição de credencial que é rejeitada retorna o envelope de erro que toda resposta da API do Object Storage usa. Para os outros códigos que ela pode retornar, consulte [Buckets e objetos](/pt-br/documentacao/plataforma/object-storage/buckets-e-objetos/#erros). | Código | Título | Status | Causa | | ------- | -------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `17008` | `Not Allowed Capabilities` | 400 | O array `capabilities` carrega um valor fora dos seis que a plataforma aceita. O campo `meta.allowed_capabilities` da resposta os lista | A capability `listBuckets` muda o que o endpoint responde para um objeto que não está no bucket. Uma credencial sem `listBuckets` retorna `403 Forbidden`; uma credencial com ela retorna `404 Not Found`, que informa a causa real. --- ## Recursos relacionados - [Usar ferramentas compatíveis com S3](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/dados/protocolo-s3-para-object-storage.md): Os passos que configuram um cliente contra o endpoint desta página. - [Buckets e objetos](/pt-br/documentacao/plataforma/object-storage/buckets-e-objetos.md): Os mesmos buckets e objetos pela API da Azion v4, com todos os campos e todos os erros. - [Como Object Storage funciona](/pt-br/documentacao/plataforma/object-storage/como-funciona.md): O que um nível de acesso muda, e por que ele não restringe uma credencial. - [Limites do Object Storage](/pt-br/documentacao/plataforma/object-storage/limites.md): Os limites de buckets, chaves e access keys, com o uso que cada plano inclui. - [Connectors](/pt-br/documentacao/plataforma/connectors.md): O objeto que coloca um bucket por trás de uma aplicação, que é como os objetos chegam aos usuários finais.