Indexar dados do Armazenamento de Tabelas do Azure

Neste artigo, saiba como configurar um indexador que importa o conteúdo da tabela do Armazenamento do Azure e o torna pesquisável na Pesquisa de IA do Azure. As entradas para o indexador são suas entidades, em uma só tabela. 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 de indexação do Armazenamento de Tabelas do Azure. Ele usa o portal do Azure e 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.

Pré-requisitos

• Armazenamento de Tabelas do Azure

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

• Permissões de leitura no Armazenamento do Azure. Uma cadeia de conexão de "acesso total" inclui uma chave que dá acesso ao conteúdo, mas se você estiver usando as funções do Azure, verifique se a identidade gerenciada do serviço de pesquisa tem as permissões Acesso a Dados e Leitor.

Para trabalhar nos exemplos deste artigo, você precisa do portal do Azure ou de um cliente REST. Se você estiver usando o portal do Azure, verifique se o acesso a todas as redes públicas está habilitado. Outras abordagens para criar um indexador de Tabela do Azure incluem os SDKs do Azure.

Experimente com dados de exemplo

Use estas instruções para criar uma tabela no Armazenamento do Azure para fins de teste.

1. Entre no portal do Azure, navegue até sua conta de armazenamento e crie uma tabela chamada hotéis.

2. Instalar o Gerenciador de Armazenamento do Azure.

3. Download HotelsData_toAzureSearch.csv do GitHub. Esse arquivo é um subconjunto do conjunto de dados de exemplo de hotéis internos. Ele omite a coleção de salas, descrições traduzidas e coordenadas geográficas.

4. No Gerenciador de Armazenamento do Azure, entre no Azure, selecione sua assinatura e selecione sua conta de armazenamento.

5. Abra Tabelas e selecione hotéis.

6. Selecione Importar na barra de comandos e selecione o arquivo HotelsData_toAzureSearch.csv.

7. Aceite os padrões. Selecione Importar para carregar os dados.

Você deve ter 50 registros de hotel na tabela com uma partitionKey gerada automaticamente, rowKey e carimbo de data/hora. Agora você pode usar esse conteúdo para indexação no portal do Azure, no cliente REST ou em um SDK do Azure.

O campo Descrição fornece o conteúdo mais detalhado. Você deve direcionar esse campo para pesquisa de texto completo e consultas de vetor opcionais.

Use o Portal do Azure

Você pode usar o assistente Importar dados ou Assistente para Importar e vetorizar dados para automatizar a indexação de uma tabela ou exibição do banco de dados SQL. A configuração da fonte de dados é semelhante para ambos os assistentes.

1. Inicie o assistente.

2. Em Conecte-se aos seus dados, selecione ou verifique se o tipo de fonte de dados está no Armazenamento de Tabelas do Azure ou se os campos de seleção de dados solicitam tabelas.

   O nome da fonte de dados refere-se ao objeto de conexão da fonte de dados na Pesquisa de IA do Azure. Se você usar o assistente de vetor, o nome da fonte de dados será gerado automaticamente usando um prefixo personalizado especificado no final do fluxo de trabalho do assistente.

3. Especifique a conta de armazenamento e o nome da tabela. A consulta é opcional. É útil se você tiver colunas específicas que quer importar.

4. Especifique um método de autenticação, uma identidade gerenciada ou uma chave de API interna. Se você não especificar uma conexão de identidade gerenciada, o portal do Azure usará a chave.

   Se você configurar a Pesquisa de IA do Azure para usar uma identidade gerenciada e criar uma atribuição de função no Armazenamento do Azure que conceda permissões Acesso a Leitor e Dados à identidade, o indexador poderá se conectar ao armazenamento de tabelas usando as funções do Microsoft Entra ID.

5. Para o assistente Importar e vetorizar dados, você pode especificar opções para a detecção de exclusão,

   A detecção de exclusão requer que você tenha um campo pré-existente na tabela que possa ser usado como um sinalizador de exclusão reversível. Deve ser um campo booliano (você pode nomeá-lo IsDeleted). Especifique true como o valor de exclusão reversível. No índice de pesquisa, adicione um campo de pesquisa correspondente chamado IsDeleted definido como recuperável e filtre.

6. Continue com as etapas restantes para concluir o assistente:

   • Início Rápido: assistente de importação de dados

   • Início Rápido: assistente de importação e vetorização de dados

Usar as APIs REST

Essa seção demonstra as chamadas à API REST que criam uma fonte de dados, um índice e um indexador.

Definir a fonte de dados

A definição da fonte de dados especifica os dados de origem a serem indexados, as credenciais e as políticas para detecção de alterações. Uma fonte de dados é um recurso independente que pode ser usada por vários indexadores.

1. Crie ou atualize uma fonte de dados para configurar sua definição:

    POST https://[service name].search.windows.net/datasources?api-version=2024-07-01 
    {
        "name": "my-table-storage-ds",
        "description": null,
        "type": "azuretable",
        "subtype": null,
        "credentials": {
           "connectionString": "DefaultEndpointsProtocol=https;AccountName=<account name>"
        },
        "container": {
           "name": "my-table-in-azure-storage",
           "query": ""
        },
        "dataChangeDetectionPolicy": null,
        "dataDeletionDetectionPolicy": null,
        "encryptionKey": null,
        "identity": null
    }
   

2. Defina "type" como "azuretable" (obrigatório).

3. Defina "credentials" para uma cadeia de conexão do Armazenamento do Microsoft Azure. A próxima seção descreve os formatos compatíveis.

4. Defina "container" como o nome da tabela.

5. Opcionalmente, defina "query" como um filtro em PartitionKey. A configuração desta propriedade é uma melhor prática que aprimora o desempenho. Se "query" for nulo, o indexador executará uma verificação de tabela completa, que poderá resultar em baixo desempenho se as tabelas forem grandes.

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 uma tabela usando as conexões a seguir.

Partição para aprimorar o desempenho

Por padrão, a Pesquisa de IA do Azure usará o seguinte filtro de consulta interno para controlar quais entidades de origem foram atualizadas desde a última execução: Timestamp >= HighWaterMarkValue. Já que as tabelas do Azure não têm um índice secundário no campo Timestamp, esse tipo de consulta requer uma verificação completa e, portanto, é lenta para tabelas grandes.

Para evitar uma verificação completa, você pode usar partições de tabela para restringir o escopo de cada trabalho do indexador.

• Se seus dados podem ser particionados naturalmente em vários intervalos de partição, crie uma fonte de dados e um indexador correspondente para cada intervalo de partição. Cada indexador deve processar apenas um intervalo de partição específico, resultando em um melhor desempenho de consulta. Se os dados que precisam ser indexados têm um pequeno número de partições fixas, isso é ainda melhor: nesse caso, cada indexador faz apenas uma verificação de partição.

  Por exemplo, para criar uma fonte de dados para o processamento de um intervalo de partição com chaves de 000 a 100, use uma consulta como esta: "container" : { "name" : "my-table", "query" : "PartitionKey ge '000' and PartitionKey lt '100' " }

• Se os dados são particionados por hora (por exemplo, se você cria uma partição a cada dia ou semana), considere a seguinte abordagem:

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

  • Monitore o progresso do indexador usando a API Obter Status do Indexador e atualize periodicamente a condição <TimeStamp> da consulta com base no valor de marca d'água alta bem-sucedido mais recente.

  • Com essa abordagem, se você precisar disparar uma reindexação completa, redefinirá a consulta de fonte de dados, além de redefinir o indexador.

Adicionar campos de pesquisa a um índice

Em um índice de pesquisa, adicione campos para aceitar o conteúdo e os metadados de suas entidades de tabela.

1. Crie ou atualize um índice para definir os campos de pesquisa que armazenarão o conteúdo das entidades:

   POST https://[service name].search.windows.net/indexes?api-version=2024-07-01 
   {
     "name" : "my-search-index",
     "fields": [
       { "name": "Key", "type": "Edm.String", "key": true, "searchable": false },
       { "name": "SomeColumnInMyTable", "type": "Edm.String", "searchable": true }
     ]
   }
   

2. Crie um campo de chave do documento ("key": true), mas permita que o indexador o preencha automaticamente. Um indexador de tabela preenche o campo de chave com a partição concatenada e as chaves de linha da tabela. Por exemplo, se a PartitionKey de uma linha for 1 e a RowKey for 1_123, o valor da chave será 11_123. Se a chave de partição for nula, apenas a chave de linha será usada.

   Se você estiver usando o Assistente para Importação de Dados para criar o índice, o portal do Azure vai inferir um campo “Chave” para o índice de pesquisa e usar um mapeamento de campo implícito para conectar os campos de origem e destino. Você não precisa adicionar o campo por conta própria e não precisa configurar um mapeamento de campo.

   Se você estiver usando as APIs REST e quiser mapeamentos de campo implícitos, crie e nomeie o campo de chave do documento como "Chave" na definição do índice de pesquisa, conforme mostrado na etapa anterior ({ "name": "Key", "type": "Edm.String", "key": true, "searchable": false }). O indexador preenche o campo Chave automaticamente, sem necessidade de mapeamentos de campo.

   Se você não quiser um campo chamado "Chave" no índice de pesquisa, adicione um mapeamento de campo explícito na definição do indexador com o nome de campo desejado, definindo o campo de origem como "Chave":

    "fieldMappings" : [
      {
        "sourceFieldName" : "Key",
        "targetFieldName" : "MyDocumentKeyFieldName"
      }
   ]
   

3. Agora, adicione quaisquer outros campos de entidade que você deseja no índice. Por exemplo, se uma entidade for parecida com o exemplo a seguir, o índice de pesquisa deverá ter campos para HotelName, Description e Category para receber esses valores.

   

   Usar os mesmos nomes e tipos de dados compatíveis minimiza a necessidade de mapeamentos de campo. Quando os nomes e tipos são os mesmos, o indexador pode determinar o caminho de dados automaticamente.

Configurar e executar o indexador de tabela

Depois de ter um índice e uma fonte de dados, você poderá 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.

1. Crie ou atualize um indexador dando um nome a ele e referenciando a fonte de dados e o índice de destino:

   POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
   {
       "name" : "my-table-indexer",
       "dataSourceName" : "my-table-storage-ds",
       "targetIndexName" : "my-search-index",
       "disabled": null,
       "schedule": null,
       "parameters" : {
           "batchSize" : null,
           "maxFailedItems" : null,
           "maxFailedItemsPerBatch" : null,
           "configuration" : { }
       },
       "fieldMappings" : [ ],
       "cache": null,
       "encryptionKey": null
   }
   

2. 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. O campo Destino é o nome do campo no índice de pesquisa.

    "fieldMappings" : [
      {
        "sourceFieldName" : "Description",
        "targetFieldName" : "HotelDescription"
      }
   ]
   

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

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 status do indexador e o histórico de execução, verifique o histórico de execução do indexador no portal do Azure ou envie uma APIrequest REST 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]

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2023-02-21T00:23:24.957Z",
            "endTime":"2023-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2023-02-21T00:23:24.957Z",
                "endTime":"2023-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.

Próximas etapas

Saiba mais sobre como executar o indexador, monitorar o status ou agendar a execução do indexador. Os seguintes artigos se aplicam a indexadores que efetuam pull do conteúdo do Armazenamento do Microsoft Azure:

• Tutorial: indexar blobs JSON do Armazenamento do Azure
• Tutorial: indexar blobs criptografados no Armazenamento do Azure