Tutoriais

 

Obter credenciais para executar o acesso

 

A forma mais simples de acessar a API de S3 da Magalu cloud é usando um par de chaves da Api Key, que são os campos ID e SECRET que  estão disponíveis na página do ID Magalu, após a criação das credenciais.

Configurando o AWS Client

 

Após obter e instalar o AWS Client é necessário configurá-lo com o ID e o Secret obtidos no passo anterior. Para isso execute o comando “aws configure” que solicitará as informações conforme abaixo:

 

aws configure <Enter>

AWS Access Key ID [None]: <ID>

AWS Secret Access Key [****************c8aa]: <Secret>

Default region name [None]: us-east-1

Default output format [None]:<Enter>

 

Onde houver a marcação <Região> substituir pela URL correspondente abaixo:

 

 

Criando Buckets através da API S3

Há duas maneiras de criar buckets, uma delas é via código por meio da API S3.

 

aws --endpoint-url '<Região>' s3 mb s3://mybucket




make_bucket: mybucket

 

Alternativamente, você pode criar um bucket através do Console da Magalu Cloud.

 

Após criar sua conta https://console.magalu.cloud/ , acessando o Console da Magalu Cloud você encontra a opção de criar um bucket em uma das regiões disponíveis.

 

 

Você pode acessar o gerenciador de Buckets do MagaluCloud pelo menu lateral e criar um novo bucket a partir dele.

No gerenciador de Buckets utilize as opções para criar um novo Bucket.

 

 

Para criar o Bucket é necessário escolher a região do datacenter convenientemente. Se os dados forem acessados de uma localização geográfica específica, recomendamos escolher a região do datacenter mais próxima ao cliente.

 

Em alguns casos a opção de buckets públicos está habilitada. Isso permitirá que o bucket possa ter seus objetos armazenados listados por qualquer pessoa. Lembre-se que o acesso é somente para a leitura dos dados.

 

Listando Buckets através da API S3

 

aws --endpoint-url '<Região>' s3 ls

 

mybucket

 

Listando Objetos

 

aws --endpoint-url '<Região>' s3 ls s3://mybucket

 

2022-06-23 12:43:11  1073741824 arquivo_grande.img

22022-06-23 12:54:31  691405178 arquivo_grande.tar.gz

32022-06-23 12:22:39    7664885 vpn.deb

 

Upload de Objetos

 

aws --endpoint-url '<Região>' s3 cp s3-wt.md s3://mybucket

 

upload: ./s3-wt.md to s3://mybucket/s3-wt.md

 

Upload de Objetos multipart automático

 

O upload de um arquivo em partes (multipart) pode ser feito de forma automática ou manual. 

Para realizar upload como multipart automaticamente, é necessário fazer uma configuração no client para o mesmo exercer a divisão do arquivo no tamanho desejado. O valor padrão do AWS CLI é de 8MB. 

 

aws configure set default.s3.multipart_threshold <valor_desejado>

 

Após a configuração, os arquivos que com tamanhos maiores que o determinado no threshold irão executar as operações de múltiplas partes automaticamente.

Desta forma podemos executar o comando de copy e a CLI fará todo esse processo automaticamente caso não ocorra nenhuma falha no envio.

 

aws --endpoint-url '<Região>' s3 cp <arquivo> s3://<nome-do-bucket>

• Em caso de falha no upload automático o arquivo não será gravado no destino, fazendo-se necessário reiniciar o upload.

 

Atualmente com a AWS CLI não é possível retomar o upload  do arquivo em caso de falha do ponto onde ocorreu o erro. Consulte a seção de limites deste documento.

Upload de Objetos multipart manual

 

Iniciamos com a comando create-multipart-upload para criar a sessão de envio de partes e depois upload-part para enviar cada parte do arquivo.

 

aws --endpoint-url '<Região>' s3api create-multipart-upload --bucket <nome-do-bucket> --key <nome-original-arquivo>

 

Após ter o UploadId gerado, podemos dar início ao envio das partes com o comando upload-part.

 

aws --endpoint-url '<Região>' s3api upload-part --bucket <nome-do-bucket> --key <nome-original-arquivo> --part-number <numero-da-parte> --body <parte-do-arquivo> --upload-id <upload-id> 

 

Caso ainda não tenha o arquivo dividido em partes é possível usar o comando abaixo para gerar as partes do tamanho desejado.

 

split -b 20M draw.io-20.3.0-windows-installer.exe ./draw-io-parts/

split -b 20M <arquivo> ./<path>/

 

Para verificar as partes já enviadas podemos utilizar o comando list-parts. o upload-id pode ser obtido com o comando list-multipart-uploads.

aws --endpoint-url '<Região>' s3api list-parts --bucket <nome-do-bucket> --key <nome-original-arquivo> --upload-id <upload-id>

• Em caso de falha em alguma parte  no upload multipart manual será necessário reenviar somente o pedaço com falha.

 

Para finalizar o envio do arquivo utilize as informações de Etag e PartNumber listados na consulta anterior para consolidar o arquivo incluindo em um arquivo JSON.

 

Com o arquivo gerado execute o comando complete-multipart-upload para enviar a lista de partes a serem consolidadas.

 

aws --endpoint-url '<Região>' s3api complete-multipart-upload --multipart-upload file://<local-do-arquivo> --bucket <nome-do-bucket> --key <nome-original-arquivo> --upload-id <upload-id>

 

Caso ainda existam arquivos com sessões em abertos que não serão mais utilizados é necessário efetuar a finalização com o comando abort-multipart-upload  para evitar o uso de espaço indevido.

aws --endpoint-url '<Região>' s3api abort-multipart-upload --bucket <nome-do-bucket> --key <nome-original-arquivo> --upload-id <upload-id>

Alterando as permissões de acesso do Bucket

 

Um bucket pode ter dois tipos de permissões de acesso. As permissões podem ser configuradas durante a criação do bucket ou alteradas depois que o bucket já está criado.  As permissões são:

 

Private: Mantém o bucket privado permitindo acesso somente ao seu dono.

 

Public-read: Permite que qualquer usuário liste os objetos no bucket, porém não permite que os objetos sejam alterados.

Concedendo Acesso Público (Public-read)

 

aws --endpoint-url '<Região>' s3api put-bucket-acl --bucket mybucket --acl public-read

 

Removendo o Acesso Público

 

aws --endpoint-url '<Região>' s3api put-bucket-acl --bucket mybucket --acl private

 

4.7.3 -  Concedendo Acesso para um Tenant Específico

Caso o bucket não seja público, via console será possível modificar permissões de escrita/leitura de um bucket para um tenant específico, onde apenas esse Tenant poderá realizar operações nos objetos ali contidos.

4.7.4 -  Removendo Acesso para um Tenant Específico

Caso o bucket esteja compartilhado, via Console será possível remover o acesso que um tenant possua.

 

4.7.5 - Listando Objetos compartilhados

 

Para listar objetos ou fazer download de arquivos de um bucket compartilhado (ACL public-read ou ACL de um tenant específico), é necessário ter credenciais para autenticação. A operação se mantém similar ao uso normal, com o acréscimo da identificação do proprietário do bucket, que consiste em seu Project Id. 

Essa informação pode ser encontrada no Console na sua lista de buckets clicando nos 3 pontos à direita do bucket desejado haverá o caminho “Copiar URL”.

 

 

Devendo ser adicionada a URL endpoint para S3 destacada no campo –endpoint-url nos exemplos abaixo: 

 

exemplo de url: https://br-se-1.magaluobjects.com/v1/AUTH_413f290fd45e4dc9aaf7jeb2d964fc68

 

aws --endpoint-url '<endpoint-url>' s3 ls s3://mybucket

 

2023-01-31 15:46:23       1544 s3-wt.md

 

Como acessar via navegador:

 

Exemplo de como listar arquivos dentro de um bucket (público): https://br-se-1.magaluobjects.com/v1/AUTH_413f290fd45e4dc9aaf7jeb2d964fc68/mybucket

 

Exemplo de como visualizar arquivos dentro de um bucket (público):

https://br-se-1.magaluobjects.com/v1/AUTH_413f290fd45e4dc9aaf7jeb2d964fc68/mybucket/my-file

Download de Objetos de um bucket compartilhado

 

aws --endpoint-url '<endpoint-url>' s3 cp s3://mybucket/s3-wt.md .

 

download: s3://mybucket/s3-wt.md to ./s3-wt.md

 

Upload em um bucket compartilhado

 

Quando um bucket é compartilhado com um Tenant específico com permissões de escrita, será possível realizar uploads nesse bucket utilizando a URL de compartilhamento como no exemplo anterior. O upload se dá de maneira bem semelhante.

aws --endpoint-url '<endpoint-url>' s3 cp myfile s3://mybucket/s3-wt.md

 

upload: ./myfile to s3://mybucket/s3-wt.md

 

Exclusão de Objetos

 

Objetos podem ser excluídos apenas pelo Administrador do bucket. Portanto, ainda que um bucket ou objeto estejam públicos, não há riscos de exclusão por parte de terceiros. Para excluir objetos, você pode utilizar o comando rm conforme abaixo:

 

aws --endpoint-url '<Região>' s3 rm s3://mybucket/s3-wt.md

 

delete: s3://mybucket/s3-wt.md

 

Exclusão de Bucket

 

aws --endpoint-url '<Região>' s3 rb s3://mybucket

 

remove_bucket: mybucket

 

URL Pré-assinadas (Pre-signed)

 

A funcionalidade de URL pré-assinadas consiste em poder compartilhar com qualquer pessoa na internet um objeto, a princípio privado,  sem necessidade de ter credenciais para o acesso. O compartilhamento é através de um link temporário, gerado localmente, e que pode ser acessado pelo navegador de preferência (por exemplo).  Para gerar uma URL pré-assinada você pode utilizar o comando abaixo:

 

aws --endpoint-url '<Região>' s3 presign --expires-in 420 s3://mybucket/s3-wt.md

 

<Região>/mybucket/s3-wt.md?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=12f8c166-4483-4adc-9e83-cde426c9dff2%2F20230505%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230505T115206Z&X-Amz-Expires=420&X-Amz-SignedHeaders=host&X-Amz-Signature=3f6ade59cc4254d5268f24026d40ce7e14b912f2d6ffb180930d362c8647a52d

 

O campo expires-in determina por quanto tempo, em segundos, essa url gerada poderá ser usada para acessar o objeto.

 

Habilitando Versionamento no Bucket

 

Ao habilitar o versionamento em um bucket, são armazenadas várias versões de um mesmo objeto no bucket. Sendo possível guardar, baixar e recuperar versões do mesmo arquivo.  Por padrão, os buckets não tem o versionamento habilitado. Após o versionamento ser ativado, ele pode ser suspenso a qualquer momento.

 

Para habilitar o versionamento no bucket:

 

aws s3api put-bucket-versioning --bucket my-bucket --versioning-configuration Status=Enabled --endpoint <endpoint_url>

 

Para suspender o versionamento no bucket:

 

aws s3api put-bucket-versioning --bucket my-bucket --versioning-configuration Status=Suspended --endpoint <endpoint_url>

 

Checar o status de versionamento no bucket:

 

aws s3api get-bucket-versioning --bucket my-bucket --endpoint <endpoint_url>

 

Para listar todas as versões de arquivos do bucket:

 

aws s3api list-object-versions --bucket my-bucket --endpoint <endpoint_url>

 

Configurando o RClone:

 

No Linux ou WSL2, pode ser instalado com seguinte comando:

 

sudo -v ; curl https://rclone.org/install.sh | sudo bash

Para mais informações veja como Instalar a versão mais recente do RClone

 

Após a instalação, será necessário configurar as credenciais através de um arquivo de configuração rclone.conf que deve estar no caminho ~/.config/rclone/rclone.conf (Linux) ou %APPDATA%/rclone/rclone.conf (Windows). Adicione as seguintes linhas ao arquivo. Caso não exista, crie:

 

[s3]

type = s3

provider = Minio

access_key_id = <ID>

secret_access_key = <SECRET>

region = us-east-1

endpoint = <Região>

 

Para efetuar o primeiro comando e testar as configurações execute o comando para criar um bucket:

 

Criar Buckets:

 

rclone mkdir s3:<bucket_name>

 

Listar Buckets:

 

rclone lsd s3:

 

Listar Objetos:

 

rclone ls s3:<bucket_name>

 

Upload Objeto:

 

rclone copy to/myfile s3:mybucket/myfile --s3-no-check-bucket

 

Faz-se necessário flag --s3-no-check-bucket para rclone não tentar criar o bucket já existente

• Para subir arquivos grandes porém menores que 5GB usar as tags --ignore-checksum --ignore-size

Upload Objeto Multipart:

 

rclone copy <object_name> s3:<bucket_name>/ --s3-upload-cutoff=10M --s3-chunk-size=10M --log-level=DEBUG --progress

 

rclone copyto <object_name> s3:<bucket_name>/example-chunk --s3-upload-cutoff=10M --s3-chunk-size=10M --log-level=DEBUG

Listar partes em caso de falha:

 

rclone backend list-multipart-uploads s3:<bucket_name>

 

• Em caso de falha no upload automático o arquivo não será gravado no destino, fazendo-se necessário reiniciar o upload.

Upload Diretório:

 

rclone copy path/to/folder/ s3:<bucket_name/destination>

 

Upload entre diretórios s3:

 

rclone copy s3:<bucket_name/origin> s3:<bucket_name/destination>

 

Mover entre diretórios s3:

 

rclone move s3:<bucket_name/origin/file> s3:<bucket_name/destination>

 

Atualizar entre diretórios s3:

 

rclone sync s3:<bucket_name/origin> s3:<bucket_name/destination>

 

Download Objetos:

 

rclone copy s3:<bucket_name/myfile> ./

 

Deletar Objeto:

 

rclone delete s3:<bucket_name/myfile>

 

Deletar Bucket:

 

rclone rmdir s3:<bucket_name>

 

Deletar Bucket+Objetos:

 

rclone purge s3:<bucket_name>

 

 

Funções úteis