Indexar dados de Arquivos do Azure

Artigo
12/13/2023

Importante

O indexador dos Arquivos do Azure está em versão prévia pública, de acordo com os Termos de Uso Complementares. Use uma API REST em versão prévia (2020-06-30-preview ou posterior) para criar a fonte de dados do indexador.

Neste artigo, saiba como configurar um indexador que importa o conteúdo de Arquivos do Azure e o torna pesquisável na IA do Azure Search. As entradas para o indexador são os seus arquivos em apenas um 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 da indexação de arquivos no Armazenamento do Microsoft 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 e criar um indexador. A extração de dados ocorre quando você envia a solicitação Criar Indexador.

Pré-requisitos

Arquivos do Azure, camada otimizada para transação.
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.
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 nesse artigo.

Formatos de documento com suporte

O indexador dos Arquivos do Azure pode extrair 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)
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

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 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 serã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 conteúdo textual de um documento é extraído para um campo de cadeia de caracteres chamado "content". 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, 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.

Crie ou atualize uma fonte de dados para atribuir uma definição a ela, usando uma versão prévia da API 2020-06-30-preview ou posterior para "type": "azurefile".

{
    "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>" }
}

Defina "type" como "azurefile" (obrigatório).
Defina "credentials" para uma cadeia de conexão do Armazenamento do Microsoft Azure. A próxima seção descreve os formatos compatíveis.
Defina "container" para o compartilhamento de arquivos raiz e use "query" para especificar todas as subpastas.

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

Credenciais e cadeias de conexão com suporte

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

Cadeia de conexão da conta de armazenamento com acesso completo
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
Você pode obter a cadeia de conexão na página da conta de Armazenamento no portal do Azure selecionando Chaves de acesso no painel de navegação à esquerda. Você deve selecionar uma cadeia de conexão completa, não apenas uma chave.

Adicionar campos de pesquisa a um índice

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

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

POST /indexes?api-version=2020-06-30
{
  "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 }        
  ]
}

Crie um campo de chave do documento ("key": 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álidas para chaves de documento. Como o indexador tem uma propriedade "base64EncodeKeys" (true por padrão), ele codifica automaticamente a propriedade metadata, sem a necessidade de configuração ou de 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 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 tiverem um valor faltando 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.
Adicione um campo "content" para armazenar o texto extraído de cada arquivo por meio da propriedade "content" do blob. Não é necessário usar esse nome, mas, usá-lo permite aproveitar os mapeamentos de campo implícitos.
Adicione campos para propriedades de metadados padrão. Na indexação de arquivos, as propriedades de metadados padrão são as mesmas propriedades de metadados de blob. O indexador dos Arquivos do Azure cria mapeamentos de campo internos automaticamente para essas propriedades que converte os nomes de propriedades com hífen em nomes de propriedade com sublinhados (_). Ainda é necessário adicionar os campos desejados para usar a definição de índice, mas pode-se 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) – o 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. A IA do Azure Search usa esse carimbo de data/hora para identificar os arquivos alterados, a fim de evitar a reindexação total 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 estiver 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 ele pode expirar.

Configurar e executar o indexador dos Arquivos do Azure

Uma vez que o índice e a fonte de dados forem criados, será possível 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.

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=2020-06-30
{
  "name" : "my-file-indexer",
  "dataSourceName" : "my-file-datasource",
  "targetIndexName" : "my-search-index",
  "parameters": {
     "batchSize": null,
     "maxFailedItems": null,
     "maxFailedItemsPerBatch": null,
     "base64EncodeKeys": null,
     "configuration": {
        "indexedFileNameExtensions" : ".pdf,.docx",
        "excludedFileNameExtensions" : ".png,.jpeg" 
    }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

Na seção "configuration" opcional, forneça os critérios de inclusão ou exclusão. Se ela for deixada não especificada, todos os arquivos no compartilhamento de arquivo serão recuperados.

Se os parâmetros indexedFileNameExtensions e excludedFileNameExtensions estiverem presentes, primeiro a IA do Azure Search examinará indexedFileNameExtensions e depois excludedFileNameExtensions. Se a mesma extensão de arquivo estiver nas duas listas, ela será excluída da indexação.
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 os mapeamentos de campo porque o indexador tem suporte interno para mapear as propriedades de metadados e "content" para campos com nomes semelhantes e campos com tipo em um índice. Para propriedades de metadados, o indexador substituirá automaticamente os hifens - por sublinhados no índice de pesquisa.
Confira Criar um indexador para obter mais informações sobre outras propriedades.

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

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=2020-06-30
  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ções contém até 50 execuções mais recentes, classificadas em ordem cronológica inversa, de modo que a execução mais recente apareça em primeiro lugar.

Próximas etapas

Agora você pode executar o indexador, monitorar o statusou agendar a execução do indexador. Os seguintes artigos se aplicam a indexadores que efetuam pull do conteúdo do Armazenamento do Microsoft Azure: