Indexar dados do Armazenamento de Blobs do Azure

Artigo
03/18/2024

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 do Armazenamento de Blobs incluem camada de acesso Frequente, camada de acesso Esporádico e camada de acesso aos Arquivos. Somente as camada de acesso Frequente e Esporádico podem ser acessadas por indexadores.
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.

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

Defina "type" como "azureblob" (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 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.

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.

Cadeia de conexão de identidade gerenciada
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }`
Essa cadeia de conexão não exige uma chave de conta, mas você precisa já ter configurado um serviço de pesquisa para se conectar usando uma identidade gerenciada.

Cadeia de conexão da SAS (assinatura de acesso compartilhado**) da conta de armazenamento
`{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" }`
As SAS devem ter as permissões de lista e leitura nos contêineres e objetos (blobs neste caso).

Assinatura de acesso compartilhado do contêiner
`{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.windows.net/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" }`
As SAS devem ter a lista e permissões de leitura no contêiner. Para obter mais informações, confira Como usar assinaturas de acesso compartilhado.

Observação

Se você usar credenciais SAS, você precisará atualizar as credenciais de fonte de dados periodicamente com assinaturas renovadas para impedir sua expiração. Se as credenciais SAS expirarem, o indexador falhará com uma mensagem de erro semelhante a "As credenciais fornecidas na cadeia de conexão são inválidas ou expiraram".

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.

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=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_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
        { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": false, "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.
- 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. 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.
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. 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.

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-blob-indexer",
  "dataSourceName" : "my-blob-datasource",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "base64EncodeKeys": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

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.
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.
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.
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
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.
Confira Criar um indexador para obter mais informações sobre outras propriedades. Para ver a lista completa de descrições de parâmetros, confira Parâmetros de configuração de blob na 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.

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.

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=2020-06-30
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
      }
    }
}

Parâmetro	Valores válidos	Descrição
"maxFailedItems"	-1, null ou 0, inteiro positivo	Continuar a indexação se ocorrem erros a qualquer momento do processamento, ao analisar blobs ou ao adicionar documentos a um índice. Definir as propriedades com o número de falhas aceitáveis. Um valor de `-1` permite o processamento, independentemente de quantos erros ocorram. Caso contrário, o valor será um inteiro positivo.
"maxFailedItemsPerBatch"	-1, null ou 0, inteiro positivo	O mesmo que acima, mas usado para indexação do lote.
"failOnUnsupportedContentType"	true ou false	Se o indexador não puder determinar o tipo de conteúdo, especifique se deseja continuar ou falhar o trabalho.
"failOnUnprocessableDocument"	true ou false	Se o indexador não puder processar um documento de um tipo de conteúdo que em outros contextos tem suporte, especifique se deseja continuar ou falhar o trabalho.
"indexStorageMetadataOnlyForOversizedDocuments"	true ou false	Por padrão, os blobs superdimensionados são tratados como erros. Se você definir esse parâmetro como true, o indexador tentará indexar seus metadados mesmo que o conteúdo não possa ser indexado. Para obter os limites do tamanho do blob, consulte Limites de serviço.