Tutorial: Consulta do Azure Cosmos DB através da API de Tabela

APLICA-SE A: API de Tabela

A API de Tabela DB de Tabela do Azure Cosmos suporta consultas OData e LINQ em dados de chave/valor (tabela).

Este artigo abrange as seguintes tarefas:

  • Consulta de dados com a API de Tabela

As consultas neste artigo utilizam a seguinte tabela de People exemplo:

PartitionKey RowKey E-mail NúmeroNumEmpresa
Arápia Telão Walter@contoso.com 425-555-0101
Silva Ben Ben@contoso.com 425-555-0102
Silva Jeff Jeff@contoso.com 425-555-0104

Consulte Consulta de Tabelas e Entidades para obter detalhes sobre como consultas através da API de Tabela.

Para obter mais informações sobre as funcionalidades premium que o Azure Cosmos DB oferece, consulte API de Tabela DB e Programar com a API de Tabela no .NET.

Pré-requisitos

Para que estas consultas funcionem, tem de ter uma conta do Azure Cosmos DB e ter dados de entidade no contentor. Não tem nenhum destes? Conclua o guia de introdução de cinco minutos ou o tutorial para programadores para criar uma conta e preencher a sua base de dados.

Consulta emKey PartitionKey e RowKey

Uma vez que as propriedades ChavePartition e RowKey formam a chave primária de uma entidade, pode utilizar a seguinte sintaxe especial para identificar a entidade:

Consulta

https://<mytableendpoint>/People(PartitionKey='Harp',RowKey='Walter')  

Resultados

PartitionKey RowKey E-mail NúmeroNumEmpresa
Arápia Telão Walter@contoso.com 425-555-0104

Em alternativa, pode especificar estas propriedades como parte $filter da opção, conforme apresentado na secção seguinte. Tenha em atenção que os nomes das propriedades chave e os valores constantes são sensíveis às caixas e às caixas. Ambas as propriedades PartitionKey e RowKey são do tipo Cadeia.

Consulta utilizando um filtro OData

Ao construir uma cadeia de filtros, tenha em atenção estas regras:

  • Utilize os operadores lógicos definidos pela Especificação do Protocolo OData para comparar uma propriedade a um valor. Tenha em atenção que não pode comparar uma propriedade a um valor dinâmico. Um lado da expressão tem de ser uma constante.
  • O nome da propriedade, operador e valor constante têm de ser separados por espaços codificados por URL. Um espaço é codificado como URL como %20 .
  • Todas as partes da cadeia de filtros são sensíveis às caixas e às caixas.
  • O valor constante tem de ser do mesmo tipo de dados que a propriedade para que o filtro devolva resultados válidos. Para obter mais informações sobre os tipos de propriedade suportados, consulte Compreender o Modelo de Dados de Serviço de Tabela.

Eis uma consulta de exemplo que mostra como filtrar pelas propriedades ParttionKey e Email ao utilizar $filter OData.

Consulta

https://<mytableapi-endpoint>/People()?$filter=PartitionKey%20eq%20'Smith'%20and%20Email%20eq%20'Ben@contoso.com'

Para obter mais informações sobre como construir expressões de filtro para vários tipos de dados, consulte Consultando Tabelas e Entidades.

Resultados

PartitionKey RowKey E-mail NúmeroNumEmpresa
Silva Ben Ben@contoso.com 425-555-0102

As consultas nas propriedades de datetime não devolvem dados quando executados na API de Tabela do Azure Cosmos DB. Enquanto o armazenamento da Tabela do Azure armazena valores de data com a granularidade de tempo de marcações, a API de Tabela no Azure Cosmos DB utiliza a _ts propriedade. A _ts propriedade está num segundo nível de granularidade, que não é um filtro OData. Por isso, as consultas nas propriedades de cronologia são bloqueadas pelo Azure Cosmos DB. Como soluções, pode definir uma propriedade de tipo de dados datetime ou tipo de dados longo personalizado e definir o valor de data do cliente.

Consulta utilizando LINQ

Também pode ecorrer uma consulta utilizando LINQ, que traduz as expressões de consulta de OData correspondentes. Eis um exemplo de como criar consultas com o .NET SDK:

IQueryable<CustomerEntity> linqQuery = table.CreateQuery<CustomerEntity>()
            .Where(x => x.PartitionKey == "4")
            .Select(x => new CustomerEntity() { PartitionKey = x.PartitionKey, RowKey = x.RowKey, Email = x.Email });

Passos seguintes

Neste tutorial, fez o seguinte:

  • Aprendeu a fazer consultas através da API de Tabela

Agora pode avançar para o próximo tutorial para saber como distribuir os seus dados globalmente.