Dados de índice do Armazenamento de Tabela do Azure

Artigo
02/22/2024

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 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 Dados e Leitor.
Use um cliente REST para formular chamadas REST semelhantes às mostradas neste artigo.

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.

Crie ou atualize uma fonte de dados para definir sua definição:

 POST https://[service name].search.windows.net/datasources?api-version=2023-11-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
 }

Defina "type" como "azuretable" (obrigatório).
Defina "credenciais" como uma cadeia de conexão do Armazenamento do Azure. A próxima seção descreve os formatos suportados.
Defina "container" como o nome da tabela.
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.

Cadeia de conexão da conta de armazenamento de acesso total
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
Você pode obter a cadeia de conexão na página Conta de armazenamento no portal do Azure selecionando Teclas de acesso no painel de navegação esquerdo. Certifique-se de selecionar uma cadeia de conexão completa e 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 requer uma chave de conta, mas você deve ter configurado anteriormente um serviço de pesquisa para se conectar usando uma identidade gerenciada.

Cadeia de conexão 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;" }`
O SAS deve ter as permissões de lista e leitura em tabelas e entidades.

Assinatura de acesso compartilhado de 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;" }`
O SAS deve ter as permissões de lista e leitura no contêiner. Para obter mais informações, consulte Usando assinaturas de acesso compartilhado.

Nota

Se você usar credenciais SAS, precisará atualizar as credenciais da fonte de dados periodicamente com assinaturas renovadas para evitar 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 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.

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=2023-11-01 
{
  "name" : "my-search-index",
  "fields": [
    { "name": "Key", "type": "Edm.String", "key": true, "searchable": false },
    { "name": "SomeColumnInMyTable", "type": "Edm.String", "searchable": true }
  ]
}

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 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"
   }
]
```
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.

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=2023-11-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,
        "base64EncodeKeys" : null,
        "configuration" : { }
    },
    "fieldMappings" : [ ],
    "cache": null,
    "encryptionKey": null
}

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"
   }
]
```
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, envie uma solicitação Obter Status do Indexador:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2023-11-01
  Content-Type: application/json  
  api-key: [admin key]

A resposta inclui o status e o número de itens processados. Deve ser semelhante ao 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çã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: