Программы 1С в облаке (1С:Фреш) | Работа с данными приложения в сервисе clobus.uz через стандартный интерфейс OData

В этой статье рассказывается об использовании стандартного интерфейса OData для программного чтения и записи данных приложений абонентов сервиса clobus.uz.

1. Протокол OData

OData (Open Data Protocol) — это открытый веб-протокол для запроса, добавления, удаления и обновления данных. OData позволяет выполнять операции с ресурсами с помощью HTTP-запросов и получать ответы в форматах XML или JSON. Подробнее о протоколе OData можно прочесть в Википедии.

Доступ к данным посредством OData можно использовать, например:

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

2. Поддержка в платформе «1С:Предприятие»

Начиная с версии 8.3.5, в платформе «1С:Предприятие» поддерживается доступ через протокол OData к данным информационных баз «1С:Предприятия». Это позволяет читать и записывать из внешнего приложения данные прикладного решения «1С:Предприятия» без модификации кода этого прикладного решения.

2.1. Автоматически создаваемый REST-интерфейс для использования OData

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

Этот автоматически создаваемый REST-интерфейс прикладных решений на платформе «1С:Предприятие» принято называть стандартным интерфейсом OData.

2.2. Условия использования стандартного интерфейса OData

Для использования стандартного интерфейса OData:

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

2.3. Возможности стандартного интерфейса OData

С помощью стандартного интерфейса OData доступны:

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

При действиях с данными с помощью стандартного интерфейса OData платформа «1С:Предприятие» выполняет все обычные проверки прав доступа и вызывает обработчики событий.

Подробнее о возможностях стандартного интерфейса OData рассказано здесь.

3. Использование интерфейса OData в сервисе clobus.uz

В сервисе clobus.uz все прикладные информационные базы опубликованы с включенной поддержкой интерфейса OData.

Поэтому для приложений абонентов сервиса clobus.uz возможны чтение и запись данных с помощью HTTP-запросов стандартного интерфейса OData.

Ограничение: в сервисе clobus.uz в OData-запросах не поддерживается HTTP-заголовок 1C_OData-DataLoadMode: true, позволяющий при записи объектов эмулировать запись, выполняемую во время работы механизма обмена данными (свойство ОбменДанными.Загрузка = Истина). OData-запросы с таким заголовком не будут обработаны.

4. Обработка «Настройка автоматического REST-сервиса»

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

Создать служебного пользователя, от имени которого может вызываться интерфейс OData.
Настроить состав объектов приложения, которые будут доступны через интерфейс OData.

Обработка доступна пользователям, имеющим в приложении административные права (роль Полные права). В сервисе Фреш такие права в приложении имеет владелец абонента.

4.1. Вызов обработки

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

Администрирование — Синхронизация данных — Настройки стандартного интерфейса OData;
Администрирование и НСИ — Синхронизация данных — Настройки стандартного интерфейса OData;
Настройки — Синхронизация данных — Настройки стандартного интерфейса OData.

4.2. Создание служебного пользователя

Для использования интерфейса OData рекомендуется создать в приложении отдельного служебного пользователя. Это можно сделать в обработке Настройка автоматического REST-сервиса на вкладке Авторизация.

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

4.3. Настройка состава объектов, доступных через интерфейс OData

На вкладке Состав окна обработки Настройка автоматического REST-сервиса можно указать, какие объекты прикладного решения будут доступны через интерфейс OData.

Рекомендуется включать доступ только для видов объектов, используемых в задачах, для которых будет использоваться интерфейс OData. Если для доступа к каким-либо видам объектов необходимо включить доступ через интерфейс OData также и к подчиненным им видам объектов, то обработка Настройка автоматического REST-сервиса выведет соответствующее сообщение и позволит включить такой доступ.

Не рекомендуется включать доступ через OData к планам обмена, так как их некорректное изменение может привести к неработоспособности приложения абонента.

После задания состава объектов, доступных через интерфейс OData, нужно нажать кнопку Записать и закрыть.

5. HTTP-запросы интерфейса OData

5.1. URL запроса

5.1.1. Формат URL

URL HTTP-запросов стандартного интерфейса OData имеет вид:

URL-приложения/odata/standard.odata/идентификатор-ресурса?параметры

Здесь:

URL-приложения — адрес, по которому выполняется доступ к приложению в браузере (без кода языка), например, https://clobus.uz/a/sbm/12345;
/odata/standard.odata/ — признак обращения к стандартному интерфейсу OData;
идентификатор-ресурса — особым образом сформированный идентификатор ресурса (возможно, с параметром) или предопределенные ресурсы. Например:
- Catalog_Контрагенты — обращение к справочнику Контрагенты;
- Catalog_Контрагенты(guid'c3fbdcaf-b8e1-11e4-8271-001e101f0864') — обращение к записи справочника Контрагенты с указанным guid;
параметры — параметры запроса, они указываются в виде пар ключ=значение, разделенных символами &, как это принято в HTTP-запросах. Параметры не обязательны. Если параметры отсутствуют, то и символ ?, разделяющий имя ресурса и параметры, в запросе не указывается.

5.1.2. Пример

Например, в запросе:

GET https://clobus.uz/a/sbm/12345/odata/standard.odata/Catalog_Номенклатура?$format=json&$filter=Артикул eq '345'

https://clobus.uz/a/sbm/12345 — URL приложения, к которому делается запрос;
/odata/standard.odata/ — признак обращения к стандартному интерфейсу OData;
Catalog_Номенклатура — наименование ресурса, к которому относится запрос (справочник Номенклатура);
$format=json и $filter=Артикул eq '345' — параметры запроса, разделенные символами &.

5.2. Заголовок аутентификации

В запросе нужно использовать HTTP-заголовок Authorization: Basic с указанием логина/пароля пользователя, от имени которого осуществляется HTTP-запрос (строка логин:пароль, закодированная в формате base64). Этот пользователь должен иметь в приложении либо административные права (роль Полные права), либо роль УдаленныйДоступOData.

5.3. Метод запроса

HTTP-метод запроса выбирается в зависимости от того, какая операция выполняется:

Операция	HTTP метод
Получение данных	GET
Создание объекта	POST
Обновление данных	PATCH или PUT
Удаление данных	DELETE

При использовании для обновления данных метода PATCH в запросе можно указывать только обновляемые свойства сущности, а при использовании метода PUT нужно указывать все свойства сущности.

5.4. Указание строк, уникальных идентификаторов и дат

В запросе OData:

строки указываются в одинарных кавычках (апострофах). Например: ’Санкт-Петербург’;
уникальные идентификаторы указываются как guid’строка’. Например: guid’7426fe18-e7e6-11ec-872c-fa163e21d4b7’;
даты указываются как datetime’yyyy-mm-ddThh:mm:ss’. Например: datetime’2022-09-25T12:30:59’.

5.5. Результат запроса

В результате выполнения запроса клиентское приложение получает ответ сервера, который может содержать данные, предоставленные сервером. Формат этих данных может быть XML (по умолчанию) или JSON.

Чтобы получить от сервера данные в формате JSON, можно:

указать параметр запроса $format=json
или указать в запросе HTTP-заголовок Accept: application/json

5.6. Правила формирования идентификатора ресурса

5.6.1. Тип и имя объекта конфигурации

Идентификатор ресурса, указываемый в URL стандартного интерфейса OData, начинается с указания типа и имени объекта конфигурации:

Обозначение в URL	Что означает
Catalog_имя	Обращение к справочнику с указанным именем
Document_имя	Обращение к документу/документам с указанным именем
DocumentJournal_имя	Обращение к журналу документов с указанным именем
Constant_имя	Обращение к константе с указанным именем
ExchangePlan_имя	Обращение к плану обмена с указанным именем
ChartOfAccounts_имя	Обращение к плану счетов с указанным именем
ChartOfCalculationTypes_имя	Обращение к плану видов расчета с указанным именем
ChartOfCharacteristicTypes_имя	Обращение к плану видов характеристик с указанным именем
InformationRegister_имя	Обращение к регистру сведений с указанным именем
AccumulationRegister_имя	Обращение к регистру накопления с указанным именем
CalculationRegister_имя	Обращение к регистру расчета с указанным именем
AccountingRegister_имя	Обращение к регистру бухгалтерии с указанным именем
BusinessProcess_имя	Обращение к бизнес-процессу с указанным именем
Task_имя	Обращение к задаче/задачам с указанным именем

Здесь имя объекта записывается так, как оно показано в свойстве объекта Имя в конфигураторе.

5.6.2. Суффикс имени

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

Суффикс	Что означает
_имя-табличной-части	Обращение к табличной части объекта
_RowType	Обращение к строке табличной части объекта
_RecordType	Обращение к записи регистра

5.6.3. Выбор элемента

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

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

Если ключевых полей более одного, то они должны быть указаны все. Если ключевое поле одно, то в круглых скобках можно указать только значение этого ключевого поля. Например:

URL запроса содержит	Это обращение
Catalog_Организации(guid'de0977f8-b6af-11e4-bf8c-74d02b7dfd8c')	К записи справочника Организации с указанным guid
InformationRegister_КурсыВалют(Period='1986-01-01T00:00:00', Валюта_Key=guid '74813622-b5b8-11e4-8355-74d02b7dfd8c')	К указанной записи регистра сведений Курсы валют
Catalog_Организации_КонтактнаяИнформация(LineNumber=5, Ref_Key=guid'de0977f8-b6af-11e4-bf8c-74d02b7dfd8c')	К строке 5 табличной части Контактная информация записи справочника Организации с указанным guid

5.6.4. Указание действия

В заключительной части идентификатора ресурса можно указать после символа / действие с ресурсом. Например:

Действие	Описание	Условие применения
$count	В ответе нужно вывести не элементы, а только их количество	Для GET-запросов, выдающих список элементов
Наименование-реквизита-объекта	В ответе нужно вывести только значение указанного реквизита	Для запросов, результатом которых является объект
Наименование-табличной-части	В ответе нужно вывести только указанную табличную часть	Для запросов, результатом которых является объект
Наименование-метода(параметры)	Для выбранного объекта нужно применить указанный метод	Для объектов тех видов, к которым применим данный метод

Замечание. В ответе можно вывести значение реквизита подчиненного объекта. В этом случае полное имя реквизита формируется с использованием разделителя /. Например, /Контрагент/ИНН означает, что в запросе следует вывести только значение реквизита ИНН объекта, на который ссылается реквизит ответа Контрагент.

5.6.5. Методы

Вот некоторые методы, которые можно использовать в OData-запросах (подробнее см. здесь):

Метод	Описание	Условие применения
SliceLast(Period=дата, Condition='строка-условия')	Выдать срез последних	Для запросов к периодическим регистрам сведений
SliceFirst(Period=дата, Condition='строка-условия')	Выдать срез первых	Для запросов к периодическим регистрам сведений
Post()	Проведение документа	Для документов
Post(PostingModeOperational=true)	Проведение документа в оперативном режиме	Для документов
Unpost()	Отмена проведения документа	Для документов
Unpost(PostingModeOperational=true)	Отмена проведения документа в оперативном режиме	Для документов
ExecuteTask()	Выполение задачи	Для задач
Start()	Запуск бизнес-процесса	Для бизнес-процессов
Start(RoutePoint=имя-точки-маршрута)	Запуск бизнес-процесса с заданной точки маршрута	Для бизнес-процессов

Ниже приведены примеры использования некоторых из этих методов:

в разделе 6.5.1 — проведение и отмена проведения документов с помощью методов Post и Unpost;
в разделе 6.5.2 — вывод курса валюты на указанную дату с помощью метода SliceFirst.

Также имеются специальные методы для регистров накопления, бухгалтерии и расчета подробнее (см. здесь, здесь и здесь):

Объект	Метод	Обеспечивает доступ к виртуальной таблице
Регистр накопления	Balance	Остатков регистра накопления
	Turnovers	Оборотов регистра накопления
	BalanceAndTurnovers	Оборотов и оборотов регистра накопления
Регистр бухгалтерии	Balance	Остатков регистра бухгалтерии
	Turnovers	Оборотов регистра бухгалтерии
	BalanceAndTurnovers	Оборотов и оборотов регистра бухгалтерии
	ExtDimensions	Субконто регистра бухгалтерии
	RecordsWithExtDimensions	Движений с субконто регистра бухгалтерии
	DrCrTurnover	Оборотов с агрегацией регистра бухгалтерии
Регистр расчета	ScheduledData	Графика регистра расчета
	ActualActionPeriod	Фактического периода действия регистра расчета
	ИмяПерерасчета	Записей перерасчета
	BaseИмяБазовогоРегистраРасчета	Базовых данных регистра расчета

5.7. Параметры запроса

Как уже говорилось, в HTTP-запросе стандартного интерфейса OData после символа ? могут указываться параметры запроса в виде разделенных амперсендами пар ключ=значение. Если параметры отсутствуют, то символ ?, разделяющий имя ресурса и параметры, в запросе не указывается.

5.7.1. Параметры, задающие условия отбора

Параметр	Описание
$filter=условие-отбора	В ответ нужно включить только элементы, удовлетворяющие заданному условию (об условиях рассказано ниже)
$top=число	В ответ нужно включить не более указанного количества элементов
$skip=число	Исключить из ответа указанное количество первых записей. Если параметры $top и $skip указываются одновременно, то параметр $skip будет применен раньше, чем параметр $top
allowedOnly=true	Включать в ответ только те элементы, которые не попадают под ограничения доступа к данным. Если этот параметр не указан, то при наличии ограничений доступа к каким-либо данным, подпадающим под условия отбора, запрос возвращает ошибку с кодом 401.

5.7.2. Параметры, задающие режимы отображения результатов

