Adicionar, atualizar ou excluir documentos (API REST de versão prévia)
aplica-se a: 2023-07-01-Preview. Não há mais suporte para essa versão. Atualizar imediatamente para uma versão mais recente.
Importante
2023-07-01-Preview adiciona:
- Suporte para campos de vetor em um documento.
Você pode enviar documentos que contêm campos de vetor para um índice especificado usando HTTP POST. Para uma atualização grande, o envio em lote (até 1.000 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 | Necessário. Defina esse valor como o nome exclusivo definido pelo usuário do serviço de pesquisa. |
| nome do índice | Necessário. Defina esse valor como o nome do índice que recebe os documentos. Você só pode postar documentos em um índice por vez. |
| api-version | 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 obrigatórios e opcionais.
| Campos | Descrição |
|---|---|
| Tipo de conteúdo | Necessário. 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. Consulte Conectar-se ao Azure AI Search usando de 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 upload devem incluir os dados do documento como um conjunto de pares chave/valor.
Os campos de vetor 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 de vetor 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 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 é "carregar". |
| 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 de 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 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 de forma durável 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 de 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 conteúdo de texto e vetor
Para legibilidade, 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"
}
. . .
]
}
Nota
Quando você carrega DateTimeOffset valores com informações de fuso horário para o í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.