Compatibilidade com S3
Alcance buckets do Object Storage pelo protocolo S3: a credencial, suas capabilities, o endpoint e as operações que Azion suporta.
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.
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:
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 que aponta para ele e de uma regra que envia requisições para o connector, à frente de uma aplicação.
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.
| 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 |
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 |
Criar uma credencial
Crie a credencial com o personal token da conta que é dona dos buckets:
A resposta carrega 201 e a credencial, com as duas chaves:
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
A resposta é paginada e carrega todos os campos de cada credencial, exceto o secret key:
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:
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.
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 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, e para as tarifas, consulte Preços.
A última coluna traz a forma 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 /<bucket>?list-type=2 | 200 |
| PutObject | PUT /<bucket>/<key> | 200 |
| GetObject | GET /<bucket>/<key> | 200 |
| HeadObject | HEAD /<bucket>/<key> | 200 |
| DeleteObject | DELETE /<bucket>/<key> | 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 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.
| 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.