Dados de índice do Azure Data Lake Storage Gen2

Artigo
04/11/2024

Neste artigo, saiba como configurar um indexador que importa conteúdo do Azure Data Lake Storage (ADLS) Gen2 e o torna pesquisável no Azure AI Search. As entradas para o indexador são seus blobs, em um único 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 para 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, 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 através do Armazenamento do Azure. Ao configurar uma conta de armazenamento, você tem a opção de habilitar o namespace hierárquico, organizando 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 para ADLS Gen2 incluem quente, frio e arquivamento. Apenas hot e cool podem ser acessados pelos indexadores de pesquisa.
Blobs contendo texto. Se você tiver dados binários, poderá incluir enriquecimento de IA para análise de imagem. O conteúdo de Blob não pode exceder os limites do indexador para sua camada de serviço de pesquisa.
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, mas se você estiver usando funções do Azure, verifique se a identidade gerenciada do serviço de pesquisa tem permissões de Leitor de Dados de Blob de Armazenamento.
Use um cliente REST para formular chamadas REST semelhantes às mostradas neste artigo.

Nota

O ADLS Gen2 implementa um modelo de controle de acesso que dá suporte ao controle de acesso baseado em função do Azure (Azure RBAC) e às ACLs (listas de controle de acesso) semelhantes ao POSIX no nível de blob. O Azure AI Search não oferece suporte a permissões no nível do 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 forem um requisito do aplicativo, considere a filtragem de segurança como uma solução potencial.

Formatos de documento suportados

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

Determinar quais blobs indexar

Antes de configurar a indexação, revise os dados de origem para determinar se as alterações devem ser feitas antecipadamente. Um indexador pode indexar conteúdo de um contêiner de cada vez. Por padrão, todos os blobs no contêiner são processados. Você tem várias opções para um processamento mais seletivo:

Coloque blobs em uma pasta virtual. Uma definição de fonte de dados indexadora inclui um parâmetro "query" que pode usar uma pasta virtual. Se você especificar uma pasta virtual, somente os blobs na pasta serão indexados.
Inclua ou exclua blobs por tipo de arquivo. A lista de formatos de documento suportados pode ajudá-lo a determinar quais blobs devem ser excluídos. Por exemplo, talvez você queira excluir arquivos de imagem ou áudio que não forneçam texto pesquisável. Esta capacidade é controlada através de definições de configuração no indexador.

Incluir ou excluir blobs arbitrários. Se quiser ignorar um blob específico por qualquer motivo, você pode adicionar as seguintes propriedades e valores de metadados aos blobs no Armazenamento de Blobs. Quando um indexador encontra essa propriedade, ele ignora o blob ou seu conteúdo na execução de indexação.

Nome da propriedade	Valor do imóvel	Explicação
"AzureSearch_Skip"	`"true"`	Instrui o indexador de blob a ignorar completamente o blob. Nem metadados nem extração de conteúdo são tentados. 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 à `"dataToExtract" : "allMetadata"` configuração descrita em 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 prosseguirá. Se ocorrerem erros suficientes, o processamento pode parar. Você pode especificar tolerância a erros nas definições de configuração do indexador.

Um indexador normalmente cria um documento de pesquisa por blob, onde o conteúdo de texto e os metadados são capturados como campos pesquisáveis em um índice. Se os blobs forem arquivos inteiros, você poderá 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 de metadados de blob

Os metadados de Blob também podem ser indexados, e isso é útil se você acha 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, você deve definir campo no índice de pesquisa do tipo Edm.String, com o mesmo nome da chave de metadados do blob. Por exemplo, se um blob tiver uma chave de metadados com valor High, você deve definir um campo nomeado Sensitivity em seu índice de Sensitivity pesquisa e ele será preenchido com o valor High.

As propriedades de metadados de blob padrão podem ser extraídas em campos com nomes e tipos semelhantes, 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") em um nome equivalente sublinhado ("metadata_storage_name").

Você ainda precisa adicionar os campos sublinhados à definição de índice, mas pode omitir 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) - 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 modificado pela última vez para o blob. O Azure AI Search usa esse carimbo de data/hora para identificar blobs alterados, para evitar a reindexação de tudo 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 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 pode expirar.

Por fim, quaisquer propriedades de metadados específicas para o formato de documento dos blobs que você está indexando 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 salientar que você não precisa definir campos para todas as propriedades acima em seu í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, 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.

Crie ou atualize uma fonte de dados para definir 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 Azure. A próxima seção descreve os formatos suportados.
Defina "container" para o contêiner de blob 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 contêiner de blob usando as seguintes conexões.

Cadeia de conexão da conta de armazenamento de acesso total
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
Você pode obter a cadeia de conexão na página Conta de armazenamento no portal do Azure selecionando Teclas de acesso no painel de navegação esquerdo. Certifique-se de selecionar uma cadeia de conexão completa e 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 requer uma chave de conta, mas você deve ter configurado anteriormente um serviço de pesquisa para se conectar usando uma identidade gerenciada.

Cadeia de conexão 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;" }`
O SAS deve ter a lista e permissões de leitura em contêineres e objetos (blobs neste caso).

Nota

Se você usar credenciais SAS, precisará atualizar as credenciais da fonte de dados periodicamente com assinaturas renovadas para evitar 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 conteúdo de blob e metadados:

{
    "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 de documento ("chave": 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 arquivo. O campo chave ("ID" neste exemplo) será preenchido com valores de metadata_storage_path porque é o padrão.
- metadata_storage_name, utilizável apenas se os nomes forem exclusivos. Se pretender que este campo seja a chave, avance "key": true para esta definição de campo.
- 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.
As propriedades de metadados geralmente incluem caracteres, como / e -, que são inválidos para chaves de documento. Como o indexador tem uma propriedade "base64EncodeKeys" (true por padrão), ele codifica automaticamente a propriedade de metadados, sem necessidade de configuração ou mapeamento de campo.
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.
Adicione campos para propriedades de metadados padrão. O indexador pode ler propriedades de metadados personalizados, propriedades de metadados padrão e propriedades de metadados específicos de conteúdo.

Configurar e executar o indexador ADLS Gen2

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. Você também pode especificar quais partes de um blob devem ser indexadas.

Crie ou atualize um indexador dando-lhe um nome e fazendo referência à fonte de dados e ao í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 (10 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 Blob define o tamanho do lote em 10 documentos em reconhecimento ao tamanho médio maior do documento.
Em "configuração", controle quais blobs são indexados com base no tipo de arquivo ou deixe não especificado para recuperar todos os blobs.

Para "indexedFileNameExtensions", forneça uma lista separada por vírgulas de extensões de arquivo (com um ponto à esquerda). Faça o mesmo para "excludedFileNameExtensions" indicar quais extensões devem ser ignoradas. Se a mesma extensão estiver em ambas as listas, ela será excluída da indexação.
Em "configuration", defina "dataToExtract" para controlar quais partes dos blobs são indexadas:
- "contentAndMetadata" especifica que todos os metadados e conteúdo textual extraídos do blob são indexados. Este é o valor predefinido.
- "storageMetadata" especifica que apenas 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 de blob e indexados.
Em "configuração", defina "parsingMode" se os blobs devem ser mapeados para vários documentos de pesquisa ou se consistirem em texto simples, documentos JSON ou arquivos CSV.
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 blob, 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.
Consulte Criar um indexador para obter mais informações sobre outras propriedades. Para obter a lista completa de descrições de parâmetros, consulte Parâmetros de configuração de Blob na API REST.

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=2023-11-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":"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çã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.

Processar 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 blob para assim que encontra um blob com um tipo de conteúdo não suportado (por exemplo, um arquivo de áudio). Você pode usar o parâmetro "excludedFileNameExtensions" para ignorar determinados tipos de conteúdo. No entanto, convém que a indexação prossiga mesmo se ocorrerem erros e, em seguida, depure documentos individuais mais tarde. Para obter mais informações sobre erros do indexador, consulte 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	Description
"maxFailedItems"	-1, nulo ou 0, inteiro positivo	Continue a indexação se ocorrerem erros em qualquer ponto do processamento, seja ao analisar blobs ou ao adicionar documentos a um índice. Defina essas propriedades para o número de falhas aceitáveis. Um valor de `-1` permite o processamento, não importa quantos erros ocorram. Caso contrário, o valor é um inteiro positivo.
"maxFailedItemsPerBatch"	-1, nulo ou 0, inteiro positivo	O mesmo que acima, mas usado para indexação em lote.
"failOnUnsupportedContentType"	verdadeiro ou falso	Se o indexador não conseguir determinar o tipo de conteúdo, especifique se deseja continuar ou falhar o trabalho.
"failOnUnprocessableDocument"	verdadeiro ou falso	Se o indexador não conseguir processar um documento de um tipo de conteúdo suportado de outra forma, especifique se deseja continuar ou falhar o trabalho.
"indexStorageMetadataOnlyForOversizedDocuments"	verdadeiro ou falso	Blobs superdimensionados são tratados como erros por padrão. 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 limites no tamanho do blob, consulte Limites do serviço.

Limitações

Ao contrário dos indexadores de blob, os indexadores 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 a API Filesystem - Get properties. Para contas de armazenamento em que namespaces hierárquicos não estão habilitados, recomenda-se 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 é garantido que os blobs sejam reindexados após uma renomeação de diretório. Se desejar reindexar os blobs que fazem parte dos diretórios renomeados, atualize os LastModified carimbos de data/hora de todos eles.

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:

Partilhar via