Compartilhar via

Indexar dados do Armazenamento de Tabelas do Azure

  • Artigo

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 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

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.

Cadeia de conexão da conta de armazenamento com acesso completo
{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }
Você pode obter a cadeia de conexão na página da conta de Armazenamento no portal do Azure selecionando Chaves de acesso no painel de navegação à esquerda. Você deve selecionar uma cadeia de conexão completa, 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 exige uma chave de conta, mas você precisa já ter configurado um serviço de pesquisa para se conectar usando uma identidade gerenciada.
Cadeia de conexão da 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;" }
A SAS deve ter as permissões de listagem e de leitura nas tabelas e entidades.
Assinatura de acesso compartilhado do 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;" }
As SAS devem ter a lista e permissões de leitura no contêiner. Para obter mais informações, confira Como usar assinaturas de acesso compartilhado.

Observação

Se você usar credenciais SAS, você precisará atualizar as credenciais de fonte de dados periodicamente com assinaturas renovadas para impedir sua expiração. Quando 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".

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 importar dados para criar o índice, o portal 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.

    Captura de tela do conteúdo da tabela no navegador de armazenamento.

    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 histórico de execuções e o status do indexador, 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. Ela deve ser parecida com o seguinte exemplo:

    {
        "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: