Indexar dados do Azure Data Lake Storage Gen2

Artigo
04/16/2024

Neste artigo, saiba como configurar um indexador que importa o conteúdo do Azure Data Lake Storage (ADLS) Gen2 e o torna pesquisável na IA do Azure 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 o artigo Criar um indexador com informações específicas da indexação do ADLS Gen2. 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.

Para obter um exemplo de código em C#, consulte Index Data Lake Gen2 usando o Microsoft Entra ID no GitHub.

Pré-requisitos

ADLS Gen2 com namespace hierárquico habilitado. O ADLS Gen2 está disponível por meio do Armazenamento do Microsoft Azure. Ao configurar uma conta de armazenamento, você tem a opção de habilitar o namespace hierárquico, organizar arquivos em uma hierarquia de diretórios e subdiretórios aninhados. Ao habilitar um namespace hierárquico, você habilita o ADLS Gen2.
As camadas de acesso do ADLS Gen2 incluem quente, fria e de arquivos. Somente as de acesso frequente e esporádico podem ser acessadas por indexadores.
Blobs que contêm texto. Se você tiver dados binários, poderá incluir o enriquecimento de IA para análise de imagem. O conteúdo do blob não deve exceder os limites do indexador na sua camada do serviço de pesquisa.
Permissões de leitura no Armazenamento do Azure. Uma cadeia de conexão de "acesso completo" inclui uma chave que permite acesso ao conteúdo, mas se você estiver usando funções do Azure, verifique se a identidade gerenciada do serviço Pesquisa tem as permissões Leitor de dados do blob de armazenamento.
Use um cliente REST para formular chamadas REST semelhantes às mostradas nesse artigo.

Observação

O ADLS Gen2 implementa um modelo de controle de acesso que dá suporte ao Azure RBAC (controle de acesso baseado em função do Azure) e às ACLs (listas de controle de acesso) do tipo POSIX no blob. A IA do Azure Search não dá suporte a permissões no documento. Todos os usuários têm o mesmo nível de acesso a todo o conteúdo pesquisável e recuperável no índice. Se as permissões no nível do documento são um requisito de aplicativo, considere estabelecer restrições de segurança como uma solução em potencial.

Formatos de documento com suporte

O indexador do ADLS Gen2 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.

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 será ú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 fará 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.

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-adlsgen2-datasource",
    "type" : "adlsgen2",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
}

Defina "type" como "adlsgen2" (obrigatório).
Defina "credentials" como uma cadeia de conexão do Armazenamento do Microsoft Azure. A próxima seção descreve os formatos compatíveis.
Defina "container" como 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).

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:

{
    "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 do ADLS Gen2

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:

{
  "name" : "my-adlsgen2-indexer",
  "dataSourceName" : "my-adlsgen2-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 subutilizando 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 "configuration", defina "parsingMode" se os blobs devem ser mapeados para vários documentos de pesquisa ou se consistem em texto sem formatação, documentos JSON ou 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=2023-11-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":"2024-02-21T00:23:24.957Z",
            "endTime":"2024-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2024-02-21T00:23:24.957Z",
                "endTime":"2024-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 você queira que a indexação prossiga mesmo que ocorram erros e, depois, depure documentos individuais. 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=2023-11-01
{
  "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.

Limitações

Ao contrário dos indexadores de blob, os indexadores do ADLS Gen2 não podem utilizar tokens SAS de nível de contêiner para enumerar e indexar conteúdo de uma conta de armazenamento. Isso ocorre porque o indexador faz uma verificação para determinar se a conta de armazenamento tem namespaces hierárquicos habilitados chamando o Sistema de arquivos – Obter API de propriedades. Para contas de armazenamento em que namespaces hierárquicos não estão habilitados, é recomendável que os clientes utilizem indexadores de blob para garantir a enumeração de blobs com desempenho.
Se a propriedade metadata_storage_path for mapeada para ser o campo de chave de índice, não haverá garantia de que os blobs sejam reindexados em um diretório renomeado. Se você quiser reexaminar os blobs que fazem parte dos diretórios renomeados, atualize os carimbos de data/hora LastModified para todos eles.

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: