Формат полезных данных для операций службы таблиц

  • Статья

API REST службы таблиц поддерживает форматы полезных данных ATOM и JSON. Хотя протокол ATOM поддерживается для всех версий служб хранилища Azure, протокол JSON поддерживается только для версии 2013-08-15 и более поздних версий.

  • Json — это рекомендуемый формат полезных данных. JSON поддерживается для версии 2013-08-15 и более поздних версий. Необходимо использовать JSON с версией 2015-12-11 и более поздними версиями.

  • ATOM поддерживается для версий, предшествующих 11.12.2015.

Примечание

Следующие операции REST API не являются API OData и в настоящее время не поддерживают JSON: Get Table ACL, Set Table ACL, Get Table Service Properties и Set Table Service Properties.

Чтобы указать формат JSON или ATOM, укажите соответствующие значения для Content-Type заголовков и Accept (описано ниже). Обратите внимание на следующие ограничения.

  • Заголовок Content-Type требуется для всех запросов, содержащих полезные данные OData.

  • Если заголовок Accept не указан, то тип содержимого в ответе будет иметь стандартное значение application/atom+xml.

  • Если версия службы данных OData задается как 3.0, то указание параметра URI $format переопределяет значение, указанное в заголовке запроса Accept. Дополнительные сведения о версии службы OData см. в разделе Настройка заголовков версии службы данных OData .

Чтобы выбрать формат полезных данных, нужно установить заголовки запроса Content-Type и Accept согласно нижеприведенной таблице.

Формат полезных данных Заголовок Content-Type Заголовок Accept Версия службы данных (версия API REST) Поддерживаемые API
Atom application/atom+xml application/atom+xml 1.0 (любая версия)

2.0 (18.08.2011 или более поздняя версия)

3,0 (15.08.2013 или более поздняя)		 QueryTables

CreateTable

Удалить таблицу

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

Вставка сущностей

Вставка или слияние сущностей

Вставка или замена сущности

Update Entity (Обновление сущности)

Merge Entity (Слияние сущностей)

Delete Entity (Удаление сущности)
JSON application/json application/json;odata=nometadata

application/json;odata=minimalmetadata

application/json;odata=fullmetadata

Дополнительные сведения см. ниже в разделе Формат JSON.		 3,0 (15.08.2013 или более поздняя) QueryTables

CreateTable

Удалить таблицу

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

Вставка сущностей

Вставка или слияние сущностей

Вставка или замена сущности

Update Entity (Обновление сущности)

Merge Entity (Слияние сущностей)

Delete Entity (Удаление сущности)
XML application/xml application/xml Н/Д Получение списка управления доступом для таблицы

Задание списков управления доступом для таблиц

Получение свойств службы таблиц

Задание свойств службы таблиц

Формат JSON (application/json) (версии 2013-08-15 и более поздние)

OData расширяет формат JSON, определяя общие соглашения для следующих пар имя-значение, подобно формату ATOM, описанному выше. OData определяет набор канонических заметок для контрольных сведений, таких как идентификаторы, тип и ссылки. Дополнительные сведения о формате JSON см. в разделе Знакомство с JSON.

Главное преимущество использования формата OData JSON заключается в том, что прогнозируемые части полезных данных можно пропустить для уменьшения размера полезных данных. Чтобы воспроизвести эти данные, в точке приема применяются выражения для вычисления недостающих ссылок, сведений о типе и контрольных сведений. Для управления пропуском данных в наборе применяются три уровня, которые можно указать в качестве части заголовка Accept.

  • application/json;odata=nometadata

  • application/json;odata=minimalmetadata

  • application/json;odata=fullmetadata

Службой таблицы Azure поддерживаются следующие заметки ODATA.

  • odata.metadata: URL-адрес метаданных для коллекции, сущности, значения примитива или сервисного документа.

  • odata.id: идентификатор сущности, который обычно является URL-адресом ресурса.

  • odata.editlink: ссылка, используемая для изменения или обновления записи, если сущность можно обновлять и идентификатор odata.id не представляет URL-адрес, который может использоваться для изменения сущности.

  • odata.type: имя типа вмещающего объекта.

  • odata.etag: ETag сущности.

  • PropertyName@odata.type, для пользовательских свойств: имя типа целевого свойства.

  • PropertyName@odata.type, для системных свойств (т. е.PrimaryKey свойств , RowKeyиTimestamp): имя типа целевого свойства.

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

Annotations odata=fullmetadata odata=minimalmetadata odata=nometadata
odata.metadata Да Да Нет
odata.id Да Нет Нет
odata.editlink Да Нет Нет
odata.type Да Нет Нет
odata.etag Да Нет Нет
PropertyName@odata.type для пользовательских свойств Да Да Нет
PropertyName@odata.type для системных свойств Да Нет Нет

Типы свойств в канале JSON

