Indexar dados dos Arquivos do Azure

Neste artigo, saiba como configurar um indexador que importa conteúdo dos Arquivos do Azure e o torna pesquisável no Azure AI Search. As entradas para o indexador são seus arquivos em um único compartilhamento. A saída é um índice de pesquisa com conteúdo pesquisável e metadados armazenados em campos individuais.

Este artigo complementa Criar um indexador com informações específicas para indexar arquivos no Armazenamento do Azure. Ele usa as APIs REST para demonstrar um fluxo de trabalho de três partes comum a todos os indexadores: criar uma fonte de dados, criar um índice, criar um indexador. A extração de dados ocorre quando você envia a solicitação Criar indexador.

Pré-requisitos

• Azure Files, 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 contendo texto. Se você tiver dados binários, poderá incluir enriquecimento de IA para análise de imagem.

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

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

Formatos de documento suportados

O indexador de 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 blobs JSON)
• KML (XML para representações geográficas)
• 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

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 um único pedaço de texto.

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 arquivo . O arquivo MSG será retornado 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 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.

Você pode usar 2020-06-30-preview ou posterior para "tipo": "azurefile". Recomendamos a API de visualização 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=2024-05-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 "credenciais" como uma cadeia de conexão do Armazenamento do Azure. A próxima seção descreve os formatos suportados.

4. Defina "container" para o compartilhamento de arquivos raiz e use "query" para especificar quaisquer subpastas.

Uma definição de fonte de dados também pode incluir políticas de exclusão flexível, se você 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 suportadas

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

Adicionar campos de pesquisa a um índice

No índice de pesquisa, adicione campos para aceitar o conteúdo e os metadados dos seus ficheiros do Azure.

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

   POST /indexes?api-version=2024-07-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 conteúdo de blob, 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 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 apenas se os nomes forem exclusivos

   • 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 necessária, quaisquer blobs que estejam faltando 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 da chave for alterada.

3. Adicione um campo "content" para armazenar o texto extraído de cada arquivo através da propriedade "content" do blob. Você não é obrigado a usar esse nome, mas isso permite que você aproveite 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 de Arquivos do Azure cria automaticamente mapeamentos de campo internos para essas propriedades que convertem nomes de propriedades hifenizadas em nomes de propriedades 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 que você usou para carregar o arquivo. Por exemplo, application/octet-stream.
   • metadata_storage_last_modified (Edm.DateTimeOffset) - carimbo de data/hora modificado pela última vez para o arquivo. O Azure AI Search 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 ficheiro 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 de Arquivos do Azure

Depois que o índice e a fonte de dados forem criados, você estará pronto para criar o indexador. A configuração do indexador especifica as entradas, parâmetros e 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=2024-07-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 quaisquer critérios de inclusão ou exclusão. Se não forem especificados, todos os arquivos no compartilhamento de arquivos serão recuperados.

   Se ambos os indexedFileNameExtensions parâmetros estiverem excludedFileNameExtensions presentes, o Azure AI Search examinará primeiro o indexedFileNameExtensions, depois o 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 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 com nomes e digitados de forma semelhante em um índice. Para propriedades de metadados, o indexador substituirá automaticamente hífenes - 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 evitar isso definindo "desativado" como true. Para controlar a execução do indexador, execute um indexador sob demanda ou coloque-o em uma programação.

Verificar o estado 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=2024-07-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çã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óximos passos

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

• Deteção de alterações e deteção de exclusão
• Indexar grandes conjuntos de dados