Executar ou redefinir indexadores, habilidades ou documentos

No Azure AI Search, há várias maneiras de executar um indexador:

• Execute imediatamente após a criação do indexador. Esse é o padrão, a menos que você crie o indexador em um estado "desabilitado".
• Executar em um agendamento para invocar a execução em intervalos regulares.
• Execute sob demanda, com ou sem uma "redefinição".

Este artigo explica como executar indexadores sob demanda, com e sem uma redefinição. Ele também descreve a execução, a duração e a simultaneidade do indexador.

Como os indexadores se conectam aos recursos do Azure

Os indexadores são um dos poucos subsistemas que fazem chamadas externas diretas para outros recursos do Azure. Dependendo da fonte de dados externa, você pode usar chaves ou funções para autenticar a conexão.

Em termos de funções do Azure, os indexadores não têm identidades separadas: uma conexão do mecanismo de pesquisa com outro recurso do Azure é feita usando o sistema ou a identidade gerenciada atribuída pelo usuário de um serviço de pesquisa, além de uma atribuição de função no recurso do Azure de destino. Se o indexador se conectar a um recurso do Azure em uma rede virtual, você deverá criar um link privado compartilhado para essa conexão.

Execução do indexador

Um serviço de pesquisa executa um trabalho de indexador por unidade de pesquisa. Cada serviço de pesquisa começa com uma unidade de pesquisa, mas cada nova partição ou réplica aumenta as unidades de pesquisa do serviço. Você pode verificar a contagem das unidades de pesquisa na seção Essential do portal do Azure da página Visão geral. Se você precisar de processamento simultâneo, verifique se suas unidades de pesquisa incluem réplicas suficientes. Os indexadores não são executados em segundo plano, portanto, você poderá experimentar mais limitação de consulta do que o normal se o serviço estiver sob pressão.

A captura de tela a seguir mostra o número de unidades de pesquisa, que determina quantos indexadores podem ser executados ao mesmo tempo.

Depois que a execução do indexador for iniciada, você não poderá pausá-la ou interrompê-la. A execução do indexador é interrompida quando não há mais documentos para carregar ou atualizar ou quando o limite de tempo de execução é atingido.

Você pode executar vários indexadores ao mesmo tempo se tiver capacidade suficiente, mas cada indexador em si é de instância única. Iniciar uma nova instância enquanto o indexador já está na execução gera este erro: "Failed to run indexer "<indexer name>" error: "Another indexer invocation is currently in progress; concurrent invocations are not allowed."

Ambiente de execução do indexador

Um trabalho de indexador é executado em um ambiente de execução gerenciada. Atualmente, há dois ambientes:

• Um ambiente de execução privada é executado em clusters de pesquisa específicos para seu serviço de pesquisa.

• Um ambiente multilocatário tem processadores de conteúdo gerenciados e protegidos pela Microsoft sem custo adicional. Esse ambiente é usado para descarregar o processamento computacionalmente intensivo, deixando os recursos específicos do serviço disponíveis para operações de rotina. Sempre que possível, a maioria dos conjuntos de habilidades é executada no ambiente multilocatário. Esse é o padrão.

  Processamento computacionalmente intensivo refere-se a conjuntos de habilidades executados em processadores de conteúdo e trabalhos de indexador que processam um grande volume de documentos ou documentos de tamanho grande. O processamento de conjunto de habilidades nos processadores de conteúdo multilocatário é determinado pela heurística e pelas informações do sistema e não está sob controle do cliente.

Você poderá impedir o uso do ambiente multilocatário em serviços Standard2 ou superior fixando um indexador e um processamento de conjunto de habilidades exclusivamente em seus clusters de pesquisa. Defina o executionEnvironment parâmetro na definição do indexador para sempre executar um indexador no ambiente de execução privada.

Os firewalls de IP bloqueiam o ambiente multilocatário, portanto, se você tiver um firewall, crie uma regra que permita conexões de processador multilocatário.

Os limites do indexador variam para cada ambiente:

¹ As unidades de pesquisa podem ser combinações flexíveis de partições e réplicas, mas os trabalhos do indexador não estão vinculados a um ou outro. Em outras palavras, se você tiver 12 unidades, poderá ter 12 trabalhos de indexador em execução simultaneamente em execução privada, independentemente de como as unidades de pesquisa são implantadas.

² Se forem necessárias mais de duas horas para processar todos os dados, habilite a detecção de alterações e agende o indexador a ser executado em intervalos de 5 minutos para retomar a indexação rapidamente se ele parar devido a um tempo limite. Consulte Indexação de um conjunto de dados grande para obter mais estratégias.

³ "Indeterminado" significa que o limite não é quantificado pelo número de trabalhos. Algumas cargas de trabalho, como o processamento de conjunto de habilidades, podem ser executadas em paralelo, o que pode resultar em muitos trabalhos, embora apenas um indexador esteja envolvido. Embora o ambiente não imponha restrições, os limites do indexador para o serviço de pesquisa ainda se aplicam.

Executar sem redefinição

Uma operação Executar Indexador detecta e processa apenas o que é necessário para sincronizar o índice de pesquisa com alterações na fonte de dados subjacente. A indexação incremental começa localizando uma marca d'água alta interna para localizar o último documento de pesquisa atualizado, que se torna o ponto de partida para a execução do indexador em documentos novos e atualizados na fonte de dados.

A detecção de alterações é essencial para determinar o que é novo ou atualizado na fonte de dados. Os indexadores usam os recursos de detecção de alteração da fonte de dados subjacente para determinar o que há de novo ou atualizado na fonte de dados.

• O Armazenamento Azure possui detecção interna de alterações através da propriedade LastModified.

• Outras fontes de dados, como o SQL do Azure ou o Azure Cosmos DB, precisam ser configuradas para detecção de alteração para que o indexador possa ler apenas as linhas novas e atualizadas.

Se o conteúdo subjacente não for alterado, uma operação de execução não terá efeito. Nesse caso, o histórico de execução do indexador indica 0\0 documentos processados.

Você precisa redefinir o indexador, conforme explicado na próxima seção, para reprocessar na íntegra.

Redefinindo indexadores

Após a execução inicial, um indexador mantém o controle de quais documentos de pesquisa são indexados por meio de uma marca d'água alta interna. O marcador nunca é exposto, mas internamente o indexador sabe onde parou pela última vez.

Se você precisar redefinir todo ou parte de um índice, use as APIs de Redefinição disponíveis em níveis decrescentes na hierarquia de objetos.

• Redefinir Indexadores limpa a marca d'água alta e executa uma reindexação completa de todos os documentos
• Os indexadores ressincronizadores (versão prévia) executam um reindex parcial eficiente de todos os documentos
• Reiniciar Documentos (pré-visualização) reindexa um documento específico ou uma lista de documentos
• Redefinir Habilidades (versão prévia) invoca o processamento de uma habilidade específica

Após a redefinição, siga com um comando Executar para reprocessar documentos novos e existentes. Documentos de pesquisa órfãos sem correspondência na fonte de dados não podem ser removidos por meio de redefinição/execução. Se você precisar excluir documentos, confira Documentos – Indexar em vez disso.

Como redefinir e executar indexadores

Redefinir limpa a marca d'água alta. Todos os documentos no índice de pesquisa são sinalizados para substituição completa, sem atualizações embutidas ou mesclagem em conteúdo existente. Para indexadores com um conjunto de habilidades e cache de enriquecimento, redefinir o índice também redefine implicitamente o conjunto de habilidades.

O trabalho real ocorre quando você segue uma redefinição com um comando de Execução:

• Todos os novos documentos encontrados na fonte subjacente são adicionados ao índice de pesquisa.
• Todos os documentos que existem na fonte de dados e no índice de pesquisa são substituídos no índice de pesquisa.
• Qualquer conteúdo enriquecido criado a partir de conjuntos de habilidades é recriado. O cache de enriquecimento, se habilitado, será atualizado.

Como observado anteriormente, a redefinição é uma operação passiva: você deve seguir com uma solicitação Executar para recompilar o índice.

As operações de redefinição/execução se aplicam a um índice de pesquisa ou a um repositório de conhecimento, a projeções ou documentos específicos e a aprimoramentos em cache, se uma redefinição incluir habilidades explícita ou implicitamente.

A redefinição também se aplica às operações de criação e atualização. Isso não acionará a exclusão nem a limpeza de documentos órfãos no índice de pesquisa. Para obter mais informações sobre como excluir documentos, confira Documentos – Índice.

Depois de redefinir um indexador, não é possível desfazer a ação.

POST /indexers/[indexer name]/reset?api-version=[api-version]

POST /indexers/[indexer name]/run?api-version=[api-version]

GET /indexers/[indexer name]/status?api-version=[api-version]

// Reset the indexer if it already exists
try
{
    await indexerClient.GetIndexerAsync(blobIndexer.Name);
    //Rest the indexer if it exsits.
    await indexerClient.ResetIndexerAsync(blobIndexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 404) { }

await indexerClient.CreateOrUpdateIndexerAsync(blobIndexer);

// Run indexer
Console.WriteLine("Running Blob Storage indexer...\n");

try
{
    await indexerClient.RunIndexerAsync(blobIndexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 429)
{
    Console.WriteLine("Failed to run indexer: {0}", ex.Message);
}

Como redefinir habilidades (versão prévia)

Para indexadores que têm conjuntos de habilidades, você pode redefinir habilidades individuais para forçar o processamento dessa habilidade e das habilidades de downstream dependentes da saída. O cache de enriquecimento, se habilitado, também será atualizado.

Atualmente, Redefinição de Habilidades está disponível apenas através de REST, acessível na versão 2020-06-30-preview ou posterior. Recomendamos a API de versão prévia mais recente.

POST /skillsets/[skillset name]/resetskills?api-version=2024-05-01-preview
{
    "skillNames" : [
        "#1",
        "#5",
        "#6"
    ]
}

Você pode especificar habilidades individuais, conforme indicado no exemplo acima, mas se qualquer uma dessas habilidades exigir a saída de habilidades não listadas (#2 por meio de #4), as habilidades não listadas serão executadas, a menos que o cache possa fornecer as informações necessárias. Para que isso seja verdadeiro, os aprimoramentos em cache para as habilidades #2 até #4 não devem ter dependência na habilidade #1, que está listada para ser redefinida.

Se nenhuma habilidade for especificada, o conjunto de habilidades inteiro será executado e, se o cache estiver habilitado, o cache também será atualizado.

Lembre-se de acompanhar Executar Indexador para invocar o processamento real.

Como redefinir documentos (versão prévia)

O serviço Indexadores – Redefinir Documentos aceita uma lista de chaves de documento para que você possa atualizar documentos específicos. Se especificado, os parâmetros de redefinição se tornarão o único determinante do que é processado, independentemente de outras alterações nos dados subjacentes. Por exemplo, se 20 blobs foram adicionados ou atualizados desde a última execução do indexador, mas você redefinir apenas um documento, apenas esse documento será processado.

Por documento, todos os campos no documento de pesquisa são atualizados com valores e metadados da fonte de dados. Você não pode escolher quais campos atualizar.

Se a fonte de dados for o Armazenamento do Azure Data Lake (ADLS) Gen2, e os blobs estiverem associados a metadados de permissão, essas permissões também serão reingeridas no índice de pesquisa se forem alteradas nos dados subjacentes. Para obter mais informações, veja Reindexação do escopo da ACL e do RBAC com indexadores do ADLS Gen2.

Se o documento for enriquecido por meio de um conjunto de habilidades e tiver dados armazenados em cache, o conjunto de habilidades será invocado apenas para os documentos especificados e o cache será atualizado para os documentos reprocessados.

Quando você estiver testando esta API pela primeira vez, as seguintes APIs podem ajudar a validar e testar os comportamentos. Você pode usar a API de versão prévia de 30/06/2020 e posterior. Recomendamos a API de versão prévia mais recente.

1. Chame o serviço Indexadores – Obter Status com uma API de versão prévia para verificar o status da redefinição e o status da execução. Você pode encontrar informações sobre a solicitação de redefinição no final da resposta de status.

2. Chame o serviço Indexadores – Redefinir Documentos com uma API de versão prévia para especificar quais documentos processar.

   POST https://[service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2024-05-01-preview
   {
       "documentKeys" : [
           "1001",
           "4452"
       ]
   }
   

   • As chaves de documento fornecidas na solicitação são valores do índice de pesquisa, que podem ser diferentes dos campos correspondentes na fonte de dados. Se você não tiver certeza do valor da chave, envie uma consulta para retornar o valor. Você pode usar select para retornar apenas o campo-chave do documento.

   • Para blobs que são analisados em vários documentos de pesquisa (onde parsingMode está configurado para jsonLines ou jsonArrays, ou delimitedText), a chave do documento é gerada pelo indexador e pode ser desconhecida para você. Nesse cenário, uma consulta para a chave do documento para retornar o valor correto.

3. Chame Executar Indexador (qualquer versão de API) para processar os documentos especificados. Somente esses documentos específicos são indexados.

4. Chame Executar Indexador pela segunda vez para processar na última marca d'água alta.

5. Chame Pesquisar Documentos para verificar os valores atualizados e também para retornar as chaves do documento se não tiver certeza do valor. Use "select": "<field names>" se você quiser limitar quais campos aparecem na resposta.

Substituição da lista de chaves do documento

Chamar Redefinir Documentos com a API várias vezes usando diferentes chaves acrescenta as novas chaves à lista de chaves de documento redefinidas. Chamar a API com o parâmetro overwrite definido como true substituirá a lista atual pela nova:

POST https://[service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2020-06-30-Preview
{
    "documentKeys" : [
        "200",
        "630"
    ],
    "overwrite": true
}

Como ressincronizar indexadores (versão prévia)

O Resync Indexers é uma API REST de visualização que executa um reindex parcial de todos os documentos. Um indexador é considerado sincronizado com sua fonte de dados quando campos específicos de todos os documentos no índice de destino são consistentes com os dados na fonte de dados. Normalmente, um indexador obtém a sincronização após uma execução inicial bem-sucedida. Se um documento for excluído da fonte de dados, o indexador permanecerá sincronizado de acordo com essa definição. No entanto, durante a próxima execução do indexador, o documento correspondente no índice de destino será removido se o controle de exclusão estiver habilitado.

Se um documento for modificado na fonte de dados, o indexador ficará não sincronizado. Em geral, os mecanismos de controle de alterações ressincronizarão o indexador durante a próxima execução. Por exemplo, no Armazenamento do Azure, modificar um blob atualiza sua última data de modificação, permitindo que ele seja reindexado na próxima execução do indexador porque o tempo atualizado supera o marco superior definido pela execução anterior.

Por outro lado, para determinadas fontes de dados, como o ADLS Gen2, alterar as ACLs (listas de controle de acesso) de um blob não altera o último tempo modificado, renderizando o controle de alterações ineficaz se as ACLs forem ingeridas. Consequentemente, o blob modificado não será indexado novamente na execução seguinte, pois somente os documentos modificados após a última marca d’água alta são processados.

Embora o uso de “redefinir” ou “redefinir documentos” possa resolver esse problema, a opção “redefinir” pode ser demorada e ineficiente para grandes conjuntos de dados e “redefinir documentos” exige a identificação da chave do documento do blob destinado à atualização.

Os indexadores ressincronizadores oferecem uma alternativa eficiente e conveniente. Os usuários simplesmente colocam o indexador no modo ressincronizador e especificam o conteúdo a ser ressincronizado chamando a API de indexadores ressincronizadores. Na próxima execução, o indexador inspecionará apenas a parte relevante dos dados na origem e evitará qualquer processamento desnecessário que não esteja relacionado aos dados especificados. Ele também consultará os documentos existentes no índice de destino e atualizará apenas os documentos que mostram discrepâncias entre a fonte de dados e o índice de destino. Após a execução de ressincronização, o indexador será sincronizado e revertido para o modo de execução regular do indexador para execuções subsequentes.

Como ressincronizar e executar indexadores

1. Chamar Indexadores – Ressincronizar com uma versão prévia da API para especificar qual conteúdo sincronizar novamente.

   POST https://[service name].search.windows.net/indexers/[indexer name]/resync?api-version=2025-08-01-preview
   {
       "options" : [
           "permissions"
       ]
   }
   

   • O campo options é obrigatório. Atualmente, a única opção com suporte é permissions. Ou seja, somente os campos de filtro de permissão no índice de destino serão atualizados.

2. Chame o Run Indexer (qualquer versão da API) para sincronizar novamente o indexador.

3. Chame Executar Indexador pela segunda vez para processar na última marca d'água alta.

Verificar o status de redefinição "currentState"

Para verificar o status de restauração e ver quais chaves do documento estão na fila para processamento, siga estas etapas.

1. Chame Obter Status do Indexador com uma API de versão prévia.

   A API em versão prévia retornará a seção currentState, encontrada no final da resposta.

   "currentState": {
       "mode": "indexingResetDocs",
       "allDocsInitialTrackingState": "{\"LastFullEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"LastAttemptedEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"NameHighWaterMark\":null}",
       "allDocsFinalTrackingState": "{\"LastFullEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"LastAttemptedEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"NameHighWaterMark\":null}",
       "resetDocsInitialTrackingState": null,
       "resetDocsFinalTrackingState": null,
       "resyncInitialTrackingState": null,
       "resyncFinalTrackingState": null,
       "resetDocumentKeys": [
           "200",
           "630"
       ]
   }
   

2. Verifique o "modo":

   Para Redefinir Conjuntos de Habilidades, o "modo" deve ser definido como indexingAllDocs (porque possivelmente todos os documentos serão afetados, em termos dos campos preenchidos por meio do enriquecimento de IA).

   Para indexadores ressincronizadores, o "modo" deve ser definido como indexingResync. O indexador verifica todos os documentos e se concentra nos dados interessados na fonte de dados e nos campos interessados no índice de destino.

   Para Redefinir Documentos, o "mode" deve ser definido como indexingResetDocs. O indexador retém esse status até que todas as chaves do documento fornecidas na chamada Redefinir Documentos sejam processadas. Durante esse tempo, nenhum outro trabalho do indexador será executado enquanto a operação estiver em andamento. Localizar todos os documentos na lista de chaves do documento requer a quebra de cada documento para localizar e corresponder à chave, e isso pode levar algum tempo se o conjunto de dados for grande. Se um contêiner de blobs contiver centenas de blobs e os documentos que você deseja restaurar estiverem no final, o indexador não encontrará os blobs correspondentes até que todos os outros tenham sido verificados primeiro.

3. Depois que os documentos forem reprocessados, execute Obter Status do Indexador novamente. O indexador voltará ao modo indexingAllDocs e processará os documentos novos ou atualizados na próxima execução.

Verificar a cota de runtime do indexador para serviços de pesquisa de HD S3

Aplica-se aos serviços de pesquisa no tipo de preço S3 HD (Alta Densidade) Standard 3.

Para ajudá-lo a monitorar os tempos de execução do indexador em relação à janela de 24 horas, Obter Estatísticas de Serviço e Obter Status do Indexador agora retornará mais informações na resposta.

Acompanhar a cota de runtime cumulativo

Acompanhe o uso cumulativo de runtime do indexador de um serviço de pesquisa e determine quanto de cota de runtime é deixada dentro do período de janela atual de 24 horas.

Envie uma solicitação GET para o provedor de recursos do serviço de pesquisa. Para obter ajuda com a configuração de um cliente REST e a obtenção de um token de acesso, consulte Conectar-se a um serviço de pesquisa.

GET {{search-endpoint}}/servicestats?api-version=2025-08-01-preview 
  Content-Type: application/json
  Authorization: Bearer {{accessToken}}

As respostas incluem indexersRuntime propriedades, mostrando horários de início e término, segundos usados, segundos restantes e runtime cumulativo nas últimas 24 horas.

Acompanhar a cota de runtime do indexador

Retorne as mesmas informações para um único indexador.

GET {{search-endpoint}}/indexers/hotels-sample-indexer/search.status?api-version=2025-08-01-preview 
  Content-Type: application/json
  Authorization: Bearer {{accessToken}}

As respostas incluem propriedades runtime , mostrando horários de início e término, segundos usados e segundos restantes.

Próximas etapas

As APIs de redefinição são usadas para informar o escopo da próxima execução do indexador. Para o processamento real, você precisará invocar uma execução de indexador sob demanda ou permitir que um trabalho agendado conclua o trabalho. Depois que a execução for concluída, o indexador retornará ao processamento normal, independentemente de estar em um agendamento ou em um processamento sob demanda.

Depois de redefinir e executar novamente os trabalhos do indexador, você pode monitorar o status do serviço de pesquisa ou obter informações detalhadas por meio do log de recurso.

• Monitorar o status do indexador de pesquisa
• Coletar e analisar dados de log
• Agendar um indexador