Adicionar, atualizar ou excluir documentos (Versão prévia da API REST)
Aplica-se a: 2023-07-01-Preview
Importante
2023-07-01-Preview adiciona:
- Suporte para campos de vetor em um documento.
Você pode enviar por push documentos que contêm campos de vetor em um índice especificado usando HTTP POST. Para uma atualização grande, o envio 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
| Parâmetro | Descrição |
|---|---|
| nome do serviço | Obrigatórios. Defina esse valor como o nome exclusivo definido pelo usuário do serviço de pesquisa. |
| nome do índice | Obrigatórios. Defina esse valor como o nome do índice que recebe os documentos. Só é possível postar documentos em um índice por vez. |
| api-version | Obrigatórios. A versão prévia atual é 2023-07-23-Preview. Consulte Versões de API para obter mais versões. |
Cabeçalhos de solicitação
A tabela a seguir descreve os cabeçalhos de solicitação necessários e opcionais
| Campos | Descrição |
|---|---|
| Tipo de conteúdo | Obrigatórios. Defina esse valor como application/json |
| chave de 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 para o serviço de pesquisa. Carregar documentos requer uma chave de API de administrador. Confira Conectar-se ao Azure AI Search usando a autenticação de chave para obter detalhes. |
Corpo da solicitação
O corpo da solicitação contém um ou mais documentos a serem indexados. 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 carregamento devem incluir os dados do documento como um conjunto de pares de chave/valor.
Os campos vetoriais são do tipo Collection(Edm.Single). Os dados de vetor consistem em uma matriz de números de ponto flutuante de precisão única.
Os campos vetoriais podem conter milhares de inserções, dependendo da complexidade, do comprimento ou do tipo do conteúdo original. O Azure AI Search não converte conteúdo em inserções. Os documentos enviados por push para um índice devem conter inserções geradas 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 | Obrigatórios. Os valores válidos são "upload", "delete", "merge" ou "mergeOrUpload". O padrão é "carregar". |
| key_field_name | Obrigatórios. 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 | Obrigatórios. Pares nome-valor, em que o nome do campo corresponde a um nome de campo na definição de í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 com durabilidade e que a indexação foi iniciada. A indexação é executada em segundo plano e disponibiliza novos documentos (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 carregados recentemente) ou 200 (para documentos mesclados ou excluídos).
Exemplos
Exemplo: carregar dois documentos com conteúdo de texto e vetor
Para facilitar a leitura, o exemplo a seguir mostra um subconjunto de documentos e inserções. O corpo da solicitação Carregar Documentos consiste em 108 documentos, cada um com um conjunto completo de inserçõ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 DateTimeOffset valores com informações de fuso horário para 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 você precisar armazenar informações de fuso horário, adicione uma coluna extra ao índice.