Заметка odata.type используется в формате OData JSON для определения типа открытого свойства. Эта заметка присутствует, когда выполняются все приведенные ниже условия.

  • Уровень управления JSON имеет значение odata=minimalmetadata или odata=fullmetadata, как описано в разделе Формат JSON.

  • Свойство является пользовательским. Обратите внимание, что для таблиц Azure только свойства PartitionKey, RowKey и Timestamp являются системными и информация об их типе объявлена в $metadata. Заметка типа для этих свойств присутствует, только если уровень управления имеет значение odata=fullmetadata. Дополнительные сведения см. в статье Общие сведения о модели данных службы таблиц.

  • Тип свойства нельзя определить через эвристики обнаружения типа, приведенные в таблице ниже.

Тип Edm требуется заметка odata.type Тип JSON
Edm.Binary Да Строка
Edm.Boolean Нет Литералы
Edm.DateTime Да Строка
Edm.Double Нет Числовой (содержит десятичную запятую)
Edm.Guid Да Строка
Edm.Int32 Нет Числовой (не содержит десятичную запятую)
Edm.Int64 Да Строка
Edm.String нет Строка
Недоступно Нет NULL

Служба таблиц не сохраняет null значения для свойств. При записи сущности null значение может быть указано с заметкой odata.type или без нее, а любое свойство со значением null обрабатывается так, как если бы запрос не содержал этого свойства. Null значения свойств никогда не возвращаются при запросе сущностей.

Для Edm.Double значения NaN, Infinity и -Infinity представляются в JSON с помощью типа String, а заметка odata.type является обязательной. Служба таблиц не поддерживает отрицательную версию NaN, а в формате JSON не различает положительный и отрицательный нуль (обрабатывается -0.0 как 0.0).

Следующая сущность JSON содержит пример для каждого из восьми различных типов свойств.

{  
  "PartitionKey":"mypartitionkey",  
  "RowKey":"myrowkey",  
  "DateTimeProperty@odata.type":"Edm.DateTime",  
  "DateTimeProperty":"2013-08-02T17:37:43.9004348Z",  
  "BoolProperty":false,  
  "BinaryProperty@odata.type":"Edm.Binary",  
  "BinaryProperty":"AQIDBA==",  
  "DoubleProperty":1234.1234,  
  "GuidProperty@odata.type":"Edm.Guid",  
  "GuidProperty":"4185404a-5818-48c3-b9be-f217df0dba6f",  
  "Int32Property":1234,  
  "Int64Property@odata.type":"Edm.Int64",  
  "Int64Property":"123456789012",  
  "StringProperty":"test"  
}

Поскольку PartitionKey и RowKey являются системными свойствами, это означает, что все строки таблицы должны определять эти свойства, а их заметки типа нет в сущности. Эти свойства стандартны как тип Edm.String. Однако другие свойства являются настраиваемыми и поэтому содержат сведения о типах, соответствующие одному из поддерживаемых примитивных типов в приведенной выше таблице.

Примеры:

В следующем примере записи OData показан формат JSON, отправленный в виде запроса на вставку сущности в хранилище таблиц Azure (дополнительные сведения об операции вставки см. в разделе Вставка сущности ):

{  
  "Address":"Mountain View",  
  "Age":23,  
  "AmountDue":200.23,  
  "CustomerCode@odata.type":"Edm.Guid",  
  "CustomerCode":"c9da6455-213d-42c9-9a79-3e9149a57833",  
  "CustomerSince@odata.type":"Edm.DateTime",  
  "CustomerSince":"2008-07-10T00:00:00",  
  "IsActive":true,  
  "NumOfOrders@odata.type":"Edm.Int64",  
  "NumOfOrders":"255",  
  "PartitionKey":"mypartitionkey",  
  "RowKey":"myrowkey1",  
}

Когда клиент запрашивает набор сущностей в хранилище таблиц Azure, служба отвечает полезными данными JSON (дополнительные сведения об операции запроса см. в разделе Сущности запроса). Веб-канал может включать один из трех уровней информации: без метаданных, минимальные метаданные или полные метаданные. В следующих примерах демонстрируется каждый уровень:

Метаданные отсутствуют:

{  
  "value":[  
    {  
      "PartitionKey":"Customer03",  
      "RowKey":"Name",  
      "Timestamp":"2013-08-09T18:55:48.3402073Z",  
      "CustomerSince":"2008-10-01T15:25:05.2852025Z",  
    }  
}

Минимальные метаданные:

{  
  "odata.metadata":"https://myaccount.table.core.windows.net/$metadata#Customers,  
  "value":[  
    {  
      "PartitionKey":"Customer03",  
      "RowKey":"Name",  
      "Timestamp":"2013-08-09T18:55:48.3402073Z",  
      "CustomerSince@odata.type":"Edm.DateTime",  
      "CustomerSince":"2008-10-01T15:25:05.2852025Z",  
    }  
}

Полные метаданные:

{  
  "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='Customer03',RowKey='Name')",  
      "odata.etag":"W/\"0x5B168C7B6E589D2\"",  
      "odata.editLink":"Customers(PartitionKey='Customer03',RowKey='Name')",  
      "PartitionKey":"Customer03,  
      "RowKey":"Name",  
      "Timestamp@odata.type":"Edm.DateTime",  
      "Timestamp":"2013-08-09T18:55:48.3402073Z",  
      "CustomerSince@odata.type":"Edm.DateTime",  
      "CustomerSince":"2008-10-01T15:25:05.2852025Z",  
    }  
}

Дополнительные сведения о формате OData JSON см. в спецификации формата OData JSON версии 4.0 в сочетании с документом [MS-ODATAJSON]: поддержка стандартов формата JSON протокола OData.

Формат Atom (application/atom+xml) (только версии, предшествующие 11.12.2015)

Atom — это формат документов на основе XML, описывающий коллекции связанных сведений, называемых веб-каналами. Каналы состоят из нескольких элементов или записей. AtomPub определяет дополнительные конструкции формата для записей и веб-каналов, чтобы ресурсы, которые они представляли, можно было легко классифицировать, группировать, редактировать и обнаруживать. Однако, поскольку Atom не определяет, как структурированные данные кодируются с помощью веб-каналов, OData определяет набор соглашений для представления структурированных данных в веб-канале Atom, чтобы обеспечить передачу структурированного содержимого службами на основе OData.

Например, следующий пример записи OData демонстрирует формат Atom, отправленный через запрос на вставку сущности в хранилище таблиц Azure с помощью REST API (дополнительные сведения об операции вставки см. в разделе Вставка сущности ):

<?xml version="1.0" encoding="utf-8" standalone="yes"?>  
<entry xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="https://www.w3.org/2005/Atom">  
  <title />  
  <author>  
    <name />  
  </author>  
  <id />  
  <content type="application/xml">  
    <m:properties>  
      <d:Address>Mountain View</d:Address>  
      <d:Age m:type="Edm.Int32">23</d:Age>  
      <d:AmountDue m:type="Edm.Double">200.23</d:AmountDue>  
      <d:BinaryData m:type="Edm.Binary" m:null="true" />  
      <d:CustomerCode m:type="Edm.Guid">c9da6455-213d-42c9-9a79-3e9149a57833</d:CustomerCode>  
      <d:CustomerSince m:type="Edm.DateTime">2008-07-10T00:00:00</d:CustomerSince>  
      <d:IsActive m:type="Edm.Boolean">true</d:IsActive>  
      <d:NumOfOrders m:type="Edm.Int64">255</d:NumOfOrders>  
      <d:PartitionKey>mypartitionkey</d:PartitionKey>  
      <d:RowKey>myrowkey1</d:RowKey>  
    </m:properties>  
  </content>  
</entry>

Когда клиент запрашивает набор сущностей в хранилище таблиц, служба отвечает веб-каналом Atom, который представляет собой коллекцию записей Atom (дополнительные сведения об операции запроса см. в разделе Сущности запроса ):

<?xml version="1.0" encoding="utf-8" standalone="yes"?>  
<feed xml:base="https://myaccount.table.core.windows.net/" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="https://www.w3.org/2005/Atom">  
  <title type="text">Customers</title>  
  <id>https://myaccount.table.core.windows.net/Customers</id>  
  <link rel="self" title="Customers" href="Customers" />  
  <entry m:etag="W/"0x5B168C7B6E589D2"">  
  <id>https://myaccount.table.core.windows.net/Customers(PartitionKey='Customer03',RowKey='Name')</id>  
    <title type="text"></title>  
    <updated>2008-10-01T15:26:13Z</updated>  
    <author>  
      <name />  
    </author>  
    <link rel="edit" title="Customers" href="Customers (PartitionKey='Customer03',RowKey='Name')" />  
    <category term="myaccount.Customers" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />  
    <content type="application/xml">  
      <m:properties>  
        <d:PartitionKey>Customer03</d:PartitionKey>  
        <d:RowKey>Name</d:RowKey>        <d:CustomerSince m:type="Edm.DateTime">2008-10-01T15:25:05.2852025Z</d:CustomerSince>  
      </m:properties>  
    </content>  
  </entry>  
</feed>

Типы свойств в веб-канале Atom

Типы данных свойств определяются спецификацией протокола OData. Не все типы данных, определенные в спецификации, поддерживаются службой таблиц. Сведения о поддерживаемых типах данных и их сопоставлении с типами СРЕДЫ CLR см. в разделе Основные сведения о модели данных службы таблиц.

Свойство может указываться с точным типом данных или без него. Если тип не указан, свойство автоматически создается с типом данных Edm.String.

Если свойство создается с явным типом, то запрос, который возвращает сущность, включает этот тип в веб-канал Atom, так что при необходимости можно определить тип существующего свойства. Знание типа свойства важно при создании запроса, производящего фильтрацию по этому свойству. Дополнительные сведения см. в разделе Запросы к таблицам и сущностям.

Для Double свойств значения NaN, INFи -INF используются в Atom для обозначения не числа, положительной бесконечности и отрицательной бесконечности соответственно. Формы Infinity и -Infinity также принимаются. Служба таблиц не поддерживает отрицательную версию NaN. В формате Atom он различает положительный и отрицательный нуль.

См. также:

Установка заголовков версий данных службы OData
Управление версиями для служб хранилища Azure
Основные понятия службы таблиц