18.2. HTTP-сервисы

18.2.1. Cтандартный интерфейс OData

18.2.1.1. Общая информация

Стандартный интерфейс OData в «1С:Предприятии» предназначен для получения доступа к данным системы из внешнего приложения без модификации кода прикладного решения (например, если прикладное решение стоит на поддержке). Для получения такого доступа необходимо особым образом опубликовать приложение на веб-сервере и указать, какие объекты конфигурации будут использоваться таким образом (см. здесь ).

Для доступа к данным используется протокол OData (http://www.odata.org/ , на английском языке) версии 3 (http://www.odata.org/documentation/odata-version-3-0/odata-version-3-0-core-protocol , на английском языке). Поддерживаются следующие форматы представления данных: atom-xml и json. Для доступа к данным, при публикации, автоматически генерируется стандартный интерфейс OData, который позволяет читать данные «1С:Предприятия», изменять их, создавать новые объекты данных и удалять существующие. Прикладное решение на базе «1С:Предприятия» может выступать как клиентом, так и сервером при работе со стандартным интерфейсом OData. Для работы сервером практически никаких дополнительных действий осуществлять не надо (эта возможность предоставляется автоматически). Для того, чтобы стать клиентом стандартного интерфейса OData, необходимо в прикладном решении реализовать программный слой, который будет использовать данные сервера с использованием стандартных интерфейсов «1С:Предприятия», например объекта HTTPСоединение.

В одной системе могут одновременно существовать и SOAP-сервисы (которые реализуются в «1С:Предприятие» в виде Web-сервисов, см.здесь ) и стандартный интерфейс OData и HTTP-сервис (см. здесь ).

Стандартный интерфейс OData можно использовать для следующих задач:

● Интеграция прикладного решения с различными сайтами (например, на базе Microsoft SharePoint);

● Реализация сторонними средствами дополнительной функциональности прикладного решения без изменения его конфигурации;

● Загрузка данных в прикладное решение и выгрузка данных из него;

● Интеграция прикладного решения с корпоративными системами, возможно даже без дополнительного программирования.

Типичные операции, выполняемые с помощью стандартного интерфейса OData:

● Получение списка объектов системы с установленным отбором;

● Получение данных конкретного объекта системы;

● Создание нового и запись изменений существующего объекта системы;

● Проведение одного документа, старт бизнес-процесса.

18.2.1.2. Общие принципы работы

При работе с протоколом OData используется специальная терминология. При применении протокола используются следующие термины:

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

● Набор сущностей – коллекция сущностей определенного типа.

● Составной тип – набор свойств, не обладающий идентичностью.

● Функция – набор некоторых операций, выполняемых на стороне сервера, возвращающий данные (не обязательно сущность или набор сущностей) и не приводящий к наблюдаемым побочным эффектам (изменениям данных). Функция обязательно связана с сущностью или набором сущностей.

● Действие – функция, которая может изменять данные.

Термины протокола некоторым образом соответствуют терминам, принятым в системе «1С:Предприятие»:

● Сущность – в качестве сущности может выступать один из 4 групп объектов системы «1С:Предприятие»: объектные типы, наборы записей регистров, записи регистров и строки табличных частей объектных типов. Записи регистров и строки табличных объектных типов (как отдельные сущности) доступны только на чтение.

● Реквизиты объектов «1С:Предприятия» представляются как свойства сущностей. В некоторых случаях (например, реквизит объекта конфигурации составного типа) реквизит может быть представлен несколькими свойствами, одно из которых будет навигационным. Такое свойство содержит в качестве значения ссылку (URL) на сущность, описывающую объект «1С:Предприятия». Свойство, описывающее тип такого реквизита, называется диспетчеризационным. Название такого свойства завершается суффиксом _Type. Более подробное описание диспетчеризационного свойства приведено далее.

Обращение к стандартному интерфейсу OData выполняется с помощью HTTP-запроса, выполнено по определенному URL. URL формируется специальным образом и состоит из следующих частей:

1. Адрес информационной базы;

2. Признак обращения к стандартному интерфейсу OData;

3. Имя ресурса, к которому выполняется обращение;

4. Параметры запроса обращения к ресурсу.

Само обращение выполняется с помощью HTTP-запроса определенного вида. При более подробном описании работы со стандартным интерфейсом OData вид запроса будет указываться отдельно.

Рассмотрим части URL более подробно.

Адрес информационной базы

Это обычный URL, по которому выполняется доступ, например, к информационной базе с помощью веб-клиента. Например, http://host /base илиhttp://host.server.zone/data-base . Также необходимо помнить, что при использовании информационной базы, в которой настроено разделение, допустимо использовать только один способ указания значений разделителей, а именно: значения разделители можно указывать только в URL информационной базы. Указание разделителей с помощью параметра Z не поддерживается. Более подробная информация про настройку указания значений разделителей в URL информационной базы можно получить в описании файла default.vrd в книге 1С:Предприятие 8.3. "Руководство администратора" .

Признак обращения к стандартному интерфейсу OData

В качестве такого признака выступает последовательность /odata/standard.odata.

Имя ресурса, к которому выполняется обращение

Особым образом сформированный идентификатор ресурса (возможно, с параметром) или предопределенные ресурсы. Например, $metadata,Catalog_Контрагент(guid'value').

Параметры обращения к ресурсу

В качестве параметров обращения выступают параметры в виде, принятом для HTTP-запросов: ?ключ=значение&ключ2=значение2.

При обращении к ресурсу могут использоваться специальные ключевые слова, имеющие специальное назначение:

● $format – указывает, в каком формате необходимо получить данные. Если ключевое слово не указано, данные получаются в формате atom-xml.

● $format=atom – возвращает данные в формате atom-xml.

● $format=json – возвращает данные в формате json. Для указания того, что данные должны возвращаться в формате json, можно указать MIME-тип application/json в заголовке Accept HTTP-запроса на получение данных.

● $metada – указывает, что требуется получить описание стандартного интерфейса OData. Подробнее см. здесь .

● $filter – описывает отбор, применяемый при получении данных. Подробнее см. здесь .

● $select – описывает перечень свойств сущности, которые получаются при обращении к стандартному интерфейсу OData. Подробнее см.здесь .

После того, как сформирован URL необходимого ресурса, следует выполнить HTTP-запрос нужного вида. В зависимости от того, какая операция выполняется, используется соответствующий HTTP-метод:

● Получение данных – метод GET;

● Создание объекта – метод POST;

● Обновление данных:

● метод PATCH – в этом случае можно указывать только те свойств, которые необходимо обновить;

● метод PUT – в этом случае необходимо указывать все свойства сущности;

● Удаление данных – метод DELETE.

В результате выполнения запроса клиентское приложение получает ответ сервера, который кроме кода состояния может содержать различные данные, предоставленные сервером, в виде XML-документа.

В примерах URL, которые используются в данном разделе, выражение guid'value' означает выражение OData, которое описывает конкретное значение GUID (тип Edm.Guid).

18.2.1.3. Представление данных

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

Для различных типов данных используется следующее соответствие между типом «1С:Предприятия» и типом OData:

Тип «1С:Предприятия»	Тип свойства OData
Строка	Edm.String
Дата	Edm.DateTime
Число (целое)	Edm.Int16, Edm.Int32, Edm.Int64
Число (дробное)	Edm.Double
Булево	Edm.Boolean
Ссылка	Edm.Guid
Перечисление	Edm.String
ХранилищеЗначения	Состоит из трех свойств*: 1. Навигационное свойство; 2. <Имя свойства>_Base64Data; 3. <Имя свойства>_Type.
Ссылочный тип	Два свойства: ● Собственно значение ссылки на объект типа Edm.Guid; ● Навигационное свойство.
Составные типы	Два свойства типа Edm.String: ● Значение фактического типа, выраженное в виде строки; ● Имя фактического типа.

В таблице символ * означает, что:

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

● Для типа Картинка – будет получена собственно картинка с соответствующим значением HTTP-заголовка content-type;

● Для типа ДвоичныеДанные – будет получен байтовый поток;

● Для остальных типов – XDTO-сериализованное значение хранимых данных.

● Свойство <Имя свойства>_Base64Data хранит данные, которые могут быть получены с помощью навигационного свойства, только закодированные в Base64. Редактировать данные реквизита типа ХранилищеЗначения можно только с помощью этого свойства.

● Свойство <Имя свойства>_Type описывает тип данных, хранимых в реквизите. Может принимать одно и трех значений:

● application/octet-stream – двоичные данные;

● application/xml+xdto – XDTO-сериализованный объект;

● значение HTTP-заголовка content-type, соответствующего картинке, хранящейся в реквизите, например, image/jpeg для картинки формата JPEG.

Остальные типы не поддерживаются, и при попытке их чтения будет сгенерирована ошибка c кодом 501.

Имена свойств могут оканчиваться на различные суффиксы. Такие свойства имеют специальный смысл. Далее будут более подробно рассмотрены возможные суффиксы:

● Key;

● Type;

● Base64Data.

Key

Свойство с таким суффиксом содержит значение ключа соответствующего ссылочного реквизита объекта (без такого суффикса) или независимого регистра сведений без измерений. Имя с таким суффиксом используется для установки отбора в качестве имени реквизита, по которому выполняется отбор. Например, для установки отбора по ссылочному полю Контрагент, условие будет выглядеть следующим образом:Контрагент_Key=guid'value'. При этом свойство Контрагент будет содержать представление контрагента с указанным значением ссылки.

Type

Данный суффикс используется для описания реквизита составного типа. Так, если в данных есть поле составного типа Контрагент, то в документе, который возвращает стандартный интерфейс OData, этому полю будет соответствовать два свойства:

● Контрагент_Type – будет содержать описание типа значения реквизита в виде строки (тип Edm.String, диспетчеризационное свойство);

● Контрагент – будет содержать значение реквизита (соответствующего типа).

Перечень допустимых типов, которые могут быть использованы в поле с таким суффиксом, определяется схемой сервиса, который можно получить при запросе полного описания стандартного интерфейса OData (см. здесь ). Таким образом, при необходимости установить типДокумент.РасходТовара, в элемент с суффиксом _Type должно быть записано значение StandardODATA.Document_РасходТовара.

Если значение реквизита составного типа в информационной базе «1С:Предприятия» имеет значение Неопределено, то диспетчеризационное свойство будет иметь значение StandardODATA.Undefined, а само значение свойства должно игнорироваться.

Пример представления реквизита составного типа:

<d:РеквизитСоставной/>

<d:РеквизитСоставной_Type>StandardODATA.Undefined</d:РеквизитСоставной_Type>

Base64Data

Данный суффикс используется при указании имени свойства, содержащего данные, расположенные в реквизите типа ХранилищеЗначения, в виде строки Base64. Так, если в объекте конфигурации есть реквизит Файл, который имеет тип ХранилищеЗначения, то в документе, который возвращает стандартный интерфейс OData, этому полю будет соответствовать два свойства:

● Файл_Type – содержит наименование типа данных, хранимых реквизитом;

● Файл_Base64Data – содержит строку Base64, содержащую сами данные.

18.2.1.4. Правила формирования имени ресурса

При обращении к какому-либо ресурсу, его идентификатор формируется по следующему принципу:ПрефиксИмени_ИмяОбъектаКонфигурации_СуффиксИмени. С помощью стандартного интерфейса OData можно получить доступ к следующим объектам (ПрефиксИмени):

Объект конфигурации	Префикс имени для указания в URL
Справочник	Catalog
Документ	Document
Журнал документов	DocumentJournal
Константа	Constant
План обмена	ExchangePlan
План счетов	ChartOfAccounts
План видов расчета	ChartOfCalculationTypes
План видов характеристик	ChartOfCharacteristicTypes
Регистр сведений	InformationRegister
Регистр накопления	AccumulationRegister
Регистр расчета	CalculationRegister
Регистр бухгалтерии	AccountingRegister
Бизнес-процесс	BusinessProcess
Задача	Task

ИмяОбъектаКонфигурации – свойство Имя объекта конфигурации, как оно задано при разработке прикладного решения в конфигураторе.

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

● Имя табличной части объекта;

● Имя виртуальной таблицы регистра;

● RowType;

● RecordType;

Далее будут более подробно рассмотрены вышеописанные уточнения имени ресурса:

Имя табличной части объекта

Если объект обладает табличной частью, то для получения доступа ко всем записям этой табличной части необходимо добавить имя табличной части после имени самого объекта, например, для получения всех строк табличных частей Товары всех документов РасходТовара будет необходимо выполнить GET-запрос по следующему адресу: http:// host/base/odata/standard.odata/Document_РасходТовара_Товары.

Имя виртуальной таблицы регистра

В роли виртуальной таблицы регистра выступает функция, связанная с ресурсом, возвращающей набор сущностей регистра. Имя функции совпадает с английским вариантом имени используемой виртуальной таблицы языка запросов. Параметры функции соответствуют параметрам виртуальной таблицы. Так, для получения среза последних для регистра сведений КурсыВалют, следует выполнить GET-запрос по следующему адресу: http://localhost/demo/odata/standard.odata/InformationRegister_КурсыВалют/SliceLast().

RowType

Сущность с таким суффиксом описывает тип строки табличной части какого-либо объекта.

RecordType

Сущность с таким суффиксом описывает отдельную запись регистра.

18.2.1.5. Правила формирования условия отбора

$filter

При получении данных можно фильтровать данные. Для этого предназначен специальный язык, который позволяет описывать условия, каким должны соответствовать данные, которые возвращает стандартный интерфейс OData. Описание отбора начинается с ключевого слова $filter, после которого следует собственно условие. Поддерживаются следующие операции:

● Логические операции:

Описание	Имя	Пример
Равно	eq	/Catalog_Города?$filter=Description eq 'Главный'
Не равно	ne	/Catalog_Города?$filter=Description ne 'Пермь'
Больше	gt	/Catalog_Товары?$filter=Цена gt 10
Больше или равно	ge	/Catalog_Товары?$filter=Цена ge 10
Меньше	lt	/Catalog_Товары?$filter=Цена lt 10
Меньше или равно	le	/Catalog_Товары?$filter=Цена le 10
Логическое ИЛИ	or	/Catalog_Товары?$filter=Цена lt 10 or Цена gt 100
Логическое И	and	/Catalog_Товары?$filter=Цена gt 10 and Цена lt 100
Отрицание	not	/Catalog_Товары?$filter=not (Цена eq 10)

● Арифметические операции:

Описание	Имя	Пример
Сложение	add	/Catalog_Товары?$filter=Цена add 5 gt 10
Вычитание	sub	/Catalog_Товары?$filter=Цена sub 5 gt 10
Умножение	mul	/Catalog_Товары?$filter=Цена mul 5 gt 1000
Деление	div	/Catalog_Товары?$filter=Цена div 4 gt 2

● Группирующие операторы:

Описание	Имя	Пример
Приоритет операции	()	/Catalog_Товары?$filter=(Цена add 5) gt 10

Пример отбора:

http://host/odata/standard.odata/Catalog_Товары?$filter=Имя eq 'Молоко' and Цена lt 2500

При формировании условия отбора следует учитывать приоритет операций. В следующей таблице представлен список операций языка выражений отбора в порядке уменьшения приоритета. Операции с одинаковым приоритетом вычисляются слева направо:

Оператор	Описание
( )	Повышение приоритета операции
/	Навигация
-	Арифметическое отрицание
Not	Логическое отрицание
Mul	Умножение
Div	Деление
Add	Сложение
Sub	Вычитание
Gt	Больше
Ge	Больше или равно
Lt	Меньше
Le	Меньше или равно
Eq	Равно
Ne	Не равно
And	Логическое «И»
Or	Логическое «ИЛИ»

ПРИМЕЧАНИЕ. Не поддерживаются операции сравнения с реквизитом составного типа, типа УникальныйИдентификатор и типаХранилищеЗначения.

Не поддерживаются следующие операции сравнения:

● Стандартные функции в запросах;

● Лямбда-выражения и условия на свойства-коллекции.

$top

Имеется возможность ограничить количество записей, возвращаемых при обращении к ресурсу. Для этого используется ключевое слово $top.

Пример:

http://host/odata/standard.odata/Catalog_Товары?$filter=Цена lt 1000&$top=10

allowedOnly

Если при выполнении запроса необходимо получить только те объекты данных, которые не попадают под ограничения доступа к данным, то в URL получения данных необходимо добавить параметр allowedOnly.

Пример:

http://host/base/odata/standard.odata/Catalog_Товары?allowedOnly=true

Если параметр не указан или указан со значением false, то во время исполнения запроса к данным может возникнуть ошибка с кодом 401 (если результат выполнения запроса содержит данные, доступ к которым запрещен). Ошибка может не произойти в том случае, если были указаны дополнительные условия, которые ограничили выборку только разрешенными данными.

Например, для справочника Данные настроено ограничение доступа к данным, которое не позволяет получить элементы справочника, у которых реквизит ЗначениеСекретности равно 1, но позволяет получить элементы справочника, у которых реквизит ЗначениеСекретности равно 2. В этом случае следующий запрос не приведет к возникновению ошибки, т. к. явно накладывается условие, которое оставляет в выборе только разрешенные данные:

http://host/base/odata/standard.odata/Catalog_Данные?allowedOnly=false&$filter=ЗначениеСекретности eq 2

Параметр allowedOnly можно использовать только для GET-запросов к наборам сущностей.

Описание возможностей отбора в протоколе OData можно получить в документации по протоколу (на английском языке):

● http://www.odata.org/documentation/odata-v3-documentation/odata-core/#10231_The_filter_System_Query_Option ;

● http://www.odata.org/documentation/odata-v3-documentation/url-conventions/#512_Filter_System_Query_Option.

18.2.1.6. Способы получения описания стандартного интерфейса OData

Для получения упрощенного описания стандартного интерфейса OData (только список сущностей) необходимо выполнить GET-запрос с использованием URL http://host/base/odata/standard.odata.

Для получения описания стандартного интерфейса OData необходимо выполнить GET-запрос с использованием URLhttp://host/base/odata/standard.odata/$metadata. В результате будет получен полный список доступных сущностей, их атрибутов и функций в виде XML-документа. Подробное описание документа можно получить по адресу http://www.odata.org/documentation/odata-v3-documentation/common-schema-definition-language-csdl/  (на английском языке).

В случае получение данных в формате json, не поддерживается запрос получения расширенного описания метаданных видаhttp://host/base/odata/standard.odata/$metadata. Однако имеется возможность управлять детализацией информации о метаданных, которая возвращается при получении данных (как сущностей, так и списков сущностей). Для этого необходимо особым образом формировать параметр$format при выполнении запроса:

● $format=application/json;odata=minimalmetadata – в этом случае информация о метаданных передается в минимальном объеме. Это значение по умолчанию.

● $format=application/json;odata=nometadata – в этом случае информация о метаданных не передается вовсе.

● $format=application/json;odata=fullmetadata – в этом случае информация о метаданных передается в полном объеме.

18.2.1.7. Способы получения данных

С помощью стандартного интерфейса OData можно получать как списки сущностей, так и сами сущности. Эти способы получения данных отличаются URL, по которому происходит обращение к данным.

Для получения списка сущностей URL выглядит следующим образом: http://host/base/odata/standard.odata/Catalog_Товары . Это URL набора сущностей. Для получения сущности URL будет выглядеть следующим образом:http://host/base/odata/standard.odata/Catalog_Товары(guid'value') . В общем виде такой адрес будет называться канонический URL экземпляра сущности. Разница заключается в том, что в первом случае получается вся таблица справочника товаров, а вот втором выбирается один объект, который описывается набором ключевых значений (в примере ключевое значение единственное – ссылка на объект). В конкретном случае набор ключевых полей, описывающих сущность, зависит от получаемой сущности. Если ключевых полей более одного, то они должны быть указаны все. Ключевые значения указываются парами Имя=Значение, разделенными запятыми. Если ключевое значение одно – имя ключа можно не указывать. Например, для получения значения курса валюты на конкретную дату необходимо выполнить GET-запрос со следующим URL: http://host/base/odata/standard.odata/InformationRegister_КурсыВалют(Period=datetime'2008-02-05T00:00:00', Валюта_Key=guid'9d5c4222-8c4c-11db-a9b0-00055d49b45e').

При получении данных существует возможность указать, какие свойства сущности (или набора сущностей) необходимо получить с помощью стандартного интерфейса OData. Для этого существует ключевое слово $select, которое имеет несколько вариантов использования:

● Признак получения всех свойств.

В этом случае следует указать выражение вида $select=* или совсем не указывать выражение $select.

● Перечень конкретных свойств, которые необходимо получить.

В этом случае необходимо указать в выражении оператора $select перечень (через запятую) всех необходимых полей. При этом следует указывать суффиксы свойств, если это необходимо. Например, для получения значения ссылки на справочник и свойств Код и Артикул, для справочника Товары, необходимо использовать следующий URL: http://host/base/odata/standard.odata/Catalog_Товары?$select=Ref_Key, Код, Артикул.

Для получения этих же полей для конкретного экземпляра сущности (с известным идентификатором) будет использоваться следующий URL:http://host/base/odata/standard.odata/Catalog_Товары(guid'value')?$select=Ref_Key , Код, Артикул.

● Признак получения всех свойств, кроме табличных частей.

Для этого в выражении оператора $select необходимо указать значение **. При использовании следующего URL будут получены все документы РасходТовара со всеми реквизитами, кроме табличных частей: http://host/base/odata/standard.odata/Document_РасходТовара?$select=**.

Имеется возможность получать данные, доступные «через точку». В этом случае к адресу, описывающему конкретную сущность, прибавляются имена свойств, идущие «через точку», но разделенные символом «/». При этом для стандартных реквизитов следует использовать только английские имена реквизитов. Например, для получения свойства Наименование реквизита Валюта документа РасходТовара, необходимо использовать GET-запрос со следующим URL: http://host/base/odata/standard.odata/Document_РасходТовара(guid'value')/Валюта/Description .

18.2.1.8. Выполнение функций и действий

С некоторыми сущностями и наборами сущностей могут быть связаны функции. Например, через функции выполняется работа с виртуальными таблицами регистров. В этом случае URL ресурса формируется следующим образом: http://host/base/odata/standard.odata/<ресурс>/<функция>(<параметры>). Подробнее рассмотрим, из чего состоит адрес. Первая часть адреса (http://host/base/odata/standard.odata ) представляет собой стандартный префикс адреса при обращении к стандартному интерфейсу OData.<ресурс> – имя ресурса, правила формирования которого см. здесь . Имя функции соответствует англоязычному имени виртуальной таблицы языка запросов (см. здесь ). <параметры> у функции задаются парами Ключ=Значение и разделяются запятыми. Если в качестве параметра функции используется отбор, то выражение, описывающее отбор, должно удовлетворять общим правилам описания отборов (см. здесь ). Так, получение среза первых для регистра курсов валют (с параметрами), будет выполняться по следующему URL: http://host/base/odata/standard.odata/InformationRegister_КурсыВалют/SliceFirst(Period=datetime'2008-01-01T00:00:00',Condition='Валюта_Key eq guid'value'').

18.2.1.9. Ошибочные ситуации

В случае ошибочной ситуации возвращается ответ с HTTP-статусом 4XX или 5XX. Статус 4XX информирует об ошибках на стороне клиентского приложения, статус 5XX информирует об ошибке на стороне сервера.

В случае статуса 4XX сервер пытается уточнить причину ошибки и может передать клиентскому приложению дополнительный внутренний код ошибки и информационное сообщение (в виде xml-документа) в теле ответа.

Пример:

<m:error xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">

<m:code>9</m:code>

<m:message>Экземпляр сущности "НакладнаяОтгрузки" не найден по переданному ключу.</m:message>

</m:error>

Далее перечислены внутренние коды ошибок с описанием причины появления:

Код	Описание
0	Возможность не поддерживается
1	Не удалось разобрать строку
2	Неверный формат запроса
3	Запрошенный тип представления не поддерживается
4	Неверное значение свойства
5	Отсутствует обязательное значение свойства
6	Неверный URL
7	Не хватает элемента ключа сущности
8	Тип сущности не найден
9	Экземпляр сущности не найден
10	Запрошенное свойство не найдено
11	Метод не найден
12	Отсутствует обязательный аргумент метода
13	Создание строк табличных частей напрямую не поддерживается
14	Ошибка разбора опций запроса
15	Сущность с таким ключом уже существует
16	Не удалось присвоить свойство
17	Объект не поддерживает режим загрузки данных
18	Ошибка инициализации интерфейса OData: в объекте есть свойства с одинаковыми именами
19	Использованный HTTP-метод запрещен в данном контексте
20	Ошибка прав доступа. Может возникать: ● Когда у пользователя нет прав на запрошенное действие над данным объектом; ● Когда в выборку попадает объект, недоступный в связи с ограничением доступа к данным и параметр allowedOnly не используется.

18.2.1.10. Установка значений разделителей

Значения разделителей можно устанавливать только следующими способами:

● С помощью фрагментов URL при обращении к стандартному интерфейсу OData;

● С помощью файла описания публикации default.vrd.

Указанием разделителей с помощью параметры командной строки Z не поддерживается.

18.2.1.11. Публикация стандартного интерфейса OData

Публикация стандартного интерфейса OData выполняется с помощью диалога публикации на веб-сервере (Администрирование – Публикация на веб-сервере) и описано в книге 1С:Предприятие 8.3. "Руководство администратора" .

Для того чтобы объекты конфигурации стали доступны через стандартный интерфейс OData, необходимо разрешить это с помощью метода глобального контекста УстановитьСоставСтандартногоИнтерфейсаOData(). Если прикладное решение функционирует в режиме совместимости с версией 8.3.4 (и ниже), данный метод не используется. В этом случае с помощью стандартного интерфейса OData доступны все поддерживаемые объекты конфигурации.

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

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

18.2.1.12. Выполнение типовых операций

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

ВНИМАНИЕ! Данные примеры не являются законченными. Они приведены только для иллюстрации применения различных конструкций.

18.2.1.12.1. Работа с одним объектом

Чтение данных

Для получения информации о сущности следует использовать канонический URL сущности. Чтение выполняется с помощью GET-запроса.

Пример чтения ссылочного объекта:

http://host/base/odata/standard.odata/Catalog_Товары(guid'value')

Пример чтения набора записей подчиненного регистра сведений:

http://host/base/odata/standard.odata/InformationRegister_ПриходныеЦены(Recorder_Key=guid'value')

В данном примере guid'value' идентифицирует документ, выполнивший движение по регистру сведений.

Пример чтения записи регистра сведений:

http://host/base/odata/standard.odata/InformationRegister_ПриходныеЦены_RecordType(Товар_Key=guid'value', ТипЦены="Приходная")

Пример чтения строки конкретного документа:

http://host/base/odata/standard.odata/Document_РасходТовара_Товары(Ref_Key=guid'value', LineNumber=1)

Чтение виртуальной таблицы СрезПоследних регистра сведений КурсыВалют (с отбором по измерению ОсновнаяВалюта типаСправочникСсылка.Валюты) будет выглядеть следующим образом:

Пример чтения независимого регистра сведений:

http://host/base/odata/standard.odata/InformationRegister_КурсыВалют/SliceLast?Condition=Валюта/ОсновнаяВалюта_Key eq guid'value'

Пример чтения подчиненного регистра сведений (к имени регистра следует добавить _RecordType):

http://host/base/odata/standard.odata/InformationRegister_КурсыВалют_RecordType/SliceLast?Condition=Валюта/ОсновнаяВалюта_Key eq guid'value'

В данном примере guid'value' идентифицирует элемент справочника Валюты, по значению которого выполняется отбор.

Создание объекта

Для создания объекта следует воспользоваться POST-запросом с использованием URL набора сущностей, передав в теле запроса XML-документ (в формате atom), который содержит значения полей создаваемого объекта.

Далее приводится пример создания элемента справочника Товары и ответ стандартного интерфейса OData после успешного выполнения операции.

Пример POST-запроса:

POST http://host/base/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:Описание>&lt;html&gt;Шлепанцы пляжные&lt;/html&gt;</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: http://host/base/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>http://host/base/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:Описание>&lt;html&gt;Шлепанцы пляжные&lt;/html&gt;</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>

Обновление объекта

Для обновления объекта необходимо выполнить PUT-/PATCH-запрос с использованием канонического URL сущности (аналогично запросу GET для получения сущности), передав в теле запроса XML-документ (в формате atom) или JSON-документ (в формате json), который содержит значения свойств сущности.

В случае PATCH-запроса пропущенные свойства сущности будут проигнорированы, т. е. будут изменены только те свойства, которые переданы в запросе на изменение. Для PUT-запроса необходимо указывать значения всех свойств обновляемой сущности.

В следующем примере рассматривается изменение реквизита Наименование и состава табличной части ТорговыеЗалы справочника Магазины. Остальные реквизиты справочника не используются в рамках данного примера. В примере используется формат данных json.

Пример PATCH-запроса:

PATCH http://host/base/odata/standard.odata/Catalog_Магазины(guid'value')?$format=json HTTP/1.1

Host: host

Connection: keep-alive

Accept: application/json

Content-Length: 638

{

"odata.metadata": "http://host/base/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 и параметра, указывающего режим проведения документа: http://host/base/odata/standard.odata/Document_РасходТоваров(guid'value')/Post?PostingModeOperational=false .

Для отмены проведения документа суффикс состоит из команды Unpost без параметров.

18.2.1.12.2. Работа с коллекцией объектов

Для получения набора сущностей какого-либо вида, следует выполнить GET-запрос с использованием URL следующего вида:http://host/base/odata/standard.odata/ExchangePlan_ОбменДанными .

Если необходимо установить отбор на получаемый список, его можно выполнить с помощью параметра $filter (см. здесь ), который указывается в URL:

http://host/base/standard.odata/Document_Накладная?$filter=Приоритет eq 1

Обращение к виртуальной таблице регистра выглядит следующим образом (на примере виртуальной таблицы ОстаткиИОбороты регистра накопления ТоварныеЗапасы):

http://host/base/odata/standard.odata/AccumulationRegister_ТоварныеЗапасы/BalanceAndTurnovers(StartPeriod=datetime'2014-01-01', EndPeriod=datetime'2014-02-01', Condition='Товар_Key eq guid'value'')

Также для ограничения набора сущностей можно использовать параметры $top и $select (см. здесь ).

18.2.1.12.3. Работа с планами обмена

Формирование сообщения обмена

Для формирования сообщения обмена необходимо выполнить POST-запрос с использованием URL следующего вида:http://host/base/odata/standard.odata/SelectChanges?<params >. Где в качестве параметров необходимо указать следующее:

● Параметр DataExchangePoint – должен содержать канонический URL сущности треуемого элемента плана обмена;

● Параметр MessageNo – должен содержать номер сообщения обмена данными, который будет сформирован в результате данного вызова.

В результате, полный URL для формирования сообщения обмена, будет выглядеть следующим образом:http://host/base/odata/standard.odata/SelectChanges?DataExchangePoint='http://host/base/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 следующего вида: http://host/base/odata/standard.odata/ NotifyChangesReceived?<params >. Где в качестве параметров необходимо указать следующее:

● Параметр DataExchangePoint – должен содержать канонический URL сущности требуемого элемента плана обмена;

● Параметр MessageNo – должен содержать номер сообщения обмена данными, подтверждение получения которого необходимо зафиксировать.

В результате, полный URL для подтверждения получения сообщения обмена, будет выглядеть следующим образом:http://host/base/odata/standard.odata/NotifyChangesReceived?DataExchangePoint='http://host/base/odata/standard.odata/ExchangePlan_ОбменДанными(guid'value')'&MessageNo=34 .