Carregar dados em um índice de pesquisa no Pesquisa de IA do Azure 

Este artigo explica como importar documentos para um índice de pesquisa predefinido usando APIs REST, SDKs do Azure ou o portal do Azure.

Pré-requisitos

• Um serviço do Pesquisa de IA do Azure  (qualquer camada). Criar um serviço ou localizar um serviço existente.

• Um índice de pesquisa existente. Este artigo pressupõe que você já criou um índice. Se você precisar criar e carregar em uma etapa, use o assistente de importação ou um indexador.

• Permissões para carregar documentos:

  • Autenticação baseada em chave: uma chave de API de administrador para seu serviço de pesquisa.
  • Autenticação baseada em função: Colaborador de Dados de Índice de Pesquisa no serviço de pesquisa.

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

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

Use o Portal do Azure

No portal do Azure, use o assistente de importação para criar e carregar índices em um fluxo de trabalho contínuo. Caso deseje carregar um índice existente, escolha uma abordagem alternativa.

1. Acesse seu serviço de pesquisa no portal do Azure.

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

   

   Você pode seguir esses links para revisar o fluxo de trabalho: Início Rápido: criar um índice do IA do Azure Search e Início rápido: vetorização integrada.

3. Após a conclusão do assistente, use o Gerenciador de Pesquisa para verificar os resultados.

Usar as APIs REST

Documents - Index é a API REST para importação de dados para um índice de pesquisa.

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.

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

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 é reduzido para resumir e o valor inicial de HotelId é alterado para evitar a sobreposição de um documento existente.

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

   POST https://[service name].search.windows.net/indexes/hotels-sample/docs/index?api-version=2026-04-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 parâmetro @search.action como upload para criar ou substituir um documento. Defina-o como merge ou uploadOrMerge se estiver direcionando atualizações para campos específicos dentro do documento. O exemplo anterior mostra ambas as ações.

   Ação	Efeito
   carregamento	Semelhante a um "upsert" onde o documento é inserido se for novo e atualizado ou substituído se existir. Se o documento tiver valores ausentes que o índice requer, o valor do campo do documento será definido como nulo.
   merge	Atualiza um documento que já existe e reprova um documento que não pode ser encontrado. Merge substitui os valores existentes. Por esse motivo, verifique se há campos de coleção que contêm vários valores, como campos do tipo Collection(Edm.String). Por exemplo, se um campo tags começar com um valor de ["budget"] e você executar uma mesclagem com ["economy", "pool"], o valor final do campo tags será ["economy", "pool"]. Não é ["budget", "economy", "pool"].
   mergeOrUpload	Comporta-se como mesclar se o documento existir e fazer upload se o documento for novo. Essa é a ação mais comum para atualizações incrementais.
   excluir	Excluir remove o documento especificado do índice. Qualquer campo especificado em uma operação de exclusão, diferente do campo de chave, é ignorado. Se você desejar remover um campo individual de um documento, use a mesclagem e defina o campo explicitamente como nulo. Para obter mais informações, consulte Excluir documentos em um índice de pesquisa.

   Não há garantias de ordenação para as quais a ação no corpo da solicitação é executada primeiro. Não é recomendável ter várias ações "mesclar" associadas ao mesmo documento em apenas um corpo de solicitação. Se houver várias ações "mesclar" 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 ["budget"], e você executar uma mensagem com um valor ["economy", "pool"] para Tags, o valor final do campo Tags será ["economy", "pool"]. Não será ["budget", "economy", "pool"].

   Em coleções complexas, se o documento contiver um campo de coleção complexo chamado Salas 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 }]. 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 extras)

   Observação

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

3. Enviar a solicitação.

   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 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	Meaning	Com nova tentativa	Anotações
   200	O documento foi modificado ou excluído com êxito.	n/a	As operações de exclusão são idempotentes. Ou seja, mesmo se não existir uma chave de documento no índice, a tentativa de uma operação de exclusão com essa chave resulta em um código de status 200.
   201	O documento foi criado com êxito.	n/a
   400	Ocorreu um erro no documento que o impediu de ser indexado.	Não	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 especificada não existe no índice.	Não	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
   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 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 statusCode propriedade para 503. Se esse for o caso, recomendamos a limitação das 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.

4. Procure os documentos que você acabou de adicionar como uma etapa de validação:

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

Reference:Documents - Index, Documents - Get

Uma solicitação de índice bem-sucedida retorna HTTP 200 (OK) para um lote em que todos os documentos foram bem-sucedidos ou HTTP 207 (Multi-Status) se alguns documentos falharam. O corpo da resposta contém o status de cada documento:

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

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

Use 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 sua carga de dados

Depois de carregar documentos, verifique se os dados estão indexados corretamente.

GET https://[service-name].search.windows.net/indexes/hotels-sample/docs/1111?api-version=2026-04-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 um conteúdo de texto sem formatação e um conteúdo de vetor 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 de imagens e conteúdo não estruturado.

• O conteúdo do vetor é recuperado de uma fonte de dados que o fornece ou é criado por um conjunto de habilidades que implementa a vetorização integrada em uma carga de trabalho do indexador da Pesquisa de IA do Azure.

Você pode preparar esses documentos por conta própria, mas se o conteúdo residir em uma fonte de dados com suporte, executar um indexador ou usar o assistente de importação poderá automatizar a recuperação de documentos, a serialização JSON e a indexação.

Depois que os dados são indexados, as estruturas de dados físicas do índice são bloqueadas. Para obter diretrizes sobre o que pode e o que não pode ser alterado, consulte Atualizar e recompilar um índice.

A indexação não é um processo em segundo plano. Um serviço de pesquisa equilibra cargas de trabalho de indexação e consulta, mas se a latência de 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