Dados do índice do Armazenamento da Tabela Azure

Neste artigo, aprenda a configurar um indexante que importa conteúdo do Azure Table Storage e o torna pespável em Azure Cognitive Search. As entradas para o indexante são as suas entidades, numa única tabela. 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 a indexação a partir do Armazenamento de MesaS Azure. 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'.

Pré-requisitos

  • Table Storage do Azure

  • Tabelas que contêm texto. Se tiver dados binários, pode incluir enriquecimento de IA para análise de imagem.

  • Leia permissões para aceder ao Azure Storage. Uma cadeia de ligação de "acesso total" inclui uma chave que dá acesso ao conteúdo, mas se estiver a utilizar funções Azure, certifique-se de que o serviço de pesquisa gerido tem permissões de Dados e Leitores .

  • Um cliente REST, como o Carteiro, para enviar chamadas REST que criam a fonte de dados, índice e indexante.

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" : "hotel-tables",
        "type" : "azuretable",
        "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
        "container" : { "name" : "tblHotels", "query" : "PartitionKey eq '123'" }
    }
    
  2. Desagrafe "tipo" para "azuretable" (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 nome da tabela.

  5. Opcionalmente, desajei a "consulta" a um filtro no PartitionKey. Esta é uma melhor prática que melhora o desempenho. Se a "consulta" for especificada de outra forma, o indexante executará uma verificação completa da tabela, resultando num mau desempenho se as tabelas forem grandes.

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 uma tabela 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 se 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 mesas e entidades.
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".

Partição para melhor desempenho

Por predefinição, Azure Cognitive Search utiliza o seguinte filtro de consulta interna para acompanhar quais as entidades de origem que foram atualizadas desde a última execução: Timestamp >= HighWaterMarkValue. Como as tabelas Azure não têm um índice secundário no Timestamp campo, este tipo de consulta requer uma digitalização completa da tabela e, portanto, é lento para grandes tabelas.

Para evitar uma varredura completa, pode utilizar divisórias de mesa para reduzir o âmbito de cada trabalho indexante.

  • Se os seus dados puderem naturalmente ser divididos em várias gamas de partição, crie uma fonte de dados e um indexante correspondente para cada intervalo de partição. Cada indexante tem agora de processar apenas uma gama de divisórias específica, resultando num melhor desempenho de consulta. Se os dados que precisam de ser indexados têm um pequeno número de divisórias fixas, melhor ainda: cada indexante faz apenas uma varredura de partição.

    Por exemplo, para criar uma fonte de dados para o processamento de uma gama de divisórias com chaves de 000 , 100utilize uma consulta como esta: "container" : { "name" : "my-table", "query" : "PartitionKey ge '000' and PartitionKey lt '100' " }

  • Se os seus dados forem divididos pelo tempo (por exemplo, se criar uma nova partição todos os dias ou semanas), considere a seguinte abordagem:

    • Na definição de fonte de dados, especifique uma consulta semelhante ao seguinte exemplo: (PartitionKey ge <TimeStamp>) and (other filters).

    • Monitorize o progresso do indexante utilizando a API do Estado do Indexante e atualize periodicamente o <TimeStamp> estado da consulta com base no último valor de marca de alta água bem-sucedido.

    • Com esta abordagem, se precisar de desencadear uma reindexação completa, tem de redefinir a consulta de origem de dados para além de redefinir o indexante.

Adicione campos de pesquisa a um índice

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

  1. Criar ou atualizar um índice para definir campos de pesquisa que armazenarão conteúdo de entidades:

    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": "SomeColumnInMyTable", "type": "Edm.String", "searchable": true }
      ]
    }
    
  2. Crie um campo chave de documento ("chave": verdadeiro), mas permita que o indexante o povoe automaticamente. Não defina um mapeamento de campo para um campo de cordas alternativo único na sua mesa.

    Um indexante de tabela povoa o campo chave com partição concatenated e teclas de linha da mesa. Por exemplo, se uma linha é o PartitionKey PK1 e o RowKey é RK1, então o valor-chave é PK1RK1. Se a chave de partição for nula, apenas a tecla de linha é utilizada.

  3. Criar campos adicionais que correspondam aos campos da entidade. Por exemplo, se uma entidade se parece com o seguinte exemplo, o seu índice de pesquisa deve ter campos para HotelName, Description e Category.

    Screenshot do conteúdo da tabela no navegador de armazenamento.

    A utilização dos mesmos nomes e tipos de dados compatíveis minimiza a necessidade de mapeamentos de campo.

Configure e executar o indexante de tabela

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.

  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" : "table-indexer",
        "dataSourceName" : "my-table-datasource",
        "targetIndexName" : "my-search-index",
        "parameters": {
            "batchSize": null,
            "maxFailedItems": null,
            "maxFailedItemsPerBatch": null,
            "base64EncodeKeys": null,
            "configuration:" { }
        },
        "schedule" : { },
        "fieldMappings" : [ ]
    }
    
  2. 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.

  3. Consulte Criar um indexador para obter mais informações sobre outras propriedades.

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.

Passos seguintes

Pode agora executar o indexante, o estado do monitor ou a execução do indexante. Os seguintes artigos aplicam-se aos indexantes que retiram conteúdo do Azure Storage: