Documentação do Oracle Cloud Infrastructure

Suporte à API de Compatibilidade com Amazon S3 do Object Storage

Saiba como o Object Storage suporta a API de Compatibilidade com Amazon S3.

O suporte à API de Compatibilidade com Amazon S3 é fornecido no nível do bucket e no nível do objeto. A API de compatibilidade com Amazon S3 suporta IDs de versão.

Suporte a SSE-C

Usando cabeçalhos opcionais de API, você pode fornecer sua própria chave de criptografia AES de 256 bits que é usada para criptografar e descriptografar objetos de upload e download feitos no Object Storage.

Para usar suas próprias chaves para criptografia do servidor, especifique os três seguintes três cabeçalhos de solicitação com as informações da chave de criptografia:

Cabeçalhos Descrição APIs Suportadas
x-amz-server-side-encryption-customer-algorithm Especifica "AES256" como algoritmo de criptografia.

GetObject

HeadObject

PutObject

InitiateMultipartUpload

UploadPart

x-amz-server-side-encryption-customer-key Especifica a chave de criptografia de 256 bits codificada por base64 a ser usada para criptografar ou decriptografar os dados.
x-amz-server-side-encryption-customer-key-md5 Especifica a compilação MD5 de 128 bits codificada por base64 da chave de criptografia. Esse valor é usado para verificar a integridade da chave de criptografia.

O Object Storage tem APIs distintas para copiar objetos e copiar partes. O Amazon S3 usa a presença dos seguintes cabeçalhos em PutObject e UploadPart para localizar as operações da cópia. Para copiar um objeto de origem criptografado com uma chave SSE-C, você deve especificar esses três cabeçalhos para que a decodificação do objeto pelo Object Storage seja possível.

Cabeçalhos Descrição APIs Suportadas
x-amz-copy-source-server-side-encryption-customer-algorithm Especifica "AES256" como algoritmo de criptografia a ser usado para decriptografar o objeto de origem.

PutObject

UploadPart

x-amz-copy-source-server-side-encryption-customer-key Especifica a chave de criptografia de 256 bits codificada por base64 a ser usada para decriptografar o objeto de origem.
x-amz-copy-source-server-side-encryption-customer-key-md5 Especifica a compilação MD5 de 128 bits codificada por base64 da chave de criptografia usada para decriptografar o objeto de origem.

Trabalhando S3 SDKs

Os seguintes SDKs e ferramentas, juntamente com suas versões anteriores, são suportados:

Observe o seguinte em relação aos recursos de API que não são suportados ao usar os SDKs e ferramentas anteriores:

  • O AWS Signature Versão 2 (SigV2) não é suportado. Em vez disso, use o mecanismo de assinatura AWS Signature Versão 4.
  • Definindo a codificação de conteúdo da AWS para uploads de objetos para aws-chunked. Desative a codificação de conteúdo aws-chunked em suas solicitações de upload quando suportado pelo SDK, definindo as propriedades a seguir ao inicializar o cliente S3. Por exemplo, no construtor de Configuração S3, defina: chunkedEncodingEnabled = false. Consulte a documentação do SDK para obter detalhes.
  • Fazendo upload de um objeto com a codificação de conteúdo definida como aws-chunked, o que resulta em uma 501 error.
  • Se a desativação do aws-chunked não for suportada por um SDK, você poderá alternar para uma versão do AWS SDK mais antiga do que as listadas neste tópico, como o Java v2.29.x. Essas versões mais antigas não definem aws-chunked como a codificação de conteúdo padrão, permitindo que os uploads sejam concluídos com sucesso.
  • As somas de verificação de integridade da AWS com somas de verificação à direita são enviadas usando codificação em blocos. No construtor S3Client: requestChecksumCalculation = RequestChecksumCalculation.WHEN_REQUIRED. Para obter etapas detalhadas, consulte Usando a Interface S3 do OCI Object Storage.

Suporte para Criptografia Usando Suas Próprias Chaves no Serviço Vault

Usando cabeçalhos opcionais de API, você pode fornecer sua própria chave de criptografia no serviço Vault para criptografar objetos transferidos por upload para o serviço Object Storage.

Para usar suas próprias chaves no serviço Vault para criptografia do servidor, especifique o seguinte cabeçalho de solicitação com o OCID da chave no serviço Vault:

Cabeçalhos Descrição APIs Suportadas
x-amz-server-side-encryption-aws-kms-key-id OCID de uma chave existente no serviço Vault a ser usada para criptografar o objeto.

PutObject

InitiateMultipartUpload

UploadPart

Clientes Amazon S3 Suportados

