Tutorial: Consultar o Azure Cosmos DB com a API para Tabela

  • Artigo

APLICA-SE A: Tabela

O Azure Cosmos DB for Table suporta consultas OData e LINQ em relação a dados de chave/valor (tabela).

Este artigo abrange as seguintes tarefas:

  • Consultar dados com a API para Tabela

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

PartitionKey RowKey E-mail PhoneNumber
Harp Walter Walter@contoso.com 425-555-0101
Smith Ben Ben@contoso.com 425-555-0102
Smith Jeff Jeff@contoso.com 425-555-0104

Para obter detalhes sobre como consultar com a API para Tabela, veja Consultar tabelas e entidades.

Pré-requisitos

Para estas consultas funcionarem, tem de ter uma conta do Azure Cosmos DB e dados de entidade no contentor. Se não tiver uma conta ou dados, conclua o Início Rápido: Azure Cosmos DB para Tabela para .NET para criar uma conta e preencher a sua base de dados.

Consultar em PartitionKey e RowKey

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

Query

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

Resultados

PartitionKey RowKey E-mail PhoneNumber
Harp Walter Walter@contoso.com 425-555-0104

Em alternativa, pode especificar estas propriedades como parte da opção $filter, conforme mostrado na secção seguinte. Os nomes das propriedades principais e os valores constantes são sensíveis às maiúsculas e minúsculas. As propriedades PartitionKey e RowKey são do tipo Cadeia.

Consultar com um filtro OData

Quando estiver a criar uma cadeia de filtro, não se esqueça destas regras:

  • Utilize os operadores lógicos definidos pela Especificação do Protocolo OData para comparar uma propriedade a um valor. Não pode comparar uma propriedade com um valor dinâmico. Um lado da expressão tem de ser uma constante.
  • Os espaços codificados por URL têm de separar o nome da propriedade, o operador e o valor constante. Um espaço tem codificação URL como %20.
  • Todas as partes da cadeia de filtro são sensíveis a maiúsculas e minúsculas.
  • O valor constante tem de ser do mesmo tipo de dados da propriedade para que o filtro devolva resultados válidos. Para obter mais informações sobre os tipos de propriedade suportados, veja Compreender o modelo de dados do serviço Tabela.

Segue-se uma consulta de exemplo que mostra como filtrar pelas propriedades PartitionKey e Email com um $filter OData.

Query

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

Para obter mais informações sobre como criar expressões de filtro para vários tipos de dados, veja Consultar Tabelas e Entidades.

Resultados

PartitionKey RowKey E-mail PhoneNumber
Smith Ben Ben@contoso.com 425-555-0102

As consultas nas propriedades datetime não devolvem dados quando executadas na API para Tabela do Azure Cosmos DB. Enquanto o armazenamento de Tabelas do Azure armazena valores de data com granularidade de tempo de tiques, a API para 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. O Azure Cosmos DB bloqueia as consultas em propriedades de carimbo de data/hora. Como solução, pode definir uma propriedade de data/hora personalizada ou de tipo de dados longo e definir o valor de data do cliente.

Consultar com o LINQ

Também pode consultar com o LINQ, que traduz as expressões de consulta OData correspondentes. Segue-se um exemplo de como criar consultas com o SDK .NET:

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

Agora pode avançar para o tutorial seguinte para saber como distribuir dados globalmente.