Параметр	Описание
$inlinecount=allpages	В ответ нужно включить не только полученные элементы, но и их количество. Количество сообщается в реквизите ответа odata.count
$orderby=порядок-сортировки	Задает порядок отображения результатов запросов, выдающих список элементов. Здесь порядок-сортировки это перечисление через запятую реквизитов, по которым выполняется упорядочение результатов, причем после реквизита через пробел или несколько пробелов может указываться обозначение направления сортировки по данному реквизиту: asc (по возрастанию) или desc (по убыванию). По умолчанию выполняется сортировка по возрастанию. Если в порядке сортировки указано более одного реквизита, то сначала выполняется упорядочение по первому реквизиту, потом по второму, и т.д.
$expand=список-реквизитов	Для реквизитов с составными значениями в ответе интерфейса OData по умолчанию передается только ключ объекта (его guid) в поле с именем имя-реквизита_Key. С помощью параметра expand можно указать, что в ответ интерфейса OData надо включить также и сам объект. Имена реквизитов перечисляется через запятую.
$select=список-полей-ответа	Включать в ответ только указанные поля. Имена полей перечисляются через запятую.

Параметры $inlinecount, $orderby и $expand применимы только для запросов, выдающих список элементов. Параметр $expand не может использоваться для расширения реквизитов табличных частей.

В параметре $orderby возможны:

использование вызовов функций (см. раздел 5.10);
упорядочивание по свойствам дочерних реквизитов — в этом случае полное имя реквизита, по которому выполняется упорядочивание, формируется с использованием разделителя /. Например, $orderby=Контрагент/ИНН asc означает, что упорядочивание будет произведено по возрастанию значения реквизита ИНН объекта, на который ссылается реквизит ответа Контрагент.

В параметре $select при использовании совместно с параметром $expand возможно использование символов * и **:

Обозначение	Описание
*	Необходимо развернуть все реквизиты получаемого объекта
**	Необходимо развернуть все реквизиты получаемого объекта, кроме табличных частей.

Подробнее о правилах составления HTTP-запросов стандартного интерфейса OData рассказано здесь и здесь.

5.8. Условия отбора

В параметрах запроса $filter, а также в параметрах Condition, AccountCondition, BalancedAccountCondition применяемых для выполнения действий с ресурсами (см. раздел 5.6.4), указывается условие отбора. Условие формируется из:

имен реквизитов;
арифметических и логических операций (см. раздел 5.9);
вызовов функций (см. раздел 5.10);
литералов (чисел, строк, дат, уникальных идентификаторов);
круглых скобок (как обычно, они используются для явного задания порядка вычисления значения).

При указании условий запроса (параметр $filter) или реквизита, по которому выполняется упорядочивание результатов (параметр $orderby) могут применяться следующие функции:

5.9. Арифметические и логические операции

В условиях отбора запросов OData могут использоваться арифметические и логические операции.

5.9.1. Логические операции

Обозначение	Описание	Пример
eq	Равно	Пол eq 'Мужской'
ne	Не равно	Количество ne 0
gt	Больше	Сумма gt 10000
gе	Больше или равно	Цена gе 1000
lt	Меньше	Цена lt 10000
lе	Меньше или равно	Всего le 1000000
or	Логическое ИЛИ	(Возраст lt 18) or (Возраст ge 60)
and	Логическое И	(Цена gе 1000) and (Цена lt 10000)
not	Логическое НЕ	not startswith(Артикул, 'Кофе')

Не поддерживаются операции сравнения с реквизитом типа ХранилищеЗначения.

5.9.2. Арифметические операции

Обозначение	Описание	Пример
add	Сложение	Количество add 1
sub	Вычитание	Количество sub Расход
mul	Умножение	Количество mul Цена
div	Деление	СтавкаНДС div 100

5.10. Функции

В параметрах запроса $filter и $orderby, а также в параметрах Condition, AccountCondition, BalancedAccountCondition методов, применяемых для выполнения действий с ресурсами (см. раздел 5.6.4), могут применяться следующие функции.

5.10.1. Функции для работы со строками

Функция	Описание
substringof(строка1, строка2)	true, если строка1 является подстрокой строка2
endswith(строка1, строка2)	true, если строка1 заканчивается на строка2
startswith(строка1, строка2)	true, если строка1 начинается с строка2
substring(строка, позиция)	Возвращает подстроку, начиная с указанной позиции и до конца строки. Позиции нумеруются с единицы
substring(строка, позиция, длина)	Возвращает подстроку заданной длины, начиная с указанной позиции. Позиции нумеруются с единицы
concat(строка1, строка2)	Результат конкатенации строка1 и строка2
like(строка, шаблон)	true, если значение строки удовлетворяет шаблону. Синтаксис шаблона аналогичен функции ПОДОБНО() языка запросов (см. здесь)

5.10.2. Функции для работы с датами

Функция	Описание	Пример
year(дата)	Год, к которому относится дата	year(ДатаРождения) ge 2000
quarter(дата)	Номер календарного квартала, к которому относится дата	quarter(ДатаПроизводства) ne 4
month(дата)	Номер календарного месяца, к которому относится дата	month(ДатаПроизводства) ne 12
day(дата)	Число месяца, к которому относится дата	day(ДатаПроизводства) eq 31
hour(дата)	Час календарных суток	hour(ДатаНачала) eq 23
minute(дата)	Минута в часе	minute(ДатаНачала) eq 59
second(дата)	Секунда в минуте	second(ДатаНачала) eq 59
datedifference(дата1, дата2, единица)	разность дат дата1 и дата2 в единицах, указанных параметром единица: 'second' — в секундах, 'minute' — в минутах, 'hour' — в часах, 'day' — в днях, 'month' — в месяцах, 'quarter' — в кварталах, 'year' — в годах	datedifference(Произведен, ГоденДо, ‘day’) gt 30
dateadd(дата, единица, количество)	возвращает дату, полученную добавлением к значению дата заданного количества единиц, указанных параметром единица: 'second' — секунд, 'minute' — минут, 'hour' — часов, 'day' — суток, 'month' — месяцев, 'quarter' — кварталов, 'year' — лет	dateadd(Произведен, ‘day’, 30) gt ГоденДо
dayofweek(дата)	Номер дня недели	dayofweek(ДатаРождения) eq 7
dayofyear(дата)	Номер дня в году	dayofyear(ДатаРождения) eq 1

5.10.3. Функции all и any

Для отбора по реквизитам табличных частей в запросах стандартного интерфейса OData можно использовать лямбда-функции all и any. Эти функции проверяют указанное условие для всех строк табличной части объекта, и возвращают значение true:

для функции any — если условие выполнено хотя бы для одной строки табличной части;
для функции all — если условие выполнено для всех строк табличной части.

В иных случаях эти функции возвращают значение false.

Поясним синтаксис функций all и any на примере. Пусть нужно отобрать документы РасходТовара, в которых имеется хотя бы один товар с ценой большей 10000. Иными словами, в табличной части Товары этих документов должна быть хотя бы одна строка, в которой значение реквизита Цена больше 10000. Это можно сделать, использовав в запросе OData такую конструкцию:

.../Document_РасходТовара?$filter=Товары/any(d: d/Цена gt 10000)

