Buckets e objetos
Consulte os campos de um bucket e de um objeto, as onze operações de API sobre eles e o erro que cada rejeição retorna.
Um bucket é o container em que Object Storage guarda objetos. Um objeto é um arquivo, a chave sob a qual ele é armazenado e o content type com que ele é servido. Buckets não são aninhados, e um bucket guarda objetos diretamente. Esta página lista os campos de ambos, as operações que a API da Azion v4 expõe e os erros que elas retornam. Para o protocolo S3 e suas credenciais, consulte Compatibilidade com S3.
Nomes de bucket
O nome de um bucket é escolhido na criação e não pode ser alterado depois.
| Regra | Valor |
|---|---|
| Comprimento | 6 a 63 caracteres |
| Caracteres | Letras, números e o hífen (-) |
| Prefixo reservado | Um nome não pode começar com azion |
| Unicidade | Um nome é único entre todas as contas Azion, e nunca apenas dentro da sua |
Um nome já em uso retorna 17000, e um nome que começa com azion retorna 17001. Como os nomes são globais, um nome curto e genérico provavelmente já está em uso. Nomear um bucket pelo conteúdo que ele guarda e pelo acesso de que ele precisa mantém os nomes disponíveis e legíveis, como em media-assets-ro.
Campos do bucket
| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
name | string, 6 a 63 caracteres | Sim | — | O nome do bucket. Somente leitura após a criação |
workloads_access | read_only, read_write ou restricted | Sim | — | O que a plataforma da Azion pode fazer com o bucket |
last_editor | string | — | — | A conta que alterou o bucket pela última vez. Somente leitura |
last_modified | date-time | — | — | Quando o bucket foi alterado pela última vez. Somente leitura |
product_version | string | — | 1.0 | A versão do schema do bucket. Somente leitura |
workloads_access é o único campo que um PATCH aceita. Enviar name no corpo de um PATCH retorna 17004.
Níveis de acesso
workloads_access decide o que a plataforma da Azion pode fazer com o bucket quando uma aplicação o serve. Ele não restringe a API da Azion nem o protocolo S3: uma credencial que carrega writeFiles grava em um bucket definido como read_only.
| Valor | A plataforma pode | A API e o protocolo S3 podem |
|---|---|---|
read_only | Ler objetos | Ler e gravar, conforme a credencial |
read_write | Ler e gravar objetos | Ler e gravar, conforme a credencial |
restricted | Nem ler nem gravar, e o bucket não pode estar por trás de uma aplicação | Ler e gravar, conforme a credencial |
Azion Console apresenta os mesmos três níveis em Workloads Access. Para o controle e onde ele fica, consulte Criar um bucket.
Defina read_only para conteúdo que uma aplicação serve e que nada regrava. Defina read_write apenas onde uma function grava objetos durante uma requisição, e proteja o caminho na function: qualquer requisição que alcança um bucket read_write por meio de uma aplicação pode modificá-lo. Defina restricted para dados que nenhuma aplicação serve.
Chaves de objeto e prefixos
Uma chave de objeto identifica um objeto dentro de um bucket. Ela tem de 1 a 1.024 caracteres e não precisa corresponder ao nome do arquivo de onde veio.
Uma chave pode conter a barra (/), e as interfaces leem um segmento inicial compartilhado como um prefixo. Prefixos não são pastas e não são criados de antemão: fazer upload para a chave src/assets/logo.svg em um bucket vazio cria o objeto e o prefixo em uma única requisição.
Nesse bucket, README.md fica na raiz, src é um prefixo que guarda um objeto e um prefixo aninhado, e src/assets guarda logo.svg. Uma listagem com prefix=src/assets/ retorna apenas logo.svg. Um Connector que aponta para o prefixo src/assets serve esse objeto na raiz do caminho da aplicação.
Uma chave não pode ser renomeada. Fazer upload para uma chave que já guarda um objeto substitui esse objeto, e o conteúdo anterior não pode ser recuperado.
Content type
O content type armazenado com um objeto é o que o header Content-Type da requisição de upload carrega. Quando a requisição não carrega Content-Type, Azion detecta o tipo a partir do objeto.
A API também aceita um header Storage-Content-Type. Ele não tem efeito sobre o content type armazenado: um upload que envia Storage-Content-Type: image/png e nenhum Content-Type armazena o tipo que Azion detectou. Defina Content-Type na requisição de upload.
Operações
Todas as operações são autenticadas e ficam em https://api.azion.com/v4/workspace/storage.
| Operação | Método e caminho |
|---|---|
| Listar buckets | GET /buckets |
| Criar um bucket | POST /buckets |
| Recuperar um bucket | GET /buckets/{bucket_name} |
| Atualizar um bucket | PATCH /buckets/{bucket_name} |
| Excluir um bucket | DELETE /buckets/{bucket_name} |
| Listar objetos | GET /buckets/{bucket_name}/objects |
| Fazer download de um objeto | GET /buckets/{bucket_name}/objects/{object_key} |
| Criar um objeto | POST /buckets/{bucket_name}/objects/{object_key} |
| Substituir um objeto | PUT /buckets/{bucket_name}/objects/{object_key} |
| Excluir um objeto | DELETE /buckets/{bucket_name}/objects/{object_key} |
| Copiar um objeto | POST /buckets/{bucket_name}/objects/{object_key}/copy/{new_object_key} |
POST em uma chave de objeto cria o objeto e o substitui quando a chave já está em uso. PUT substitui um objeto que existe e retorna 17013 para uma chave que não existe, então ele nunca cria um objeto.
Criar um bucket
A resposta carrega 201 e o bucket criado:
Recuperar um bucket retorna o mesmo objeto em data, sem a chave state. Criar, atualizar e excluir retornam state.
Listar buckets
| Parâmetro de consulta | Efeito |
|---|---|
page, page_size | Pagina a lista. page_size aceita até 100 |
search | Corresponde a parte de um nome de bucket |
name | Corresponde a um nome de bucket exatamente |
workloads_access | Filtra pelo nível de acesso. Aceita valores separados por vírgula |
ordering | Ordena os resultados por um campo |
fields | Retorna apenas os campos indicados, separados por vírgula |
last_editor, created, last_modified | Filtra por editor ou data. Os filtros de data aceitam os sufixos __gte e __lte |
Use search para corresponder a parte de um nome. O parâmetro name corresponde ao nome inteiro, então um valor parcial não retorna nada.
Listar objetos
| Parâmetro de consulta | Padrão | Efeito |
|---|---|---|
prefix | vazio | Lista apenas as chaves sob um prefixo |
all_levels | true | Lista todas as chaves. Com false, um prefixo é retornado como uma entrada com is_folder definido como true, size igual a 0 e sem last_modified |
max_object_count | — | Número de chaves por resposta, limitado a 1.000 |
continuation_token | — | Retorna a próxima página, usando o token que a resposta anterior carregou |
Uma resposta com mais chaves do que max_object_count carrega um continuation_token. Envie-o de volta na próxima requisição para ler o restante.
Fazer upload de um objeto
Excluir um objeto
A resposta carrega 202 e {"state": "pending"}. A chave deixa de ser listada e deixa de ser servida imediatamente, e o objeto é removido permanentemente após um período de carência de 24 horas.
Excluir um bucket
Um bucket só é excluído enquanto não guarda objetos, e não dentro de 24 horas após a remoção do último objeto, por causa desse período de carência. Os dois casos retornam 17006. Um bucket que nunca guardou um objeto é excluído de imediato.
Autenticação
Toda requisição carrega um personal token:
A conta também precisa das permissões de storage para a operação. As seis permissões são View, Edit e Delete para Storage Bucket, e View, Edit e Delete para Storage Object. Para mais informações, consulte Teams permissions.
Erros
O corpo da resposta carrega um array errors. Cada entrada nomeia o code, o title, um detail, o status e o campo ao qual ela se aplica, em source.pointer.
| Código | Título | Status | Causa |
|---|---|---|---|
10039 | Invalid Choice | 400 | workloads_access carrega um valor fora dos três que o campo aceita |
10048 | Min Length | 400 | O nome do bucket tem menos de 6 caracteres |
10059 | Required Field | 400 | name ou workloads_access está ausente em uma requisição de criação |
17000 | Bucket Already Exists | 400 | O nome do bucket está em uso, na sua conta ou em outra |
17001 | Bucket Name Not Available | 400 | O nome do bucket começa com azion |
17004 | Name Cannot Be Changed | 400 | Uma requisição PATCH carrega name |
17005 | Bucket Does Not Exist | 404 | O bucket nomeado no caminho não existe |
17006 | Cannot Delete Non Empty Bucket | 400 | O bucket guarda objetos, ou um objeto foi removido dele nas últimas 24 horas |
17013 | Object Does Not Exist | 404 | A chave de objeto não existe, em um download, um PUT ou uma exclusão |
A runtime API
As operações acima são chamadas HTTP, endereçadas a api.azion.com e autenticadas com um personal token. Uma function executada no Azion Runtime alcança os mesmos buckets por um segundo caminho: ela importa o módulo azion:storage e chama put, get, delete e list em um bucket que nomeia, sem token: o construtor recebe o nome do bucket e nada mais.
Esse módulo pertence ao runtime, e não ao Object Storage, então seus métodos, o formato do StorageObject e as versões do runtime em que ele existe são documentados junto com os outros bindings do runtime, em Storage runtime API.