Indexação do Armazenamento de Tabelas do Azure com o Azure SearchIndex Azure Table storage with Azure Search

Este artigo mostra como usar o Azure Search para indexar dados armazenados no Armazenamento de Tabelas do Azure.This article shows how to use Azure Search to index data stored in Azure Table storage.

Indexador do Armazenamento de Tabelas do AzureSet up Azure Table storage indexing

Você pode configurar um indexador de armazenamento de Tabela do Azure usando estes recursos:You can set up an Azure Table storage indexer by using these resources:

Aqui, demonstraremos o fluxo usando a API REST.Here we demonstrate the flow by using the REST API.

Etapa 1: Criar uma fonte de dadosStep 1: Create a datasource

Uma fonte de dados especifica quais dados indexar, as credenciais necessárias para acessar os dados e as políticas que permitem ao Azure Search identificar com eficiência as alterações nos dados.A datasource specifies which data to index, the credentials needed to access the data, and the policies that enable Azure Search to efficiently identify changes in the data.

Para a indexação de tabela, a fonte de dados deve ter as seguintes propriedades:For table indexing, the datasource must have the following properties:

  • nome é o nome exclusivo da fonte de dados dentro de seu serviço de pesquisa.name is the unique name of the datasource within your search service.
  • type deve ser azuretable.type must be azuretable.
  • O parâmetro credentials contém a cadeia de conexão da conta de armazenamento.credentials parameter contains the storage account connection string. Consulte a seção Especificar credenciais para obter detalhes.See the Specify credentials section for details.
  • contêiner define o nome da tabela e uma consulta opcional.container sets the table name and an optional query.
    • Especifique o nome da tabela usando o parâmetro name.Specify the table name by using the name parameter.
    • Opcionalmente, especifique uma consulta usando o parâmetro query.Optionally, specify a query by using the query parameter.

Importante

Sempre que possível, use um filtro em PartitionKey para obter um melhor desempenho.Whenever possible, use a filter on PartitionKey for better performance. Qualquer outra consulta faz uma verificação de tabela completa, resultando em mau desempenho se usada em grandes tabelas.Any other query does a full table scan, resulting in poor performance for large tables. Consulte a seção Considerações sobre desempenho.See the Performance considerations section.

Para criar uma fonte de dados:To create a datasource:

POST https://[service name].search.windows.net/datasources?api-version=2019-05-06
Content-Type: application/json
api-key: [admin key]

{
    "name" : "table-datasource",
    "type" : "azuretable",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-table", "query" : "PartitionKey eq '123'" }
}   

Para obter mais informações sobre Criar a API da Fonte de Dados, consulte Criar Fonte de Dados.For more information on the Create Datasource API, see Create Datasource.

Maneiras de especificar credenciaisWays to specify credentials

Você pode fornecer as credenciais para a tabela de uma das seguintes maneiras:You can provide the credentials for the table in one of these ways:

  • Cadeia de conexão da conta de armazenamento com acesso completo: DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key> É possível obter a cadeia de conexão do portal do Azure acessando a folha Conta de armazenamento > Configurações > Chaves (para contas de armazenamento clássicas) ou Configurações > Chaves de acesso (para contas de armazenamento do Azure Resource Manager).Full access storage account connection string: DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key> You can get the connection string from the Azure portal by going to the Storage account blade > Settings > Keys (for classic storage accounts) or Settings > Access keys (for Azure Resource Manager storage accounts).
  • Cadeia de conexão da assinatura de acesso compartilhado da conta de armazenamento: TableEndpoint=https://<your account>.table.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=t&sp=rl A assinatura de acesso compartilhado deve ter a lista e permissões de leitura nos contêineres (tabelas, neste caso) e objetos (linhas de tabela).Storage account shared access signature connection string: TableEndpoint=https://<your account>.table.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=t&sp=rl The shared access signature should have the list and read permissions on containers (tables in this case) and objects (table rows).
  • Assinatura de Acesso Compartilhado de tabela: ContainerSharedAccessUri=https://<your storage account>.table.core.windows.net/<table name>?tn=<table name>&sv=2016-05-31&sig=<the signature>&se=<the validity end time>&sp=r A assinatura de acesso compartilhado deve ter permissões de consulta (leitura) na tabela.Table shared access signature: ContainerSharedAccessUri=https://<your storage account>.table.core.windows.net/<table name>?tn=<table name>&sv=2016-05-31&sig=<the signature>&se=<the validity end time>&sp=r The shared access signature should have query (read) permissions on the table.

Para saber mais sobre assinaturas de acesso compartilhado, confira Uso de assinaturas de acesso compartilhado.For more information on storage shared access signatures, see Using shared access signatures.

