你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
查询表和实体
在表服务中查询表和实体时,需要小心地构造请求 URI。 以下几节介绍了查询选项并说明了一些常见情形。
基本查询语法
若要返回给定存储帐户中的所有表,请对表资源执行操作 GET
,如 查询表 操作中所述。 用于查找表资源的基本 URI 如下所示:
https://myaccount.table.core.windows.net/Tables
要返回单个命名的表,请按如下方式指定该表:
https://myaccount.table.core.windows.net/Tables('MyTable')
要返回表中的所有实体,请在 URI 上指定表名而不指定表资源:
https://myaccount.table.core.windows.net/MyTable()
查询结果将按 PartitionKey
排序,然后按 RowKey
排序。 目前不支持以任何其他方式对结果进行排序。
你可以指定其他选项以限制返回的表或实体集,如下面的支持的查询选项部分中所述。
注意
如果查询超过最大实体数,超过超时间隔或跨越分区边界,则可以限制为单个请求返回的实体数。 有关详细信息,请参阅 查询超时和分页。
支持的查询选项
表服务支持符合 OData 协议规范的以下查询选项。 可以使用这些选项限制查询返回的表、实体或实体属性集。
系统查询选项 | 说明 |
---|---|
$filter |
仅返回符合指定筛选器条件的表或实体。 请注意, $filter 字符串中允许使用不超过 15 个离散比较。 |
$top |
仅返回集合中的前 n 个表或实体。 |
$select |
返回集合中的实体的所需属性。 仅使用 2011-08-18 或更高版本的请求支持此查询选项。 有关详细信息,请参阅 针对表服务编写 LINQ 查询。 |
注意
返回超过默认最大值或指定最大结果数的请求将返回用于执行分页的延续标记。 在发出包含继续标记的后续请求时,请确保在请求上传递原始 URI。 例如,如果已将 、 $select
或 $top
查询选项指定为原始请求的一$filter
部分,则需要在后续请求中包含该选项。 否则,后续请求可能会返回意外结果。 有关其他信息,请参阅 查询超时和分页 。
请注意, $top
如果结果已分页,则查询选项指定每页的最大结果数,而不是整个响应集中的最大结果数。
表服务不支持 OData 定义的其他查询选项。
支持的比较运算符
在 $filter
子句中,可以使用比较运算符来指定用于筛选查询结果的条件。
对于所有属性类型,支持使用以下比较运算符:
运算符 | URI 表达式 |
---|---|
Equal |
eq |
GreaterThan |
gt |
GreaterThanOrEqual |
ge |
LessThan |
lt |
LessThanOrEqual |
le |
NotEqual |
ne |
此外,布尔属性还支持以下运算符:
运算符 | URI 表达式 |
---|---|
And |
and |
Not |
not |
Or |
or |
有关筛选器语法的详细信息,请参阅 OData 协议规范。
查询字符串编码
如果要在查询字符串中使用以下字符,必须对这些字符进行编码:
- 正斜杠 (/)
- 问号 (?)
- 冒号 (:)
- “At”符号 (@)
- 与符号 (&)
- 等号 (=)
- 加号 (+)
- 逗号 (,)
- 美元符号 ($)
单引号 (')
查询字符串中的单引号必须表示为两个连续的单引号 (''
) 。 例如,“o'clock”将为:
o''clock
示例查询表达式
以下示例说明了如何使用 REST 语法为一些典型实体查询构造请求 URI。 可以使用 LINQ 语法编写相同的查询。 有关详细信息,请参阅 针对表服务编写 LINQ 查询。
请注意,也可以使用 $top
和 $filter
选项按照所描述的 String
类型的属性的筛选语法来筛选表名称。
返回前 n 个实体
要为任何查询返回前 n
个实体,请指定 $top
查询选项。 以下示例从名为 Customers 的表中返回前 10 个实体:
https://myaccount.table.core.windows.net/Customers()?$top=10
筛选 PartitionKey 和 RowKey 属性
由于 PartitionKey
和 RowKey
属性构成实体的主键,因此,你可以使用特殊语法标识该实体,如下所示:
https://myaccount.table.core.windows.net/Customers(PartitionKey='MyPartition',RowKey='MyRowKey1')
或者,可将这些属性指定为 $filter
选项的一部分,如以下部分中所示。
请注意,键属性名称和常量值区分大小写。
PartitionKey
和 RowKey
属性的类型均为 String
。
构造筛选器字符串
构造筛选器字符串时,请记住以下规则:
使用 OData 协议规范 定义的逻辑运算符将属性与值进行比较。 请注意不能比较属性和动态值;表达式的一侧必须是常量。
必须使用 URL 编码空格分隔属性名称、运算符和常量值。 空格经 URL 编码后为
%20
。筛选器字符串的所有部分都区分大小写。
常量值的数据类型必须与属性的类型相同,这样筛选器才能返回有效的结果。 有关支持的属性类型的详细信息,请参阅 Understanding the Table Service Data Model(了解表服务数据模型)。
注意
在假定属性不是字符串类型之前,请务必检查是否为属性显式设置了类型。 如果属性已显式指定类型,则返回实体时在响应内指示该类型。 如果属性未显式指定类型,将采用 String
类型,并且在返回实体时不在响应内指示该类型。
针对字符串属性进行筛选
在筛选字符串属性时,请用单引号将字符串常量引起来。
以下示例筛选 PartitionKey
和 RowKey
属性;也可以在查询字符串中添加其他非键属性。
https://myaccount.table.core.windows.net/Customers()?$filter=PartitionKey%20eq%20'MyPartitionKey'%20and%20RowKey%20eq%20'MyRowKey1'
以下示例筛选 FirstName
和 LastName
属性:
https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20eq%20'Smith'%20and%20FirstName%20eq%20'John'
请注意,表服务不支持通配符查询。 但是,可以通过对所需前缀使用比较运算符来执行前缀匹配。 以下示例返回 LastName
属性以字母“A”开头的实体:
https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20ge%20'A'%20and%20LastName%20lt%20'B'
针对数值属性进行筛选
要筛选整数或浮点数,请在 URI 上指定不带引号的常量值。
此示例返回 Age
属性值大于 30 的所有实体:
https://myaccount.table.core.windows.net/Customers()?$filter=Age%20gt%2030
以下示例返回 AmountDue
属性值小于或等于 100.25 的所有实体:
https://myaccount.table.core.windows.net/Customers()?$filter=AmountDue%20le%20100.25%20
针对布尔值属性进行筛选
要筛选布尔属性,请指定不带引号的 true
或 false
。
以下示例返回 IsActive
属性设置为 true
的所有实体:
https://myaccount.table.core.windows.net/Customers()?$filter=IsActive%20eq%20true
针对日期时间属性进行筛选
要筛选 DateTime
值,请在 URI 上指定 datetime
关键字,后跟用单引号引起来的日期/时间常量。 日期/时间常量必须采用组合 UTC 格式,如 设置 DateTime 值格式中所述。
以下示例返回 CustomerSince
属性等于 2008 年 7 月 10 日的实体:
https://myaccount.table.core.windows.net/Customers()?$filter=CustomerSince%20eq%20datetime'2008-07-10T00:00:00Z'
筛选 GUID 属性
要筛选 GUID 值,请在 URI 上指定 guid
关键字,后跟用单引号引起来的 guid 常量。
以下示例返回 GuidValue
属性等于 a455c695-df98-5678-aaaa-81d3367e5a34 的实体:
https://myaccount.table.core.windows.net/Customers()?$filter=GuidValue%20eq%20guid'a455c695-df98-5678-aaaa-81d3367e5a34'