ListVectors - Object Storage Service: Central de Documentação do Alibaba Cloud

Permissões

Por padrão, uma conta Alibaba Cloud tem permissões totais para acessar todos os recursos. Usuários e funções RAM não possuem permissões por padrão. O proprietário da conta Alibaba Cloud ou um administrador deve conceder essas permissões por meio de uma RAM policy ou de uma bucket policy.

API	Action	Descrição
ListVectors	`oss:ListVectors`	Lista dados vetoriais.

Sintaxe da solicitação

POST /?listVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Content-type: application/json

{
   "indexName": "string",
   "maxResults": int,
   "nextToken": "string",
   "returnData": boolean,
   "returnMetadata": boolean,
   "segmentCount": int,
   "segmentIndex": int,
   "filter": {
       "$and": [{
           "type": {
               "$in": ["comedy", "documentary"]
           }
       }, {
           "year": {
               "$eq": "2020"
           }
       }]
    }
}

Cabeçalhos da solicitação

Esta operação usa apenas cabeçalhos de solicitação comuns. Para mais informações, consulte Common HTTP headers.

Parâmetros da solicitação

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
indexName	String	Sim	vectorindex1	Nome do índice de vetores.
maxResults	Integer	Não	500	Número máximo de resultados retornados por solicitação. Valor padrão: 500. Valor máximo: 1.000.
nextToken	String	Não	CAESCG15aC-xxxxx	Token de consulta. Defina este parâmetro com o valor de `nextToken` da resposta anterior para obter a próxima página de resultados. Não especifique este parâmetro na primeira solicitação. O token pode ter de 1 a 2.048 bytes.
returnData	Boolean	Não	false	Indica se os dados vetoriais devem ser retornados. Valores válidos: true false (padrão)
returnMetadata	Boolean	Não	false	Indica se os metadados devem ser retornados. Valores válidos: true false (padrão)
segmentCount	Integer	Não	1	Define o grau de paralelismo das operações `ListVectors`. O valor máximo é 16. Para execução serial, defina este parâmetro como 1.
segmentIndex	Integer	Não	0	Em operações `ListVectors` paralelas, o valor de `segmentIndex` deve ser menor que o valor de `segmentCount`.
filter	Container	Não	N/A	Filtra os resultados da consulta com base em metadados. Limites aplicáveis: O tamanho total dos metadados em uma expressão de filtro não pode exceder 20 KB. A quantidade de itens de metadados em uma expressão de filtro não pode ultrapassar 1.024. As condições de filtro admitem aninhamento de até 8 níveis.

Operadores de filtro

Operador	Tipo suportado	Descrição
`$eq`	String	Corresponde ao valor exato. Em metadados do tipo array, retorna `true` se o valor de entrada corresponder a qualquer elemento do array.
`$ne`	String	Diferente de.
`$gt`	Number	Maior que.
`$gte`	Number	Maior ou igual a.
`$lt`	Number	Menor que.
`$lte`	Number	Menor ou igual a.
`$in`	Array de strings	Corresponde a qualquer valor em um array (semelhante à operação `IN` do SQL).
`$nin`	Array de strings	Não corresponde a nenhum valor no array (semelhante à operação `NOT IN` do SQL).
`$exists`	Boolean	Verifica se uma chave de metadados existe.
`$and`	Array de objetos de filtro	Executa uma operação lógica AND em um array com duas ou mais expressões de filtro.
`$or`	Array de objetos de filtro	Executa uma operação lógica OR em um array com duas ou mais expressões de filtro.
`$nor`	Array de objetos de filtro	Executa uma operação lógica NOR em um array com duas ou mais expressões de filtro.

Cabeçalhos da resposta

Esta operação usa apenas cabeçalhos de resposta comuns. Para mais informações, consulte Common HTTP headers.

Elementos da resposta

Parâmetro	Tipo	Exemplo	Descrição
nextToken	String	CAESCG15aC2xxxxx	Token de consulta para a próxima página de resultados. Se este elemento estiver vazio, todos os resultados foram retornados.
vectors	Array de objetos	N/A	Lista de objetos vetoriais.
key	String	doc-001	Chave primária do vetor. Nó pai: `vectors`
data	Object	N/A	Dados do vetor. Retornado apenas quando `returnData` é definido como `true`. Nó pai: `vectors`
metadata	Object	N/A	Metadados do vetor. Retornado apenas quando `returnMetadata` é definido como `true`. Nó pai: `vectors`

Exemplos

Exemplo de solicitação

POST /?listVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 01:33:47 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218
Content-type: application/json

{
   "indexName": "vectorindex1",
   "maxResults": 10,
   "returnData": true,
   "returnMetadata": true
}

Exemplo de resposta

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 01:33:47 GMT
Connection: keep-alive
Server: AliyunOSS
Content-type: application/json

{
   "nextToken": "CAESCG15aC2xxxxx",
   "vectors": [ 
      { 
         "data": {
            "float32": [0.1, 0.2, 0.3, 0.4, 0.5]
         },
         "key": "doc-001",
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search"
         }
      },
      { 
         "data": {
            "float32": [0.2, 0.3, 0.4, 0.5, 0.6]
         },
         "key": "doc-002",
         "metadata": {
             "category": ["science"],
             "title": "Advanced Vector Operations"
         }
      }
   ]
}

SDK

A operação ListVectors está disponível nos seguintes SDKs:

ossutil CLI

Para o comando ossutil correspondente, consulte list-vectors.

Códigos de erro

Código de erro	Código de status HTTP	Descrição
VectorIndexParameterInvalid	400	O parâmetro do índice de vetores fornecido na solicitação é inválido.
MalformedJson	400	O corpo da solicitação contém JSON malformado.
AccessDenied	403	Possíveis causas: A solicitação não inclui informações de autenticação do usuário. Você não tem as permissões necessárias para a operação.
NoSuchVectorIndex	404	O índice de vetores especificado não existe.
QpsLimitExceeded	503	A taxa de solicitações excedeu o limite de QPS.