Поделиться через


Запросы к таблицам и сущностям

При запросе данных таблиц и сущностей в службу таблиц требуется тщательно формировать 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 в службе таблиц