Carregar dados em um índice de pesquisa no Azure AI Search

Este artigo explica como importar documentos para um índice de pesquisa pré-definido usando APIs REST, SDKs Azure ou o portal Azure.

Pré-requisitos

• Um serviço Azure AI Search (qualquer nível). Crie um serviço ou encontre um existente.

• Um índice de pesquisa existente. Este artigo assume que já criou um índice. Se precisares de criar e carregar numa só etapa, usa o assistente de importação ou um indexador.

• Permissões para carregar documentos:

  • Autenticação baseada em chaves: Uma chave API de administrador para o seu serviço de pesquisa.
  • Autenticação baseada em funções: Papel de Contribuidor de Dados de Índice de Pesquisa no serviço de pesquisa.

• Para desenvolvimento de SDK, instale a biblioteca cliente Azure Search:

  • .NET: Azure.Search.Documents
  • Python: azure-search-documents
  • JavaScript: @azure/search-documents
  • Java: azure-search-documents

Utilizar o portal do Azure

No portal Azure, use o assistente de importação para criar e carregar índices num fluxo de trabalho fluido. Se quiser carregar um índice existente, escolha uma abordagem alternativa.

1. Vá para o seu serviço de pesquisa no portal do Azure.

2. Na página de Visão Geral , selecione Importar dados na barra de comandos para criar e preencher um índice de pesquisa.

   

   Você pode seguir estes links para revisar o fluxo de trabalho: Guia de início rápido: criar um índice de pesquisa de IA do Azure e Guia de início rápido: vetorização integrada.

3. Após a conclusão do assistente, use o Search Explorer para verificar os resultados.

Utilizar APIs REST

Documentos - Índice é a API REST para importar dados para um índice de pesquisa.

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.

As APIs REST são úteis para testes iniciais de prova de conceito, onde você pode testar fluxos de trabalho de indexação sem precisar escrever muito código. O @search.action parâmetro determina se os documentos são adicionados na íntegra ou parcialmente em termos de valores novos ou de substituição para campos específicos.

Guia de início rápido: a pesquisa de texto completo usando REST explica as etapas. O exemplo a seguir é uma versão modificada do exemplo. O valor é cortado para maior brevidade e o primeiro valor HotelId é alterado para evitar a substituição de um documento existente.

1. Formule uma chamada POST especificando o nome do índice, o ponto de extremidade "docs/index" e um corpo de solicitação que inclua o @search.action parâmetro.

   POST https://[service name].search.windows.net/indexes/hotels-sample/docs/index?api-version=2025-09-01
   Content-Type: application/json   
   api-key: [admin key] 
   {
       "value": [
       {
       "@search.action": "upload",
       "HotelId": "1111",
       "HotelName": "Stay-Kay City Hotel",
       "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.",
       "Category": "Boutique",
       "Tags": [ "pool", "air conditioning", "concierge" ]
       },
       {
       "@search.action": "mergeOrUpload",
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "This is description is replacing the original one for this hotel. New and changed values overwrite the previous ones. In a comma-delimited list like Tags, be sure to provide the full list because there is no merging of values within the field itself.",
       "Category": "Boutique",
       "Tags": [ "pool", "free wifi", "concierge", "my first new tag", "my second new tag" ]
       }
     ]
   }
   

2. Defina o @search.action parâmetro como upload para criar ou substituir um documento. Defina-o como merge ou uploadOrMerge se você estiver direcionando atualizações para campos específicos dentro do documento. O exemplo anterior mostra ambas as ações.

   Ação	Efeito
   carregamento	Semelhante ao conceito de "upsert", em que o documento é inserido se for novo e, se já existir, é atualizado ou substituído por uma versão nova. Se o documento estiver faltando valores que o índice exige, o valor do campo do documento é definido como null.
   intercalação	Atualiza um documento que já existe e falha em um documento que não pode ser encontrado. A mesclagem substitui os valores existentes. Por esse motivo, certifique-se de verificar se há campos de coleta que contenham vários valores, como campos do tipo Collection(Edm.String). Por exemplo, se um tags campo começar com um valor de ["budget"] e você executar uma mesclagem com ["economy", "pool"], o valor final do tags campo será ["economy", "pool"]. Não é ["budget", "economy", "pool"].
   mesclarOuCarregar	Comporta-se como mesclar se o documento existir e carregar se o documento for novo. Esta é a ação mais comum para atualizações incrementais.
   eliminar	Delete remove o documento especificado do índice. Qualquer campo especificado em uma operação de exclusão, diferente do campo chave, é ignorado. Se você quiser remover um campo individual de um documento, use mesclar em vez disso e defina o campo explicitamente como nulo. Para mais informações, consulte Eliminar documentos num índice de pesquisa.

   Não há garantias de ordenação quanto a qual 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.

   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"]. Não é ["orçamento", "economia", "conjunto de recursos"].

   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ê executar uma mesclagem com um valor de [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], o valor final do campo Rooms será [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Não será nenhum dos seguintes:

   • [{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] (acrescentar elementos)

   • [{ "Tipo": "Quarto Standard", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60.5 }] (mesclar elementos em ordem e, em seguida, anexar quaisquer extras)

   Observação

   Quando você carrega valores DateTimeOffset com informações de fuso horário em seu índice, o Azure AI Search normaliza esses valores para UTC. Por exemplo, 2025-01-13T14:03:00-08:00 será armazenado como 2025-01-13T22:03:00Z. Se precisar armazenar informações de fuso horário, adicione uma coluna extra ao índice.

3. Envie o pedido.

   A tabela a seguir explica os vários códigos de status por documento que podem ser retornados na resposta. Alguns códigos de status indicam problemas com a própria solicitação, enquanto outros indicam condições de erro temporárias. Este último você deve tentar novamente após um atraso.

   Código de estado	Meaning	Repetível	Observações
   200	O documento foi modificado ou eliminado com êxito.	não aplicável	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 resulta em um código de status 200.
   201	O documento foi criado com sucesso.	não aplicável
   400	Ocorreu um erro no documento que o impediu de ser indexado.	Não	A mensagem de erro na resposta indica o que está errado com o documento.
   404	O documento não pôde ser mesclado porque a chave fornecida não existe no índice.	Não	Este erro não ocorre para 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
   429	Indica que você excedeu sua cota no número de documentos por índice.	Não	Você deve criar um novo índice ou atualizar para limites de capacidade mais altos.
   503	O seu serviço de pesquisa está temporariamente indisponível, possivelmente devido a carga pesada.	Yes	Neste caso, o seu código deve aguardar antes de tentar de novo ou arrisca prolongar a indisponibilidade do serviço.

   Observação

   Se o código do cliente encontrar frequentemente uma resposta 207, uma possível razão é que o sistema está sob carga. Você pode confirmar isso verificando a statusCode propriedade para 503. Se esse for o caso, recomendamos limitar as solicitações de indexação. Caso contrário, se o tráfego de indexação não diminuir, o sistema poderá começar a rejeitar todas as solicitações com erros 503.

4. Procure os documentos que acabou de adicionar como passo de validação:

   GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2025-09-01
   

Referência:Documentos - Índice, Documentos - Obter

Um pedido de índice bem-sucedido retorna HTTP 200 (OK) para um lote onde todos os documentos tiveram sucesso, ou HTTP 207 (Multi-Estado) se alguns documentos falharam. O corpo de resposta contém o estado de cada documento:

{
    "value": [
        { "key": "1111", "status": true, "statusCode": 201 },
        { "key": "2", "status": true, "statusCode": 200 }
    ]
}

Quando a chave ou ID do documento é nova, null torna-se o valor de qualquer campo não especificado no documento. Para ações em um documento existente, os valores atualizados substituem os valores anteriores. Todos os campos que não foram especificados em "merge" ou "mergeUpload" são deixados intactos no índice de pesquisa.

Usar os SDKs do Azure

A programação é fornecida nos seguintes SDKs do Azure.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Create the search client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample";
string apiKey = "<your-admin-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.windows.net");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Define documents to upload
var documents = new[]
{
    new { HotelId = "1111", HotelName = "Stay-Kay City Hotel", Category = "Boutique" },
    new { HotelId = "1112", HotelName = "Old Century Hotel", Category = "Luxury" }
};

// Upload documents
IndexDocumentsResult result = await searchClient.IndexDocumentsAsync(
    IndexDocumentsBatch.Upload(documents));

Console.WriteLine($"Uploaded {result.Results.Count} documents");

Verifique a carga de dados

Após carregar os documentos, verifique se os dados estão corretamente indexados.

GET https://[service-name].search.windows.net/indexes/hotels-sample/docs/1111?api-version=2025-09-01
api-key: [admin-key]

// Verify document was indexed
var document = await searchClient.GetDocumentAsync<Hotel>("1111");
Console.WriteLine($"Found: {document.Value.HotelName}");

Como funciona a importação de dados

Um serviço de pesquisa aceita documentos JSON que estão em conformidade com o esquema de índice. Um serviço de pesquisa pode importar e indexar conteúdo de texto sem formatação e conteúdo vetorial em documentos JSON.

• O conteúdo de texto sem formatação é recuperado de campos na fonte de dados externa, de propriedades de metadados ou de conteúdo enriquecido gerado por um conjunto de habilidades. As habilidades podem extrair ou inferir descrições textuais a partir de imagens e conteúdo não estruturado.

• O conteúdo vetorial é recuperado de uma fonte de dados que o fornece ou é criado por um conjunto de habilidades que implementa vetorização integrada em uma carga de trabalho do indexador do Azure AI Search.

Pode preparar estes documentos você mesmo, mas se o conteúdo residir numa fonte de dados suportada, correr um indexador ou usar o assistente de importação pode automatizar a recuperação de documentos, serialização JSON e indexação.

Uma vez que os dados são indexados, as estruturas de dados físicas do índice são bloqueadas. Para obter orientação sobre o que pode e o que não pode ser alterado, consulte Atualizar e reconstruir um índice.

A indexação não é um processo em segundo plano. Um serviço de pesquisa equilibra a indexação e as cargas de trabalho de consulta, mas se a latência da consulta for muito alta, você poderá adicionar capacidade ou identificar períodos de baixa atividade de consulta para carregar um índice.

Para obter mais informações, consulte Estratégias de importação de dados.

Solucionar erros comuns