Observação

Se você usar credenciais de assinaturas de acesso compartilhado, você precisará atualizar as credenciais de fonte de dados periodicamente com assinaturas renovadas para impedir sua expiração.If you use shared access signature credentials, you will need to update the datasource credentials periodically with renewed signatures to prevent their expiration. Se as credenciais de assinatura de acesso compartilhado expirarem, o indexador falha com uma mensagem de erro semelhante a "Credenciais fornecidas na cadeia de conexão são inválidas ou expiraram."If shared access signature credentials expire, the indexer fails with an error message similar to "Credentials provided in the connection string are invalid or have expired."

Etapa 2: Crie um índiceStep 2: Create an index

O índice especifica os campos em um documento, os atributos e outras construções que modelam a experiência de pesquisa.The index specifies the fields in a document, the attributes, and other constructs that shape the search experience.

Para criar um índice:To create an index:

POST https://[service name].search.windows.net/indexes?api-version=2019-05-06
Content-Type: application/json
api-key: [admin key]

{
      "name" : "my-target-index",
      "fields": [
        { "name": "key", "type": "Edm.String", "key": true, "searchable": false },
        { "name": "SomeColumnInMyTable", "type": "Edm.String", "searchable": true }
      ]
}

Para obter mais informações sobre a criação de índices, consulte Criar Índice.For more information on creating indexes, see Create Index.

Etapa 3: Criar um indexadorStep 3: Create an indexer

Um indexador conecta uma fonte de dados a um índice de pesquisa de destino e fornece um agendamento para automatizar a atualização de dados.An indexer connects a datasource with a target search index and provides a schedule to automate the data refresh.

Após o índice e a fonte de dados terem sido criados, será possível criar o indexador:After the index and datasource are created, you're ready to create the indexer:

POST https://[service name].search.windows.net/indexers?api-version=2019-05-06
Content-Type: application/json
api-key: [admin key]

{
  "name" : "table-indexer",
  "dataSourceName" : "table-datasource",
  "targetIndexName" : "my-target-index",
  "schedule" : { "interval" : "PT2H" }
}

Esse indexador é executado a cada duas horas.This indexer runs every two hours. (O intervalo de agendamento é definido como "PT2H".) Para executar um indexador a cada 30 minutos, defina o intervalo para "PT30M".(The schedule interval is set to "PT2H".) To run an indexer every 30 minutes, set the interval to "PT30M". O intervalo mais curto com suporte é de cinco minutos.The shortest supported interval is five minutes. O agendamento é opcional; se ele for omitido, um indexador será executado apenas uma vez quando for criado.The schedule is optional; if omitted, an indexer runs only once when it's created. No entanto, você pode executar um indexador sob demanda a qualquer momento.However, you can run an indexer on demand at any time.

Para obter mais informações sobre Criar a API do Indexador, consulte Criar Indexador.For more information on the Create Indexer API, see Create Indexer.

Para obter mais informações sobre como definir agendas do indexador, consulte como programar indexadores para o Azure Search.For more information about defining indexer schedules see How to schedule indexers for Azure Search.

Lidar com nomes de campos diferentesDeal with different field names

Algumas vezes, os nomes de campos no índice existente são diferentes dos nomes de propriedades na sua tabela.Sometimes, the field names in your existing index are different from the property names in your table. Você pode usar os mapeamentos de campo para mapear os nomes de propriedade da tabela para os nomes de campo em seu índice de pesquisa.You can use field mappings to map the property names from the table to the field names in your search index. Para saber mais sobre os mapeamentos de campo, consulte Os mapeamentos de campo do Indexador do Azure Search reduzem as diferenças entre fontes de dados e índices de pesquisa.To learn more about field mappings, see Azure Search indexer field mappings bridge the differences between datasources and search indexes.

Manipular chaves de documentoHandle document keys

No Azure Search, a chave do documento identifica exclusivamente um documento.In Azure Search, the document key uniquely identifies a document. Cada índice de pesquisa deve ter exatamente um campo de chave do tipo Edm.String.Every search index must have exactly one key field of type Edm.String. O campo de chave é necessário para cada documento adicionado ao índice.The key field is required for each document that is being added to the index. (Na verdade, ele é o único campo obrigatório.)(In fact, it's the only required field.)

Como as linhas de tabela têm uma chave composta, o Azure Search gera um campo sintético chamado Key que é uma concatenação dos valores de chave de linha e de chave de partição.Because table rows have a compound key, Azure Search generates a synthetic field called Key that is a concatenation of partition key and row key values. Por exemplo, se a PartitionKey de uma linha for PK1 e a RowKey for RK1, o valor do campo Key será PK1RK1.For example, if a row’s PartitionKey is PK1 and RowKey is RK1, then the Key field's value is PK1RK1.

Observação

O valor Key pode conter caracteres inválidos em chaves de documento, como traços.The Key value may contain characters that are invalid in document keys, such as dashes. É possível lidar com caracteres inválidos usando a base64Encode função de mapeamento de campo.You can deal with invalid characters by using the base64Encode field mapping function. Se você fizer isso, lembre-se também de usar a codificação de Base 64 protegida por URL ao transmitir as chaves de documento nas chamadas à API como Pesquisa.If you do this, remember to also use URL-safe Base64 encoding when passing document keys in API calls such as Lookup.

Indexação incremental e detecção de exclusãoIncremental indexing and deletion detection

Ao configurar um indexador de tabela para ser executado em um agendamento, ele reindexará somente linhas novas ou atualizadas, conforme determinado pelo valor Timestamp de uma linha.When you set up a table indexer to run on a schedule, it reindexes only new or updated rows, as determined by a row’s Timestamp value. Você não precisa especificar uma política de detecção de alteração.You don’t have to specify a change detection policy. Indexação incremental é habilitada automaticamente para você.Incremental indexing is enabled for you automatically.

Para indicar que determinados documentos devem ser removidos do índice, você pode usar uma estratégia de exclusão reversível.To indicate that certain documents must be removed from the index, you can use a soft delete strategy. Em vez de excluir uma linha, adicione uma propriedade para indicar que ela foi excluída e configure uma política de detecção de exclusão reversível na fonte de dados.Instead of deleting a row, add a property to indicate that it's deleted, and set up a soft deletion detection policy on the datasource. Por exemplo, a política a seguir considerará que uma linha foi excluída se esta tiver uma propriedade de metadados IsDeleted com o valor "true":For example, the following policy considers that a row is deleted if the row has a property IsDeleted with the value "true":

PUT https://[service name].search.windows.net/datasources?api-version=2019-05-06
Content-Type: application/json
api-key: [admin key]

{
    "name" : "my-table-datasource",
    "type" : "azuretable",
    "credentials" : { "connectionString" : "<your storage connection string>" },
    "container" : { "name" : "table name", "query" : "<query>" },
    "dataDeletionDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy", "softDeleteColumnName" : "IsDeleted", "softDeleteMarkerValue" : "true" }
}   

Considerações sobre o desempenhoPerformance considerations

Por padrão, o Azure Search usa o filtro de consulta a seguir: Timestamp >= HighWaterMarkValue.By default, Azure Search uses the following query filter: 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.Because Azure tables don’t have a secondary index on the Timestamp field, this type of query requires a full table scan and is therefore slow for large tables.

Aqui estão duas abordagens possíveis para melhorar o desempenho de indexação de tabela.Here are two possible approaches for improving table indexing performance. Ambas as abordagens dependem do uso de partições de tabela:Both of these approaches rely on using table partitions:

  • Se seus dados podem ser naturalmente particionados em vários intervalos de partição, crie uma fonte de dados e um indexador correspondente para cada intervalo de partição.If your data can naturally be partitioned into several partition ranges, create a datasource and a corresponding indexer for each partition range. Cada indexador deve processar apenas um intervalo de partição específico, resultando em um melhor desempenho de consulta.Each indexer now has to process only a specific partition range, resulting in better query performance. 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.If the data that needs to be indexed has a small number of fixed partitions, even better: each indexer only does a partition scan. 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:For example, to create a datasource for processing a partition range with keys from 000 to 100, use a query like this:

    "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 nova partição a cada dia ou semana), considere a seguinte abordagem:If your data is partitioned by time (for example, you create a new partition every day or week), consider the following approach:

    • Use uma consulta com o seguinte formato: (PartitionKey ge <TimeStamp>) and (other filters).Use a query of the form: (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.Monitor indexer progress by using Get Indexer Status API, and periodically update the <TimeStamp> condition of the query based on the latest successful high-water-mark value.
    • Com essa abordagem, se você precisar disparar uma reindexação completa, você precisará redefinir a consulta de fonte de dados, além de redefinir o indexador.With this approach, if you need to trigger a complete reindexing, you need to reset the datasource query in addition to resetting the indexer.

Ajude-nos a aprimorar o Azure SearchHelp us make Azure Search better

Se você tiver solicitações de recursos ou ideias para aperfeiçoamentos, envie-os por meio do nosso site UserVoice.If you have feature requests or ideas for improvements, submit them on our UserVoice site.