Adicionar, atualizar ou excluir documentos (API REST de visualização)
Aplica-se a: 2023-07-01-Preview. Esta versão não é mais suportada. Atualize imediatamente para uma versão mais recente.
Importante
2023-07-01-Preview adiciona:
- Suporte para campos vetoriais em um documento.
Você pode enviar documentos que contêm campos vetoriais para um índice especificado usando HTTP POST. Para uma atualização grande, o processamento em lote (até 1000 documentos por lote, ou cerca de 16 MB por lote) melhora o desempenho da indexação.
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=2023-07-01-Preview
Content-Type: application/json
api-key: [admin key]
Parâmetros de URI
Cabeçalhos de solicitação
A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais.
| Campos | Descrição |
|---|---|
| Tipo de conteúdo | Necessário. Defina esse valor como application/json |
| Chave API | Opcional se você estiver usando funções do Azure e um token de portador for fornecido na solicitação, caso contrário, uma chave será necessária. Uma chave de api é uma cadeia de caracteres exclusiva gerada pelo sistema que autentica a solicitação no seu serviço de pesquisa. O carregamento de documentos requer uma chave de API de administração. Consulte Conectar-se à Pesquisa de IA do Azure usando de autenticação de chave para obter detalhes. |
Órgão do Pedido
O corpo do pedido contém um ou mais documentos a indexar. Os documentos são identificados exclusivamente por meio de uma chave que diferencia maiúsculas de minúsculas. Cada documento está associado a uma ação: "upload", "delete", "merge" ou "mergeOrUpload". As solicitações de upload devem incluir os dados do documento como um conjunto de pares chave/valor.
Os campos vetoriais são do tipo Collection(Edm.Single). Os dados vetoriais consistem em uma matriz de números de ponto flutuante de precisão única.
Os campos vetoriais podem conter milhares de incorporações, dependendo da complexidade, comprimento ou tipo do conteúdo original. O Azure AI Search não converte conteúdo em incorporações. Os documentos enviados por push para um índice devem conter incorporações que você gerou anteriormente.
{
"value": [
{
"@search.action": "upload (default) | merge | mergeOrUpload | delete",
"key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)
"field_name": field_value (key/value pairs matching index schema),
"vector_field_name": [ array of single-precision floating point numbers ]
...
},
...
]
}
| Propriedade | Descrição |
|---|---|
| @search.action | Necessário. Os valores válidos são "upload", "delete", "merge" ou "mergeOrUpload". O padrão é "upload". |
| key_field_name | Necessário. Uma definição de campo no índice que serve como a chave do documento e contém apenas valores exclusivos. As chaves do documento só podem conter letras, números, traços ("-"), sublinhados ("_") e sinais de igual ("=") e diferenciam maiúsculas de minúsculas. |
| field_name | Necessário. Pares nome-valor, em que o nome do campo corresponde a um nome de campo na definição do índice. O valor é definido pelo usuário, mas deve ser válido para o tipo de campo. |
Resposta
Código de status: 200 é retornado para uma resposta bem-sucedida, o que significa que todos os itens foram armazenados de forma durável e que a indexação começou. A indexação é executada em segundo plano e torna novos documentos disponíveis (ou seja, consultáveis e pesquisáveis) alguns segundos após a conclusão da operação de indexação.
A indexação bem-sucedida é indicada quando a propriedade status é definida como true para todos os itens. A propriedade statusCode deve ser 201 (para documentos recém-carregados) ou 200 (para documentos mesclados ou excluídos).
Exemplos
Exemplo: Carregar dois documentos com texto e conteúdo vetorial
Para facilitar a leitura, o exemplo a seguir mostra um subconjunto de documentos e incorporações. O corpo da solicitação Upload Documents consiste em 108 documentos, cada um com um conjunto completo de incorporações para "titleVector" e "contentVector".
POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/index?api-version={{api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
"value": [
{
"id": "1",
"title": "Azure App Service",
"content": "Azure App Service is a fully managed platform for building, deploying, and scaling web apps. You can host web apps, mobile app backends, and RESTful APIs. It supports a variety of programming languages and frameworks, such as .NET, Java, Node.js, Python, and PHP. The service offers built-in auto-scaling and load balancing capabilities. It also provides integration with other Azure services, such as Azure DevOps, GitHub, and Bitbucket.",
"category": "Web",
"titleVector": [
-0.02250031754374504,
. . .
],
"contentVector": [
-0.024740582332015038,
. . .
],
"@search.action": "upload"
},
{
"id": "2",
"title": "Azure Functions",
"content": "Azure Functions is a serverless compute service that enables you to run code on-demand without having to manage infrastructure. It allows you to build and deploy event-driven applications that automatically scale with your workload. Functions support various languages, including C#, F#, Node.js, Python, and Java. It offers a variety of triggers and bindings to integrate with other Azure services and external services. You only pay for the compute time you consume.",
"category": "Compute",
"titleVector": [
-0.020159931853413582,
. . .
],
"contentVector": [
-0.02780858241021633,,
. . .
],
"@search.action": "upload"
}
. . .
]
}
Observação
Quando você carrega valores de DateTimeOffset com informações de fuso horário em seu índice, o Azure AI Search normaliza esses valores para UTC. Por exemplo, 2019-01-13T14:03:00-08:00 será armazenado como 2019-01-13T22:03:00Z. Se precisar armazenar informações de fuso horário, adicione uma coluna extra ao índice.
Ver também
- Carregar dados em um de índice de pesquisa