Как видно, непосредственно перед названием функции any указывается имя табличной части Товары и слеш /. В скобках указывается имя переменной (в данном случае использовано имя d). Эта переменная будет использоваться в логическом выражении, она обозначает строку табличной части. После имени переменной следует двоеточие и затем указывается проверяемое логическое выражение. Обозначение d/Цена означает реквизит Цена строки d табличной части документа.

Аналогично, чтобы отобрать документы РасходТовара, у которых в табличной части Товары во всех строках значение реквизита Цена больше 10000, в запросе OData можно использовать следующую конструкцию:

.../Document_РасходТовара?$filter=Товары/all(d: d/Цена gt 10000)

Ниже в разделе 6.5.1 приведен пример использования функции any.

5.10.4. Прочие функции

Функция	Описание
round(число)	Округление числа до ближайшего целого
isof(выражение, тип)	true, если заданное выражение имеет указанный тип. Тип задается в виде строки с названием типа, например: 'String', 'Number', 'Boolean', 'Date', 'Catalog_Товары' и т. д.
cast(выражение, тип)	Приведение выражения к указанному типу. Тип задается в виде строки с названием типа, например: 'String', 'Number', 'Boolean', 'Date', 'Catalog_Товары' и т. д.

6. Примеры запросов с помощью стандартного интерфейса OData

Приведенные ниже примеры показывают лишь некоторые самые простые возможности запросов с помощью стандартного интерфейса OData. Более полные сведения можно прочесть в руководстве разработчика 1С:Предприятия.

6.1. Общие сведения

6.1.1. Приложение для примеров использования стандартного интерфейса OData

Для удобства приведем сквозной пример использования стандартного интерфейса OData. В нем мы будем использовать демонстрационное приложение Управление нашей фирмой. В нем нужно:

Включить валютный учет (Настройки — Еще больше возможностей —Деньги —установить флажок Несколько валют.
Добавить валюту Доллар США (Деньги —Валюты), включив для нее режим установки курса загружается из Интернета.
В обработке Настройка автоматического REST-сервиса (см. раздел 4) включить доступ через интерфейс OData к следующим объектам конфигурации:
- справочники Номенклатура, Организации, Сотрудники, Физические лица
- документы Доверенность, ЗаказПокупателя
- регистр сведений КурсыВалют

6.1.2. Клиент для HTTP-запросов

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

Для выдачи всех видов HTTP-запросов можно использовать расширение REST Client среды разработки Visual Studio Code (ссылка) или любое аналогичное приложение.

6.1.3. ПрефиксURL

Все OData-запросы к приложению начинаются со строки адрес-приложения/odata/standard.odata. Например, если адрес приложения https://clobus.uz/a/sbm_demo/1962515, то OData-запросы к этому приложению начинаются со строки https://clobus.uz/a/sbm_demo/1962515/odata/standard.odata

Для наглядности и экономии места мы будем в дальнейшем вместо этой строки использовать обозначение ПрефиксURL.

6.2. Получение списков

Покажем применение методов стандартного интерфейса OData, выдающих списки различных сущностей — записей справочника, записей регистров, документов и т.д. Мы будем это делать на примере справочников Сотрудники, ФизическиеЛица и Номенклатура. Аналогичным образом можно получать сведения о других видах объектов прикладного решения.

6.2.1. Количество объектов

Просмотрим сведения о справочнике Сотрудники. Для начала узнаем количество записей в этом справочнике. Для этого укажем в GET-запросе после имени объекта Catalog_Сотрудники нужное действие /$count:

GET ПрефиксURL/Catalog_Сотрудники/$count

Здесь вместо ПрефиксURL нужно использовать строку, как указано в разделе 6.1.3. Далее это замечание мы повторять не будем.

Запрос можно ввести в адресной строке браузера (только URL, без указания метода GET).

Должен быть выдан ответ — количество сотрудников, например:

29
6.2.2. Вывод списка

Выведем первые 2 записи справочника ФизическиеЛица. Для этого укажем в запросе параметр $top=2. Также зададим в этом запросе и будем указывать в последующих запросах параметр $format=json, указывающий применение формата JSON для кодирования данных в теле ответа и в теле запроса.

GET ПрефиксURL/Catalog_ФизическиеЛица?$format=json&$top=2

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_ФизическиеЛица", "value": [ { "Ref_Key": "baebacee-b80e-11e4-826f-001e101fe696", "DataVersion": "AAAAAAAAAAA=", "DeletionMark": false, "Parent_Key": "00000000-0000-0000-0000-000000000000", "IsFolder": false, "Code": "ФР-0000002", "Description": "Абнагимова Ирина Витальевна", "ДатаРождения": "1947-08-05T00:00:00", "Пол": "Женский", "ИНН": "", "СтраховойНомерПФР": "", "Гражданство_Key": "00000000-0000-0000-0000-000000000000", "Недействителен": false, "БанковскийСчетПоУмолчанию_Key": "00000000-0000-0000-0000-000000000000", "КонтактнаяИнформация": [], "ДополнительныеРеквизиты": [], "Predefined": false, "PredefinedDataName": "" }, { "Ref_Key": "baebad03-b80e-11e4-826f-001e101fe696", "DataVersion": "AAAAAAAAAAA=", "DeletionMark": false, "Parent_Key": "00000000-0000-0000-0000-000000000000", "IsFolder": false, "Code": "ФР-0000003", "Description": "Аввакумов Вадим Иванович", "ДатаРождения": "1966-06-04T00:00:00", "Пол": "Мужской", "ИНН": "", "СтраховойНомерПФР": "", "Гражданство_Key": "00000000-0000-0000-0000-000000000000", "Недействителен": false, "БанковскийСчетПоУмолчанию_Key": "00000000-0000-0000-0000-000000000000", "КонтактнаяИнформация": [], "ДополнительныеРеквизиты": [], "Predefined": false, "PredefinedDataName": "" } ] }
6.2.3. Отбор отображаемых реквизитов

Пусть нас интересуют только ФИО, пол и дата рождения. Выведем первые 3 записи справочника ФизическиеЛица только с этими реквизитами. Для этого укажем в запросе параметры $top=3 и $select=Description,Пол,ДатаРождения. Введем GET-запрос:

GET ПрефиксURL/Catalog_ФизическиеЛица?$format=json&$top=3&$select=Description,Пол,ДатаРождения

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_ФизическиеЛица", "value": [ { "Description": "Абнагимова Ирина Витальевна", "Пол": "Женский", "ДатаРождения": "1947-08-05T00:00:00" }, { "Description": "Аввакумов Вадим Иванович", "Пол": "Мужской", "ДатаРождения": "1966-06-04T00:00:00" }, { "Description": "Авдеев Александр Алексеевич", "Пол": "Мужской", "ДатаРождения": "1980-11-15T00:00:00" } ] }
6.2.4. Отбор объектов

Пусть нас интересуют только сведения о мужчинах. Выведем ФИО и дату рождения для первых 3 записей справочника ФизическиеЛица, в которых Пол='Мужской'. Для этого добавим в запрос параметр $filter=Пол eq 'Мужской':

GET ПрефиксURL/Catalog_ФизическиеЛица?$format=json&$top=3&$select=Description,ДатаРождения&$filter=Пол eq 'Мужской'

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_ФизическиеЛица", "value": [ { "Description": "Аввакумов Вадим Иванович", "ДатаРождения": "1966-06-04T00:00:00" }, { "Description": "Авдеев Александр Алексеевич", "ДатаРождения": "1980-11-15T00:00:00" }, { "Description": "Александров Дмитрий Олегович", "ДатаРождения": "1977-08-04T00:00:00" } ] }
6.2.5. Показ количества объектов, удовлетворяющих условиям отбора

Указав в запросе OData параметр $inlinecount=allpages, можно одновременно получить записи, удовлетворяющие условиям отбора, и общее количество таких записей.

Выведем ФИО и дату рождения для первых 3 записей справочника ФизическиеЛица, в которых Пол='Мужской', и получим общее количество записей, в которых Пол='Мужской'. Введем запрос:

GET ПрефиксURL/Catalog_ФизическиеЛица?$format=json&$top=3&$select=Description,ДатаРождения&$filter=Пол eq 'Мужской'&$inlinecount=allpages

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_ФизическиеЛица", "odata.count": "28", "value": [ { "Description": "Аввакумов Вадим Иванович", "ДатаРождения": "1987-06-04T00:00:00" }, { "Description": "Авдеев Александр Алексеевич", "ДатаРождения": "1980-11-15T00:00:00" }, { "Description": "Александров Дмитрий Олегович", "ДатаРождения": "1977-08-04T00:00:00" } ] }

Как видно, ответ на запрос такой же, как в разделе 6.2.4, только добавилась строка:

"odata.count": "28",

Это означает, что условиям отбора удовлетворяют 28 записей. Обратите внимание, что в ответе показаны сведения лишь о трех записях, так как использован параметр $top=3.

6.2.6. Использование функций при отборе

В запросе OData, выдающем список, можно использовать функции (см. раздел 5.10):

при задании условий отбора (параметр $filter, см. раздел 5.7.1);
при задании порядка сортировки результатов (параметр $orderby, см. раздел 5.7.2).

Покажем пример использования функции при задании условий отбора. Выведем список наименований и артикулов первых трех записей справочника Номенклатура, в которых наименование начинается со строки 'Таз'.

Для проверки будем использовать функцию startswith. Введем такой запрос:

GET ПрефиксURL/Catalog_Номенклатура?$format=json&$filter=startswith(НаименованиеПолное,'Таз')&$select=НаименованиеПолное,Артикул&$top=3

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_Номенклатура", "value": [ { "НаименованиеПолное": "Таз пластмассовый овальный с ручками (\"POBEDA\"), 25 л", "Артикул": "8940" }, { "НаименованиеПолное": "Таз пластмассовый овальный с ручками (\"POBEDA\"), 35 л", "Артикул": "8941" }, { "НаименованиеПолное": "Таз пластмассовый овальный с ручками (\"POBEDA\"), 55 л", "Артикул": "8942" } ] }
6.2.7. Раскрытие подчиненных объектов

Посмотрим, как устроена запись справочника Сотрудники:

GET ПрефиксURL/Catalog_Сотрудники?$format=json&$top=1

Должен быть выдан примерно такой ответ:

Как видно, в этой записи есть реквизит Физлицо_Key. Это ссылка на запись справочника ФизическиеЛица. Попросим включить эту запись в ответ интерфейса OData. Для этого добавим к запросу параметр $expand=Физлицо. Введем запрос:

GET ПрефиксURL/Catalog_Сотрудники??$format=json&$top=1&$expand=Физлицо

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_Сотрудники", "value": [ { "Ref_Key": "baebacef-b80e-11e4-826f-001e101fe696", "DataVersion": "AAAAAAAAAAA=", "DeletionMark": false, "Parent_Key": "00000000-0000-0000-0000-000000000000", "IsFolder": false, "Code": "В-02", "Description": "Абнагимова Ирина Витальевна", "Физлицо_Key": "baebacee-b80e-11e4-826f-001e101fe696", "ТипЗанятости": "ОсновноеМестоРаботы", "СчетРасчетовСПерсоналом_Key": "60f112fb-b5b8-11e4-8355-74d02b7dfd8c", "СчетРасчетовСПодотчетниками_Key": "60f112fd-b5b8-11e4-8355-74d02b7dfd8c", "СчетРасчетовПоПерерасходу_Key": "60f112fe-b5b8-11e4-8355-74d02b7dfd8c", "Недействителен": false, "ШтрихКод": "", "МагнитныйКод": "", "ДополнительныеРеквизиты": [], "Predefined": false, "PredefinedDataName": "", "Физлицо@navigationLinkUrl": "Catalog_Сотрудники(guid'baebacef-b80e-11e4-826f-001e101fe696')/Физлицо", "Физлицо": { "Parent_Key": "00000000-0000-0000-0000-000000000000", "Гражданство_Key": "00000000-0000-0000-0000-000000000000", "БанковскийСчетПоУмолчанию_Key": "00000000-0000-0000-0000-000000000000", "DeletionMark": false, "IsFolder": false, "DataVersion": "AAAAAAAAAAA=", "ИНН": "", "ДатаРождения": "1947-08-05T00:00:00", "Недействителен": false, "Predefined": false, "Ref_Key": "baebacee-b80e-11e4-826f-001e101fe696", "Code": "ФР-0000002", "Description": "Абнагимова Ирина Витальевна", "СтраховойНомерПФР": "", "Пол": "Женский", "КонтактнаяИнформация": [], "PredefinedDataName": "", "ДополнительныеРеквизиты": [] }, "СчетРасчетовСПерсоналом@navigationLinkUrl": "Catalog_Сотрудники(guid'baebacef-b80e-11e4-826f-001e101fe696')/СчетРасчетовСПерсоналом", "СчетРасчетовСПодотчетниками@navigationLinkUrl": "Catalog_Сотрудники(guid'baebacef-b80e-11e4-826f-001e101fe696')/СчетРасчетовСПодотчетниками", "СчетРасчетовПоПерерасходу@navigationLinkUrl": "Catalog_Сотрудники(guid'baebacef-b80e-11e4-826f-001e101fe696')/СчетРасчетовПоПерерасходу" } ] }

6.2.8. Раскрытие подчиненных объектов и отбор отображаемых реквизитов

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

$expand=Физлицо&$select=Description,Code,ТипЗанятости,Физлицо/Пол,Физлицо/ДатаРождения

Так как реквизиты Пол и ДатаРождения входят в подчиненный объект Физлицо, то они указываются в параметре $select как Физлицо/Пол и Физлицо/ДатаРождения. Получается следующий запрос:

GET ПрефиксURL/Catalog_Сотрудники?$format=json&$top=1&$expand=Физлицо&$select=Description,Code,ТипЗанятости,Физлицо/Пол,Физлицо/ДатаРождения

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_Сотрудники", "value": [ { "Description": "Абнагимова Ирина Витальевна", "Code": "В-02", "ТипЗанятости": "ОсновноеМестоРаботы", "Физлицо@navigationLinkUrl": "Catalog_Сотрудники(guid'baebacef-b80e-11e4-826f-001e101fe696')/Физлицо", "Физлицо": { "Пол": "Женский", "ДатаРождения": "1947-08-05T00:00:00" } } ] }
6.2.9. Сортировка результатов

Упорядочим записи справочника Сотрудники по реквизитам Тип занятости и Code, и выведем значения реквизитов Тип занятости, Code и Description для первых 3 записей упорядоченного списка. Для упорядочения записей в запросе нужно указать параметр $orderby=ТипЗанятости desc,Code:

GET ПрефиксURL/Catalog_Сотрудники?$format=json&$orderby=ТипЗанятости desc,Code&$select=Description,Code,ТипЗанятости&$top=3

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_Сотрудники", "value": [ { "Description": "Администратор", "Code": "", "ТипЗанятости": "ОсновноеМестоРаботы" }, { "Description": "Абдулов Юрий Владимирович", "Code": "В-01", "ТипЗанятости": "ОсновноеМестоРаботы" }, { "Description": "Абнагимова Ирина Витальевна", "Code": "В-02", "ТипЗанятости": "ОсновноеМестоРаботы" } ] }
6.2.10. Сортировка по полям подчиненного объекта

Пусть нам нужно получить сведения о сотрудниках, упорядоченные по полу, типу занятости и коду. Пол сотрудника хранится в подчиненном объекте Физлицо. Поэтому в запрос нужно включить:

параметр $expand=Физлицо, включающий в ответ содержимое объекта Физлицо, а не только ссылку на этот объект;
строку Физлицо/Пол в значения параметров $orderby и $select, чтобы сведения о поле сотрудника учитывались при сортировке результатов и выводились в результатах запроса.

Получается запрос следующего вида:

GET ПрефиксURL/Catalog_Сотрудники?$format=json&$expand=Физлицо&$select=Description,Code,ТипЗанятости,Физлицо/Пол&$orderby=Физлицо/Пол,Code,Description&$top=3

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_Сотрудники", "value": [ { "Description": "Абдулов Юрий Владимирович", "Code": "В-01", "ТипЗанятости": "ОсновноеМестоРаботы", "Физлицо@navigationLinkUrl": "Catalog_Сотрудники(guid'b770ac08-b76d-11e4-be02-74d02b7dfd8c')/Физлицо", "Физлицо": { "Пол": "Мужской" } }, { "Description": "Аввакумов Вадим Иванович", "Code": "В-04", "ТипЗанятости": "ОсновноеМестоРаботы", "Физлицо@navigationLinkUrl": "Catalog_Сотрудники(guid'baebacfa-b80e-11e4-826f-001e101fe696')/Физлицо", "Физлицо": { "Пол": "Мужской" } }, { "Description": "Аввакумов Вадим Иванович", "Code": "В-05", "ТипЗанятости": "Совместительство", "Физлицо@navigationLinkUrl": "Catalog_Сотрудники(guid'baebad04-b80e-11e4-826f-001e101fe696')/Физлицо", "Физлицо": { "Пол": "Мужской" } } ] }

6.3. Работа с отдельными объектами

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

6.3.1. Получение записи

Получим запись справочника ФизическиеЛица с ключом baebad03-b80e-11e4-826f-001e101fe696:

GET ПрефиксURL/Catalog_ФизическиеЛица(guid'baebad03-b80e-11e4-826f-001e101fe696')?$format=json

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_ФизическиеЛица/@Element", "Гражданство_Key": "00000000-0000-0000-0000-000000000000", "КонтактнаяИнформация": [], "ДополнительныеРеквизиты": [], "БанковскийСчетПоУмолчанию_Key": "00000000-0000-0000-0000-000000000000", "Недействителен": false, "DeletionMark": false, "ДатаРождения": "1966-06-04T00:00:00", "Пол": "Мужской", "Ref_Key": "baebad03-b80e-11e4-826f-001e101fe696", "Description": "Аввакумов Вадим Иванович", "IsFolder": false, "PredefinedDataName": "", "DataVersion": "AAAAAAAAAAA=", "Code": "ФР-0000003", "Parent_Key": "00000000-0000-0000-0000-000000000000", "СтраховойНомерПФР": "", "ИНН": "", "Predefined": false }
6.3.2. Чтение записи с отбором отображаемых реквизитов

Получим ту же запись справочника, но выведем только ФИО, пол и дату рождения. Для этого нужно добавить в запрос параметр $select=Description,Пол,ДатаРождения:

GET ПрефиксURL/Catalog_ФизическиеЛица(guid'baebad03-b80e-11e4-826f-001e101fe696')?$format=json&$select=Description,Пол,ДатаРождения

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_ФизическиеЛица/@Element", "Description": "Аввакумов Вадим Иванович", "ДатаРождения": "1966-06-04T00:00:00", "Пол": "Мужской" }
6.3.3. Раскрытие подчиненных объектов и отбор отображаемых реквизитов

При получении одной записи справочника нельзя сразу же раскрыть содержимое подчиненных объектов с помощью оператора $expand. Как было сказано ранее, этот оператор применим только при получении списка элементов. Если требуется получить ФИО, код, тип занятости, дату рождения и пол конкретного сотрудника, то для этого придется выполнить два запроса. Первым запросом получаем ФИО, код, тип занятости сотрудника из записи справочника Сотрудники:

GET ПрефиксURL/Catalog_Сотрудники(guid'baebacfa-b80e-11e4-826f-001e101fe696')?$format=json&$select=Description,Code,ТипЗанятости

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_Сотрудники/@Element", "ТипЗанятости": "ОсновноеМестоРаботы", "Code": "В-04", "Description": "Аввакумов Вадим Иванович" }

Вторым запросом получаем дату рождения и пол из подчиненного объекта Физлицо. Чтобы обратиться к подчиненному объекту, добавляем в URL после выбора записи справочника строку /Физлицо:

GET ПрефиксURL/Catalog_Сотрудники(guid'baebacef-b80e-11e4-826f-001e101fe696')/Физлицо?$format=json&$select=Пол,ДатаРождения

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_ФизическиеЛица/@Element", "Пол": "Мужской", "ДатаРождения": "1966-06-04T00:00:00" }
6.3.4. Исправление данных

Исправим данные записи справочника ФизическиеЛица, которую мы получили в разделе 6.3.1. А именно, заменим значение ИНН на '772800173088', а год рождения на 1987.

Для этого можно применить PATCH-запрос:

PATCH ПрефиксURL/Catalog_ФизическиеЛица(guid'baebad03-b80e-11e4-826f-001e101fe696')?$format=json

В теле этого запроса необходимо передать JSON-объект с исправленными данными:

