Adicionar, Atualizar ou Eliminar Documentos (API REST da Pesquisa de IA do Azure)
Pode importar documentos de pesquisa para um índice especificado com HTTP POST. Para uma grande atualização, o batching (até 1000 documentos por lote ou cerca de 16 MB por lote) é recomendado e irá 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 origens de dados do Azure suportadas, os indexadores oferecem uma alternativa mais simples para adicionar e atualizar documentos. Para obter mais informações, veja Indexer operations (Operações do indexador).
Parâmetros do URI
| Parâmetro | Description |
|---|---|
| nome do serviço | Obrigatório. Defina-o como o nome exclusivo e definido pelo utilizador do seu serviço de pesquisa. |
| nome do índice | Necessário no URI, especificando o índice a publicar documentos. Só pode publicar documentos num índice de cada vez. |
| api-version | Obrigatório. A versão estável atual é api-version=2020-06-30. Veja Versões da API para obter mais versões. |
Cabeçalhos do Pedido
A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.
| Campos | Description |
|---|---|
| Content-Type | Obrigatório. Defina esta opção como application/json |
| api-key | Opcional se estiver a utilizar funções do Azure e for fornecido um token de portador no pedido, caso contrário, é necessária uma chave. Uma chave de api é uma cadeia exclusiva gerada pelo sistema que autentica o pedido no seu serviço de pesquisa. Carregar documentos requer uma chave de API de administrador. Veja Ligar à Pesquisa de IA do Azure com a autenticação de chaves para obter detalhes. |
Corpo do Pedido
O corpo do pedido contém um ou mais documentos a indexar. Os documentos são identificados por uma chave exclusiva sensível às maiúsculas e minúsculas. Cada documento está associado a uma ação: "upload", "delete", "merge" ou "mergeOrUpload". Os pedidos de carregamento têm de incluir os dados do documento como um conjunto de pares 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 | Description |
|---|---|
| @search.action | Obrigatório. Os valores válidos são "upload", "delete", "merge" ou "mergeOrUpload". A predefinição é "carregar". Pode combinar ações, uma por documento, no mesmo lote.
"upload": uma ação de carregamento é 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": Eliminar remove o documento especificado do índice. Qualquer campo que especificar numa operação de eliminação, que não seja o campo de chave, será ignorado. Se quiser remover um campo individual de um documento, utilize merge e defina o campo explicitamente como null.
"mergeOrUpload": esta ação comporta-se como intercalação se já existir um documento com a chave especificada no índice. Se o documento não existir, comporta-se como carregar com um novo documento. "intercalação": a intercalação atualiza um documento existente com os campos especificados. Se o documento não existir, a intercalação falhará. Qualquer campo que especifique numa intercalação irá substituir o campo existente no documento. Isto também se aplica a coleções de tipos primitivos e complexos. Nas coleções primitivas, se o documento contiver um campo Etiquetas do tipo Coleção(Edm.String) com um valor de ["orçamento"], e executar uma intercalação com um valor de ["economia", "conjunto"] para Etiqueta, o valor final do campo Etiquetas será ["economia", "conjunto"]. Não será ["orçamento", "economia", "conjunto"]. Em coleções complexas, se o documento contiver um campo de coleção complexo denominado Salas com um valor de [{ "Type": "Budget Room", "BaseRate": 75.0 }], e executa uma intercalação 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 }]. 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 }] (elementos de intercalação por ordem e, em seguida, acrescentar quaisquer extras) |
| key_field_name | Obrigatório. Uma definição de campo no índice que serve de chave de documento e contém apenas valores exclusivos. As chaves de documento só podem conter letras, números, traços ("-"), carateres de sublinhado ("_") e sinais de igual ("=") e são sensíveis às maiúsculas e minúsculas. Para obter mais informações, veja Regras de nomenclatura. |
| field_name | Obrigató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 utilizador, mas tem de ser válido para o tipo de campo. |
Nota
Não existem garantias de ordenação para a qual a ação no corpo do pedido é executada primeiro. Não é recomendado ter várias ações de "intercalação" associadas ao mesmo documento num único corpo de pedido. Se existirem várias ações de "intercalação" necessárias para o mesmo documento, execute a intercalação do lado do cliente antes de atualizar o documento no índice de pesquisa.
Resposta
Código de estado: 200 é devolvido 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, pesquisáveis e pesquisáveis) alguns segundos após a conclusão da operação de indexação. O atraso específico depende da carga no serviço.
A indexação bem-sucedida é indicada pela propriedade de estado que está a ser definida como verdadeira para todos os itens, bem como pela propriedade statusCode que está a ser definida como 201 (para documentos recentemente carregados) ou 200 (para documentos intercalados ou eliminados):
{
"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 estado: 207 é devolvido quando pelo menos um item não foi indexado com êxito. Os itens que não foram indexados têm o campo de estado definido como falso. 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 seguinte explica os vários códigos de estado por documento que podem ser devolvidos na resposta. Alguns códigos de estado indicam problemas com o próprio pedido, enquanto outros indicam condições de erro temporárias. Este último deve tentar novamente após um atraso.
| Código de estado | Significado | Repetível | Notas |
|---|---|---|---|
| 200 | O documento foi modificado ou eliminado com êxito. | n/a | As operações de eliminação são idempotentes. Ou seja, mesmo que uma chave de documento não exista no índice, tentar uma operação de eliminação com essa chave resulta num código de estado 200. |
| 201 | O documento foi criado com êxito. | n/a | |
| 400 | Ocorreu um erro no documento que o impediu de ser indexado. | No | A mensagem de erro na resposta indica o que está errado com o documento. |
| 404 | Não foi possível intercalar o documento porque a chave especificada não existe no índice. | No | Este erro não ocorre em carregamentos, uma vez que criam novos documentos e não ocorre para eliminações porque são idempotentes. |
| 409 | Foi detetado um conflito de versão ao tentar indexar um documento. | Yes | Tal pode acontecer quando tenta indexar o mesmo documento mais do que uma vez em simultâneo. |
| 422 | O índice está temporariamente indisponível pois 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, o código deve aguardar antes de tentar novamente ou arrisca prolongar a indisponibilidade do serviço. |
Nota
Se o código de cliente encontrar frequentemente uma resposta 207, uma razão possível é que o sistema está sob carga. Pode confirmar isto ao verificar a statusCode propriedade 503. Se for este o caso, recomendamos a limitação dos pedidos de indexação. Caso contrário, se a indexação do tráfego não diminuir, o sistema poderá começar a rejeitar todos os pedidos com erros 503.
Código de estado: 429 indica que excedeu a quota no número de documentos por índice. Tem de criar um novo índice ou atualizar para limites de capacidade mais elevados.
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"
}
]
}
Nota
Quando carrega DateTimeOffset valores com informações de fuso horário para o índice, o Azure AI Search normaliza estes valores para UTC. Por exemplo, 2019-01-13T14:03:00-08:00 será armazenado como 2019-01-13T22:03:00Z. Se precisar de armazenar informações de fuso horário, terá de adicionar uma coluna extra ao índice.