Object Storage Service:S3 and S3 Vectors APIs on OSS: supported operations and limitations

Operações da API S3 compatíveis com buckets de uso geral

A tabela a seguir descreve as operações da API de bucket, objeto e multipart do S3 compatíveis com buckets de uso geral no OSS.

Diferenças entre buckets de uso geral e o S3

Esta seção descreve as diferenças entre os buckets de uso geral no OSS e o S3:

• Estilo de requisição

  O Amazon S3 suporta dois estilos de endereçamento de requisição: virtual-hosted e path-style. As requisições no estilo virtual-hosted usam o nome do bucket como um subdomínio no endpoint, enquanto as requisições no estilo path-style colocam o nome do bucket no caminho da url. Por motivos de segurança, o OSS suporta apenas o estilo virtual-hosted. Portanto, após a migração do S3 para o OSS, você deve configure todas as aplicações cliente e as ferramentas compatíveis com o S3 para usarem requisições no estilo virtual-hosted. Caso contrário, o sistema negará o acesso.

• Definições de listas de controle de acesso (ACLs)

  A definição de ACL difere entre o OSS e o S3. A tabela a seguir descreve as diferenças.

  Nível	Permissão	S3	OSS
  Bucket	READ	Permissão para listar buckets.	Se um objeto em um bucket não tiver permissões configuradas, você só poderá executar operações de leitura nele.
  	WRITE	Permissão para gravar ou sobrescrever objetos em um bucket.	Se o objeto a ser gravado não existir no bucket especificado, o sistema o criará no bucket. Se o objeto a ser gravado já existir no bucket especificado e não tiver permissões configuradas, você poderá sobrescrevê-lo. Use InitiateMultipartUpload para fazer upload de objetos.
  	READ_ACP	Permissão para ler a ACL de um bucket.	Apenas o proprietário do bucket e os usuários RAM autorizados têm permissão para ler a ACL de um bucket.
  	WRITE_ACP	Permissão para configure a ACL de um bucket.	Apenas o proprietário do bucket e os usuários RAM autorizados têm permissão para configure a ACL de um bucket.
  Objeto	READ	Permissão para ler um objeto.	Permissão para ler um objeto.
  	WRITE	N/A	Permissão para sobrescrever um objeto.
  	READ_ACP	Permissão para ler a ACL de um objeto.	Apenas o proprietário do bucket e os usuários RAM autorizados têm permissão para ler a ACL de um objeto.
  	WRITE_ACP	Permissão para configure a ACL de um objeto.	Apenas o proprietário do bucket e os usuários RAM autorizados têm permissão para configure a ACL de um objeto.

  Importante

  O OSS suporta apenas os seguintes modos de ACL do S3: private, public-read e public-read-write.

• Classe de armazenamento

  As classes de armazenamento do OSS e do S3 não têm correspondência direta (o OSS oferece 5 classes de armazenamento, enquanto o S3 oferece 7 classes principais) e diferem em aspectos como duração mínima de armazenamento e método de acesso. Você pode alterar a classe de armazenamento dos objetos do OSS de acordo com suas necessidades. Os principais mapeamentos e diferenças são:

  Classe de armazenamento do OSS	Classe de armazenamento correspondente no S3	Principais diferenças
  Standard	STANDARD	Duração mínima de armazenamento: nenhuma exigência no OSS nem no S3. Método de acesso: ambos suportam acesso em tempo real.
  Infrequent Access	STANDARD_IA ONEZONE_IA	Mapeamento: o IA com redundância de zona do OSS corresponde ao STANDARD_IA, e o IA com redundância local corresponde ao ONEZONE_IA. Duração mínima de armazenamento: 30 dias para ambos. Método de acesso: ambos suportam acesso em tempo real e cobram taxas de recuperação de dados.
  Archive	GLACIER_IR GLACIER (Flexible)	Duração mínima de armazenamento: 60 dias para o OSS e 90 dias para o S3. Método de acesso: o OSS requer uma operação de restauração (cerca de 1 minuto), mas você pode ative o acesso em tempo real a objetos Archive. O S3 GLACIER_IR oferece acesso em tempo real no nível de milissegundos, enquanto o GLACIER (Flexible) requer uma operação de restauração (Expedited: 1 a 5 minutos, Standard: 3 a 5 horas, Bulk: 5 a 12 horas).
  Cold Archive	DEEP_ARCHIVE	Duração mínima de armazenamento: 180 dias para ambos. Método de acesso: ambos exigem uma operação de restauração. Restauração no OSS: alta prioridade em cerca de 1 hora, padrão de 2 a 5 horas e em lote de 5 a 12 horas. Entre as classes de armazenamento do S3, apenas o GLACIER (Flexible) atinge essa duração de restauração. O DEEP_ARCHIVE requer Standard ≤12 horas (Batch de 9 a 12 horas) e Bulk ≤48 horas.
  Deep Cold Archive	Nenhuma classe de armazenamento correspondente	Classe de armazenamento exclusiva do OSS para dados extremamente frios. A AWS não possui uma classe de armazenamento mais fria que o DEEP_ARCHIVE (nenhuma classe S3 correspondente). Duração mínima de armazenamento: 180 dias para o OSS (nenhuma classe S3 correspondente). Método de acesso: o OSS requer uma operação de restauração, com alta prioridade em cerca de 12 horas e padrão em cerca de 48 horas. Entre as classes de armazenamento do S3, apenas o DEEP_ARCHIVE atinge essa duração de restauração.

  Nota

  Além disso, o S3 oferece uma classe de armazenamento dedicada INTELLIGENT_TIERING que move objetos automaticamente entre várias camadas de acesso com base na frequência de acesso. O OSS não fornece uma classe de armazenamento dedicada de camadas inteligentes; você pode alcançar um armazenamento em camadas automático semelhante com regras de ciclo de vida.

  Se o acesso em tempo real a objetos Archive não estiver ativado para um bucket, você deve primeiro restaurar os objetos Archive no bucket antes de acessá-los. O OSS ignora a duração do estado restaurado configurada para objetos nas operações da API S3. Por padrão, o estado restaurado dura um dia e você pode estendê-lo por até sete dias. Depois disso, o objeto entra no estado congelado.

• ETag

  • Se os objetos forem carregados usando o método PUT, o ETag de um objeto do OSS e o ETag de um objeto do Amazon S3 diferem no uso de maiúsculas e minúsculas. O ETag de um objeto do OSS usa letras maiúsculas, enquanto o ETag de um objeto do Amazon S3 usa letras minúsculas. Se o seu cliente usar o ETag para validar o conteúdo, configure-o para ignorar a diferença entre maiúsculas e minúsculas e evitar erros.

  • Se os objetos forem carregados por meio do método de upload multipart, o OSS calculará os valores de ETag com um método diferente do S3.

Operações da API S3 Vectors compatíveis com buckets de vetores

Os buckets de vetores no OSS Vectors são compatíveis com o protocolo Amazon S3 Vectors. Você não precisa reescrever sua aplicação. Aponte o endpoint do cliente S3 Vectors no AWS SDK para o nome de domínio de acesso do seu bucket de vetores. Assim, você poderá gerencie buckets de vetores, índices de vetores e dados de vetores, além de execute consultas de similaridade. Para obter mais informações sobre o OSS Vectors, consulte OSS Vectors. Para obter mais informações sobre as operações nativas da API do OSS Vectors, consulte OSS Vector operations.

Para acessar um bucket de vetores com o AWS SDK, configure o cliente da seguinte forma:

• Nome do service: s3vectors. As requisições usam a assinatura AWS Signature Version 4. O SDK gerencia a assinatura. Nenhuma configuração extra é necessária.

• Endpoint público: https://$bucketname-$uid.$regionID.oss-vectors.aliyuncs.com

• Endpoint interno: https://$bucketname-$uid.$regionID-internal.oss-vectors.aliyuncs.com

• Região: o id da região onde o bucket de vetores está localizado, como cn-hangzhou.

A tabela a seguir descreve as operações da API S3 Vectors que os buckets de vetores suportam e as operações correspondentes da API do OSS Vectors.

O OSS Vectors não suporta as seguintes operações do S3 Vectors. Chamar qualquer uma dessas operações retorna o erro 405 MethodNotAllowed: UpdateIndexMode, PutVectorBucketDefaultIndexMode, TagResource, UntagResource e ListTagsForResource.

O código de exemplo a seguir mostra como usar Python (Boto3) para crie um índice de vetores, gravar dados de vetores e consultar vetores por meio da API S3 Vectors. Antes de execute o código, instale uma versão do Boto3 que inclua o cliente S3 Vectors (pip install -U boto3) e armazene seu par de AccessKey em variáveis de ambiente.

import os
import boto3

# The access domain name of the vector bucket, in the https://$bucketname-$uid.$regionID.oss-vectors.aliyuncs.com format.
client = boto3.client(
    "s3vectors",
    region_name="cn-hangzhou",
    endpoint_url="https://examplebucket-123***456.cn-hangzhou.oss-vectors.aliyuncs.com",
    aws_access_key_id=os.environ.get("OSS_ACCESS_KEY_ID"),
    aws_secret_access_key=os.environ.get("OSS_ACCESS_KEY_SECRET"),
)

# Create a vector index. The index name can contain only letters and digits and must start with a letter.
client.create_index(
    vectorBucketName="examplebucket",
    indexName="exampleindex",
    dataType="float32",
    dimension=4,
    distanceMetric="cosine",
)

# Write vector data.
client.put_vectors(
    vectorBucketName="examplebucket",
    indexName="exampleindex",
    vectors=[
        {
            "key": "key1",
            "data": {"float32": [0.1, 0.2, 0.3, 0.4]},
            "metadata": {"genre": "doc"},
        }
    ],
)

# Query vector data.
response = client.query_vectors(
    vectorBucketName="examplebucket",
    indexName="exampleindex",
    queryVector={"float32": [0.1, 0.2, 0.3, 0.4]},
    topK=3,
    returnDistance=True,
    returnMetadata=True,
)
print(response["vectors"])

Diferenças entre buckets de vetores e o S3 Vectors

Ao migrar do S3 Vectors para o OSS Vectors, observe as seguintes diferenças:

• Como os recursos são endereçados

  O S3 Vectors usa um endpoint de service fixo e identifica o bucket de vetores pelo parâmetro vectorBucketName ou vectorBucketArn no corpo da requisição. O OSS Vectors resolve o bucket de vetores a partir do nome de domínio de terceiro nível e valida o corpo da requisição em relação a ele. Se o parâmetro vectorBucketName ou vectorBucketArn no corpo da requisição não corresponder ao bucket de vetores no nome de domínio, o sistema retorna o erro 400 ValidationException.

• Formato do ARN

  O OSS Vectors usa o formato de nome de recurso da Alibaba Cloud. O ARN de um bucket de vetores é acs:ossvector:$regionID:$uid:$bucketname e o ARN de um índice de vetores é acs:ossvector:$regionID:$uid:$bucketname/$indexname. O OSS Vectors não suporta o formato arn:aws:s3vectors:*. Os parâmetros ARN são opcionais em todas as requisições. Recomendamos endereçar os recursos pelo nome com os parâmetros vectorBucketName e indexName.

• Convenções de nomenclatura

  O nome de um bucket de vetores deve ter entre 3 e 32 caracteres (3 a 63 caracteres no S3 Vectors) e pode conter apenas letras minúsculas, dígitos e hifens (-). Ele não pode começar ou terminar com um hífen (-). O nome de um índice de vetores deve ter entre 1 e 63 caracteres, pode conter apenas letras e dígitos, e deve começar com uma letra. No S3 Vectors, o nome de um índice tem entre 3 e 63 caracteres e pode conter letras minúsculas, dígitos, hifens (-) e pontos (.). Portanto, ao migrar do S3 Vectors, você deve renomear os índices de vetores que contenham hifens (-), underscores (_) ou pontos (.).

• Criptografia no lado do servidor

  O OSS Vectors não suporta criptografia no lado do servidor. O OSS Vectors analisa o parâmetro encryptionConfiguration nas requisições CreateVectorBucket e CreateIndex, mas o ignora sem retornar erro. As respostas de GetVectorBucket e GetIndex não incluem esse parâmetro.

• Tags de recurso

  O OSS Vectors não suporta tags de recurso. O OSS Vectors analisa o parâmetro tags nas requisições CreateVectorBucket, mas o ignora. As operações TagResource, UntagResource e ListTagsForResource retornam o erro 405 MethodNotAllowed.

• Sem suporte ao Enhanced Mode (pré-filtragem de metadados)

  O S3 Vectors adicionou o modo de índice ENHANCED para pré-filtragem de metadados e renomeou o modo original para CLASSIC. O OSS Vectors não suporta esse modo. As operações e parâmetros relacionados comportam-se da seguinte forma:

  • O OSS Vectors não suporta as operações UpdateIndexMode e PutVectorBucketDefaultIndexMode, que retornam o erro 405 MethodNotAllowed.

  • O QueryVectors não suporta o parâmetro queryMode. Esse parâmetro é opcional no S3 Vectors. Se você defina-o como CLASSIC ou ENHANCED, o sistema retorna o erro 400 ValidationException com a mensagem Unknown field: queryMode in request. Omita esse parâmetro para executar consultas normalmente.

  • O OSS Vectors não suporta o operador de filtro $startsWith, disponível apenas no modo ENHANCED. Ele retorna o erro 400 ValidationException com a mensagem Invalid filter operation: $startsWith.

  • As respostas do GetIndex não incluem indexMode, e as respostas do GetVectorBucket não incluem defaultIndexMode.

  Se você precisar de pré-filtragem de metadados ou pesquisa híbrida, use índices no Fusion Mode no OSS Vectors. Para obter mais informações, consulte OSS Vectors.

• Recursos sem equivalente no S3 Vectors

  O S3 Vectors não possui operações equivalentes para o log de acesso de buckets de vetores (PutVectorBucketLogging, GetVectorBucketLogging e DeleteVectorBucketLogging) e para os índices no Fusion Mode com pesquisa híbrida (PutVectorIndexFusion e QueryVectorsFusion). Use as operações nativas da API do OSS Vectors para esses recursos. O CreateIndex na API S3 Vectors cria um índice no Standard Mode.

• Respostas de erro

  Uma requisição compatível com S3 retorna informações de erro no formato JSON e o tipo de exceção no cabeçalho de resposta x-amzn-errortype. A tabela a seguir descreve os tipos de exceção comuns.

  Código de status HTTP	Tipo de exceção	Causa comum
  400	ValidationException	Um parâmetro da requisição é inválido. Por exemplo, o formato do ARN é inválido, o nome do índice não está em conformidade com as convenções de nomenclatura ou o bucket de vetores no corpo da requisição não corresponde ao do nome de domínio.
  400	SerializationException	O corpo da requisição não está em conformidade com a especificação ou não é um corpo JSON válido. A mensagem de erro é Failed to parse request.
  403	AccessDeniedException	O AccessKey id não existe, a verificação de assinatura falhou ou você não tem as permissões necessárias.
  404	NotFoundException	O bucket de vetores ou índice de vetores especificado não existe.
  405	MethodNotAllowed	O OSS Vectors não suporta a operação. Por exemplo, a operação é uma operação de tag de recurso.
  409	ConflictException	O nome do bucket de vetores ou do índice de vetores já existe, ou você tentou exclua um bucket de vetores que não está vazio.