{ "ИНН": "772800173088", "ДатаРождения": "1987-06-04T00:00:00" }

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_ФизическиеЛица/@Element", "DeletionMark": false, "ИНН": "772800173088", "Parent_Key": "00000000-0000-0000-0000-000000000000", "Code": "ФР-0000003", "БанковскийСчетПоУмолчанию_Key": "00000000-0000-0000-0000-000000000000", "Недействителен": false, "Predefined": false, "КонтактнаяИнформация": [], "ДополнительныеРеквизиты": [], "ДатаРождения": "1987-06-04T00:00:00", "Пол": "Мужской", "Description": "Аввакумов Вадим Иванович", "Гражданство_Key": "00000000-0000-0000-0000-000000000000", "IsFolder": false, "PredefinedDataName": "", "Ref_Key": "baebad03-b80e-11e4-826f-001e101fe696", "DataVersion": "AAAAAAAAAAE=", "СтраховойНомерПФР": "" }

Как видно, результат запроса — это исправленная запись справочника ФизическиеЛица. Реквизиты ИНН и ДатаРождения в ней получили новые значения.

При желании можно вывести карточку этого физического лица в приложении (меню Персонал — Физические лица), и убедиться, что в карточке показаны исправленные значения реквизитов ИНН и Дата рождения.

6.3.5. Добавление

Добавим в справочник ФизическиеЛица новую запись. Для этого можно использовать POST-запрос:

POST ПрефиксURL/Catalog_ФизическиеЛица?$format=json

В теле этого запроса необходимо передать JSON-объект с данными записи справочника:

{ "DeletionMark": false, "Parent_Key": "00000000-0000-0000-0000-000000000000", "IsFolder": false, "Code": "ФР-0000041", "Description": "Иванов Андрей Борисович", "ДатаРождения": "1992-12-13T00:00:00", "Пол": "Мужской", "ИНН": "772800192179", "СтраховойНомерПФР": "", "Гражданство_Key": "00000000-0000-0000-0000-000000000000", "Недействителен": false, "БанковскийСчетПоУмолчанию_Key": "00000000-0000-0000-0000-000000000000", "КонтактнаяИнформация": [], "ДополнительныеРеквизиты": [], "Predefined": false, "PredefinedDataName": "" }

Как видно, здесь указаны те же реквизиты, которые получены при чтении записи справочника (см. раздел 6.3.1), только без служебных реквизитов odata.metadata, DataVersion и Ref_Key.

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_ФизическиеЛица/@Element", "Description": "Иванов Андрей Борисович", "ИНН": "772800192179", "ДатаРождения": "1992-12-13T00:00:00", "PredefinedDataName": "", "ДополнительныеРеквизиты": [], "DataVersion": "AAAAAAAAAAA=", "Ref_Key": "1683a3cc-44e5-11ed-8d7b-005056892602", "СтраховойНомерПФР": "", "Гражданство_Key": "00000000-0000-0000-0000-000000000000", "IsFolder": false, "КонтактнаяИнформация": [], "Predefined": false, "Пол": "Мужской", "БанковскийСчетПоУмолчанию_Key": "00000000-0000-0000-0000-000000000000", "Code": "ФР-0000041", "Parent_Key": "00000000-0000-0000-0000-000000000000", "DeletionMark": false, "Недействителен": false }

Как видно, результат запроса содержит сведения о добавленной записи справочника ФизическиеЛица.

При желании можно вывести в приложении форму справочника ФизическиеЛица (меню Персонал — Физические лица) и убедиться, что в справочнике имеется добавленная запись.

6.3.6. Удаление

Удалим созданную запись из справочника ФизическиеЛица. Для этого можно использовать DELETE-запрос:

DELETE ПрефиксURL/Catalog_ФизическиеЛица(guid'1683a3cc-44e5-11ed-8d7b-005056892602')

В запросе указывается ключ (guid) той записи, которую нужно удалить.

Ответ на запрос будет с HTTP-кодом состояния 204 No content и пустым телом. При желании можно вывести в приложении форму справочника ФизическиеЛица и убедиться, что запись удалена из справочника.

Внимание. Следует иметь в виду, что при удалении объектов посредством стандартного интерфейса OData пометка на удаление не выполняется, а объект удаляется непосредственно.

6.4. Работа с табличными частями

Стандартный интерфейс OData содержит специальные средства для работы с табличными частями документов, справочников, задач и бизнес-процессов. Покажем их использование на примерах.

6.4.1. Отбор по значениям реквизитов табличных частей

Покажем пример применения функции any. Выведем список документов ЗаказПокупателя, в табличной части Запасы которых имеется хотя бы один товар с ценой большей 50000. В списке покажем только номера, даты и guid документов.

Отбор будет выполнен с помощью указания параметра $filter=Запасы/any(d: d/Цена gt 50000). Синтаксис функций all и any был объяснен в разделе 5.10.3.

Можно использовать следующий запрос:

GET ПрефиксURL/Document_ЗаказПокупателя?$format=json&$select=Number,Date,Ref_Key&$filter=Запасы/any(d: d/Цена gt 50000)

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Document_ЗаказПокупателя", "value": [ { "Number": "АСФР-000068", "Date": "2017-08-14T12:00:00", "Ref_Key": "5977a565-4afc-11e5-808c-74d02b7dfd8c" }, { "Number": "АСФР-000026", "Date": "2018-03-04T17:43:55", "Ref_Key": "e558b378-e040-11e5-9ef1-bcaec5b897eb" }, { "Number": "АСФР-000030", "Date": "2018-03-18T10:45:53", "Ref_Key": "f1a6853a-e5c7-11e5-9ef1-bcaec5b897eb" }, { "Number": "АСФР-000032", "Date": "2018-04-06T17:34:54", "Ref_Key": "f1a6855e-e5c7-11e5-9ef1-bcaec5b897eb" } ] }
6.4.2. Чтение табличных частей

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

GET ПрефиксURL/Catalog_Организации_КонтактнаяИнформация/?$format=json&$top=5&$select=Тип,Представление

Здесь мы запросили сведения только о 5 первых строках табличных частей (параметр $top=5). Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_Организации_КонтактнаяИнформация", "value": [ { "Тип": "АдресЭлектроннойПочты", "Представление": "assol@mail.ru" }, { "Тип": "АдресЭлектроннойПочты", "Представление": "sborka@mail.ru" }, { "Тип": "Телефон", "Представление": "(495) 5552255, доб. 702" }, { "Тип": "Телефон", "Представление": "(495) 502-77-55" }, { "Тип": "Факс", "Представление": "(495) 5553322" } ] }

Как видно, для обращения к строкам табличной части КонтактнаяИнформация справочника Организации используется обозначение Catalog_Организации_КонтактнаяИнформация.

6.4.3. Отбор строк табличных частей

В OData-запросе к табличной части можно задать условие отбора. Предположим, что мы заметили неточность в электронной почте assol@mail.ru. Получим все сведения строки табличной части, в которой указана эта электронная почта. Для этого можно использовать следующий запрос:

GET ПрефиксURL/Catalog_Организации_КонтактнаяИнформация/?$format=json&$filter=Представление eq 'assol@mail.ru'

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_Организации_КонтактнаяИнформация", "value": [ { "Ref_Key": "6e3445bb-b5b8-11e4-8355-74d02b7dfd8c", "LineNumber": "2", "Тип": "АдресЭлектроннойПочты", "Вид_Key": "6e34475f-b5b8-11e4-8355-74d02b7dfd8c", "Представление": "assol@mail.ru", "ЗначенияПолей": "<КонтактнаяИнформация xmlns=\"http://www.v8.1c.ru/ssl/contactinfo\" xmlns:xs=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" Представление=\"assol@mail.ru\"><Комментарий/><Состав xsi:type=\"ЭлектроннаяПочта\" Значение=\"assol@mail.ru\"/>", "Страна": "", "Регион": "", "Город": "", "АдресЭП": "assol@mail.ru", "ДоменноеИмяСервера": "mail.ru", "НомерТелефона": "", "НомерТелефонаБезКодов": "", "Значение": "", "ВидДляСписка_Key": "6e34475f-b5b8-11e4-8355-74d02b7dfd8c", "ДействуетС": "0001-01-01T00:00:00", "Вид@navigationLinkUrl": "Catalog_Организации_КонтактнаяИнформация(Ref_Key=guid'6e3445bb-b5b8-11e4-8355-74d02b7dfd8c', LineNumber=2)/Вид", "ВидДляСписка@navigationLinkUrl": "Catalog_Организации_КонтактнаяИнформация(Ref_Key=guid'6e3445bb-b5b8-11e4-8355-74d02b7dfd8c', LineNumber=2)/ВидДляСписка" } ] }
6.4.4. Чтение табличной части объекта

Для показа табличной части объекта можно задать параметр $select=имя-табличной-части. Например, для показа табличной части Запасы документа Доверенность с guid 98043082-f588-11e5-98a6-bcaec5b897eb можно использовать следующий запрос:

GET ПрефиксURL/Document_Доверенность(guid'98043082-f588-11e5-98a6-bcaec5b897eb')/?$format=json&$select=Запасы

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Document_Доверенность/@Element", "Запасы": [ { "LineNumber": "1", "НаименованиеТовара": "Ручка", "ЕдиницаИзмерения": "шт", "Количество": 1 } ] }

Другой способ — указать слеш / и имя табличной части после операции выбора объекта:

GET ПрефиксURL/Document_Доверенность(guid'98043082-f588-11e5-98a6-bcaec5b897eb')/Запасы?$format=json

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Collection(StandardODATA.Document_Доверенность_Запасы_RowType)", "value": [ { "LineNumber": "1", "НаименованиеТовара": "Ручка", "ЕдиницаИзмерения": "шт", "Количество": 1 } ] }
6.4.5. Изменение табличной части

Для изменения табличной части объекта можно использовать PATCH-запрос для объекта, которому принадлежит табличная часть. Например, пусть в документе Доверенность, который мы читали в разделе 6.4.4, нужно изменить в первой строке табличной части количество на 10, и добавить строку табличной части с наименованием Стул и количеством 5. Для этого можно использовать следующий запрос:

PATCH ПрефиксURL/Document_Доверенность(Ref_Key=guid'98043082-f588-11e5-98a6-bcaec5b897eb')/?$format=json

В теле этого запроса необходимо передать JSON-объект с данными табличной части:

{ "Запасы": [ { "LineNumber": "1", "НаименованиеТовара": "Ручка", "ЕдиницаИзмерения": "шт", "Количество": 10 }, { "LineNumber": "2", "НаименованиеТовара": "Стул", "ЕдиницаИзмерения": "шт", "Количество": 5 } ] }

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

В ответе будут выданы данные измененного документе Доверенность.

6.5. Применение методов

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

проведение и отмена проведения документа;
применение среза первых для регистра сведений.

6.5.1. Проведение и отмена проведения документа

Покажем возможность проведения и отмены проведения документа на примере документа ЗаказПокупателя. Создадим в приложении заказ покупателя (пункт меню Продажи — Заказы покупателя), например, скопировав один из имеющихся заказов.

Установим для нового заказа состояние Обсуждение КП и заполним дату отгрузки, иначе приложение не позволит провести документ. Сохраним документ, нажав кнопку Записать (не Провести и закрыть).

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

Теперь узнаем guid созданного документа, введя запрос:

GET ПрефиксURL/Document_ЗаказПокупателя?$format=json&$orderby=Date desc&$top=1&$select=Ref_Key,Number,Date,Posted

Здесь мы сортируем сведения о документах по убыванию даты (параметр $orderby=Date desc), запрашиваем вывод сведений только об одном документе (параметр $top=1) и просим вывести только значения реквизитов Ref_Key, Number, Date и Posted.

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Document_ЗаказПокупателя", "value": [ { "Ref_Key": "f3f4dc08-4553-11ed-8d7b-005056892602", "Number": "АСФР-000112", "Date": "2022-10-06T11:50:38", "Posted": false } ] }

Как видно, последний заказ покупателя имеет ключ f3f4dc08-4553-11ed-8d7b-005056892602, и документ не проведен ("Posted": false).

Проведем этот документ, применив к нему метод Post():

POST ПрефиксURL/Document_ЗаказПокупателя(guid'f3f4dc08-4553-11ed-8d7b-005056892602')/Post()

Ответ на запрос будет содержать HTTP-код состояния 200 OK и пустое тело ответа.

Проверим свойства документа. Это можно сделать с помощью приведенного выше GET-запроса. Увидим, что документ проведен ("Posted": true). Также можно обновить в приложении список заказов покупателей и увидеть, что значок заказа содержит галочку, обозначающую, что документ проведен.

При желании можно отменить проведение документа, применив к нему метод Unpost():

POST ПрефиксURL/Document_ЗаказПокупателя(guid'f3f4dc08-4553-11ed-8d7b-005056892602')/Unpost()

Следует иметь в виду, что приложение может, исходя из своей бизнес-логики, отказать в проведении или отмене проведения документа. В этом случае на OData-запрос будет выдан ответ с HTTP-кодом состояния 500. Причину ошибки можно узнать, попробовав провести или отменить проведение документа интерактивно в приложении:

6.5.2. Срез первых для периодического регистра сведений

Покажем применение метода SliceFirst для вывода курса валюты на указанную дату. Формат вызова этого метода: SliceFirst(Period=дата, Condition='строка-условия').

Курсы валют хранятся в периодическом регистре сведений КурсыВалют. Чтобы найти курс валюты USD (доллара США), введем запрос:

GET ПрефиксURL/InformationRegister_КурсыВалют/SliceFirst(Period=datetime'2022-09-30T00:00:00', Condition='Валюта/Description eq 'USD')?$format=json&$expand=Валюта&$select=Курс,Period

Здесь в ответе на OData-запрос раскрывается вложенный объект Валюта и накладывается условие, что значение реквизита Description этого объекта равно USD. Параметр $select=Курс,Period означает, что в ответе нужно вывести только значения реквизитов Курс и Period.

Должен быть выдан примерно такой ответ:

{ "odata.metadata": "https://clobus.uz:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#InformationRegister_КурсыВалют", "value": [ { "Курс": 57.413, "Period": "2022-09-30T00:00:00" } ] }

Таким образом, значение курса валюты USD на 30 сентября 2022 г. — 57.413.