Consultar tabelas e entidades

  • Artigo

Consultar tabelas e entidades no serviço Tabela requer uma construção cuidadosa do URI do pedido. As secções seguintes descrevem as opções de consulta e demonstram alguns cenários comuns.

Sintaxe de Consulta Básica

Para devolver todas as tabelas numa determinada conta de armazenamento, execute uma GET operação no recurso Tabelas, conforme descrito na operação Tabelas de Consultas . O URI básico para abordar o recurso Tabelas é o seguinte:

https://myaccount.table.core.windows.net/Tables

Para devolver uma única tabela com nome, especifique essa tabela da seguinte forma:

https://myaccount.table.core.windows.net/Tables('MyTable')

Para devolver todas as entidades numa tabela, especifique o nome da tabela no URI, sem o recurso Tabelas:

https://myaccount.table.core.windows.net/MyTable()

Os resultados da consulta são ordenados por PartitionKeye, em seguida, por RowKey. A ordenação de resultados de qualquer outra forma não é atualmente suportada.

Pode especificar opções adicionais para limitar o conjunto de tabelas ou entidades devolvidas, conforme descrito na seguinte secção Opções de Consulta Suportadas .

Nota

O número de entidades devolvidas para um único pedido pode ser limitado, se a consulta exceder o número máximo de entidades, exceder o intervalo de tempo limite ou ultrapassar um limite de partição. Para obter mais informações, veja Tempo Limite da Consulta e Paginação.

Opções de Consulta Suportadas

O serviço Tabela suporta as seguintes opções de consulta, que estão em conformidade com a Especificação do Protocolo OData. Pode utilizar estas opções para limitar o conjunto de tabelas, entidades ou propriedades de entidade devolvidas por uma consulta.

Opção de consulta do sistema Description
$filter Devolve apenas tabelas ou entidades que satisfaçam o filtro especificado.

Tenha em atenção que não são permitidas mais de 15 comparações discretas numa $filter cadeia.
$top Devolve apenas as principais n tabelas ou entidades do conjunto.
$select Devolve as propriedades pretendidas de uma entidade do conjunto. Esta opção de consulta só é suportada para pedidos com a versão 2011-08-18 ou mais recente. Para obter mais informações, veja Writing LINQ Queries Against the Table Service (Escrever Consultas LINQ contra o Serviço de Tabelas).

Nota

Um pedido que devolve mais do que o número máximo predefinido ou especificado de resultados devolve um token de continuação para executar a paginação. Ao fazer pedidos subsequentes que incluam tokens de continuação, certifique-se de que transmite o URI original no pedido. Por exemplo, se tiver especificado uma $filteropção de consulta , $selectou $top como parte do pedido original, deverá incluir essa opção nos pedidos subsequentes. Caso contrário, os seus pedidos subsequentes poderão devolver resultados inesperados. Veja Tempo Limite da Consulta e Paginação para obter informações adicionais.

Tenha em atenção que a opção $top de consulta no caso em que os resultados são paginados especifica o número máximo de resultados por página e não o número máximo de resultados em todo o conjunto de respostas.

As opções de consulta adicionais definidas pelo OData não são suportadas pelo serviço Tabela.

Operadores de Comparação Suportados

Dentro de uma $filter cláusula, pode utilizar operadores de comparação para especificar os critérios para filtrar os resultados da consulta.

Para todos os tipos de propriedade, são suportados os seguintes operadores de comparação:

Operador Expressão URI
Equal eq
GreaterThan gt
GreaterThanOrEqual ge
LessThan lt
LessThanOrEqual le
NotEqual ne

Além disso, os seguintes operadores são suportados para propriedades booleanas:

Operador Expressão URI
And and
Not not
Or or

Para obter mais informações sobre a sintaxe do filtro, veja a Especificação do Protocolo OData.

Codificação de Cadeias de Consulta

Os seguintes carateres têm de ser codificados para serem utilizados numa cadeia de consulta:

  • Barra de reencaminhamento (/)
  • Ponto de interrogação (?)
  • Dois pontos (:)
  • Símbolo 'At' (@)
  • E comercial (&)
  • Sinal de igual (=)
  • Sinal de adição (+)
  • Vírgula (,)
  • Sinal de dólar ($)

Plicas (')

As aspas individuais nas cadeias de consulta têm de ser representadas como duas aspas individuais consecutivas (''). Por exemplo, "o'clock" seria:

o''clock

Expressões de Consulta de Exemplo

Os exemplos seguintes mostram como construir o URI do pedido para algumas consultas de entidade típicas com sintaxe REST. As mesmas consultas podem ser escritas com a sintaxe LINQ. Para obter mais informações, veja Writing LINQ Queries Against the Table Service (Escrever Consultas LINQ contra o Serviço de Tabelas).

Tenha em atenção que as $top opções e $filter também podem ser utilizadas para filtrar os nomes das tabelas, utilizando a sintaxe demonstrada para filtrar as propriedades do tipo String.

Devolver as Entidades Principais n

Para devolver as principais n entidades de qualquer consulta, especifique a opção $top de consulta. O exemplo seguinte devolve as 10 principais entidades de uma tabela denominada Clientes:

https://myaccount.table.core.windows.net/Customers()?$top=10

Filtrar nas Propriedades PartitionKey e RowKey

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

https://myaccount.table.core.windows.net/Customers(PartitionKey='MyPartition',RowKey='MyRowKey1')

Em alternativa, pode especificar estas propriedades como parte da opção $filter, conforme mostrado na secção seguinte.

Tenha em atenção que os nomes das propriedades chave e os valores constantes são sensíveis a maiúsculas e minúsculas. PartitionKey As propriedades e RowKey são do tipo String.

Construir Cadeias de Filtro

Ao construir uma cadeia de filtro, tenha estas regras em mente:

  • Utilize os operadores lógicos definidos pela Especificação do Protocolo OData para comparar uma propriedade com um valor. Tenha em atenção que não é possível comparar uma propriedade com um valor dinâmico; um dos lados da expressão tem de ser uma constante.

  • O nome da propriedade, o operador e o valor constante têm de estar separados por espaços com codificação URL. 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 Noções Básicas sobre o Modelo de Dados do Serviço Tabela.

Nota

Certifique-se de que verifica se uma propriedade foi explicitamente escrita antes de assumir que é de um tipo diferente da cadeia. Se uma propriedade tiver sido explicitamente escrita, o tipo é indicado na resposta quando a entidade é devolvida. Se a propriedade não tiver sido escrita explicitamente, será do tipo Stringe o tipo não será indicado na resposta quando a entidade for devolvida.

Filtrar nas Propriedades da Cadeia

Ao filtrar as propriedades da cadeia, coloque a constante de cadeia entre plicas.

O exemplo seguinte filtra as PartitionKey propriedades e RowKey ; também podem ser adicionadas propriedades adicionais não chave à cadeia de consulta.

https://myaccount.table.core.windows.net/Customers()?$filter=PartitionKey%20eq%20'MyPartitionKey'%20and%20RowKey%20eq%20'MyRowKey1'

O exemplo seguinte filtra uma FirstName propriedade e LastName :

https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20eq%20'Smith'%20and%20FirstName%20eq%20'John'

Tenha em atenção que o serviço Tabela não suporta consultas universais. No entanto, pode efetuar a correspondência de prefixos com operadores de comparação no prefixo pretendido. O exemplo seguinte devolve entidades com uma LastName propriedade que começa com a letra "A":

https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20ge%20'A'%20and%20LastName%20lt%20'B'

Filtrar em Propriedades Numéricas

Para filtrar um número inteiro ou vírgula flutuante, especifique o valor constante no URI sem aspas.

Este exemplo devolve todas as entidades com uma Age propriedade cujo valor é superior a 30:

https://myaccount.table.core.windows.net/Customers()?$filter=Age%20gt%2030

Este exemplo devolve todas as entidades com uma AmountDue propriedade cujo valor é menor ou igual a 100,25:

https://myaccount.table.core.windows.net/Customers()?$filter=AmountDue%20le%20100.25%20

Filtrar em Propriedades Booleanas

Para filtrar um valor booleano, especifique true ou false sem aspas.

O exemplo seguinte devolve todas as entidades em que a IsActive propriedade está definida como true:

https://myaccount.table.core.windows.net/Customers()?$filter=IsActive%20eq%20true

Filtrar em Propriedades DateTime

Para filtrar um DateTime valor, especifique a datetime palavra-chave no URI, seguida da constante de data/hora em plicas. A constante de data/hora tem de estar no formato UTC combinado, conforme descrito em Formatar valores DateTime.

O exemplo seguinte devolve entidades em que a CustomerSince propriedade é igual a 10 de julho de 2008:

https://myaccount.table.core.windows.net/Customers()?$filter=CustomerSince%20eq%20datetime'2008-07-10T00:00:00Z'

Filtragem nas Propriedades do GUID

Para filtrar um valor GUID, especifique a guid palavra-chave no URI, seguida da constante guid em plicas.

O exemplo seguinte devolve entidades em que a GuidValue propriedade é igual a :

https://myaccount.table.core.windows.net/Customers()?$filter=GuidValue%20eq%20guid'a455c695-df98-5678-aaaa-81d3367e5a34'

Consulte também

Conceitos do Serviço Tabela
Compreender o Modelo de Dados do Serviço de Tabelas
Endereçar Recursos de Serviço de Tabela
Tempo Limite de Consulta e Paginação
Writing LINQ Queries Against the Table Service