Интерфейс OData: примеры типовых операций
В данном разделе будут приведены примеры выполнения некоторых типовых операций по работе с данными с помощью стандартного интерфейса OData.
ВНИМАНИЕ!
Данные примеры не являются законченными. Они приведены только для иллюстрации применения различных конструкций.
Работа с одним объектом
Чтение данных
Для получения информации о сущности следует использовать канонический URL сущности. Чтение выполняется с помощью GET-запроса.
Пример чтения ссылочного объекта:
https://host/base/zone/odata/standard.odata/Catalog_Товары(guid'value')
Пример чтения набора записей подчиненного регистра сведений:
https://host/base/zone/odata/standard.odata/InformationRegister_ПриходныеЦены(Recorder_Key=guid'value')
В данном примере guid’value’ идентифицирует документ, выполнивший движение по регистру сведений.
Пример чтения записи регистра сведений:
https://host/base/zone/odata/standard.odata/InformationRegister_ПриходныеЦены_RecordType(Товар_Key=guid'value', ТипЦены="Приходная")
Пример чтения строки конкретного документа:
https://host/base/zone/odata/standard.odata/Document_РасходТовара_Товары(Ref_Key=guid'value', LineNumber=1)
Чтение виртуальной таблицы СрезПоследних регистра сведений КурсыВалют (с отбором по измерению ОсновнаяВалюта типа СправочникСсылка.Валюты) будет выглядеть следующим образом:
Пример чтения независимого регистра сведений:
https://host/base/zone/odata/standard.odata/InformationRegister_КурсыВалют/SliceLast?Condition=Валюта/ОсновнаяВалюта_Key eq guid'value'
Пример чтения подчиненного регистра сведений (к имени регистра следует добавить _RecordType):
https://host/base/zone/odata/standard.odata/InformationRegister_КурсыВалют_RecordType/SliceLast?Condition=Валюта/ОсновнаяВалюта_Key eq guid'value'
В данном примере guid’value’ идентифицирует элемент справочника Валюты, по значению которого выполняется отбор.
Пример получения остатков на счете из регистра бухгалтерии с условием по конкретному контрагенту:
https://host/base/zone/odata/standard.odata/AccountingRegister_Хозрасчетный/Balance(AccountCondition='Account_Key eq guid'value1'',Condition='ExtDimension1 eq cast(guid'value2', 'Catalog_Контрагенты')',ExtraDimensions='value3')?$format=json
В данном примере:
- guid’value1′ – уникальный идентификатор элемента плана счетов;
- guid’value2′ – уникальный идентификатор элемента плана видов характеристик ВидыСубконтоХозрасчетные с типом значения СправочникСсылка.Контрагенты;
- ‘value3’ – уникальный идентификатор элемента справочника Контрагенты.
Создание объекта
Для создания объекта следует воспользоваться POST-запросом с использованием URL набора сущностей, передав в теле запроса документ (в поддерживаемом формате), который содержит значения полей создаваемого объекта. Если передаваемый документ содержит свойства, отсутствующие у создаваемого объекта, то эти свойства игнорируются.
Далее приводится пример создания элемента справочника Товары и ответ стандартного интерфейса OData после успешного выполнения операции.
Пример POST-запроса (формат atom):
POST https://host/base/zone/odata/standard.odata/Catalog_Товары HTTP/1.1
User Agent: Fiddler
Host: host
Content Length: 981
<entry>
<category term="StandardODATA.Catalog_Товары" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>
<title type="text"/>
<updated>2014 02 14T12:05:55</updated>
<author/>
<summary/>
<content type="application/xml">
<m:properties xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
<d:DeletionMark>false</d:DeletionMark>
<d:Parent_Key>bbb079ae 8c51 11db a9b0 00055d49b45e</d:Parent_Key>
<d:IsFolder>false</d:IsFolder>
<d:Code>000000800</d:Code>
<d:Description>Шлепанцы</d:Description>
<d:Артикул>SL56X</d:Артикул>
<d:Поставщик_Key>086715b0 f348 11db a9c5 00055d49b45e</d:Поставщик_Key>
<d:Вид>Товар</d:Вид>
<d:Штрихкод/>
<d:Описание><html>Шлепанцы пляжные</html></d:Описание>
</m:properties>
</content>
</entry>
Пример ответа стандартного интерфейса OData:
HTTP/1.1 201 Created
Content Length: 2705
Content Type: application/atom+xml;type=entry;charset=utf 8
Location: https://host/base/zone/odata/standard.odata/Catalog_Товары(guid'41aa6331 954f 11e3 814b 005056c00008')
Server: Microsoft IIS/7.5
DataServiceVersion: 3.0
X Powered By: ASP.NET
Date: Fri, 14 Feb 2014 08:18:36 GMT
<?xml version="1.0" encoding="UTF 8"?>
<entry 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">
<id>https://host/base/zone/odata/standard.odata/Catalog_Товары(guid'41aa6331 954f 11e3 814b 005056c00008')</id>
<category term="StandardODATA.Catalog_Товары" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>
<title type="text"/>
<updated>2014 02 14T12:18:36</updated>
<author/>
<summary/>
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/ФайлКартинки"
href="Catalog_Товары(guid'41aa6331 954f 11e3 814b 005056c00008')/ФайлКартинки"
type="application/atom+xml;type=entry;charset=utf 8"
title="ФайлКартинки"/>
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Parent"
href="Catalog_Товары(guid'41aa6331 954f 11e3 814b 005056c00008')/Parent"
type="application/atom+xml;type=entry;charset=utf 8"
title="Parent"/>
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Поставщик"
href="Catalog_Товары(guid'41aa6331 954f 11e3 814b 005056c00008')/Поставщик"
type="application/atom+xml;type=entry;charset=utf 8"
title="Поставщик"/>
<link rel="edit"
href="Catalog_Товары(guid'41aa6331 954f 11e3 814b 005056c00008')"
title="edit link"/>
<content type="application/xml">
<m:properties xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
<d:Ref_Key>41aa6331 954f 11e3 814b 005056c00008</d:Ref_Key>
<d:DataVersion m:null="true"/>
<d:Description>Шлепанцы</d:Description>
<d:Code>000000800</d:Code>
<d:Parent_Key>bbb079ae 8c51 11db a9b0 00055d49b45e</d:Parent_Key>
<d:IsFolder>false</d:IsFolder>
<d:DeletionMark>false</d:DeletionMark>
<d:Артикул>SL56X</d:Артикул>
<d:Поставщик_Key>086715b0 f348 11db a9c5 00055d49b45e</d:Поставщик_Key>
<d:ФайлКартинки_Key>00000000 0000 0000 0000 000000000000</d:ФайлКартинки_Key>
<d:Вид>Товар</d:Вид>
<d:Штрихкод/>
<d:Описание><html>Шлепанцы пляжные</html></d:Описание>
<d:ФайлКартинки_Key>00000000 0000 0000 0000 000000000000</d:ФайлКартинки_Key>
<d:Parent_Key>bbb079ae 8c51 11db a9b0 00055d49b45e</d:Parent_Key>
<d:Поставщик_Key>086715b0 f348 11db a9c5 00055d49b45e</d:Поставщик_Key>
</m:properties>
</content>
</entry>
Пример POST-запроса (формат json):
POST https://host/base/zone/odata/standard.odata/Catalog_Товары HTTP/1.1
Accept: application/json
Accept Charset: UTF 8
User Agent: Fiddler
Content Type: application/json
Content Length: 2426
{
"DeletionMark":false,
"Parent_Key":"bbb079ae 8c51 11db a9b0 00055d49b45e",
"IsFolder":false
"Code":"000000800",
"Description":"Шлепанцы",
"Артикул":"SL56X",
"Поставщик_Key":"086715b0 f348 11db a9c5 00055d49b45e",
"Вид":"Товар",
"Штрихкод":null,
"Описание:"Шлепанцы пляжные"
}
Обновление объекта
Для обновления объекта необходимо выполнить PUT-/PATCH-запрос с использованием канонического URL сущности (аналогично запросу GET для получения сущности), передав в теле запроса XML-документ (в формате atom) или JSON-документ (в формате json), который содержит значения свойств сущности. Если передаваемый документ содержит свойства, отсутствующие у создаваемого объекта, то эти свойства игнорируются.
В случае PATCH-запроса пропущенные свойства сущности будут проигнорированы, т. е. будут изменены только те свойства, которые переданы в запросе на изменение. Для PUT-запроса необходимо указывать значения всех свойств обновляемой сущности.
При модификации сущности через PUT-запрос, при записи значений ссылочных реквизитов, следует использовать поле ИмяСсылочногоРеквизита@odata.bind куда следует поместить URI-сущности (можно в укороченном варианте – только фрагмент пути после standard.odata).
Например:
PUT http://host /base/odata/standard.odata/Document_Документ(guid'19961ec3 3c5f 11e7 8785 50465da19fe4')?$format=json
{
"Date": "2015 01 01T12:01:07",
"Организация@odata.bind": "Catalog_Организации(guid'298584b5 92e4 11e3 8bc3 0050568b1678')",
"Склад@odata.bind": http://host /base/odata/standard.odata/Catalog_Склады(guid'081bc346 2abc 13e4 a1bd 0050568b1688')
…
}
В следующем примере рассматривается изменение реквизита Наименование и состава табличной части ТорговыеЗалы справочника Магазины. Остальные реквизиты справочника не используются в рамках данного примера. В примере используется формат данных json.
Пример PATCH-запроса:
PATCH https://host/base/zone/odata/standard.odata/Catalog_Магазины(guid'value')?$format=json HTTP/1.1
Host: host
Connection: keep alive
Accept: application/json
Content Length: 638
{
"odata.metadata": "https://host/base/zone/odata/standard.odata/$metadata#Catalog_Магазины/@Element",
"Description": "Новое описание магазина",
"ТорговыеЗалы@odata.type" : "Collection(StandardODATA.Catalog_Магазины_ТорговыеЗалы_RowType)"
"ТорговыеЗалы": [
{
"LineNumber": "1",
"Название": "Синий зал",
"Площадь": 56,
"ДатаОткрытия": "2015 01 01T00:00:00"
},
{
"LineNumber": "2",
"Название": "Красный зал",
"Площадь": 56,
"ДатаОткрытия": "2015 06 13T11:45:41"
}
]
}
ВНИМАНИЕ!
Табличную часть следует передавать полностью (все строки) даже в том случае, если требуется изменить данные только в одной строке этой табличной части.
В данном примере guid’value’ идентифицирует изменяемый элемент справочника Магазины.
Удаление объекта
Для удаления объекта следует воспользоваться DELETE-запросом с использованием канонического URL сущности.
ВНИМАНИЕ!
Пометка на удаление не выполняется, объект удаляется непосредственно.
Оптимистическая блокировка данных
Для оптимистической блокировки данных (т.е. для проверки, что данные не изменились с момента считывания) нужно использовать заголовок If-Match HTTP-запроса, связанного с модификацией (PATCH) или удалением (DELETE) данных.
В качестве значения заголовка должно выступать значение свойства DataVersion, которое получено при предварительном чтении сущности.
Механизм работает следующим образом:
- При запросе экземпляра сущности среди прочих возвращается свойство DataVersion. При запросе набора сущностей с каждой из сущностей набора возвращается свойство DataVersion.
- Клиентское приложение должно сохранить у себя это значение версии объекта и затем использовать его в запросах PATCH и DELETE, передавая его в заголовке If-Match.
- Если значение свойства DataVersion в момент исполнения запроса совпадает со значением заголовка If-Match, то происходит запрошенное действие. В противном случае действие не выполняется, а клиенту возвращается HTTP статус 412.
Запись объекта в режиме загрузки данных
Если при записи объекта необходимо эмулировать запись, выполняемую во время работы механизма обмена данными (свойство ОбменДанными.Загрузка = Истина) следует использовать HTTP-заголовок 1C_OData-DataLoadMode со значением true при выполнении соответствующей операции записи.
Проведение и отмена проведения документа
Для проведения документа необходимо выполнить POST-запрос с использованием канонического URL сущности (аналогично запросу GET для получения сущности), указав особым образом сформированный суффикс URL. Суффикс в этом случае будет состоять из команды Post и параметра, указывающего режим проведения документа: https://host/base/zone/odata/standard.odata/Document_РасходТоваров(guid’value’)/Post?PostingModeOperational=false.
Для отмены проведения документа суффикс состоит из команды Unpost без параметров.
Работа с коллекцией объектов
Для получения набора сущностей какого-либо вида, следует выполнить GET-запрос с использованием URL следующего вида: https://host/base/zone/odata/standard.odata/ExchangePlan_ОбменДанными.
Если необходимо установить отбор на получаемый список, его можно выполнить с помощью параметра $filter (см. здесь), который указывается в URL:
http://host/base/standard.odata/Document_Накладная?$filter=Приоритет eq 1
Обращение к виртуальной таблице регистра выглядит следующим образом (на примере виртуальной таблицы ОстаткиИОбороты регистра накопления ТоварныеЗапасы):
https://host/base/zone/odata/standard.odata/AccumulationRegister_ТоварныеЗапасы/BalanceAndTurnovers(StartPeriod=datetime'2014 01 01', EndPeriod=datetime'2014 02 01', Condition='Товар_Key eq guid'value'')1
Также для ограничения набора сущностей можно использовать параметры $top и $select (см. здесь).
Работа с планами обмена
Формирование сообщения обмена
Для формирования сообщения обмена необходимо выполнить POST-запрос с использованием URL следующего вида: https://host/base/zone/odata/standard.odata/SelectChanges?<params>. Где в качестве параметров необходимо указать следующее:
- Параметр DataExchangePoint – должен содержать канонический URL сущности треуемого элемента плана обмена;
- Параметр MessageNo – должен содержать номер сообщения обмена данными, который будет сформирован в результате данного вызова.
В результате, полный URL для формирования сообщения обмена, будет выглядеть следующим образом:
https://host/base/zone/odata/standard.odata/SelectChanges?DataExchangePoint='https://host/base/zone/odata/standard.odata/ExchangePlan_ОбменДанными(guid'value')'&MessageNo=34
.
В результате будет получен список изменений, которые необходимо передать в другой узел, в виде потока atom-feed. Каждый элемент будет представлен в формате atom-entry, а удаленные элементы будет представлены в формате atom-deleted-entry (RFC 6721, http://tools.ietf.org/html/rfc6721, на английском языке).
Уведомление о получении изменений
Для уведомления сервера о том, что сообщение обмена успешно получено, необходимо выполнить POST-запрос с использованием URL следующего вида: https://host/base/zone/odata/standard.odata/NotifyChangesReceived?<params>. Где в качестве параметров необходимо указать следующее:
- Параметр DataExchangePoint – должен содержать канонический URL сущности требуемого элемента плана обмена;
- Параметр MessageNo – должен содержать номер сообщения обмена данными, подтверждение получения которого необходимо зафиксировать.
В результате, полный URL для подтверждения получения сообщения обмена, будет выглядеть следующим образом:
https://host/base/zone/odata/standard.odata/NotifyChangesReceived?DataExchangePoint='https://host/base/zone/odata/standard.odata/ExchangePlan_ОбменДанными(guid'value')'&MessageNo=34
.
Работа с OData из Microsoft Excel
В качестве примера работы с OData из сторонних программ можно привести Excel. Для использования OData нужно в разделе “Данные” в меню “Получить данные” выбрать “Из других источников” → “Из канала OData”.
В открывшемся окне нужно указать ссылку на нужную сущность, например на список контрагентов https://bp.42clouds.com/bp_base1/12345/odata/standard.odata/Catalog_Контрагенты
На форме авторизации нужно выбрать “Базовый”, ввести логин/пароль пользователя (служебного или обычного), в качестве уровня, к которому следует применить эти параметры, указать вашу область данных, нажать “Подключение”.
Excel выведет данные предварительного просмотра, которые можно будет загрузить в таблицу или преобразовать.
