Dados de índice do Armazenamento de Blobs do Azure

O blob indexer importa conteúdo do Armazenamento de Blobs do Azure e torna-o pesquisável no Pesquisa de IA do Azure. O indexador recebe blobs num único contentor como entrada. O resultado é um índice de pesquisa que armazena conteúdo e metadados pesquisáveis em campos individuais.

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

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

Pré-requisitos

• Armazenamento de Blobs do Azure, desempenho padrão (v2 de uso geral).

• As camadas de acesso incluem quente, frio, frio e arquivamento. Os indexadores podem recuperar blobs em camadas de acesso quente, fria e gelada.

• 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 blob não pode ultrapassar os limites do indexador para o seu escalão de preços.

  Os limites do blob indexer cobrem o tamanho máximo do blob e o número de caracteres que o Pesquisa de IA do Azure extrai de um blob. Se usares um conjunto de competências, o limite de entrada ou serviço de cada competência aplica-se separadamente após a quebra do documento.

• Uma configuração de rede suportada e acesso a dados. No mínimo, você precisa de permissões de leitura no Armazenamento do Azure. Uma cadeia de conexão de armazenamento que inclui uma chave de acesso oferece acesso de leitura ao conteúdo de armazenamento. Se, em vez disso, estiver a usar logins e funções do Microsoft Entra, verifique se a identidade gerida do serviço de pesquisa tem permissões de Leitor de Dados de Blob de Armazenamento.

  Por padrão, tanto a pesquisa quanto o armazenamento aceitam solicitações de endereços IP públicos. Se a segurança da rede não for uma preocupação imediata, você poderá indexar 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 Acesso do indexador a conteúdo protegido por recursos de segurança de rede do Azure para obter orientação sobre o acesso a dados.

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

Tarefas suportadas

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 deteta arquivos e metadados novos e atualizados por meio da deteção de alterações integrada. Você pode configurar a atualização de dados em um cronograma ou sob demanda.

• Deteção de exclusão: O indexador pode detetar exclusões por meio de soft delete nativo ou por meio de metadados personalizados.

• IA aplicada através de conjuntos de competências: O indexador suporta totalmente os conjuntos de competências. Este suporte inclui funcionalidades-chave como vetorização integrada, que adiciona fragmentação de dados e embedding.

• Modos de análise: o indexador suporta modos de análise JSON se você quiser analisar matrizes ou linhas JSON em documentos de pesquisa individuais. Ele também suporta o modo de interpretação Markdown.

• Compatibilidade com outras funcionalidades: O indexador funciona perfeitamente com outras funcionalidades do indexador, como sessões de depuração, cache do indexador para enriquecimentos incrementais (pré-visualização) e armazenamento de conhecimento.

Formatos de documento suportados

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

• CSV (consulte Indexação de blobs CSV)
• EML
• EPUB
• GZ
• HTML
• JSON (consulte Indexação de blobs JSON)
• KML (XML para representações geográficas)
• Markdown
• Formatos do Microsoft Office: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG (e-mails do Outlook), XML (XML WORD de 2003 e 2006)
• Formatos de documentos abertos: ODT, ODS, ODP
• PDF
• Arquivos de texto sem formatação (consulte também Indexação de texto sem formatação)
• RTF
• XML
• CEP

Determinar quais blobs indexar

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

• Coloque blobs em uma pasta virtual. A definição de fonte de dados de um indexador inclui um parâmetro que pode aceitar uma pasta virtual. Se especificar uma pasta virtual, o indexador indexa apenas os blobs da pasta.

• Inclua ou exclua blobs por tipo de arquivo. A lista de formatos de documento suportados pode ajudá-lo a determinar quais blobs devem ser excluídos. Por exemplo, talvez você queira excluir arquivos de imagem ou áudio que não forneçam texto pesquisável. Controlas esta funcionalidade através das definições de configuração no indexador.

• Incluir ou excluir blobs arbitrários. Para saltar um blob específico, adicione as seguintes propriedades e valores de metadados aos blobs no Armazenamento de Blobs do Azure. Quando um indexador encontra essa propriedade, ele ignora o blob ou seu conteúdo na execução de indexação.

  Nome da propriedade	Valor do imóvel	Explanation
  AzureSearch_Skip	true	Instrui o indexador de blob a ignorar completamente o blob. O indexador não tenta extrair metadados ou conteúdos. Esta propriedade é útil quando um determinado blob falha repetidamente e interrompe o processo de indexação.
  AzureSearch_SkipContent	true	O indexador ignora o conteúdo e extrai apenas os metadados. Esta propriedade é equivalente à "dataToExtract": "allMetadata" definição descrita nas definições de configuração, mas está direcionada para um blob específico.

Se não definires critérios de inclusão ou exclusão, o indexador reporta um blob inelegível como erro e segue em frente. Se ocorrerem erros suficientes, o processamento pode parar. Você pode especificar tolerância a erros nas definições de configuração do indexador.

Um indexador normalmente cria um documento de pesquisa por blob, onde o conteúdo de texto e os metadados são capturados como campos pesquisáveis em um índice. Se os blobs forem arquivos inteiros, você poderá 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 incorporado (como um arquivo ZIP, um documento do Word com email do Outlook incorporado contendo anexos ou um arquivo . MSG com anexos) também é indexado como um único documento. Por exemplo, todas as imagens extraídas dos anexos de um .MSG são retornadas no campo normalized_images. Se tiver imagens, considere adicionar enriquecimento por IA para obter mais utilidade de pesquisa desse conteúdo.

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

Indexação de metadados de blob

Podes indexar metadados de blob juntamente com o conteúdo. O indexador extrai propriedades dos metadados e armazena-as em campos de índice, o que é útil para criar filtros e consultas.

Defina campos no seu índice de pesquisa para as propriedades de metadados que pretende capturar. Não precisa de definir todas as propriedades de metadados padrão ou personalizadas disponíveis. Basta registar as propriedades de que precisa para a sua aplicação.

Atualmente, este indexador não suporta a indexação de etiquetas de índice de blob.

Propriedades padrão dos metadados do blob

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

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

O indexador reconhece e pode mapear estas propriedades padrão de metadados se definir campos correspondentes no seu índice:

• metadata_storage_name (Edm.String) é o nome do ficheiro do blob. Por exemplo, se tiver um blob /my-container/my-folder/subfolder/resume.pdf, o valor deste campo é 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. Utilize esta propriedade para incluir URLs de blob nos resultados da pesquisa para navegação ou atribuição da origem.

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

• metadata_storage_last_modified (Edm.DateTimeOffset) é a data/hora de última modificação do blob. O Pesquisa de IA do Azure usa este carimbo temporal 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 aceder ao blob. Não guarde este token para uso posterior, pois pode expirar.

Metadados personalizados e específicos de conteúdo

Para metadados personalizados ou definidos pelo utilizador, defina um campo com exatamente o mesmo nome da chave de metadados do blob. Por exemplo, se os teus blobs tiverem uma chave Sensitivity de metadados com valor High, define um campo nomeado Sensitivity de tipo Edm.String no teu índice.

Também podes representar propriedades de metadados específicas do formato do documento dos blobs que estás a indexar. Para mais informações, consulte as propriedades dos metadados de conteúdo.

Definir a fonte de dados

A definição da fonte de dados especifica os dados a serem indexados, credenciais e 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 definir 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 para uma cadeia de conexão do Armazenamento do Azure. A próxima seção descreve os formatos suportados.

4. Define container para o blob container, e usa query para especificar quaisquer subpastas.

Também pode incluir políticas de eliminação suave numa definição de fonte de dados se quiser que o indexador apague um documento de pesquisa quando o documento de origem for sinalizado para eliminação.

Credenciais e cadeias de conexão suportadas

Os indexadores podem ligar-se a um contentor de blob usando as seguintes ligações.

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 armazenem conteúdo e metadados de 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. Crie um campo de chave de documento ("key": true). Para conteúdo de blob, os melhores candidatos são propriedades de metadados.

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

   • metadata_storage_name é utilizável apenas se os nomes forem únicos. Se pretender que este campo seja a chave, avance "key": true para esta definição de campo.

   • Uma propriedade de metadados personalizada que você adiciona aos blobs. Essa opção requer que seu processo de upload de blob adicione essa propriedade de metadados a todos os blobs. Como a chave é uma propriedade obrigatória, quaisquer blobs que não tenham valor deixam de ser indexados. Se você usar uma propriedade de metadados personalizada como uma chave, evite fazer alterações nessa propriedade. Os indexadores adicionam documentos duplicados para o mesmo blob se a propriedade da chave mudar.

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

3. Adicione um campo content para armazenar o texto extraído de cada ficheiro através da propriedade content do blob. Não é obrigado a usar este nome, mas ao usá-lo, pode tirar partido dos mapeamentos implícitos de campos.

4. Adicione campos para propriedades de metadados padrão. O indexador pode ler propriedades de metadados personalizados, propriedades de metadados padrão e propriedades de metadados específicos de 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, parâmetros e propriedades que controlam os comportamentos em tempo de execução. Você também pode especificar quais partes de um blob devem ser indexadas.

1. Crie ou atualize um indexador dando-lhe um nome e fazendo referência à fonte de dados e ao í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. Definir batchSize se o padrão (10 documentos) subutilizar ou sobrecarregar os recursos disponíveis. Os tamanhos de lote padrão são específicos da fonte de dados. A indexação de Blob define o tamanho do lote em 10 documentos em reconhecimento ao tamanho médio maior do documento.

3. Em configuration, controla quais blobs são indexados com base no tipo de ficheiro, ou deixa não especificado para recuperar todos os blobs.

   Para indexedFileNameExtensions, forneça uma lista separada por vírgulas de extensões de arquivo (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 exclui-a da indexação.

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

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

   • storageMetadata especifica que o indexador indexa apenas as propriedades padrão do blob e os metadados especificados pelo utilizador.

   • allMetadata especifica que o indexador extrai do conteúdo do blob e indexa propriedades padrão do blob e quaisquer metadados para tipos de conteúdo encontrados.

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

5. Sob 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 um melhor desempenho alternando para a análise de texto sem formatação . Se você precisar de uma análise mais granular que mapeie blobs para vários documentos de pesquisa, especifique um modo diferente. A análise um-para-muitos é suportada 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 precisar de várias versões de um campo de origem no índice de pesquisa.

   Na indexação de blobs, muitas vezes pode omitir os mapeamentos de campos porque o indexador tem suporte embutido para mapear as propriedades content e os metadados para campos com nomes e tipos semelhantes num índice. Para propriedades de metadados, o indexador substitui automaticamente hífenes - com sublinhados no índice de pesquisa.

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

Um indexador é executado automaticamente quando é criado. Podes evitar esta ação definindo disabled como verdadeiro. Para controlar a execução do indexador, execute um indexador sob demanda ou coloque-o em uma programação.

Indexar dados de múltiplos contentores do Azure Blob num único índice

Lembre-se de que um indexador só pode indexar dados de um único contentor. Se precisar de indexar dados de vários contentores e consolidá-los num único índice de AI Search, configure vários indexadores que apontem todos para o mesmo índice. Esteja atento ao número máximo de indexadores disponíveis por SKU.

Por exemplo, pode usar dois indexadores para extrair dados de duas fontes de dados distintas chamadas 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 chamado 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 que é executada em exemplo paralelo:

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" : [ ]
}

Verificar o estado do indexador

Para monitorizar o status do indexador e o histórico de execução, envie uma solicitação Get Indexer Status:

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. Deve ser semelhante ao 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ções contém até 50 das execuções mais recentemente concluídas. As entradas estão ordenadas por ordem cronológica inversa, por isso a execução mais recente vem primeiro.

Troubleshooting

Use esta secção para diagnosticar valores de metadados em falta e falhas comuns de indexação de blobs.

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

Se estiver a ver valores nulos ou vazios para campos de metadados nos seus resultados de pesquisa, use esta lista de verificação:

1. Verifique se o campo existe no seu esquema de índice: Verifique se definiu um campo para cada propriedade de metadados que pretende capturar. Executa um pedido GET no teu índice para confirmar que o campo está presente.

2. Utilize o nome correto do campo: Para propriedades padrão do blob, utilize o nome com underscores, 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 definiu dataToExtract corretamente:

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

   Verifica a configuração do teu indexador para garantir que a definição corresponde à tua intenção.

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

5. Verifique o histórico de execução do indexador: Vá ao seu indexador no portal Azure ou use o Get Indexer Status (API REST) para ver detalhes de execução e quaisquer mensagens de erro.

Falhas no indexador e tipos de conteúdo não suportados

Por defeito, o indexador de blobs para assim que encontra um blob com um tipo de conteúdo não suportado, como um ficheiro de áudio. Você pode usar o excludedFileNameExtensions parâmetro para ignorar determinados tipos de conteúdo.

Se quiser que a indexação continue quando alguns documentos falham, ajuste os parâmetros seguintes e depois investigue documentos individuais mais tarde. Para mais informações, consulte as orientações de resolução de problemas do Indexador e erros e avisos do Indexador.

Quando ocorrem erros, cinco parâmetros do 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

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