Object Storage

O Object Storage da Azion é um serviço de armazenamento escalável e seguro projetado para integrar o armazenamento de objetos com a Azion Web Platform usando o padrão S3 para operações de objetos.

O Object Storage permite que você crie buckets, que podem ser usados como origens para applications ou como diretórios para upload de objetos em tempo real. Além da criação de buckets, você possui controle total sobre a alocação de armazenamento, gerenciamento de acesso a buckets e objetos, e a capacidade de fazer upload, alterar e deletar objetos.

Por que usar o Object Storage da Azion?

• Latência Mínima: Distribua objetos em nossos Points of Presence (POPs) globais, garantindo que o dado esteja o mais próximo possível do usuário final.

• Custo Zero de Data Transfer Out (DTO): Não cobramos pela saída de dados através da infraestrutura da Azion. Isso elimina surpresas no faturamento e permite escala massiva sem custos exorbitantes de transferência.

• Compatibilidade S3 Nativa: Utilize o protocolo S3, garantindo compatibilidade imediata com o ecossistema de ferramentas, SDKs e bibliotecas que você já utiliza, como AWS CLI e Boto3.

Boas práticas para entrega de objetos

Ao usar o Object Storage, é essencial entender a abordagem correta para entregar objetos aos usuários finais para evitar problemas de performance e throttling.

Use Applications com Connectors para entrega de objetos

A forma recomendada de entregar objetos armazenados no Object Storage aos usuários finais é através de Applications conectadas aos seus buckets usando Connectors. Esta abordagem:

• Direciona o tráfego através da rede de edge da Azion, garantindo performance ideal e baixa latência
• Fornece capacidades de caching para reduzir requisições à origem
• Evita rate limiting no endpoint de gerenciamento
• Escala adequadamente para cenários de alto tráfego

Evite acesso direto ao endpoint S3

O endpoint S3 (s3.us-east-005.azionstorage.net) é projetado para operações de gerenciamento de objetos, não para entregar conteúdo diretamente aos usuários finais. O acesso direto a este endpoint para entrega de conteúdo pode resultar em:

• Rate limiting e throttling (erros HTTP 429): O endpoint possui rate limits e não foi construído para lidar com a escala necessária para entrega de conteúdo ao usuário final
• Performance subótima: As requisições contornam a rede de edge da Azion, resultando em maior latência
• Sem benefícios de caching: Requisições diretas não se beneficiam do caching de edge

Não use pre-signed URLs para entrega ao usuário final

Gerar pre-signed URLs que apontam diretamente para o endpoint azionstorage.net não é recomendado para entregar objetos aos usuários finais. Quando navegadores acessam essas URLs, eles:

• Contornam inteiramente a rede de edge da Azion
• Atingem o endpoint de gerenciamento diretamente, o que pode acionar rate limits
• Não se beneficiam das funcionalidades de caching e otimização de edge

Em vez disso, use Applications com Connectors para servir objetos através do seu domínio, aproveitando a infraestrutura global de edge da Azion para performance e confiabilidade ideais.

Implementação

Buckets

Os buckets são o sistema utilizado para organizar objetos, ou arquivos, armazenados. Semelhantes a pastas, os buckets são contêineres de nível superior para armazenar objetos. Buckets podem ser criados usando a API da Azion.

Todos os buckets criados com o Object Storage da Azion são armazenados no servidor de nuvem us-east.

Nomes de buckets são exclusivos dentre todas as contas Azion. Os nomes devem ter entre 6 e 63 caracteres e não podem começar com azion. São aceitos caracteres alfanuméricos e hífen (-).

As melhores práticas para nomear buckets incluem especificar que tipos de objetos são armazenados e o tipo de permissões para os objetos. Por exemplo, um bucket para uma application Banking App em modo somente leitura (read-only) poderia ser nomeado banking-app-ro.

Objetos

Objetos, ou arquivos, podem ser enviados, modificados, baixados e removidos dos buckets por meio da Azion REST API, do Azion Runtime e do protocolo S3.

Object key

Uma object key é uma string de caracteres que compõe identificador de objetos armazenados em buckets do Object Storage. Por meio das ferramentas disponíveis, os usuários podem recuperar um arquivo armazenado em um bucket usando sua chave de objeto.

Não é obrigatório que a object key corresponda ao caminho do arquivo original ou nome do armazenamento local de onde ele foi retirado, nem que contenha a extensão original do arquivo. No entanto, ao fazer o upload de um arquivo local para um bucket, é recomendado que o nome do arquivo corresponda à object key para que ele se encaixe às convenções do armazenamento local. Por exemplo, para o arquivo local pasta/arquivo.png, a object key deve ser a mesma.

A object key não pode ser alterada. Fazer o upload de um objeto diferente ou modificar o conteúdo de um objeto usando uma chave existente substitui o objeto. Uma vez que um objeto é substituído, versões anteriores não podem ser recuperadas.

Prefix

Um prefixo é uma combinação de caminhos que simulam uma hierarquia de pastas. Como os buckets não podem ser organizados em pastas, você pode usar a barra (/) ao criar chaves para categorizar objetos do seu bucket em um prefixo.

Por exemplo, a lista de keys abaixo mostra a hierarquia simulada de uma aplicação armazenada em um bucket com prefixes:

O objeto README.md está localizado na raiz do bucket. O prefix src corresponde a uma pasta e contém os objetos index.js e index.html. Além disso, o prefix src/assets contém um objeto styles.css e o prefix src/assets/images, por sua vez, contém o objeto image.png.

O upload de um objeto diferente ou a modificação do conteúdo do objeto usando uma key existente substitui o objeto. Depois que um objeto é substituído, as versões anteriores não podem ser recuperadas.

Origem

Com Object Storage, você pode usar buckets como uma origin no Connector da Azion para buscar o conteúdo de uma application.

Você pode determinar se o conteúdo é retirado da raiz do bucket ou de um prefix dentro do bucket.

Operações

Uma operação refere-se a qualquer troca de dados entre um cliente e o Object Storage. Todas as ações relacionadas a buckets e objetos, como criar, excluir, listar e atualizar, são consideradas uma operação. Cada vez que um desses métodos é usado, uma operação é registrada através da API ou do protocolo S3.

A versão atual do Object Storage oferece operações listadas abaixo, dependendo de se a Azion API ou o protocolo S3 é usado.

Operações e Faturamento

Nosso modelo de faturamento é transparente e focado no uso efetivo, sem penalizar o sucesso do seu tráfego:

Nota: O armazenamento (Storage) é calculado por GB/hora, sem retenção mínima.

Operações da API da Azion

ListObjects

Recupera uma lista de objetos carregados em um bucket.

Esta operação retorna detalhes de todos os objetos no bucket, incluindo o tamanho em bytes e o timestamp da última modificação.

CreateBucket

Cria um novo bucket para uma conta.

ListBuckets

Recupera uma lista de buckets associados a uma conta.

UpdateBucket

Modifica as informações do bucket.

Use esta operação para alterar as permissões de acesso aos objetos no bucket. Buckets não podem ser renomeados com esta operação.

GetObject

Recupera um objeto de um bucket.

PostObject

Faz o upload de um objeto para um bucket. Os objetos são limitados a um tamanho máximo de 20 MB.

Para a API da Azion, você pode especificar o tipo MIME do objeto sendo enviado no corpo usando o cabeçalho Content-Type. Por exemplo, objetos com a extensão .txt devem conter o cabeçalho Content-Type: text/plain. Se o tipo MIME não for especificado, Object Storage tentará interpretar o tipo de arquivo com base na extensão do arquivo. Alternativamente, use o tipo MIME application/octet-stream para indicar que os dados são um fluxo binário e o servidor deve tratá-los como dados binários brutos.

Enviar um novo objeto com uma chave de objeto já existente no bucket substituirá o objeto anterior.

Para fazer upload de um arquivo binário, como uma imagem:

PutObject

Faz o upload de um objeto para um bucket.

Enviar um novo objeto com uma chave de objeto que já existia no bucket substituirá o objeto anterior.

DeleteObject

Remove um objeto de um bucket.

Quando você exclui um objeto que está sendo servido no edge, ele deixará de ser servido imediatamente e não será mais listado no bucket.

DeleteBucket

Remove um bucket de uma conta.

Buckets que contêm objetos não podem ser excluídos. Após remover o último objeto de um bucket, há um período de 24 horas antes que o bucket possa ser excluído.

Operações do protocolo S3

Se listBuckets estiver habilitado, ao tentar recuperar arquivos que não estão no bucket usando uma credencial S3, a resposta de status 404 Not Found correta é retornada em vez de um status 403 Forbidden. Descubra mais sobre as capacidades do S3 em compatibilidade com o protocolo S3.

Leia mais sobre Como acessar o Object Storage usando o protocolo S3.