Você pode configurar vários aplicativos clientes para se comunicar com os pontos finais compatíveis com Amazon S3 do Object Storage. Este tópico fornece alguns exemplos de configuração para Clientes do Amazon S3 compatíveis.

AWS SDK for Java

O repositório do AWS SDK for Java, o download de arquivos e links da documentação estão disponíveis no GitHub: https://github.com/aws/aws-sdk-java.

Veja aqui um exemplo de configuração do AWS SDK for Java para usar o serviço Object Storage 


                // Put the Access Key and Secret Key here
                
AWSCredentialsProvider credentials = new AWSStaticCredentialsProvider(new BasicAWSCredentials(
 "gQ4+YC530sBa8qZI6WcbUbtH8oar0exampleuniqueID",
                         "7fa22331ebe62bf4605dc9a42aaeexampleuniqueID"))));

// Your namespace
String namespace = "namespace";

// The region to connect to
String region = "us-ashburn-1";

// Create an S3 client pointing at the region
String endpoint = String.format("%s.compat.objectstorage.%s.oraclecloud.com",namespace,region);
AwsClientBuilder.EndpointConfiguration endpointConfiguration = new AwsClientBuilder.EndpointConfiguration(endpoint, region);
AmazonS3 client = AmazonS3Client.builder()
 .standard()
 .withCredentials(credentials)
 .withEndpointConfiguration(endpointConfiguration)
 .disableChunkedEncoding()
 .enablePathStyleAccess()
 .build();

AWS SDK for Javascript

O repositório do AWS SDK for Javascript, os links da documentação e as instruções de instalação estão disponíveis no GitHub: https://github.com/aws/aws-sdk-js.

Veja aqui um exemplo de configuração do AWS SDK for Javascript para usar o serviço Object Storage 

s3 = new AWS.S3({
  region: 'us-ashburn-1',
  endpoint: 'https://' + mynamespace + '.compat.objectstorage.us-ashburn-1.oraclecloud.com',
  accessKeyId: 'gQ4+YC530sBa8qZI6WcbUbtH8oar0exampleuniqueID',
  secretAccessKey: '7fa22331ebe62bf4605dc9a42aaeexampleuniqueID',
  s3ForcePathStyle: true,
  signatureVersion: 'v4',
});

AWS SDK for Python (Boto3)

O repositório do AWS SDK for Python (Boto3), os links da documentação e as instruções de instalação estão disponíveis no GitHub: https://github.com/boto/boto3.

Veja aqui um exemplo de configuração do AWS SDK for Python para usar o serviço Object Storage 

import boto3
  
s3 = boto3.resource(
    's3',
    aws_access_key_id="gQ4+YC530sBa8qZI6WcbUbtH8oar0exampleuniqueID",
    aws_secret_access_key="7fa22331ebe62bf4605dc9a42aaeexampleuniqueID",
    region_name="us-phoenix-1", # Region name here that matches the endpoint
    endpoint_url="https://mynamespace.compat.objectstorage.us-phoenix-1.oraclecloud.com" # Include your namespace in the URL
)
  
# Print out the bucket names
for bucket in s3.buckets.all():
    print bucket.name

Montando Buckets do Serviço Object Storage com o Uso de s3fs

O s3fs permite que o Linux e o macOS montem o Object Storage como um sistema de arquivos. O repositório do s3fs, os links da documentação, as instruções de instalação e exemplos estão disponíveis no GitHub: https://github.com/s3fs-fuse/s3fs-fuse.

O s3fs não é adequado para todos os aplicativos. Entenda as seguintes limitações:

  • Os serviços de armazenamento de objetos têm alta latência em comparação com os sistemas de arquivos locais quanto ao tempo até o primeiro byte e falta de acesso de gravação aleatório. O s3fs obtém o melhor throughput nas cargas de trabalho que leem somente arquivos grandes.
  • Não é possível atualizar parcialmente um arquivo; portanto, alterar um único byte requer fazer upload do arquivo inteiro.
  • Gravações aleatórias ou anexos em arquivos requerem a regravação de todo o arquivo.
  • s3fs não oferece suporte a downloads parciais; portanto, mesmo que você só queira ler um byte de um arquivo, precisará fazer download de todo o arquivo.
  • s3fs não suporta cópias de arquivos do servidor. Primeiro, é necessário fazer download dos arquivos copiados para o cliente e, em seguida, fazer upload para o novo local.
  • As operações de metadados, como listar diretórios, têm um desempenho insatisfatório por causa da latência da rede.
  • s3fs não suporta links físicos nem renomeações atômicas de arquivos ou diretórios.
  • O s3fs não fornece coordenação entre vários clientes que montam o mesmo bucket.

Para montar um bucket do serviço Object Storage como um sistema de arquivos

  1. Siga as instruções de instalação fornecidas no GitHub: https://github.com/s3fs-fuse/s3fs-fuse.

    Se não for possível instalar usando um pacote predefinido, siga as instruções de compilação encontradas aqui: https://github.com/s3fs-fuse/s3fs-fuse/blob/master/COMPILATION.md.

  2. Informe as credenciais do par de Chave de Acesso/Chave Secreta em um arquivo de credenciais ${HOME}/.passwd-s3fs: 
    cat ${HOME}/.passwd-s3fs
access_key:secret_key

    Por exemplo:

    cat ${HOME}/.passwd-s3fs
gQ4+YC530sBa8qZI6WcbUbtH8oar0exampleuniqueID:7fa22331ebe62bf4605dc9a42aaeexampleuniqueID

    Em seguida, defina permissões somente de proprietário para o arquivo de credenciais:

    chmod 600 ${HOME}/.passwd-s3fs
  3. Criar um ponto de montagem para montar um bucket do serviço Object Storage:

    Onde:

    • bucket_name é o nome do bucket que você deseja montar.
    • local_directory_name é o nome do diretório local no qual você deseja montar o bucket.
    • namespace_name é o exclusivo gerado pelo sistema designado à sua tenancy no momento de criação da conta. Você pode usar a CLI ou a Console para obter o nome do seu namespace. Consulte Namespaces do Serviço Object Storage para obter detalhes.
    • region_ID é o identificador da região em que o bucket reside. Consulte Regiões e Domínios de Disponibilidade para obter detalhes.
    • endpoint: Se você quiser montar um bucket que foi criado em sua região home, não será necessário especificar o parâmetro endpoint. Se desejar montar um bucket que foi criado em outra região, especifique o parâmetro endpoint.
  4. Para montar automaticamente o bucket como um sistema de arquivo na inicialização de sistema usando s3fs, adicione o seguinte ao arquivo /etc/fstab: 
    
                                    bucket_name /path/to/local_directory_name fuse.s3fs use_path_request_style,passwd_file=/root/.s3fs-password,url=https://namespace_name.compat.objectstorage.region_ID.oraclecloud.com,endpoint=region_ID kernel_cache,multipart_size=128,parallel_count=50,multireq_max=100,max_background=1000,_netdev
  5. Para verificar a montagem do bucket s3fs, execute o comando df -h. A saída mostra o novo ponto de montagem para o bucket. Navegue até o novo ponto de montagem e execute o comando ls para listar todos os objetos no bucket.

Para solucionar problemas de montagem de um bucket do serviço Object Storage

  • Se você receber erros de autorização, revise suas políticas de IAM e certifique-se de ter uma política que permita montar um bucket como um sistema de arquivos. Por exemplo:
    Allow group s3fsAdmins to manage object-family in compartment MyCompartment
  • Verifique se você está usando o nome de namespace correto no URL do comando s3fs. Para verificar o nome de seu namespace, consulte Namespaces do Serviço Object Storage.
  • Certifique-se de que o bucket nomeado que você está tentando montar exista e esteja em um compartimento ao qual você tenha acesso. Use uma das seguintes maneiras de verificar o nome do bucket:
    • Faça logon na Console e localize o bucket nomeado no compartimento ao qual você tem acesso.
    • Use o comando da CLI oci os bucket list --namespace <object_storage_namespace> --compartment-id <target_compartment_id> .
  • Para montar um bucket que foi criado em uma região diferente da sua região home, você precisa especificar essa outra região nos parâmetros url e endpoint.
  • Se você montar um bucket como o usuário raiz, outros usuários não poderão listar ou acessar objetos no bucket, a menos que você adicione -o allow_other ao comando s3fs ou allow_other às opções de montagem /etc/fstab. Você também pode fornecer parâmetros específicos de UID e GID para especificar detalhes de acesso do usuário.

  • Se você revisou e verificou os diagnósticos e as soluções para problemas e precisa entrar em contato com o Suporte, execute o comando de montagem novamente no modo DEBUG para obter mais detalhes sobre a falha. Adicione o seguinte ao final do comando e salve a saída: 

    -o dbglevel=info -f -o curldbg

Para desmontar um bucket do Object Storage de um sistema de arquivos

Execute o seguinte comando, especificando o ponto de montagem:
umount /path/to/<local_directory_name>

Interface de Linha de Comando (CLI) do AWS