Query Entities

Artigo
06/27/2023

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

Solicitação

Para solicitações que usam a opção $select de consulta, você deve usar a versão 2011-08-18 ou posterior. Além disso, os cabeçalhos DataServiceVersion e MaxDataServiceVersion devem ser definidos como 2.0.

Para usar a projeção, você deve fazer a solicitação usando a versão 2013-08-15 ou posterior. Os DataServiceVersion cabeçalhos e MaxDataServiceVersion devem ser definidos como 3.0. Para obter mais informações, consulte Definir os cabeçalhos de versão do serviço de dados OData.

Você pode construir a solicitação da Query Entities seguinte maneira. Recomendamos HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento e substitua mytable pelo nome da tabela.

Método	URI da solicitação	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 da entidade definida para ser consultada pode ter várias formas no URI da solicitação. Para obter mais informações, consulte Consultar tabelas e entidades.

URI do serviço de armazenamento emulado

Ao fazer uma solicitação no serviço de armazenamento emulado, especifique o nome do host 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 da solicitação	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 maneiras. Para obter mais informações, consulte Diferenças entre o emulador de armazenamento e os serviços de Armazenamento do Azure.

Parâmetros do URI

A Query Entities operação dá suporte às opções de consulta definidas pela especificação do protocolo OData .

Cabeçalhos da solicitação

A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais:

Cabeçalho da solicitação	Descrição
`Authorization`	Obrigatórios. Especifica o esquema de autorização, o nome da conta e a assinatura. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
`Date` ou `x-ms-date`	Obrigatórios. Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
`x-ms-version`	Opcional. Especifica a versão da operação a ser usada para esta solicitação. Para obter mais informações, consulte Controle de versão para os Serviços de Armazenamento do Azure.
`Accept`	Opcional. Especifica o tipo de conteúdo aceito da carga de resposta. Os valores possíveis são: - `application/atom+xml` (somente versões antes de 2015-12-11) - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` Para obter mais informações, consulte Formato de carga para operações de Armazenamento de Tabelas.
`x-ms-client-request-id`	Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres KiB (1 kibibyte) que é registrado nos logs quando o registro em log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações recebidas pelo servidor.

Corpo da solicitação

Nenhum.

Solicitação 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 status HTTP, um conjunto de cabeçalhos de resposta e um corpo de resposta.

Código de status

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

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

Cabeçalhos de resposta

A resposta para esta operação inclui os cabeçalhos a seguir. 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 serem retornadas excede 1.000. - O intervalo de tempo limite do servidor é excedido. - Um limite de servidor é atingido, se a consulta retorna dados que são distribuídos entre vários servidores. Para obter mais informações sobre como usar os tokens de continuação, consulte Tempo limite e paginação de consulta.
`x-ms-request-id`	Identifica exclusivamente a solicitação que foi feita. Você pode usá-lo para solucionar problemas da solicitação. Para obter mais informações, consulte Solucionar problemas de operações de API.
`x-ms-version`	Indica a versão do Armazenamento de Tabelas que foi usada para executar a solicitação. Esse cabeçalho é retornado para solicitações feitas na versão 2009-09-19 e mais recente.
`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 da carga. O valor desse cabeçalho depende do valor do cabeçalho de solicitação `Accept`. Os valores possíveis são: - `application/atom+xml` (somente 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, consulte Formato de carga para operações de Armazenamento de Tabelas.
`x-ms-client-request-id`	Pode ser usado para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho é igual ao valor do `x-ms-client-request-id` cabeçalho, se ele estiver presente na solicitação e o valor for no máximo 1.024 caracteres ASCII visíveis. Se o `x-ms-client-request-id` cabeçalho não estiver presente na solicitação, esse cabeçalho não estará presente na resposta.

Resposta de exemplo

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 retorna a lista de entidades em uma tabela como um conjunto de entidades OData. A lista de entidades está em um formato JSON ou em um feed Atom, dependendo do Accept cabeçalho da solicitação.

Observação

Recomendamos JSON como o formato de conteúdo. É o único formato com suporte para a versão 2015-12-11 e posterior.

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

Aqui está um URI de solicitação de exemplo para uma Query Entities operação em uma tabela de clientes:

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

Aqui está o conteúdo de resposta no JSON sem metadados:

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

Aqui está o conteúdo 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"  
      }  
   ]  
}

Aqui está o conteúdo 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"  
      }  
   ]  
}

Atom feed (versões anteriores a 2015-12-11)

Aqui está um URI de solicitação de exemplo para uma Query Entities operação em uma tabela de clientes:

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

Aqui está um exemplo de resposta atom 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

Essa operação poderá ser executada pelo proprietário da conta e por qualquer pessoa com uma assinatura de acesso compartilhado que tenha permissão para executar essa operação.

Comentários

Uma consulta no Armazenamento de Tabelas pode retornar no máximo 1.000 entidades ao mesmo tempo e pode ser executada por 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 1.000 entidades.
A consulta não foi concluída em cinco segundos.
A consulta cruza o limite da partição.

Você pode usar os tokens de continuação para construir uma solicitação subsequente para a próxima página de dados. Para obter mais informações sobre tokens de continuação, consulte Tempo limite e paginação de consulta.

Observação

Ao fazer solicitações subsequentes que incluem tokens de continuação, não se esqueça de passar o URI original na solicitação. Por exemplo, se você tiver especificado uma $filteropção de consulta , $selectou $top como parte da solicitação original, inclua essa opção em solicitações subsequentes. Caso contrário, suas solicitações subsequentes poderão retornar resultados inesperados.

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

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

Para solicitações de projeção que usam a opção $select de consulta, a versão deve ser 2011-08-18 ou posterior. O número máximo de propriedades retornadas é 255. O corpo da resposta inclui todas as propriedades projetadas, mesmo que as propriedades não façam parte da entidade retornada.

Por exemplo, se a solicitação incluir uma propriedade que a entidade projetadas não contenha, a propriedade ausente será marcada com um atributo nulo. O corpo da 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 à solicitação para agendar e processar a consulta é de 30 segundos. Esse total inclui os cinco segundos para execução da consulta.

Observe que o lado direito de uma expressão de consulta deve ser uma constante. Você não pode referenciar uma propriedade no lado direito da expressão. Para obter detalhes sobre como construir expressões de consulta, consulte Consultar tabelas e entidades.

Uma expressão de consulta não pode conter null valores. Os seguintes caracteres devem ser codificados se você usá-los em uma cadeia de caracteres de consulta:

Barra (/)
Ponto de interrogação (?)
Dois-pontos (:)
Em sinal (@)
E comercial (&)
Sinal de igual (=)
Sinal de adição (+)
Vírgula (,)
Sinal de dólar ($)

Qualquer aplicativo que possa autorizar e enviar uma solicitação HTTP GET pode consultar entidades em uma tabela.

Para obter mais informações sobre operações de consulta com suporte no Armazenamento de Tabelas por meio do LINQ, consulte Operadores de consulta compatíveis com o Armazenamento de Tabelas e Gravar consultas LINQ no Armazenamento de Tabelas.

Confira também

Códigos de erro do Armazenamento de Tabelas
Autorizar solicitações para o Armazenamento do Azure
Status e códigos de erro
Endereçando recursos de Armazenamento de Tabelas
Consultar tabelas e entidades
Definir os cabeçalhos de versão do serviço de dados OData
Insert Entity
Atualizar Entidade
Excluir Entidade