Dados do índice de Armazenamento de Blobs do Azure

Neste artigo, aprenda a configurar um indexante que importa conteúdos de Armazenamento de Blobs do Azure e o torna pesmável em Azure Cognitive Search. As entradas para o indexante são as suas bolhas, num único recipiente. A saída é um índice de pesquisa com conteúdo pesmável e metadados armazenados em campos individuais.

Este artigo complementa Criar um indexante com informações específicas para o Blob Storage. Utiliza as APIs REST para demonstrar um fluxo de trabalho em três partes comum a todos os indexantes: criar uma fonte de dados, criar um índice, criar um indexante. A extração de dados ocorre quando submete o pedido de 'Criar Indexer'.

Os indexantes blob são frequentemente utilizados tanto para o enriquecimento de IA como para o processamento baseado em texto. Este artigo centra-se nos indexadores para indexação baseada em texto, onde apenas o conteúdo textual e metadados são ingeridos para cenários completos de pesquisa de texto.

Pré-requisitos

  • Armazenamento de Blobs do Azure, desempenho standard (v2 de uso geral).

  • Os níveis de acesso para blob storage incluem Hot, Cool e Archive. Apenas Hot and Cool pode ser acedido por indexadores de pesquisa.

  • Blobs fornecendo conteúdo de texto e metadados. Se as bolhas contiverem conteúdo binário ou texto não estruturado, considere adicionar enriquecimento de IA para o processamento de imagem e linguagem natural. O conteúdo do blob não pode exceder os limites do indexante para o seu nível de serviço de pesquisa.

  • Uma configuração de rede suportada e acesso a dados. No mínimo, você precisará de permissões de leitura no Azure Storage. Uma cadeia de ligação de armazenamento que inclui uma chave de acesso lhe dará acesso ao conteúdo de armazenamento. Se em vez disso estiver a utilizar Azure AD logins e funções, certifique-se de que a identidade gerida do serviço de pesquisa tem permissões de Storage Blob Data Reader.

    Por predefinição, tanto a pesquisa como o armazenamento aceitam pedidos de endereços IP públicos. Se a segurança da rede não for uma preocupação imediata, pode indexar dados de blob usando apenas a cadeia de ligação e ler permissões. Quando estiver pronto para adicionar proteções de rede, consulte o Indexer o acesso aos conteúdos protegidos pelas funcionalidades de segurança da rede Azure para obter orientação sobre o acesso aos dados.

  • Um cliente REST, como o Carteiro, para fazer os pedidos descritos neste artigo.

Formatos de documento suportados

O indexante blob pode extrair texto dos seguintes formatos de documento:

  • CSV (ver indexante de bolhas de CSV)
  • EML
  • EPUB
  • .GZ
  • HTML
  • JSON (ver Indexing JSON blobs)
  • KML (XML para representações geográficas)
  • Formatos do Microsoft Office: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG (e-mails outlook), XML (ambos 2003 e 2006 WORD XML)
  • Formatos de Documento Aberto: ODT, ODS, ODP
  • PDF
  • Ficheiros de texto simples (ver também Indexar texto simples)
  • .RTF
  • XML
  • .ZIP

Determinar quais bolhas para indexar

Antes de configurar a indexação, reveja os seus dados de origem para determinar se devem ser feitas alterações à frente. Um indexante pode indexar o conteúdo de um recipiente de cada vez. Por predefinição, todas as bolhas no recipiente são processadas. Tem várias opções para um processamento mais seletivo:

  • Coloque as bolhas numa pasta virtual. Uma definição de fonte de dados indexante inclui um parâmetro de "consulta" que pode tomar uma pasta virtual. Se especificar uma pasta virtual, apenas as bolhas na pasta estão indexadas.

  • Incluir ou excluir bolhas por tipo de ficheiro. A lista de formatos de documento suportados pode ajudá-lo a determinar quais as bolhas a excluir. Por exemplo, pode querer excluir ficheiros de imagem ou áudio que não forneçam texto pesalizável. Esta capacidade é controlada através de definições de configuração no indexante.

  • Incluir ou excluir bolhas arbitrárias. Se quiser saltar uma bolha específica por qualquer motivo, pode adicionar as seguintes propriedades e valores de metadados a bolhas no Blob Storage. Quando um indexante encontra esta propriedade, salta a bolha ou o seu conteúdo na corrida de indexação.

    Nome da propriedade Valor patrimonial Explicação
    "AzureSearch_Skip" "true" Instrui o indexante blob a saltar completamente a bolha. Não se tenta nem metadados nem extração de conteúdo. Isto é útil quando uma determinada bolha falha repetidamente e interrompe o processo de indexação.
    "AzureSearch_SkipContent" "true" Ignora o conteúdo e extrai apenas os metadados. isto é equivalente à "dataToExtract" : "allMetadata" definição descrita nas definições de configuração , apenas com uma determinada bolha.

Se não estabelecer critérios de inclusão ou exclusão, o indexante reportará uma bolha inelegível como um erro e seguirá em frente. Se ocorrerem erros suficientes, o processamento pode parar. Pode especificar tolerância de erro nas definições de configuração do indexante.

Um indexante normalmente cria um documento de pesquisa por blob, onde o conteúdo de texto e metadados são capturados como campos pesjáveis num índice. Se as bolhas forem ficheiros inteiros, pode potencialmente analisá-los em vários documentos de pesquisa. Por exemplo, pode analisar linhas num ficheiro CSV para criar um documento de pesquisa por linha.

Indexação de metadados blob

Os metadados blob também podem ser indexados, e isso é útil se você pensar que alguma das propriedades de metadados padrão ou personalizados será útil em filtros e consultas.

As propriedades de metadados especificados pelo utilizador são extraídas verbatim. Para receber os valores, tem de definir o campo no índice de pesquisa do tipo Edm.String, com o mesmo nome que a tecla de metadados da bolha. Por exemplo, se uma bolha tiver uma chave de Sensitivity metadados com valor High, deverá definir um campo nomeado Sensitivity no seu índice de pesquisa e será povoado com o valor High.

As propriedades de metadados blob standard podem ser extraídas em campos com nome semelhante e dactilografados, conforme listado abaixo. O indexante blob cria automaticamente mapeamentos de campo internos para estas propriedades de metadados blob, convertendo o nome hifenizado original ("nome de armazenamento de metadados") para um nome equivalente sublinhado ("metadata_storage_name").

Ainda tem de adicionar os campos sublinhados à definição de índice, mas pode omitir mapeamentos de campo porque o indexante fará a associação automaticamente.

  • metadata_storage_name (Edm.String) - o nome do ficheiro da bolha. Por exemplo, se tiver uma bolha /meu-recipiente/minha pasta/sub-dobra/resume.pdf, o valor deste campo é resume.pdf.

  • metadata_storage_path (Edm.String) - o URI completo da bolha, 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 especificado pelo código utilizado para carregar a bolha. Por exemplo, application/octet-stream.

  • metadata_storage_last_modified (Edm.DateTimeOffset) - última estampada modificada para a bolha. Azure Cognitive Search usa esta estampagem de tempo para identificar bolhas alteradas, para evitar reindexar tudo após a indexação inicial.

  • metadata_storage_size (Edm.Int64) - tamanho de bolha 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 símbolo SAS temporário que pode ser usado por habilidades personalizadas para ter acesso à bolha. Este token não deve ser guardado para utilização posterior, pois pode expirar.

Por último, quaisquer propriedades de metadados específicas do formato documental das bolhas que está a indexar também podem ser representadas no esquema de índice. Para obter mais informações sobre metadados específicos de conteúdo, consulte as propriedades dos metadados de conteúdo.

É importante salientar que não precisa de definir campos para todas as propriedades acima do seu índice de pesquisa - basta capturar as propriedades que precisa para a sua aplicação.

Definir a fonte de dados

A definição de fonte de dados especifica os dados para indexar, 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 indexantes.

  1. Criar ou atualizar uma fonte de dados para definir a 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. Desagrafe "tipo" para "azureblob" (obrigatório).

  3. Desconfie de "credenciais" a uma cadeia de ligação Azure Storage. A secção seguinte descreve os formatos suportados.

  4. Coloque o "recipiente" no recipiente blob e utilize "consulta" para especificar quaisquer sub-dobradeiras.

Uma definição de fonte de dados também pode incluir políticas de eliminação suave, se pretender que o indexante apague um documento de pesquisa quando o documento de origem estiver sinalizado para eliminação.

Credenciais suportadas e cordas de ligação

Os indexantes podem ligar-se a um recipiente de bolhas utilizando as seguintes ligações.

Cadeia de ligação de conta de armazenamento de acesso completo
{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }
Pode obter o fio de ligação da página de conta de Armazenamento em portal do Azure selecionando as teclas de acesso no painel de navegação esquerdo. Certifique-se de que seleciona uma cadeia de ligação completa e não apenas uma chave.
Cadeia de ligação de identidade gerida
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }
Esta cadeia de ligação não requer uma chave de conta, mas deve ter configurado previamente um serviço de pesquisa para ligar usando uma identidade gerida.
Cadeia de conexão de acesso compartilhado de conta de armazenamento** (SAS)
{ "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 ler permissões em recipientes e objetos (bolhas neste caso).
Assinatura de acesso compartilhado do contentor
{ "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 a lista e ler permissões no recipiente. Para mais informações, consulte usando assinaturas de acesso partilhado.

Nota

Se utilizar credenciais SAS, terá de atualizar periodicamente as credenciais de origem de dados com assinaturas renovadas para evitar a sua expiração. Se as credenciais SAS expirarem, o indexante falhará com uma mensagem de erro semelhante a "As credenciais fornecidas na cadeia de ligação são inválidas ou caducaram".

Adicione campos de pesquisa a um índice

Num índice de pesquisa, adicione campos para aceitar o conteúdo e metadados das suas bolhas Azure.

  1. Criar ou atualizar um índice para definir campos de pesquisa que armazenarão conteúdo e metadados 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 },        
        ]
      }
    }
    
  2. Criar um campo chave de documento ("chave": verdadeiro). Para o conteúdo blob, os melhores candidatos são propriedades de metadados.

    • metadata_storage_path (predefiniçã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 são únicos. Se quiser este campo como chave, passe "key": true para esta definição de campo.

    • Uma propriedade de metadados personalizados que adiciona às bolhas. Esta opção requer que o seu processo de upload de blob adicione essa propriedade de metadados a todas as bolhas. Uma vez que a chave é uma propriedade necessária, quaisquer bolhas que faltem a um valor não serão indexadas. Se utilizar uma propriedade de metadados personalizados como chave, evite fazer alterações nessa propriedade. Os indexantes adicionarão documentos duplicados para a mesma bolha se a propriedade chave mudar.

    As propriedades dos metadados incluem frequentemente caracteres, tais como / , que -são inválidos para as teclas de documento. Como o indexante tem uma propriedade "base64EncodeKeys" (verdadeiro por padrão), codifica automaticamente a propriedade dos metadados, sem necessidade de configuração ou mapeamento de campo.

  3. Adicione um campo de "conteúdo" para armazenar texto extraído de cada ficheiro através da propriedade "conteúdo" da bolha. Não é obrigado a usar este nome, mas fazê-lo permite-lhe tirar partido de mapeamentos de campo implícitos.

  4. Adicione campos para propriedades de metadados padrão. O indexante pode ler propriedades de metadados personalizados, propriedades de metadados padrão e propriedades de metadados específicos do conteúdo .

Configure e executar o indexante blob

Uma vez criado o índice e a fonte de dados, está pronto para criar o indexante. A configuração do indexante especifica as entradas, parâmetros e propriedades que controlam os comportamentos do tempo de execução. Também pode especificar quais as partes de uma bolha a indexar.

  1. Criar ou atualizar um indexante dando-lhe um nome e referindo-se à fonte de dados e ao índice-alvo:

    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" : [ ]
    }
    
  2. Desafinado batchSize se o padrão (10 documentos) for subutilizante ou esmagador dos recursos disponíveis. Os tamanhos predefinidos do lote são específicos da fonte de dados. A indexação da blob define o tamanho do lote em 10 documentos em reconhecimento do tamanho médio do documento maior.

  3. Em "configuração", o controlo que as bolhas são indexadas com base no tipo de ficheiro, ou deixar não especificado para recuperar todas as bolhas.

    Para "indexedFileNameExtensions", fornecer uma lista separada de vírgulas de extensões de ficheiros (com um ponto de referência). Faça o mesmo para "excludedFileNameExtensions" indicar quais as extensões que devem ser ignoradas. Se a mesma extensão estiver em ambas as listas, será excluída da indexação.

  4. Em "configuração", descreva "dataToExtract" para controlar quais as partes das bolhas indexadas:

  5. Em "configuração", descreva "parsingMode" se as bolhas deverão ser mapeadas para vários documentos de pesquisa, ou se forem constituídas por texto simples, documentos JSON ou ficheiros CSV.

  6. Especifique os 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, pode muitas vezes omitir mapeamentos de campo porque o indexante tem suporte incorporado para mapear as propriedades de "conteúdo" e metadados para campos de nome semelhante e dactilografados num índice. Para as propriedades dos metadados, o indexante substituirá automaticamente os hífens - por sublinhados no índice de pesquisa.

  7. Consulte Criar um indexador para obter mais informações sobre outras propriedades. Para obter a lista completa das descrições dos parâmetros, consulte os parâmetros de configuração blob na API REST.

Um indexante funciona automaticamente quando é criado. Pode evitar isto definindo "desativado" para ser verdadeiro. Para controlar a execução do indexante, executar um indexante a pedido ou colocá-lo em um horário.

Verificar o estado do indexador

Para monitorizar o estado do indexante e o histórico de execução, envie um pedido de Estado do Indexante :

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 estado e o número de itens processados. Deve parecer 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 mais recentes concluídas, que são ordenadas na ordem cronológica inversa para que a última execução seja a primeira.

Processar erros

Os erros que ocorrem geralmente durante a indexação incluem tipos de conteúdo não suportados, conteúdo em falta ou bolhas de grandes dimensões.

Por predefinição, o indexante blob para assim que encontra uma bolha com um tipo de conteúdo não suportado (por exemplo, um ficheiro áudio). Pode utilizar o parâmetro "ExclusãoFileNameExtensions" para saltar certos tipos de conteúdo. No entanto, é melhor indexar para proceder mesmo que ocorram erros e, em seguida, depurar documentos individuais mais tarde. Para obter mais informações sobre erros do indexante, consulte a orientação de resolução de problemasdo Indexer e os erros e avisos do Indexer.

Existem cinco propriedades indexantes que controlam a resposta do indexante 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 Description
"maxFailedItems" -1, nulo ou 0, inteiro positivo Continue a indexar se os erros ocorrerem em qualquer ponto de processamento, quer enquanto analisa as bolhas, quer adicionando documentos a um índice. Desa esta aduso destas propriedades para o número de falhas aceitáveis. Um valor de -1 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 de lotes.
"failOnUnsupportedContentType" true ou false Se o indexador não conseguir determinar o tipo de conteúdo, especifique se deve continuar ou falhar o trabalho.
"failOnUnprocessableDocument" true ou false Se o indexador não conseguir processar um documento de um tipo de conteúdo apoiado de outra forma, especifique se deve continuar ou falhar no trabalho.
"indexStorageMetadataOnlyForOversizedDocuments" true ou false As bolhas de grandes dimensões são tratadas como erros por defeito. Se definir este parâmetro como verdadeiro, o indexante tentará indexar os seus metadados mesmo que o conteúdo não possa ser indexado. Para limites no tamanho da bolha, consulte limites de serviço.

Passos seguintes

Pode agora controlar a forma como executa o indexante, monitorizar oestado ou agendar a execução do indexante. Os seguintes artigos aplicam-se aos indexantes que retiram conteúdo do Azure Storage: