Entidades de Consulta

  • Artigo

A Query Entities operação consulta entidades numa tabela e inclui as $filter opções e $select .

Pedir

Para pedidos que utilizam a opção $select de consulta, tem de utilizar a versão 2011-08-18 ou posterior. Além disso, os DataServiceVersion cabeçalhos e MaxDataServiceVersion têm de ser definidos como 2.0.

Para utilizar a projeção, tem de fazer o pedido com a versão 2013-08-15 ou posterior. Os DataServiceVersion cabeçalhos e MaxDataServiceVersion têm de ser definidos como 3.0. Para obter mais informações, veja Definir os cabeçalhos da versão do serviço de dados OData.

Pode construir o pedido da Query Entities seguinte forma. Recomendamos HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento e substitua mytable pelo nome da tabela.

Método URI do pedido Versão HTTP
GET https://myaccount.table.core.windows.net/mytable(PartitionKey='<partition-key>',RowKey='<row-key>')?$select=<comma-separated-property-names>

https://myaccount.table.core.windows.net/mytable()?$filter=<query-expression>&$select=<comma-separated-property-names>		 HTTP/1.1

O endereço do conjunto de entidades a consultar pode assumir várias formas no URI do pedido. Para obter mais informações, veja Consultar tabelas e entidades.

URI do serviço de armazenamento emulado

Quando estiver a fazer um pedido relativamente ao serviço de armazenamento emulado, especifique o nome do anfitrião do emulador e a porta do serviço de tabela como 127.0.0.1:10002. Siga essas informações com o nome da conta de armazenamento emulada.

Método URI do pedido Versão HTTP
GET http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='<partition-key>',RowKey='<row-key>')?$select=<comma-separated-property-names>

http://127.0.0.1:10002/devstoreaccount1/mytable()?$filter=<query-expression>?$select=<comma-separated-property-names>		 HTTP/1.1

O serviço Tabela no emulador de armazenamento difere do Armazenamento de Tabelas do Azure de várias formas. Para obter mais informações, veja Diferenças entre o emulador de armazenamento e os serviços de Armazenamento do Azure.

Parâmetros do URI

A Query Entities operação suporta as opções de consulta que a especificação do protocolo OData define.

Cabeçalhos do pedido

A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais:

Cabeçalho do pedido Description
Authorization Obrigatório. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
Date ou x-ms-date Obrigatório. Especifica a Hora Universal Coordenada (UTC) do pedido. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
x-ms-version Opcional. Especifica a versão da operação a utilizar para este pedido. Para obter mais informações, veja Controlo de versões dos serviços de Armazenamento do Azure.
Accept Opcional. Especifica o tipo de conteúdo aceite do payload de resposta. Os valores possíveis são:

- application/atom+xml (apenas versões antes de 2015-12-11)
- application/json;odata=nometadata
- application/json;odata=minimalmetadata
- application/json;odata=fullmetadata

Para obter mais informações, veja Formato de payload para operações de Armazenamento de Tabelas.
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de carateres de 1 kibibyte (KiB) que é registado nos registos quando o registo é configurado. Recomendamos vivamente que utilize este cabeçalho para correlacionar as atividades do lado do cliente com os pedidos que o servidor recebe.

Corpo do pedido

Nenhum.

Pedido de exemplo

Request Syntax:  
GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince  HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-12-11  
x-ms-date: Mon, 27 Jun 2016 15:25:14 GMT  
Authorization: SharedKeyLite myaccount:<some key>  
Accept: application/json;odata=nometadata  
Accept-Charset: UTF-8  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx

Resposta

A resposta inclui um código de estado HTTP, um conjunto de cabeçalhos de resposta e um corpo de resposta.

Código de estado

Uma operação bem-sucedida devolve o código de estado 200 (OK).

Para obter informações sobre códigos de estado, veja Códigos de estado e de erro e códigos de erro do Armazenamento de Tabelas.

Cabeçalhos de resposta

A resposta para esta operação inclui os seguintes cabeçalhos. A resposta também pode incluir cabeçalhos HTTP padrão adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.

Cabeçalho de resposta Descrição
x-ms-continuation-NextPartitionKey

x-ms-continuation-NextRowKey		 Indica que:

- O número de entidades a devolver excede 1000.
- O intervalo de tempo limite do servidor foi excedido.
- É atingido um limite do servidor, se a consulta devolver dados distribuídos por vários servidores.

Para obter mais informações sobre como utilizar os tokens de continuação, veja Tempo limite de consulta e paginação.
x-ms-request-id Identifica exclusivamente o pedido que foi feito. Pode utilizá-lo para resolver o pedido. Para obter mais informações, veja Resolver problemas de operações da API.
x-ms-version Indica a versão do Armazenamento de Tabelas que foi utilizada para executar o pedido. Este cabeçalho é devolvido para pedidos feitos na versão 2009-09-19 e posterior.
Date Um valor de data/hora UTC que indica a hora em que o serviço enviou a resposta.
Content-Type Indica o tipo de conteúdo do payload. O valor deste cabeçalho depende do valor do cabeçalho do Accept pedido. Os valores possíveis são:

- application/atom+xml (apenas versões antes de 2015-12-11)
- application/json;odata=nometadata
- application/json;odata=minimalmetadata
- application/json;odata=fullmetadata

Para obter mais informações sobre tipos de conteúdo válidos, veja Formato de payload para operações de Armazenamento de Tabelas.
x-ms-client-request-id Pode ser utilizado para resolver problemas de pedidos e respostas correspondentes. O valor deste cabeçalho é igual ao valor do x-ms-client-request-id cabeçalho, se estiver presente no pedido e o valor for, no máximo, 1024 carateres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente no pedido, este cabeçalho não estará presente na resposta.

Resposta de amostra

Response Status:  
HTTP/1.1 200 OK  
  
Response Headers:  
Content-Type: application/json  
x-ms-request-id: 87f178c0-44fe-4123-a4c1-96c8fa6d9654  
Date: Mon, 27 Jun 2016 15:25:14 GMT  
x-ms-version: 2015-12-11  
Connection: close

Corpo da resposta

A Query Entities operação devolve a lista de entidades numa tabela como um conjunto de entidades OData. A lista de entidades está num formato JSON ou num feed Atom, dependendo do Accept cabeçalho do pedido.

Nota

Recomendamos JSON como o formato de payload. É o único formato suportado para a versão 2015-12-11 e posterior.

JSON (versão 2013-08-15 e posterior)

Eis um URI de pedido de exemplo para uma Query Entities operação numa tabela de clientes:

GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince

Eis o payload de resposta em JSON sem metadados:

{  
   "value":[  
      {  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

Eis o payload de resposta em JSON com metadados mínimos:

{  
   "odata.metadata":"https://myaccount.table.core.windows.net/$metadata#Customers",  
   "value":[  
      {  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince@odata.type":"Edm.DateTime",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

Eis o payload de resposta em JSON com metadados completos:

{  
   "odata.metadata":" https://myaccount.table.core.windows.net/metadata#Customers",  
   "value":[  
      {  
         "odata.type":"myaccount.Customers",  
         "odata.id":"https://myaccount.table.core.windows.net/Customers(PartitionKey=Customer',RowKey='Name')",  
         "odata.etag":"W/\"0x5B168C7B6E589D2\"",  
         "odata.editLink":"Customers(PartitionKey=Customer',RowKey='Name')",  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp@odata.type":"Edm.DateTime",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince@odata.type":"Edm.DateTime",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

Feed atom (versões anteriores a 2015-12-11)

Eis um URI de pedido de exemplo para uma Query Entities operação numa tabela de clientes:

GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince

Eis uma resposta do Atom de exemplo para a Query Entities operação:

<?xml version="1.0" encoding="UTF-8"?>  
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xml:base="https://myaccount.table.core.windows.net">  
   <id>https://myaccount.table.core.windows.net/Customers</id>  
   <title type="text">Customers</title>  
   <updated>2013-08-22T00:50:32Z</updated>  
   <link rel="self" title="Customers" href="Customers" />  
   <entry m:etag="W/"0x5B168C7B6E589D2"">  
      <id>https://myaccount.table.core.windows.net/Customers(PartitionKey='Customer',RowKey='Name')</id>  
      <category term="myaccount.Customers" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />  
      <link rel="edit" title="Customers" href="Customers(PartitionKey='Customer',RowKey='Name')" />  
      <title />  
      <updated>2013-08-22T00:50:32Z</updated>  
      <author>  
         <name />  
      </author>  
      <content type="application/xml">  
         <m:properties>  
            <d:PartitionKey>Customer</d:PartitionKey>  
            <d:RowKey>Name</d:RowKey>  
            <d:Timestamp m:type="Edm.DateTime">2013-08-22T00:20:16.3134645Z</d:Timestamp>  
            <d:CustomerSince m:type="Edm.DateTime">2008-10-01T15:25:05.2852025Z</d:CustomerSince>  
         </m:properties>  
      </content>  
   </entry>  
</feed>

Autorização

Esta operação pode ser efetuada pelo proprietário da conta e por qualquer pessoa com uma assinatura de acesso partilhado que tenha permissão para realizar esta operação.

Observações

Uma consulta no Armazenamento de Tabelas pode devolver um máximo de 1000 entidades de uma só vez e pode ser executada durante um máximo de cinco segundos. A resposta inclui cabeçalhos personalizados que contêm um conjunto de tokens de continuação em qualquer um dos seguintes casos:

  • O conjunto de resultados contém mais de 1000 entidades.
  • A consulta não terminou em cinco segundos.
  • A consulta cruza o limite de partição.

Pode utilizar os tokens de continuação para construir um pedido subsequente para a próxima página de dados. Para obter mais informações sobre os tokens de continuação, veja Tempo limite de consulta e paginação.

Nota

Quando estiver a 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, inclua essa opção nos pedidos subsequentes. Caso contrário, os seus pedidos subsequentes poderão devolver resultados inesperados.

A $top opção de consulta neste caso especifica o número máximo de resultados por página. Não especifica o número máximo de resultados em todo o conjunto de respostas.

Para obter mais informações, veja Consultar tabelas e entidades.

Para pedidos de projeção que utilizam a opção $select de consulta, a versão tem de ser 2011-08-18 ou posterior. O número máximo de propriedades devolvidas é 255. O corpo da resposta inclui todas as propriedades projetadas, mesmo que as propriedades não façam parte da entidade devolvida.

Por exemplo, se o pedido incluir uma propriedade que a entidade projetada não contém, a propriedade em falta é marcada com um atributo nulo. O corpo de resposta de exemplo anterior inclui a Address propriedade, que não faz parte da entidade projetada. O valor da propriedade é, portanto, nulo: <d:Address m:null="true" />.

O tempo total atribuído ao pedido de agendamento e processamento da consulta é de 30 segundos. Esse total inclui os cinco segundos para a execução de consultas.

Tenha em atenção que o lado direito de uma expressão de consulta tem de ser uma constante. Não pode referenciar uma propriedade no lado direito da expressão. Para obter detalhes sobre a construção de expressões de consulta, veja Consultar tabelas e entidades.

Uma expressão de consulta não pode conter null valores. Os seguintes carateres têm de ser codificados se os utilizar numa cadeia de consulta:

  • Barra de reencaminhamento (/)

  • Ponto de interrogação (?)

  • Dois pontos (:)

  • Ao iniciar sessão (@)

  • E comercial (&)

  • Sinal de igual (=)

  • Sinal de adição (+)

  • Vírgula (,)

  • Sinal de dólar ($)

Qualquer aplicação que possa autorizar e enviar um pedido HTTP GET pode consultar entidades numa tabela.

Para obter mais informações sobre as operações de consulta suportadas no Armazenamento de Tabelas através do LINQ, veja Operadores de consultas suportados para o Armazenamento de Tabelas e escrever consultas LINQ no Armazenamento de Tabelas.

Ver também

Códigos de erro do Armazenamento de Tabelas
Autorizar pedidos para o Armazenamento do Azure
Códigos de estado e de erro
Endereçar recursos do Armazenamento de Tabelas
Consultar tabelas e entidades
Definir os cabeçalhos da versão do serviço de dados OData
Inserir Entidade
Atualizar Entidade
Eliminar Entidade