Indexar dados do Armazenamento de Blobs do Azure

O indexador de blob importa conteúdo de Armazenamento de Blobs do Azure e o torna pesquisável em Pesquisa de IA do Azure . O indexador recebe blobs em um único contêiner como entrada. A saída é um índice de pesquisa que armazena o conteúdo pesquisável e os metadados em campos individuais.

Este artigo usa as APIs REST do Serviço de Pesquisa para demonstrar como configurar e executar o indexador. No entanto, você também pode usar:

• Um pacote do SDK do Azure (qualquer versão)
• Assistente de importação de dados no portal do Azure

Pré-requisitos

• Armazenamento de Blobs do Azure, desempenho Standard (uso geral v2).

• As camadas de acesso incluem as camadas de acesso frequente, esporádico, frio e aos arquivos. Os indexadores podem recuperar blobs em camadas de acesso frequente, esporádico e frio.

• Blobs que fornecem conteúdo de texto e metadados. Se os blobs contiverem conteúdo binário ou texto não estruturado, considere adicionar enriquecimento de IA para processamento de imagem e linguagem natural. O conteúdo do blob não pode exceder os limites do indexador para seu tipo de preço.

  Os limites do indexador de blob abrangem o tamanho máximo do blob e o número de caracteres que Pesquisa de IA do Azure  extrai de um blob. Se você utilizar um skillset, o limite de entrada ou de serviço de cada habilidade será aplicado separadamente após a extração de conteúdo do documento.

• Uma configuração de rede com suporte e acesso a dados. No mínimo, você precisará de permissões de leitura no Armazenamento do Microsoft Azure. Uma cadeia de conexão de armazenamento que inclui uma chave de acesso dá acesso de leitura ao conteúdo de armazenamento. Se, em vez disso, você estiver usando logons e funções do Microsoft Entra, verifique se a identidade gerenciada do serviço de pesquisa tem permissões do Leitor de dados de Armazenamento de Blobs.

  Por padrão, a pesquisa e o armazenamento aceitam solicitações de endereços IP públicos. Se a segurança de rede não for uma preocupação imediata, você poderá indexar os dados de blob usando apenas a cadeia de conexão e as permissões de leitura. Quando estiver pronto para adicionar proteções de rede, consulte o Acesso do Indexador ao conteúdo protegido pelos recursos de segurança de rede do Azure para obter diretrizes sobre acesso a dados.

• Use um cliente REST para formular chamadas REST semelhantes às mostradas nesse artigo.

Tarefas com suporte

Você pode usar esse indexador para as seguintes tarefas:

• Indexação de dados e indexação incremental: o indexador pode indexar arquivos e metadados associados de contêineres e pastas de blob. Ele detecta arquivos e metadados novos e atualizados por meio da detecção de alterações interna. Você pode configurar a atualização de dados através de um agendamento ou sob demanda.

• Detecção de exclusão: o indexador pode detectar exclusões por meio de exclusão reversível ou metadados personalizados.

• IA aplicada por meio de conjuntos de habilidades: O indexador dá suporte total a conjuntos de habilidades. Esse suporte inclui os principais recursos, como a vetorização integrada, que adiciona agrupamento de dados e inserção.

• Modos de análise: o indexador dá suporte a modos de análise JSON se você quiser analisar matrizes ou linhas JSON em documentos de pesquisa individuais. Ele também dá suporte ao modo de análise Markdown.

• Compatibilidade com outros recursos: O indexador funciona perfeitamente com outros recursos do indexador, como sessões de depuração, cache do indexador para enriquecimentos incrementais (versão prévia) e repositório de conhecimento.

Formatos de documento com suporte

O indexador de blob pode extrair o texto dos seguintes formatos de documento:

• CSV (consulte Indexando BLOBs CSV)
• EML
• EPUB
• GZ
• HTML
• JSON (consulte Como indexar blobs JSON)
• KML (XML para representações geográficas)
• Markdown
• Formatos do Microsoft Office: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG (emails do Outlook) e XML (WORD XML 2003 e 2006)
• Abrir formatos de documento: ODT, ODS, ODP
• PDF
• Arquivos de texto sem formatação (consulte também Como indexar texto sem formatação)
• RTF
• XML
• ZIP

Determinar os blobs para indexação

Antes de configurar a indexação, examine os dados de origem para determinar se você precisa fazer alterações. Um indexador pode indexar o conteúdo de um contêiner por vez. Por padrão, o indexador processa todos os blobs no contêiner. Você tem várias opções para um processamento mais seletivo:

• Coloque os blobs em uma pasta virtual. Uma definição de fonte de dados do indexador inclui um query parâmetro que pode aceitar uma pasta virtual. Se você especificar uma pasta virtual, o indexador indexa apenas esses blobs na pasta.

• Inclua ou exclua blobs por tipo de arquivo. A lista de formatos de documento com suporte pode ajudar você a determinar os blobs a serem excluídos. Por exemplo, é útil excluir arquivos de imagem ou de áudio que não fornecem um texto pesquisável. Você controla essa funcionalidade por meio de configurações no indexador.

• Inclua ou exclua blobs arbitrários. Para ignorar um blob específico, adicione as seguintes propriedades e valores de metadados aos blobs no Armazenamento de Blobs do Azure. Quando um indexador encontrar essa propriedade, ele vai ignorar o blob ou o conteúdo dele na execução da indexação.

  Nome da propriedade	Valor da propriedade	Explanation
  AzureSearch_Skip	true	Instrui o indexador de blobs a ignorar o blob por completo. O indexador não tenta extrair metadados ou conteúdo. Essa propriedade é útil quando um blob específico falha repetidamente e interrompe o processo de indexação.
  AzureSearch_SkipContent	true	O indexador ignora o conteúdo e extrai apenas os metadados. Essa propriedade é equivalente à configuração "dataToExtract": "allMetadata" descrita nas definições de configuração, mas é aplicada especificamente a um blob.

Se você não configurar critérios de inclusão ou exclusão, o indexador relatará um blob inelegível como um erro e avançará. Se ocorrerem erros suficientes, o processamento poderá ser interrompido. Você pode especificar a tolerância a erros nas definições de configuração do indexador.

Um indexador normalmente cria um documento de pesquisa por blob, em que o conteúdo de texto e os metadados são capturados como campos pesquisáveis em um índice. Se os blobs são arquivos inteiros, você pode potencialmente analisá-los em vários documentos de pesquisa. Por exemplo, você pode analisar linhas em um arquivo CSV para criar um documento de pesquisa por linha.

Um documento composto ou inserido (como um arquivo ZIP, um documento do Word com um email do Outlook inserido contendo anexos ou ainda um arquivo .MSG com anexos) também é indexado como um documento individual. Por exemplo, todas as imagens extraídas dos anexos de um arquivo .MSG são retornadas no campo normalized_images. Se você tiver imagens, considere adicionar enriquecimento de IA para aproveitar ao máximo a pesquisa desse conteúdo.

O indexador extrai o conteúdo textual de um documento em um campo de cadeia de caracteres chamado content. Você também pode extrair metadados padrão e definidos pelo usuário.

Indexação dos metadados de blobs

Você pode indexar metadados de blob junto com o conteúdo. O indexador extrai propriedades de metadados e as armazena em campos de índice, o que é útil para criar filtros e consultas.

Defina campos em seu índice de pesquisa para as propriedades de metadados que você deseja capturar. Você não precisa definir todas as propriedades de metadados padrão ou personalizada disponíveis. Basta capturar as propriedades necessárias para seu aplicativo.

Atualmente, esse indexador não dá suporte à indexação de marcas de índice de blob.

Propriedades padrão de metadados de blob

Para metadados de blob padrão, defina campos em seu índice usando os mesmos nomes sublinhados. Para obter exemplos de definição de campo passo a passo, consulte Adicionar campos de pesquisa a um índice.

Para a configuração do indexador, incluindo a dataToExtract configuração que controla quais metadados extrair, consulte Configurar e executar o indexador de blob.

O indexador reconhece e pode mapear essas propriedades de metadados padrão se você definir campos correspondentes em seu índice:

• metadata_storage_name (Edm.String) é o nome do arquivo do blob. Por exemplo, se você tiver um blob /my-container/my-folder/subfolder/resume.pdf, o valor desse campo será resume.pdf.

• metadata_storage_path (Edm.String) é o URI completo do blob, incluindo a conta de armazenamento. Por exemplo, https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf. Use essa propriedade para incluir URLs de blob nos resultados da pesquisa para navegação ou atribuição de origem.

• metadata_storage_content_type (Edm.String) é o tipo de conteúdo especificado pelo código que você usou para carregar o blob. Por exemplo, application/octet-stream.

• metadata_storage_last_modified (Edm.DateTimeOffset) é o último carimbo de data/hora modificado do blob. Pesquisa de IA do Azure  usa esse carimbo de data/hora para identificar blobs alterados e evitar reindexar tudo após a indexação inicial.

• metadata_storage_size (Edm.Int64) é o tamanho do blob em bytes.

• metadata_storage_content_md5 (Edm.String) é o hash MD5 do conteúdo do blob, se disponível.

• metadata_storage_sas_token (Edm.String) é um token SAS temporário que as habilidades personalizadas podem usar para obter acesso ao blob. Não armazene esse token para uso posterior, pois ele pode expirar.

Metadados personalizados e específicos do conteúdo

Para metadados de blob personalizados ou definidos pelo usuário, defina um campo com exatamente o mesmo nome que a chave de metadados do blob. Por exemplo, se os blobs tiverem uma chave Sensitivity de metadados com valor High, defina um campo chamado Sensitivity de tipo Edm.String em seu índice.

Você também pode representar propriedades de metadados específicas para o formato de documento dos blobs que você está indexando. Para obter mais informações, consulte As propriedades de metadados de conteúdo.

Definir a fonte de dados

A definição da fonte de dados especifica os dados a serem indexados, as credenciais e as políticas para identificar alterações nos dados. Uma fonte de dados é definida como um recurso independente para que possa ser usada por vários indexadores.

1. Crie ou atualize uma fonte de dados para configurar sua definição:

   {
       "name" : "my-blob-datasource",
       "type" : "azureblob",
       "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
       "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
   }
   

2. Defina type como azureblob (obrigatório).

3. Defina credentials como uma cadeia de conexão do Armazenamento do Azure. A próxima seção descreve os formatos compatíveis.

4. Defina container como o contêiner de blob e use query para especificar quaisquer subpastas.

Você também pode incluir políticas de exclusão reversível em uma definição de fonte de dados se quiser que o indexador exclua um documento de pesquisa quando o documento de origem for sinalizado para exclusão.

Credenciais e cadeias de conexão com suporte

Os indexadores podem se conectar a um contêiner de blob usando as conexões a seguir.

Adicionar campos de pesquisa a um índice

Em um índice de pesquisa, adicione campos para aceitar o conteúdo e os metadados de seus blobs do Azure.

1. Crie ou atualize um índice para definir campos de pesquisa que armazenam o conteúdo e os metadados do blob:

   POST https://[service name].search.windows.net/indexes?api-version=2026-04-01
   {
       "name" : "my-search-index",
       "fields": [
           { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
           { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false },
           { "name": "metadata_storage_name", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
           { "name": "metadata_storage_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
           { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true },        
       ]
   }
   

2. Criar um campo de chave de documento ("key": true). Para conteúdo de blob, os melhores candidatos são propriedades de metadados.

   • metadata_storage_path (padrão) é o caminho completo para o objeto ou arquivo. O campo de chave (ID neste exemplo) é preenchido com valores de metadata_storage_path porque é o padrão.

   • metadata_storage_name só será utilizável se os nomes forem exclusivos. Caso deseje ter esse campo como a chave, mova "key": true para essa definição de campo.

   • Uma propriedade de metadados personalizada que você adiciona a blobs. Essa opção exige que o processo de carregamento de blob adicione essa propriedade de metadados a todos os blobs. Como a chave é uma propriedade necessária, todos os blobs que não têm um valor não são indexados. Se você usar uma propriedade de metadados personalizada como uma chave, evite fazer alterações nessa propriedade. Os indexadores adicionarão documentos duplicados para o mesmo blob se a propriedade de chave for alterada.

   As propriedades de metadados geralmente incluem caracteres, como / e -, que são inválidas para chaves de documento. No entanto, o indexador codifica automaticamente a propriedade de metadados principal, sem necessidade de configuração ou mapeamento de campo.

3. Adicione um campo content para armazenar o texto extraído de cada arquivo por meio da propriedade content do blob. Você não precisa usar esse nome, mas, ao usá-lo, pode aproveitar os mapeamentos de campo implícitos.

4. Adicione campos para propriedades de metadados padrão. O indexador pode ler propriedades de metadados personalizadas, de metadados padrão e de metadados específicas do conteúdo.

Configurar e executar o indexador de blob

Depois de criar o índice e a fonte de dados, crie o indexador. A configuração do indexador especifica as entradas, os parâmetros e as propriedades que controlam os comportamentos de runtime. Você também pode especificar as partes de um blob que serão indexadas.

1. Crie ou atualize um indexador dando um nome a ele e referenciando a fonte de dados e o índice de destino:

   POST https://[service name].search.windows.net/indexers?api-version=2026-04-01
   {
     "name" : "my-blob-indexer",
     "dataSourceName" : "my-blob-datasource",
     "targetIndexName" : "my-search-index",
     "parameters": {
         "batchSize": null,
         "maxFailedItems": null,
         "maxFailedItemsPerBatch": null,
         "configuration": {
             "indexedFileNameExtensions" : ".pdf,.docx",
             "excludedFileNameExtensions" : ".png,.jpeg",
             "dataToExtract": "contentAndMetadata",
             "parsingMode": "default"
         }
     },
     "schedule" : { },
     "fieldMappings" : [ ]
   }
   

2. Defina batchSize se o padrão (10 documentos) subutiliza ou sobrecarrega os recursos disponíveis. Os tamanhos de lote padrão são específicos da fonte de dados. A indexação de Blobs define o tamanho do lote em 10 documentos ao reconhecer o maior tamanho médio do documento.

3. Em configuration, controle quais blobs são indexados com base no tipo de arquivo ou deixe não especificados para recuperar todos os blobs.

   Em indexedFileNameExtensions, forneça uma lista separada por vírgula de extensões de arquivos (com um ponto à esquerda). Faça o mesmo para excludedFileNameExtensions indicar quais extensões o indexador deve ignorar. Se a mesma extensão estiver em ambas as listas, o indexador a excluirá da indexação.

4. Em configuration, defina dataToExtract para controlar quais partes dos blobs são indexadas:

   • contentAndMetadata especifica que o indexador indexa todos os metadados e conteúdo textual extraídos do blob. Esse é o valor padrão.

   • storageMetadata especifica que o indexador indexa apenas as propriedades de blob padrão e os metadados especificados pelo usuário.

   • allMetadata especifica que o indexador extrai o conteúdo do blob e indexa as propriedades padrão do blob, além dos metadados dos tipos de conteúdo encontrados.

   • Para obter uma lista completa das propriedades de metadados padrão disponíveis e seus tipos de campo, consulte Indexação de metadados de blob.

5. Em configuration, defina parsingMode. O modo de análise padrão é um documento de pesquisa por blob. Se os blobs forem texto sem formatação, você poderá obter melhor desempenho alternando para análise de texto sem formatação. Se você precisar de uma análise mais granular que mapeia blobs para vários documentos de pesquisa, especifique um modo diferente. Há suporte para análise um para muitos para blobs que consistem em:

   • Documentos JSON
   • Arquivos CSV

6. Especifique mapeamentos de campo se houver diferenças no nome ou tipo de campo, ou se você precisar de várias versões de um campo de origem no índice de pesquisa.

   Na indexação de blobs, frequentemente você pode omitir os mapeamentos de campo porque o indexador tem suporte interno para mapear content e as propriedades de metadados para campos em um índice que possuem nomes e tipos semelhantes. Para as propriedades de metadados, o indexador substitui automaticamente os hifens - por sublinhados no índice de pesquisa.

7. Confira Criar um indexador para obter mais informações sobre outras propriedades. Para obter a lista completa de descrições de parâmetro, confira a API REST.

Um indexador é executado automaticamente quando é criado. Você pode impedir essa ação definindo disabled como true. Para controlar a execução do indexador, execute um indexador sob demanda ou coloque-o em um agendamento.

Indexar dados de vários contêineres de Blob do Azure para um único índice

Lembre-se de que um indexador só pode indexar dados de um único contêiner. Se você precisar indexar dados de vários contêineres e consolidá-los em um único índice de Pesquisa de IA, configure vários indexadores que apontam para o mesmo índice. Lembre-se do número máximo de indexadores disponíveis por SKU.

Por exemplo, você pode usar dois indexadores para efetuar pull de dados de duas fontes de dados distintas nomeadas my-blob-datasource1 e my-blob-datasource2. Cada fonte de dados aponta para um contêiner de Blob do Azure separado, mas ambos direcionam para o mesmo índice denominado my-search-index.

Primeiro exemplo de definição de indexador:

POST https://[service name].search.windows.net/indexers?api-version=2026-04-01
{
  "name" : "my-blob-indexer1",
  "dataSourceName" : "my-blob-datasource1",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

Segunda definição de indexador executada em paralelo: exemplo:

POST https://[service name].search.windows.net/indexers?api-version=2026-04-01
{
  "name" : "my-blob-indexer2",
  "dataSourceName" : "my-blob-datasource2",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

Checar o status do indexador

Para monitorar o histórico de execuções e o status do indexador, envie uma solicitação Obter Status do Indexador:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-04-01
  Content-Type: application/json  
  api-key: [admin key]

A resposta inclui o status e o número de itens processados. Ela deve ser parecida com o seguinte exemplo:

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

O histórico de execução contém até 50 das execuções concluídas mais recentemente. As entradas são classificadas em ordem cronológica inversa, portanto, a execução mais recente vem primeiro.

Solução de problemas

Use esta seção para diagnosticar valores de metadados ausentes e falhas comuns de indexação de blobs.

Os campos de metadados são nulos nos resultados da pesquisa

Se você estiver vendo valores nulos ou vazios para campos de metadados nos resultados da pesquisa, use esta lista de verificação:

1. Verifique se o campo existe no esquema de índice: Verifique se você definiu um campo para cada propriedade de metadados que deseja capturar. Execute uma solicitação GET em seu índice para confirmar se o campo está presente.

2. Use o nome do campo correto: Para propriedades de blob padrão, use o nome sublinhado, como metadata_storage_path em vez de metadata-storage-path. Para metadados personalizados, o nome do campo deve corresponder exatamente à chave de metadados do blob.

3. Confirme se o indexador foi dataToExtract definido corretamente:

   • contentAndMetadata (padrão) extrai o conteúdo e os metadados padrão/personalizados.
   • storageMetadata extrai apenas propriedades de blob padrão e metadados personalizados.
   • allMetadata extrai propriedades padrão mais metadados específicos do tipo de conteúdo.

   Verifique a configuração do indexador para garantir que a configuração corresponda à sua intenção.

4. Execute novamente o indexador após atualizações de esquema: Se você adicionou um novo campo ao índice, execute o indexador novamente para que os documentos sejam processados no esquema atualizado. Os documentos existentes podem precisar ser reprocessados antes que o novo campo seja preenchido.

5. Verifique o histórico de execução do indexador: Acesse o indexador no portal do Azure ou use Obter Status do Indexador (API REST) para exibir detalhes de execução e quaisquer mensagens de erro.

Falhas do indexador e tipos de conteúdo sem suporte

Por padrão, o indexador de blob é interrompido assim que encontra um blob com um tipo de conteúdo sem suporte, como um arquivo de áudio. É possível usar o parâmetro excludedFileNameExtensions para ignorar alguns tipos de conteúdo.

Se você quiser que a indexação continue quando alguns documentos falharem, ajuste os parâmetros a seguir e investigue documentos individuais mais tarde. Para obter mais informações, consulte as diretrizes de solução de problemas do Indexador e os erros e avisos do Indexador.

Quando ocorrem erros, cinco parâmetros de indexador controlam a resposta do indexador:

PUT /indexers/[indexer name]?api-version=2026-04-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
      }
    }
}

Conteúdo relacionado

• Detecção e exclusão de alterações
• Indexar conjuntos de dados grandes
• Acesso do indexador ao conteúdo protegido pelos recursos de segurança de rede do Azure