ListBuckets

Recupera uma lista de buckets associados a uma conta.

Comando S3cmd: s3cmd ls

HeadBucket

Verifica a existência e permissões do bucket, retornando 200 OK se existir ou 404 Not Found se não existir.

Comando S3cmd: s3cmd info s3://BUCKET

ListMultipartUploads

Lista uploads multipart em andamento em um bucket. Refere-se a um upload multipart que o S3 iniciou uma requisição de Create Multipart Upload, mas que ainda não foi concluído ou abortado.

Comando S3cmd: s3cmd multipart s3://BUCKET

ListObjects

Retorna uma lista de até 1.000 objetos no bucket, ordenados alfabeticamente por chave. Você pode usar os parâmetros de consulta para filtrar a pesquisa.

Comando S3cmd: s3cmd ls s3://BUCKET

Para mais de 1.000 resultados, é recomendável usar ListObjectsV2

ListObjectsV2

Retorna uma lista de até 1.000 objetos no bucket, ordenados alfabeticamente por chave. Você pode usar os parâmetros de consulta para filtrar a pesquisa.

Este limite é uma configuração padrão. No entanto, se os resultados da pesquisa excederem o tamanho máximo do conjunto de resultados, o primeiro conjunto é retornado na resposta inicial, o elemento de resposta <IsTruncated> contém o valor verdadeiro e o elemento <NextContinuationToken> contém um token para recuperar o próximo conjunto de resultados.

Use este token como o parâmetro de consulta continuation-token em outra requisição para recuperar o próximo conjunto de resultados.

Comando S3cmd: s3cmd ls s3://BUCKET

CopyObject

Cria uma cópia de um objeto que já está armazenado.

Comando S3cmd: s3cmd cp s3://BUCKET1/OBJECT1 s3://BUCKET2/OBJECT2

GetObject

Recupera um objeto de um bucket.

Comando S3cmd: s3cmd get s3://BUCKET/OBJECT LOCAL_FILE

HeadObject

Recupera metadados de um objeto sem retornar o próprio objeto.

Comando S3cmd: s3cmd info s3://BUCKET/OBJECT

DeleteObject

Remove um objeto de um bucket completamente.

Comando S3cmd: s3cmd del s3://BUCKET/OBJECT

DeleteObjects

Exclui vários objetos de um bucket em uma única requisição. No corpo XML, forneça as chaves dos objetos e, opcionalmente, os IDs das versões se você quiser excluir uma versão específica do objeto.

Comando S3cmd: s3cmd del s3://BUCKET/PREFIX --recursive

AbortMultipartUpload

Aborta um upload multipart.

Comando S3cmd: s3cmd abortmp s3://BUCKET/OBJECT Id

CompleteMultipartUpload

Completa um upload multipart montando partes previamente carregadas.

Esta operação é parte do processo de upload multipart do S3, sendo tratada automaticamente como parte do processo de upload ao carregar arquivos grandes, uma vez que todas as partes sejam carregadas com sucesso.

CreateMultipartUpload

Inicia um upload multipart e retorna um uploadId. Este uploadId é usado para associar todas as partes em um upload multipart específico.

Esta operação é parte do processo de upload multipart do S3, sendo tratada automaticamente como parte do processo de upload ao carregar arquivos grandes quando você usa o comando put com um arquivo grande. Não há necessidade de chamar explicitamente esta operação.

ListParts

Lista partes que foram carregadas para um determinado upload multipart.

Este limite é uma configuração padrão. No entanto, se o número de resultados da pesquisa for maior do que o tamanho máximo do conjunto de resultados, o primeiro conjunto é retornado na resposta inicial, o elemento de resposta contém o valor verdadeiro e o elemento contém um token para recuperar o próximo conjunto de resultados. Use este token como o parâmetro de consulta part-number-marker em outra requisição para recuperar o próximo conjunto de resultados.

Comando S3cmd: s3cmd listmp s3://BUCKET/OBJECT Id

PutObject

Faz o upload de um objeto para um bucket.

Comando S3cmd: s3cmd put FILE s3://BUCKET/OBJECT

UploadPart

Faz o upload de uma parte do arquivo em um upload multipart. O s3cmd divide automaticamente arquivos grandes em partes e as carrega. Você não precisa gerenciar as partes ou chamar esta operação diretamente manualmente.

Autenticação e permissões

Você pode gerenciar as seguintes permissões para o Object Storage:

• Teams Permissions na Azion: operações envolvendo buckets, como upload, listagem e exclusão de objetos, sempre requerem autenticação através da conta Azion. Vá para Teams Permissions para saber mais sobre as permissões disponíveis no Object Storage.
• Permissões de bucket: gerencie o acesso do edge e de outros usuários a buckets e objetos dentro dos buckets; relacionado ao atributo edge_access.
• Credenciais S3: gerencie o acesso para usuários da conta Azion através de capacidades e atribua permissões de operação exclusivas para acesso ao protocolo S3.

Permissões de bucket

Além da autenticação necessária e das permissões necessárias, algumas operações da API podem ser restritas por permissões de bucket. As permissões disponíveis são:

• Read-only: objetos no bucket podem ser lidos, mas não modificados pela Azion Web Platform.
• Read-write: objetos no bucket podem ser modificados pela Azion Web Platform.
• Restricted: objetos no bucket podem ser modificados e lidos, mas não podem ser acessados pela Azion Web Platform. Buckets restritos não podem ser modificados usando o Azion Runtime e não podem ser usados como origem para applications.

Essas permissões estão relacionadas à forma como o edge pode acessar o bucket:

• Se o bucket estiver configurado como read-only, a Azion Web Platform pode recuperar objetos do bucket, mas não pode fazer upload ou modificá-los. No entanto, usuários autorizados podem continuar escrevendo no Object Storage através da API ou do protocolo S3.
• Se o bucket estiver configurado como read-write, a Azion Web Platform e outros usuários podem tanto recuperar quanto modificar objetos dentro do bucket.
• Se o bucket estiver configurado como restricted, a Azion Web Platform não pode acessar o conteúdo do bucket. Nesse caso, apenas usuários autorizados podem continuar escrevendo no Object Storage através da API ou do protocolo S3.

Por exemplo, quando um usuário externo tenta enviar uma requisição POST ou PUT para uma application usando um bucket configurado com permissões read-only ou restricted como sua origem, o edge negará o acesso e retornará uma mensagem de erro.

Credenciais S3

Object Storage oferece compatibilidade com o protocolo S3 por meio de credenciais.

Credenciais podem ser criadas para qualquer bucket que você possua ou para sua conta como um todo para gerenciar todos seus buckets. Com elas, você pode controlar permissões para operações associadas a essa credencial. As permissões para a credencial são exclusivas para acesso através do protocolo S3.

Para criar uma credencial S3, você deve usar um personal token da Azion e executar uma requisição POST via API. No entanto, após a credencial ser criada, ela funciona independentemente do seu token Azion. Dessa forma, mesmo que o token expire, a credencial permanece válida.

Uma vez que uma credencial é criada, uma access key e uma secret key são geradas, as quais podem ser usadas para configurar o acesso ao bucket através do protocolo S3. Por razões de segurança, a secret key não estará disponível após a criação da credencial. Credenciais existentes não podem ser modificadas.

Uma vez que o acesso de um usuário é verificado, ele estará autorizado a realizar operações dependendo das capabilities e permissões definidas para a credencial.

Capabilities

Você pode atribuir as seguintes capabilities às credenciais S3:

• listFiles: equivalente a ListObjects, retorna uma lista de objetos dentro do bucket.
• readFiles: equivalente a GetObject, retorna um objeto do bucket através da object key.
• writeFiles: equivalente a PutObject, permite modificar arquivos no bucket através da object key.
• deleteFiles: equivalente a DeleteObject, permite a exclusão de objetos através da object key.
• listAllBucketNames: equivalente a ListBuckets, permite que você liste todos os buckets associados à conta.
• listBuckets: se habilitado, retorna a resposta de status 404 Not Found correta ao tentar recuperar arquivos que não estão no bucket usando a credencial.

Mapeamento de capability para operação

A tabela a seguir mapeia cada capability S3 para suas operações associadas:

Compatibilidade com protocolo S3

Após a criação de uma credencial S3 para um bucket, você pode usar o protocolo S3 (s3://) para executar operações de acordo com a lista de capabilities.

O protocolo S3 permite acessar buckets e objetos usando a URL de Object Storage. Esta configuração facilita operações de objetos através de ferramentas de interface de linha de comando (CLI), como s3cmd, serviços de banco de dados ou funções.

Você pode usar a access key e secret key fornecidas pela API de credenciais S3 para configurar uma conexão usando o protocolo S3.

Para fazer isso, você precisará das seguintes informações:

Limites

Estes são os limites default: