Dados de índice do Armazenamento de Tabela do Azure

Neste artigo, saiba como configurar um indexador que importa conteúdo do Armazenamento de Tabela do Azure e o torna pesquisável no Azure AI Search. As entradas para o indexador são suas entidades, em uma única tabela. 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 Armazenamento de Tabela 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, 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 contendo 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 funções do Azure, verifique se a identidade gerenciada do serviço de pesquisa tem permissões de Leitor e Acesso a Dados.

Para trabalhar com os exemplos neste artigo, você precisa do portal do Azure ou de um cliente REST. Se estiver a utilizar o portal do Azure, certifique-se de que o acesso a todas as redes públicas está ativado. Outras abordagens para criar um indexador de Tabela do Azure incluem SDKs do Azure.

Tente 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. Instale o Azure Storage Explorer.

3. Faça o download HotelsData_toAzureSearch.csv do GitHub. Este arquivo é um subconjunto do conjunto de dados de exemplo de hotéis interno. Omite a coleção de quartos, 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, em seguida, selecione o arquivo HotelsData_toAzureSearch.csv .

7. Aceite as predefinições. Selecione Importar para carregar os dados.

Você deve ter 50 registros de hotel na tabela com uma partitionKey, rowKey e carimbo de data/hora gerados automaticamente. 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 este campo para pesquisa de texto completo e consultas vetoriais opcionais.

Utilizar o portal do Azure

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

1. Iniciar o assistente.

2. Em Conectar aos seus dados, selecione ou verifique se o tipo de fonte de dados é o Armazenamento de Tabela 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 no Azure AI Search. 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 deseja importar.

4. Especifique um método de autenticação, seja 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 o Azure AI Search para usar uma identidade gerenciada e criar uma atribuição de função no Armazenamento do Azure que conceda permissões de Leitor e Acesso a Dados à identidade, seu indexador poderá se conectar ao armazenamento de tabelas usando a ID e as funções do Microsoft Entra.

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

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

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

   • Guia de início rápido: assistente para importação de dados

   • Guia de início rápido: assistente de importação e vetorização de dados

Utilizar APIs REST

Esta seção demonstra as chamadas de 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, credenciais e políticas para deteção de alterações. Uma fonte de dados é um recurso independente que pode ser usado por vários indexadores.

1. Crie ou atualize uma fonte de dados para definir 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 "credenciais" como uma cadeia de conexão do Armazenamento do Azure. A próxima seção descreve os formatos suportados.

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

5. Opcionalmente, defina "query" para um filtro em PartitionKey. Definir essa propriedade é uma prática recomendada que melhora o desempenho. Se "query" for null, o indexador executará uma verificação de tabela completa, o que pode resultar em baixo desempenho se as tabelas forem grandes.

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

Partição para melhorar o desempenho

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

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

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

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

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

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

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

  • Com essa abordagem, se você precisar acionar uma reindexação completa, redefina a consulta da 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 das entidades da tabela.

1. Crie ou atualize um índice para definir campos de pesquisa que armazenarão conteúdo de 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 de documento ("chave": true), mas permita que o indexador o preencha automaticamente. Um indexador de tabela preenche o campo de chave com chaves de linha e partição concatenadas da tabela. Por exemplo, se PartitionKey de uma linha é 1 e RowKey é 1_123, então o valor da chave é 11_123. Se a chave de partição for nula, apenas a chave de linha será usada.

   Se você estiver usando o assistente Importar dados para criar o índice, o portal do Azure 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 sozinho 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" em seu í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 em seu índice. Por exemplo, se uma entidade se parecer com o exemplo a seguir, seu índice de pesquisa deverá ter campos para HotelName, Descrição e Categoria para receber esses valores.

   

   Usar os mesmos nomes e tipos de dados compatíveis minimiza a necessidade de mapeamentos de campo. Quando 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ê 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.

1. 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-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 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. Consulte Criar um indexador para obter mais informações sobre outras propriedades.

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, verifique o histórico de execução do indexador no portal do Azure ou envie uma solicitação de API REST Get Indexer Status

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çã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.

Próximos passos

Saiba mais sobre como 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:

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