Dados de índice de Arquivos do Azure (versão prévia)

O indexador Arquivos do Azure (versão prévia) importa conteúdo de um compartilhamento de arquivos para um índice de Pesquisa de IA do Azure . As entradas para o indexador são seus arquivos em uma única pasta compartilhada. A saída é um índice de pesquisa com conteúdo pesquisável e metadados armazenados em campos individuais.

Para configurar e executar o indexador, você pode usar:

• APIs REST de pré-visualização do Serviço de Pesquisa, qualquer versão de pré-visualização.
• Um pacote SDK do Azure, qualquer versão.
• Assistente de importação de dados no portal do Azure.

Pré-requisitos

• Arquivos do Azure, camada otimizada para transações.

• Um compartilhamento de arquivos SMB que fornece o conteúdo de origem. Não há suporte para compartilhamentos NFS.

• Arquivos que contêm texto. Se você tiver dados binários, poderá incluir o enriquecimento de IA para análise de imagem.

• Os arquivos de origem processados pelo indexador do Arquivos do Azure usam os limites compartilhados de tamanho de arquivo de origem e de caracteres extraídos para indexadores do tipo blob.

• Permissões de leitura em Armazenamento do Azure. Uma cadeia de conexão de "acesso completo" inclui uma chave que concede acesso ao conteúdo.

• Use um cliente REST para formular chamadas REST semelhantes às mostradas neste 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 tabelas. 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 em um agendamento ou sob demanda.
• Detecção de exclusão: O indexador pode detectar exclusões por meio de metadados personalizados.
• IA aplicada em conjuntos de habilidades:Conjuntos de habilidades são totalmente compatíveis com o indexador. Isso inclui os principais recursos, como a vetorização integrada , que adiciona etapas de 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 JSON ou linhas em documentos de pesquisa individuais. Ele também dá suporte ao modo de análise markdown.
• Compatibilidade com outros recursos: O indexador foi projetado para funcionar perfeitamente com outros recursos do indexador, como sessões de depuração, cache do indexador para enriquecimentos incrementais e repositório de conhecimento.

Formatos de documento com suporte

O indexador Arquivos do Azure pode extrair texto dos seguintes formatos de documento:

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

Como os Arquivos do Azure são indexados

Por padrão, a maioria dos arquivos é indexada como um único documento de pesquisa no índice, incluindo arquivos com conteúdo estruturado, como JSON ou CSV, que são indexados como uma única parte do texto.

Um documento composto ou inserido (como um arquivo ZIP, um documento Word com Outlook email inserido contendo anexos ou um . O arquivo MSG com anexos) também é indexado como um único documento. Por exemplo, todas as imagens extraídas dos anexos de um arquivo .MSG serão retornadas no campo normalized_images. Se você tiver imagens, considere adicionar enriquecimento de IA para obter mais utilidade de pesquisa desse conteúdo.

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

Definir a fonte de dados

A definição da fonte de dados especifica os dados para indexar, 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.

Você pode usar 2020-06-30-preview ou posterior para "type": "azurefile". Recomendamos a API de versão prévia mais recente.

1. Crie uma fonte de dados para definir sua definição usando uma API de visualização para "type": "azurefile".

   POST /datasources?api-version=2026-08-01-preview
   {
       "name" : "my-file-datasource",
       "type" : "azurefile",
       "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
       "container" : { "name" : "my-file-share", "query" : "<optional-directory-name>" }
   }
   

2. Defina "type" como "azurefile" (obrigatório).

3. Defina "credentials" para uma cadeia de conexão do Armazenamento do Microsoft Azure. A próxima seção descreve os formatos com suporte.

4. Defina "contêiner" para o compartilhamento de arquivos raiz e use "consulta" para especificar quaisquer subpastas.

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

Credenciais e cadeias de conexão com suporte

Os indexadores podem se conectar a um compartilhamento de arquivos usando as conexões a seguir.

Adicionar campos de pesquisa a um índice

No índice search, adicione campos para aceitar o conteúdo e os metadados de seus arquivos Azure.

1. Crie ou atualize um índice para definir campos de pesquisa que armazenarão o conteúdo do arquivo e os metadados.

   POST /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_path", "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": true, "filterable": true, "sortable": true }        
     ]
   }
   

2. Crie um campo de chave de documento ("chave": true). Para o conteúdo de blobs, os melhores candidatos são propriedades de metadados. As propriedades de metadados geralmente incluem caracteres, como / e -, que são inválidos para chaves de documento. O indexador codifica automaticamente a propriedade de metadados de chave, sem a necessidade de configuração ou mapeamento de campo.

   • metadata_storage_path (padrão) caminho completo para o objeto ou arquivo

   • metadata_storage_name utilizável somente se os nomes forem exclusivos

   • Uma propriedade de metadados personalizada que você adiciona aos blobs. Essa opção exige que o processo de envio 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 serã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.

3. Adicione um campo "conteúdo" para armazenar o texto extraído de cada arquivo por meio da propriedade "content" do blob. Você não precisa usar esse nome, mas fazer isso permite aproveitar os mapeamentos de campo implícitos.

4. Adicione campos para propriedades de metadados padrão. Na indexação de arquivos, as propriedades de metadados padrão são as mesmas que as propriedades de metadados de blob. O indexador Arquivos do Azure cria automaticamente mapeamentos de campo internos para essas propriedades que convertem nomes de propriedades hifenizadas em nomes de propriedade sublinhados. Você ainda precisa adicionar os campos que deseja usar a definição de índice, mas pode omitir a criação de mapeamentos de campo na fonte de dados.

   • metadata_storage_name (Edm.String) – o nome do arquivo. Por exemplo, se você tiver um arquivo /my-share/my-folder/subfolder/resume.pdf, o valor desse campo será resume.pdf.
   • metadata_storage_path (Edm.String) – o URI completo do arquivo, incluindo a conta de armazenamento. Por exemplo, https://myaccount.file.core.windows.net/my-share/my-folder/subfolder/resume.pdf
   • metadata_storage_content_type (Edm.String) – tipo de conteúdo conforme especificado pelo código usado para carregar o arquivo. Por exemplo, application/octet-stream.
   • metadata_storage_last_modified (Edm.DateTimeOffset) – carimbo de data/hora da última modificação do arquivo. Pesquisa de IA do Azure  usa esse carimbo de data/hora para identificar arquivos alterados, para evitar a reindexação de tudo após a indexação inicial.
   • metadata_storage_size (Edm.Int64) – tamanho do arquivo em bytes.
   • metadata_storage_content_md5 (Edm.String) – hash MD5 do conteúdo do arquivo, se disponível.
   • metadata_storage_sas_token (Edm.String) – um token SAS temporário que pode ser usado por habilidades personalizadas para obter acesso ao arquivo. Esse token não deve ser armazenado para uso posterior, pois pode expirar.

Configurar e executar o indexador Arquivos do Azure

Depois que o índice e a fonte de dados tiverem sido criados, você estará pronto para criar o indexador. A configuração do indexador especifica as entradas, os parâmetros e as propriedades que controlam os comportamentos de tempo de execução.

1. Crie ou atualize um indexador dando-lhe um nome e fazendo referência à fonte de dados e ao índice de destino:

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

2. Na seção opcional "configuração", forneça qualquer critério de inclusão ou exclusão. Se não for especificado, todos os arquivos no compartilhamento de arquivos serão recuperados.

   Se os parâmetros indexedFileNameExtensions e excludedFileNameExtensions estiverem presentes, Pesquisa de IA do Azure  primeiro examinará indexedFileNameExtensions e, em seguida, em excludedFileNameExtensions. Se a mesma extensão de arquivo estiver presente em ambas as listas, ela será excluída da indexação.

3. 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 arquivos, muitas vezes você pode omitir mapeamentos de campo porque o indexador tem suporte interno para mapear as propriedades de "conteúdo" e metadados para campos nomeados e digitados de forma semelhante em um índice. Para propriedades de metadados, o indexador substituirá automaticamente os hifens - por sublinhados no índice de pesquisa.

4. Consulte Criar um indexador para obter mais informações sobre outras propriedades.

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

Verificar o status do indexador

Para monitorar o status do indexador e o histórico de execução, 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. Ele deve ser semelhante ao exemplo a seguir:

    {
        "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, que são classificadas na ordem cronológica inversa para que a execução mais recente venha primeiro.

Próximas etapas

Agora você pode executar o indexador, monitorar o status ou agendar a execução do indexador. Os artigos a seguir se aplicam a indexadores que extraem conteúdo de Armazenamento do Azure:

• Detecção de mudanças e detecção de exclusões
• Indexar conjuntos de dados grandes