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

Query Entities (Сущности запроса)

  • Статья

Операция 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 (только версии до 11.12.2015)
- application/json;odata=nometadata
- application/json;odata=minimalmetadata
- application/json;odata=fullmetadata

Дополнительные сведения см. в разделе Формат полезных данных для операций хранилища таблиц.
x-ms-client-request-id Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером.

Текст запроса

Нет.

Пример запроса

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		 Указывает, что:

— Количество возвращаемых сущностей превышает 1000.
— превышено время ожидания сервера.
— Достигнута граница сервера, если запрос возвращает данные, распределенные по нескольким серверам.

Дополнительные сведения об использовании маркеров продолжения см. в разделе Время ожидания запроса и разбиение на страницы.
x-ms-request-id Однозначно идентифицирует выполненный запрос. Его можно использовать для устранения неполадок с запросом. Дополнительные сведения см. в разделе Устранение неполадок с операциями API.
x-ms-version Указывает версию хранилища таблиц, которая использовалась для выполнения запроса. Этот заголовок возвращается для запросов к версии 2009-09-19 и более поздним версиям.
Date Значение даты и времени в формате UTC, указывающее время, в которое служба отправила ответ.
Content-Type Указывает тип содержимого полезных данных. Значение этого заголовка зависит от значения заголовка запроса Accept. Возможны следующие значения:

- application/atom+xml (только версии до 11.12.2015)
- application/json;odata=nometadata
- application/json;odata=minimalmetadata
- application/json;odata=fullmetadata

Дополнительные сведения о допустимых типах контента см. в разделе Формат полезных данных для операций хранилища таблиц.
x-ms-client-request-id Может использоваться для устранения неполадок с запросами и соответствующими ответами. Значение этого заголовка равно значению заголовка x-ms-client-request-id , если он присутствует в запросе и содержит не более 1024 видимых символов 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 (версии до 11.12.2015)

Ниже приведен пример 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>

Авторизация

Эта операция может выполняться владельцем учетной записи, а также любым пользователем с подписью общего доступа, у которой имеется разрешение на выполнение данной операции.

Комментарии

Запрос к хранилищу таблиц может возвращать не более 1000 сущностей одновременно и выполняться не более пяти секунд. Ответ включает пользовательские заголовки, содержащие набор маркеров продолжения в любом из следующих случаев:

  • Результирующий набор содержит более 1000 сущностей.
  • Запрос не был завершен в течение пяти секунд.
  • Запрос пересекает границу раздела.

Маркеры продолжения можно использовать для создания последующего запроса для следующей страницы данных. Дополнительные сведения о маркерах продолжения см. в разделе Время ожидания запроса и разбиение на страницы.

Примечание

При выполнении последующих запросов, включающих маркеры продолжения, обязательно передайте исходный универсальный код ресурса (URI) в запросе. Например, если вы указали $filterпараметр запроса , $selectили $top как часть исходного запроса, включите этот параметр в последующие запросы. В противном случае последующие запросы могут возвращать непредвиденные результаты.

Параметр $top запроса в этом случае указывает максимальное количество результатов на странице. В нем не указано максимальное число результатов во всем наборе ответов.

Дополнительные сведения см. в разделе Запросы к таблицам и сущностям.

Для запросов проекции $select , использующих параметр запроса, версия должна быть 2011-08-18 или более поздней. Максимальное число возвращаемых свойств — 255. Текст ответа включает все проецируемые свойства, даже если свойства не являются частью возвращаемой сущности.

Например, если запрос содержит свойство, которого проецируемая сущность не содержит, отсутствующее свойство помечается как атрибут со значением NULL. Предыдущий пример текста ответа включает Address свойство , которое не является частью проецируемого объекта. Таким образом, значение свойства равно NULL: <d:Address m:null="true" />.

Общее время, отведенное запросу на планирование и обработку запроса, составляет 30 секунд. Эта сумма включает в себя пять секунд на выполнение запроса.

Обратите внимание, что правая часть выражения запроса должна быть константой. Нельзя ссылаться на свойство в правой части выражения. Дополнительные сведения о создании выражений запросов см. в разделе Таблицы и сущности запросов.

Выражение запроса не может содержать null значения. Следующие символы должны быть закодированы, если они используются в строке запроса:

  • Косая черта (/)

  • Вопросительный знак (?)

  • Двоеточие (:)

  • При знаке (@)

  • Амперсанд (&)

  • Знак равенства (=)

  • Знак "плюс" (+)

  • Запятая (,)

  • Знак доллара ($)

Любое приложение, которое может авторизовать и отправить HTTP-запрос GET , может запрашивать сущности в таблице.

Дополнительные сведения о поддерживаемых операциях запросов к хранилищу таблиц через LINQ см. в разделах Операторы запросов, поддерживаемые для хранилища таблиц , и Запись запросов LINQ к хранилищу таблиц.

См. также раздел

Коды ошибок хранилища таблиц
Авторизация запросов к службе хранилища Azure
Коды состояний и ошибок
Обращение к ресурсам хранилища таблиц
Запрос таблиц и сущностей
Установка заголовков версии службы данных OData
Insert Entity (Вставка сущности )
Обновление сущности
Delete Entity (Удаление сущности)