Запросы к таблицам и сущностям
При запросе данных таблиц и сущностей в службу таблиц требуется тщательно формировать 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 в запросе. Например, если вы указали $filterпараметр запроса , $selectили $top в составе исходного запроса, необходимо включить этот параметр в последующие запросы. В противном случае последующие запросы могут возвращать непредвиденные результаты. Дополнительные сведения см. в разделе Время ожидания запроса и разбиение на страницы .
Обратите внимание, что $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
Примеры выражений запроса
В следующих примерах показано, как построить URI запроса для некоторых типичных запросов сущностей с помощью синтаксиса REST. Те же запросы можно записать с помощью синтаксиса LINQ. Дополнительные сведения см. в статье Написание запросов LINQ к службе таблиц.
Обратите внимание, что параметры $top и $filter можно использовать для фильтрации имен таблиц, используя синтаксис фильтрации по свойствам типа String.
Получение n верхних сущностей
Чтобы получить n верхних сущностей для любого запроса, укажите параметр $top. В следующем примере запрашиваются 10 верхних сущностей из таблицы с именем Customers.
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.Во всех частях строки фильтра учитывается регистр.
Для получения допустимых результатов фильтра значения константы и свойства должны иметь одинаковый тип данных. Дополнительные сведения о поддерживаемых типах свойств см. в статье Общие сведения о модели данных службы таблиц.
Примечание
Обязательно проверьте, было ли свойство явно типизировано, прежде чем работать с ним как со строкой. Если свойство явно типизировано, его тип обозначается в ответе при получении сущности. Если свойству не был задан тип, то оно будет иметь тип 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 начинается с буквы А:
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
Для фильтрации по значению DateTime укажите в URI ключевое слово datetime, за которым введите константу даты или времени в одинарных кавычках. Константа даты и времени должна иметь комбинированный формат UTC, как описано в разделе Форматирование значений даты и времени.
Следующий пример возвращает сущности, у которых свойство CustomerSince равно 10 июля 2008 года:
https://myaccount.table.core.windows.net/Customers()?$filter=CustomerSince%20eq%20datetime'2008-07-10T00:00:00Z'
Фильтрация по свойствам GUID
Для фильтрации по значению GUID укажите в URI ключевое слово guid, за которым введите константу GUID в одинарных кавычках.
Следующий пример возвращает сущности, у которых свойство GuidValue равно:
https://myaccount.table.core.windows.net/Customers()?$filter=GuidValue%20eq%20guid'a455c695-df98-5678-aaaa-81d3367e5a34'
См. также:
Основные понятия службы таблиц
Основные сведения о модели данных службы таблиц
Адресация ресурсов службы таблиц
Время ожидания запроса и разбивка на страницы
Написание запросов LINQ в службе таблиц