Indexar dados do Armazenamento de Blobs do Azure

Neste artigo, saiba como configurar um indexador que importa o conteúdo da tabela do Armazenamento de Blobs do Azure e o torna pesquisável no Azure AI Search. As entradas para o indexador são seus blobs, em apenas um contêiner. 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 de Armazenamento de Blobs. 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.

Os indexadores de blob são frequentemente usados para enriquecimento de IA e processamento baseado em texto. Este artigo se concentra em indexadores para indexação baseada em texto, em que apenas o conteúdo textual e os metadados são ingeridos para cenários de pesquisa de texto completo.

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 deve exceder os limites do indexador para a camada do serviço de pesquisa.

• 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.

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)
• 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, revise os dados de origem para determinar se alguma alteração deve ser feita com antecedência. Um indexador pode indexar o conteúdo de um contêiner por vez. Por padrão, todos os blobs do contêiner são processados. 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 parâmetro "query" que pode usar uma pasta virtual. Se você especificar uma pasta virtual, somente os blobs da pasta serão indexados.

• 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. Essa funcionalidade é controlada por meio de definições de configuração no indexador.

• Inclua ou exclua blobs arbitrários. Caso deseje ignorar um blob específico por qualquer motivo, adicione as propriedades e os valores de metadados a seguir aos blobs no Armazenamento de Blobs. 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 de propriedade	Explicação
  "AzureSearch_Skip"	"true"	Instrui o indexador de blobs a ignorar o blob por completo. Não há nenhuma tentativa de extração de metadados nem de conteúdo. Isso é útil quando um blob específico falha repetidamente e interrompe o processo de indexação.
  "AzureSearch_SkipContent"	"true"	Ignora o conteúdo e extrai apenas os metadados. Isso é equivalente à configuração "dataToExtract" : "allMetadata" descrita nas definições de configuração, apenas com escopo para um blob específico.

Se você não configurar critérios de inclusão ou exclusão, o indexador relatará um blob não qualificado como um erro e seguirá em frente. 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 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.

Indexação dos metadados de blobs

Os metadados de blob também podem ser indexados, e isso é útil se você considerar que qualquer uma das propriedades de metadados padrão ou personalizadas é útil em filtros e consultas.

As propriedades de metadados especificadas pelo usuário são extraídas literalmente. Para receber os valores, é necessário definir o campo no índice de pesquisa do tipo Edm.String, com o mesmo nome que a chave de metadados do blob. Por exemplo, se um blob tiver uma chave de metadados de Sensitivity com valor High, deverá ser definido um campo chamado Sensitivity no índice de pesquisa e ele será preenchido com o valor High.

As propriedades de metadados de blob padrão podem ser extraídas em campos nomeados e digitados de maneira similar, conforme listado abaixo. O indexador de blob cria automaticamente mapeamentos de campo internos para essas propriedades de metadados de blob, convertendo o nome hifenizado original ("metadata-storage-name") para um nome equivalente sublinhado ("metadata_storage_name").

Você ainda precisa adicionar os campos sublinhados à definição do índice, mas pode omitir os mapeamentos de campo porque o indexador faz a associação automaticamente.

• 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

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

• metadata_storage_last_modified (Edm.DateTimeOffset) – carimbo de data/hora da última modificação do blob. A IA do Azure Search usa esse carimbo de data/hora para identificar os blobs alterados, a fim de evitar a reindexação total após a indexação inicial.

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

• metadata_storage_content_md5 (Edm.String) – hash MD5 do conteúdo do blob, 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 blob. Esse token não deve ser armazenado para uso posterior, pois ele pode expirar.

Por fim, as propriedades de metadados específicas do formato de documento dos blobs que são indexados também podem ser representadas no esquema de índice. Para obter mais informações sobre metadados específicos de conteúdo, consulte Propriedades de metadados de conteúdo.

É importante observar que não é necessário definir os campos para todas as propriedades acima no índice de pesquisa – basta capturar as propriedades necessárias para seu aplicativo.

Atualmente, a indexação marcas de índice de blob não é compatível com esse indexador.

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" para uma cadeia de conexão do Armazenamento do Microsoft Azure. A próxima seção descreve os formatos compatíveis.

4. Defina "container" para o contêiner de blob 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 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 armazenarão o conteúdo e os metadados do blob:

   POST https://[service name].search.windows.net/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_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 do documento ("key": true). Para conteúdo de blob, os melhores candidatos são propriedades de metadados.

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

   • metadata_storage_name, utilizável somente 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 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.

   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. Não é necessário usar esse nome, mas, usá-lo permite 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

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. 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=2024-07-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 (dez documentos) estiver utilizando ou sobrecarregando 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 os blobs que serão indexados com base no tipo de arquivo ou mantenha-o não especificado 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 em "excludedFileNameExtensions" para indicar as extensões que devem ser ignoradas. Se a mesma extensão estiver nas duas listas, ela será excluída da indexação.

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

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

   • "storageMetadata" especifica que somente as propriedades de blob padrão e os metadados especificados pelo usuário são indexados.

   • "allMetadata" especifica que as propriedades de blob padrão e quaisquer metadados para tipos de conteúdo encontrados são extraídos do conteúdo do blob e indexados.

5. Em "configuração", selecione "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, 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.

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 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.

Indexação de dados de vários contêineres de Blobs do Azure em um único índice

Lembre-se de que um indexador só pode indexar dados de um único contêiner. Se o seu requisito for indexar dados de vários contêineres e consolidá-los em um único índice do AI Search, isso poderá ser alcançado configurando vários indexadores, todos direcionados ao mesmo índice. Esteja ciente do número máximo de indexadores disponíveis por SKU.

Para ilustrar, vamos considerar um exemplo de dois indexadores, extraindo dados de duas fontes de dados distintas, denominadas 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=2024-07-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=2024-07-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=2024-07-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çõ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.

Tratar erros

Os erros que normalmente ocorrem durante a indexação incluem tipos de conteúdo sem suporte, conteúdo ausente ou blobs superdimensionados.

Por padrão, o indexador de blobs é interrompido assim que encontra um blob com um tipo de conteúdo sem suporte (por exemplo, um arquivo de áudio). Você pode usar o parâmetro "excludedFileNameExtensions" para ignorar determinados tipos de conteúdo. No entanto, talvez se queira indexar para continuar mesmo que ocorram erros e depurar documentos individuais posteriormente. Para obter mais informações sobre erros do indexador, confira Diretrizes de solução de problemas do indexador e Erros e avisos do indexador.

Há cinco propriedades do indexador que controlam a resposta do indexador quando ocorrem erros.

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

Confira também

• 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