你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

查询实体

项目
06/27/2023

Query Entities操作查询表中的实体，包括 $filter 和 $select 选项。

请求

对于使用 $select 查询选项的请求，必须使用版本 2011-08-18 或更高版本。此外，DataServiceVersion 和 MaxDataServiceVersion 标头必须设为 2.0。

若要使用投影，必须使用版本 2013-08-15 或更高版本发出请求。 DataServiceVersion和 MaxDataServiceVersion 标头必须设置为 3.0。有关详细信息，请参阅设置 OData 数据服务版本标头。

可以按如下所示构造 Query Entities 请求。建议使用 HTTPS。将 myaccount 替换为存储帐户的名称，将 mytable 替换为表的名称。

方法	请求 URI	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

要查询的实体集的地址可能会在请求 URI 上采用各种形式。有关详细信息，请参阅查询表和实体。

模拟存储服务 URI

对模拟存储服务发出请求时，请将模拟器的主机名和表服务的端口指定为 127.0.0.1:10002。使用模拟存储帐户的名称来跟踪该信息。

方法	请求 URI	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

存储模拟器中的表服务在多个方面与 Azure 表存储不同。有关详细信息，请参阅存储模拟器与 Azure 存储服务之间的差异。

URI 参数

操作 Query Entities 支持 OData 协议规范定义的查询选项。

请求标头

下表介绍了必需请求标头和可选请求标头：

请求标头	说明
`Authorization`	必需。指定授权方案、帐户名称和签名。有关详细信息，请参阅授权对 Azure 存储的请求。
`Date` 或 `x-ms-date`	必需。指定请求的协调世界时 (UTC)。有关详细信息，请参阅授权对 Azure 存储的请求。
`x-ms-version`	可选。指定用于此请求的操作的版本。有关详细信息，请参阅 Azure 存储服务的版本控制。
`Accept`	可选。指定响应负载已接受的内容类型。可能的值为： - `application/atom+xml` (2015-12-11 之前的版本仅) - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` 有关详细信息，请参阅表存储操作的有效负载格式。
`x-ms-client-request-id`	可选。提供客户端生成的不透明值，其中包含 1-kiB (KiB) 配置日志记录时记录在日志中的字符限制。强烈建议使用此标头将客户端活动与服务器接收的请求相关联。

请求正文

无。

示例请求

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

响应

响应包括 HTTP 状态代码、一组响应标头和响应正文。

状态代码

此操作成功后返回状态代码 200（正常）。

有关状态代码的信息，请参阅状态和错误代码和表存储错误代码。

响应头

此操作的响应包括以下标头。响应可能还包括其他标准 HTTP 标头。所有标准标头都符合 HTTP/1.1 协议规范。

响应标头	说明
`x-ms-continuation-NextPartitionKey` `x-ms-continuation-NextRowKey`	指示： - 要返回的实体数超过 1,000。 - 超出服务器超时间隔。 - 如果查询返回分布在多个服务器中的数据，则达到服务器边界。有关使用延续令牌的详细信息，请参阅查询超时和分页。
`x-ms-request-id`	唯一标识发出的请求。可以使用它对请求进行故障排除。有关详细信息，请参阅 API 操作疑难解答。
`x-ms-version`	指示用于执行请求的表存储版本。针对 2009-09-19 和更高版本发出的请求将返回此标头。
`Date`	一个 UTC 日期/时间值，该值指示服务发送响应的时间。
`Content-Type`	指示负载的内容类型。该标头的值取决于 `Accept` 请求标头的值。可能的值为： - `application/atom+xml` (2015-12-11 之前的版本仅) - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` 有关有效内容类型的详细信息，请参阅表存储操作的有效负载格式。
`x-ms-client-request-id`	可用于对请求和相应响应进行故障排除。如果请求中存在此标头的值 `x-ms-client-request-id` ，并且该值最多为 1,024 个可见 ASCII 字符，则此标头的值等于标头的值。 `x-ms-client-request-id`如果请求中不存在标头，则响应中不会显示此标头。

示例响应

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

响应正文

该 Query Entities 操作将表中的实体列表作为 OData 实体集返回。实体列表采用 JSON 格式或 Atom 源，具体取决于 Accept 请求的标头。

注意

建议将 JSON 作为有效负载格式。它是版本 2015-12-11 及更高版本唯一支持的格式。

JSON (版本 2013-08-15 及更高版本)

下面是针对客户表的操作的示例请求 URI Query Entities ：

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

下面是 JSON 中不含元数据的响应有效负载：

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

下面是 JSON 中包含最少元数据的响应有效负载：

{  
   "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"  
      }  
   ]  
}

下面是 JSON 中包含完整元数据的响应有效负载：

{  
   "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 源 (2015-12-11 之前的版本)

下面是针对客户表的操作的示例请求 URI Query Entities ：

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

下面是操作的示例 Atom 响应 Query Entities ：

<?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>

授权

帐户所有者以及使用有权执行此操作的共享访问签名的任何人可以执行此操作。

注解

针对表存储的查询一次最多可以返回 1,000 个实体，并且最多可以运行 5 秒。响应包括自定义标头，这些标头在以下任一情况下包含一组继续标记：

结果集包含超过 1,000 个实体。
查询未在五秒内完成。
查询跨越分区边界。

可以使用继续标记为下一页数据构造后续请求。有关继续标记的详细信息，请参阅查询超时和分页。

注意

发出包含继续令牌的后续请求时，请务必在请求中传递原始 URI。例如，如果已将、 $select或 $top 查询选项指定为原始请求的一$filter部分，请在后续请求中包含该选项。否则，后续请求可能会返回意外结果。

在这种情况下，查询 $top 选项指定每页的最大结果数。它不会指定整个响应集中的最大结果数。

有关详细信息，请参阅查询表和实体。

对于使用查询选项的 $select 投影请求，版本必须为 2011-08-18 或更高版本。返回的属性的最大数目为 255。响应正文包括所有投影属性，即使属性不是返回实体的一部分。

例如，如果请求包含投影实体不包含的属性，则会用 null 属性标记缺少的属性。前面的示例响应正文包含 Address 属性，该属性不是投影实体的一部分。因此，属性的值为 null： <d:Address m:null="true" />。

分配给请求以计划和处理查询的总时间为 30 秒。该总数包括执行查询的 5 秒。

请注意，查询表达式的右侧必须是常量。不能引用表达式右侧的属性。有关构造查询表达式的详细信息，请参阅查询表和实体。

查询表达式不能包含 null 值。如果在查询字符串中使用这些字符，则必须对以下字符进行编码：

正斜杠 (/)
问号 (?)
冒号 (:)
At sign (@)
与符号 (&)
等号 (=)
加号 (+)
逗号 (,)
美元符号 ($)

可以授权和发送 HTTP GET 请求的任何应用程序都可以查询表中的实体。

有关通过 LINQ 对表存储支持的查询操作的详细信息，请参阅表存储支持的查询运算符和针对表存储编写 LINQ 查询。

另请参阅

表存储错误代码
 授权对 Azure 存储的请求
 状态和错误代码
 寻址表存储资源
 查询表和实体
 设置 OData 数据服务版本标头
 插入实体
 更新实体
 删除实体

通过