Adicionar, atualizar ou excluir documentos (API REST do Azure AI Search)
Você pode importar documentos de pesquisa para 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) é recomendado e melhorará significativamente o desempenho da indexação.
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
Para fontes de dados do Azure com suporte, os indexadores oferecem uma alternativa mais simples para adicionar e atualizar documentos. Para obter mais informações, confira Operações do indexador.
Parâmetros de URI
| Parâmetro | Descrição |
|---|---|
| nome do serviço | Obrigatórios. Defina isso como o nome exclusivo definido pelo usuário do serviço de pesquisa. |
| nome do índice | Necessário no URI, especificando qual índice publicar documentos. Só é possível postar documentos em um índice por vez. |
| api-version | Obrigatórios. A versão estável atual é api-version=2020-06-30. Confira 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-o 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 por uma chave exclusiva 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.
{
"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)
...
},
...
]
}
| Propriedade | Descrição |
|---|---|
| @search.action | Obrigatórios. Os valores válidos são "upload", "delete", "merge" ou "mergeOrUpload". O padrão é "upload". Você pode combinar ações, uma por documento, no mesmo lote. "upload": uma ação de upload é semelhante a um 'upsert' em que o documento será inserido se for novo e atualizado/substituído se existir. Todos os campos são substituídos no caso de atualização. "delete": Excluir remove o documento especificado do índice. Qualquer campo especificado em uma operação de exclusão, diferente do campo de chave, será ignorado. Se você quiser remover um campo individual de um documento, use merge e defina o campo explicitamente como null. "mergeOrUpload": essa ação se comporta como mesclagem se um documento com a chave fornecida já existir no índice. Se o documento não existir, ele se comportará como carregar com um novo documento. "merge": a mesclagem atualiza um documento existente com os campos especificados. Se o documento não existir, a mesclagem falhará. Qualquer campo que você especificar em uma mesclagem substituirá o campo existente no documento. Isso também se aplica a coleções de tipos primitivos e complexos. Em coleções primitivas, se o documento contiver um campo Tags do tipo Collection(Edm.String) com um valor de ["budget"], e você executar uma mesclagem com um valor de ["economy", "pool"] para Tag, o valor final do campo Tags será ["economy", "pool"]. Ele não poderá ser [“budget”, “economy”, “pool”]. Em coleções complexas, se o documento contiver um campo de coleção complexo chamado Rooms com um valor de [{ "Type": "Budget Room", "BaseRate": 75.0 }], e você executa uma mesclagem com um valor de [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], o valor final do campo Salas será [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Ele não será um dos seguintes: [{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] (acrescentar elementos) [{ "Type": "Standard Room", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60.5 }] (mesclar elementos em ordem e acrescentar quaisquer extras) |
| 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. Para obter mais informações, consulte Regras de nomenclatura. |
| 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. |
Observação
Não há garantias de ordenação para a qual a ação no corpo da solicitação é executada primeiro. Não é recomendável ter várias ações de "mesclagem" associadas ao mesmo documento em um único corpo de solicitação. Se houver várias ações de "mesclagem" necessárias para o mesmo documento, execute a mesclagem do lado do cliente antes de atualizar o documento no índice de pesquisa.
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 começarão a ser indexados. 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. O atraso específico depende da carga do serviço.
A indexação bem-sucedida é indicada pela propriedade status que está sendo definida como true para todos os itens, bem como a propriedade statusCode que está sendo definida como 201 (para documentos recém-carregados) ou 200 (para documentos mesclados ou excluídos):
{
"value": [
{
"key": "unique_key_of_new_document",
"status": true,
"errorMessage": null,
"statusCode": 201
},
{
"key": "unique_key_of_merged_document",
"status": true,
"errorMessage": null,
"statusCode": 200
},
{
"key": "unique_key_of_deleted_document",
"status": true,
"errorMessage": null,
"statusCode": 200
}
]
}
Código de status: 207 é retornado quando pelo menos um item não foi indexado com êxito. Os itens que não foram indexados têm o campo status definido como false. As propriedades errorMessage e statusCode indicam o motivo do erro de indexação:
{
"value": [
{
"key": "unique_key_of_document_1",
"status": false,
"errorMessage": "The search service is too busy to process this document. Please try again later.",
"statusCode": 503
},
{
"key": "unique_key_of_document_2",
"status": false,
"errorMessage": "Document not found.",
"statusCode": 404
},
{
"key": "unique_key_of_document_3",
"status": false,
"errorMessage": "Index is temporarily unavailable because it was updated with the 'allowIndexDowntime' flag set to 'true'. Please try again later.",
"statusCode": 422
}
]
}
A propriedade errorMessage indica o motivo do erro de indexação, se possível.
A tabela a seguir explica os vários códigos de status por documento que podem ser retornados na resposta. Alguns códigos status indicam problemas com a solicitação em si, enquanto outros indicam condições de erro temporárias. Você deve testar o último novamente após um atraso.
| Código de status | Significado | Permite tentar novamente | Observações |
|---|---|---|---|
| 200 | O documento foi modificado ou excluído com êxito. | n/d | As operações de exclusão são idempotentes. Ou seja, mesmo que uma chave de documento não exista no índice, tentar uma operação de exclusão com essa chave resultará em um código de status 200. |
| 201 | O documento foi criado com êxito. | n/d | |
| 400 | Ocorreu um erro no documento que o impediu de ser indexado. | No | A mensagem de erro na resposta indica o que há de errado com o documento. |
| 404 | Não foi possível mesclar o documento porque a chave fornecida não existe no índice. | No | Esse erro não ocorre para uploads, pois eles criam novos documentos e não ocorre para exclusões porque são idempotentes. |
| 409 | Foi detectado um conflito de versão durante a tentativa de indexar um documento. | Yes | Isso pode acontecer quando você está tentando indexar o mesmo documento mais de uma vez simultaneamente. |
| 422 | O índice está temporariamente indisponível porque ele foi atualizado com o sinalizador 'allowIndexDowntime' definido como 'verdadeiro'. | Yes | |
| 503 | O serviço de pesquisa está temporariamente indisponível, possivelmente devido a uma carga pesada. | Yes | Neste caso, seu código deverá ser colocado em espera antes de uma nova tentativa, sob o risco de prolongar a indisponibilidade do serviço. |
Observação
Se o seu código de cliente com frequência encontrar uma resposta 207, um motivo possível é que o sistema esteja sob carga. Você pode confirmar isso verificando a propriedade statusCode para 503. Se esse for o caso, recomendamos a limitação de solicitações de indexação. Caso contrário, se a indexação de tráfego não diminuir, o sistema poderá começar a rejeitar todas as solicitações com erros 503.
O código de status: 429 indica que você excedeu sua cota no número de documentos por índice. Você deve criar um novo índice ou atualizar para limites de capacidade mais altos.
Exemplos
Exemplo: carregar dois documentos totalmente definidos
{
"value": [
{
"@search.action": "upload",
"HotelId": "1",
"HotelName": "Secret Point Motel",
"Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York.",
"Category": "Boutique",
"Tags": [ "pool", "air conditioning", "concierge" ],
"ParkingIncluded": false,
"LastRenovationDate": "1970-01-18T00:00:00Z",
"Rating": 3.60,
"Address": {
"StreetAddress": "677 5th Ave",
"City": "New York",
"StateProvince": "NY",
"PostalCode": "10022",
"Country": "USA"
},
"Location": {
"type": "Point",
"coordinates": [ -73.975403, 40.760586 ]
},
"Rooms": [
{
"Description": "Budget Room, 1 Queen Bed (Cityside)",
"Description_fr": "Chambre Économique, 1 grand lit (côté ville)",
"Type": "Budget Room",
"BaseRate": 96.99,
"BedOptions": "1 Queen Bed",
"SleepsCount": 2,
"SmokingAllowed": true,
"Tags": [ "vcr/dvd" ]
},
{
"Description": "Budget Room, 1 King Bed (Mountain View)",
"Description_fr": "Chambre Économique, 1 très grand lit (Mountain View)",
"Type": "Budget Room",
"BaseRate": 80.99,
"BedOptions": "1 King Bed",
"SleepsCount": 2,
"SmokingAllowed": true,
"Tags": [ "vcr/dvd", "jacuzzi tub" ]
}
]
},
{
"@search.action": "upload",
"HotelId": "2",
"HotelName": "Twin Dome Motel",
"Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
"Description_fr": "L'hôtel est situé dans une place du XIXe siècle, qui a été agrandie et rénovée aux plus hautes normes architecturales pour créer un hôtel moderne, fonctionnel et de première classe dans lequel l'art et les éléments historiques uniques coexistent avec le confort le plus moderne.",
"Category": "Boutique",
"Tags": [ "pool", "free wifi", "concierge" ],
"ParkingIncluded": false,
"LastRenovationDate": "1979-02-18T00:00:00Z",
"Rating": 3.60,
"Address": {
"StreetAddress": "140 University Town Center Dr",
"City": "Sarasota",
"StateProvince": "FL",
"PostalCode": "34243",
"Country": "USA"
},
"Location": {
"type": "Point",
"coordinates": [ -82.452843, 27.384417 ]
},
"Rooms": [
{
"Description": "Suite, 2 Double Beds (Mountain View)",
"Description_fr": "Suite, 2 lits doubles (vue sur la montagne)",
"Type": "Suite",
"BaseRate": 250.99,
"BedOptions": "2 Double Beds",
"SleepsCount": 2,
"SmokingAllowed": false,
"Tags": [ "Room Tags" ]
}
]
},
{
"@search.action": "merge",
"HotelId": "3",
"Rating": 2.39,
"Description": "Surprisingly expensive",
"LastRenovationDate": null
},
{
"@search.action": "delete",
"hotelId": "4"
}
]
}
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, precisará adicionar uma coluna extra ao índice.