Dados de índice do Armazenamento de Blobs do Azure

Artigo
11/19/2024

Neste artigo, saiba como configurar um indexador que importa conteúdo 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 um único contêiner. A saída é um índice de pesquisa com conteúdo pesquisável e metadados armazenados em campos individuais.

Para configurar e executar o indexador, você pode usar:

API REST do Serviço de Pesquisa, qualquer versão.
Um pacote SDK do Azure, qualquer versão.
Assistente de importação de dados no portal do Azure.
Assistente de importação e vetorização de dados no portal do Azure.

Este artigo usa as APIs REST para ilustrar cada etapa.

Pré-requisitos

Armazenamento de Blobs do Azure, desempenho padrão (v2 de uso geral).
As camadas de acesso incluem quente, frio, frio e arquivamento. Os indexadores podem recuperar blobs em camadas de acesso quente, fria e fria.
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 de Blob não pode exceder os limites do indexador para sua camada de serviço de pesquisa.
Uma configuração de rede suportada e acesso a dados. No mínimo, você precisa de permissões de leitura no Armazenamento do Azure. Uma cadeia de conexão de armazenamento que inclui uma chave de acesso oferece acesso de leitura ao conteúdo de armazenamento. Se, em vez disso, você estiver usando logins e funções do Microsoft Entra, verifique se a identidade gerenciada do serviço de pesquisa tem permissões de Leitor de Dados de Blob de Armazenamento .

Por padrão, tanto a pesquisa quanto o armazenamento aceitam solicitações de endereços IP públicos. Se a segurança da rede não for uma preocupação imediata, você poderá indexar 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 Acesso do indexador a conteúdo protegido por recursos de segurança de rede do Azure para obter orientação sobre o acesso a dados.
Use um cliente REST para formular chamadas REST semelhantes às mostradas neste artigo.

Tarefas suportadas

Você pode usar esse indexador para as seguintes tarefas:

Indexação de dados e indexação incremental: o indexador pode indexar arquivos e metadados associados de contêineres e pastas de blob. Ele deteta arquivos e metadados novos e atualizados por meio da deteção de alterações integrada. Você pode configurar a atualização de dados em um cronograma ou sob demanda.
Deteção de exclusão: O indexador pode detetar exclusões por meio de soft delete nativo ou por meio de metadados personalizados.
IA aplicada através de conjuntos de competências: Os conjuntos de competências são totalmente suportados pelo indexador. Isso inclui recursos importantes, como vetorização integrada que adiciona etapas de fragmentação e incorporação de dados.
Modos de análise: o indexador suporta modos de análise JSON se você quiser analisar matrizes ou linhas JSON em documentos de pesquisa individuais. Ele também suporta o modo de análise Markdown.
Compatibilidade com outros recursos: o indexador foi projetado para funcionar perfeitamente com outros recursos do indexador, como sessões de depuração, cache do indexador para enriquecimento incremental e armazenamento de conhecimento.

Formatos de documento suportados

O indexador de blob 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 seguir em frente. 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.

Um documento composto ou incorporado (como um arquivo ZIP, um documento do Word com email do Outlook incorporado contendo anexos ou um arquivo . MSG com anexos) também é indexado como um único documento. Por exemplo, todas as imagens extraídas dos anexos de um arquivo . O arquivo MSG será retornado no campo normalized_images. Se você tiver imagens, considere adicionar enriquecimento de IA para obter mais utilidade de pesquisa desse conteúdo.

O conteúdo textual de um documento é extraído em um campo de cadeia de caracteres chamado "conteúdo". Você também pode extrair metadados padrão e definidos pelo usuário.

Indexação de metadados de blob

Os metadados de Blob também podem ser indexados, e isso é útil se você achar que qualquer uma das propriedades de metadados padrão ou personalizada é ú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 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) - 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.

Atualmente, a indexação de tags de índice de blob não é suportada por esse indexador.

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-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 "credenciais" 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 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).

Assinatura de acesso compartilhado de 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;" }`
O SAS deve ter as permissões de lista e leitura no contêiner. Para obter mais informações, consulte Usando assinaturas de acesso compartilhado.

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:

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 },        
    ]
}

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. No entanto, o indexador codifica automaticamente a propriedade de metadados de chave, 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 de blob

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:

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" : [ ]
}

Defina batchSize se o padrão (10 documentos) está 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 "configuration", defina "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 um melhor desempenho alternando para a análise de texto sem formatação. Se você precisar de uma análise mais granular que mapeie blobs para vários documentos de pesquisa, especifique um modo diferente. A análise um-para-muitos é suportada para blobs que consistem em:
- Documentos JSON
- Ficheiros 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 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.

Indexação de dados de vários contêineres de Blob 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 de pesquisa de IA, isso pode ser alcançado configurando vários indexadores, todos direcionados para o mesmo índice. Por favor, 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 chamado 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 que é executada em exemplo paralelo:

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" : [ ]
}

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=2024-07-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":"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çã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 indexar para continuar mesmo se ocorrerem erros e, em seguida, depurar 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=2024-07-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.

Partilhar via