Frequently Asked Questions | Write an email | close |
В этой статье рассказывается об использовании стандартного интерфейса OData для программного чтения и записи данных приложений абонентов сервиса 1С:Фреш.
OData (Open Data Protocol) — это открытый веб-протокол для запроса, добавления, удаления и обновления данных. OData позволяет выполнять операции с ресурсами с помощью HTTP-запросов и получать ответы в форматах XML или JSON. Подробнее о протоколе OData можно прочесть в Википедии.
Доступ к данным посредством OData можно использовать, например:
Начиная с версии 8.3.5, в платформе «1С:Предприятие» поддерживается доступ через протокол OData к данным информационных баз «1С:Предприятия». Это позволяет читать и записывать из внешнего приложения данные прикладного решения «1С:Предприятия» без модификации кода этого прикладного решения.
Разработчикам прикладных решений на платформе «1С:Предприятие» не нужно писать ни строчки кода для того, чтобы с данными прикладного решения можно было работать по протоколу OData. Достаточно включить поддержку OData при публикации на веб-сервере, и платформа «1С:Предприятие» автоматически создаст REST-интерфейс, с помощью которого можно обращаться к данным всего прикладного решения по протоколу OData.
Этот автоматически создаваемый REST-интерфейс прикладных решений на платформе «1С:Предприятие» принято называть стандартным интерфейсом OData.
Для использования стандартного интерфейса OData:
С помощью стандартного интерфейса OData доступны:
При действиях с данными с помощью стандартного интерфейса OData платформа «1С:Предприятие» выполняет все обычные проверки прав доступа и вызывает обработчики событий.
Подробнее о возможностях стандартного интерфейса OData рассказано здесь.
В сервисе 1С:Фреш (1cfresh.com) все прикладные информационные базы опубликованы с включенной поддержкой интерфейса OData.
Поэтому для приложений абонентов сервиса 1С:Фреш возможны чтение и запись данных с помощью HTTP-запросов стандартного интерфейса OData.
Ограничение: в сервисе 1С:Фреш в OData-запросах не поддерживается HTTP-заголовок 1C_OData-DataLoadMode: true, позволяющий при записи объектов эмулировать запись, выполняемую во время работы механизма обмена данными (свойство ОбменДанными.Загрузка = Истина). OData-запросы с таким заголовком не будут обработаны.
Для настройки доступа через интерфейс OData в прикладных решениях обычно используется обработка Настройка автоматического REST-сервиса, позволяющая:
Обработка доступна пользователям, имеющим в приложении административные права (роль Полные права). В сервисе Фреш такие права в приложении имеет владелец абонента.
Команды, которые нужно выбрать в меню приложения для вызова обработки, могут быть следующими:
Для использования интерфейса OData рекомендуется создать в приложении отдельного служебного пользователя. Это можно сделать в обработке Настройка автоматического REST-сервиса на вкладке Авторизация.
Созданному служебному пользователю будут автоматически назначены права, необходимые для использования интерфейса OData, в частности, роль УдаленныйДоступOData. Этот служебный пользователь не будет отображаться ни в списке пользователей приложения (в режиме «1С:Предприятие»), ни в списке пользователей абонента в менеджере сервиса.
На вкладке Состав окна обработки Настройка автоматического REST-сервиса можно указать, какие объекты прикладного решения будут доступны через интерфейс OData.
Рекомендуется включать доступ только для видов объектов, используемых в задачах, для которых будет использоваться интерфейс OData. Если для доступа к каким-либо видам объектов необходимо включить доступ через интерфейс OData также и к подчиненным им видам объектов, то обработка Настройка автоматического REST-сервиса выведет соответствующее сообщение и позволит включить такой доступ.
Не рекомендуется включать доступ через OData к планам обмена, так как их некорректное изменение может привести к неработоспособности приложения абонента.
После задания состава объектов, доступных через интерфейс OData, нужно нажать кнопку .
URL HTTP-запросов стандартного интерфейса OData имеет вид:
Здесь:
идентификатор-ресурса — особым образом сформированный идентификатор ресурса (возможно, с параметром) или предопределенные ресурсы. Например:
Например, в запросе:
GET https://1cfresh.com/a/sbm/12345/odata/standard.odata/Catalog_Номенклатура?$format=json&$filter=Артикул eq '345'
В запросе нужно использовать HTTP-заголовок Authorization: Basic с указанием логина/пароля пользователя, от имени которого осуществляется HTTP-запрос (строка логин:пароль, закодированная в формате base64). Этот пользователь должен иметь в приложении либо административные права (роль Полные права), либо роль УдаленныйДоступOData.
HTTP-метод запроса выбирается в зависимости от того, какая операция выполняется:
Операция | HTTP метод |
---|---|
Получение данных | GET |
Создание объекта | POST |
Обновление данных | PATCH или PUT |
Удаление данных | DELETE |
При использовании для обновления данных метода PATCH в запросе можно указывать только обновляемые свойства сущности, а при использовании метода PUT нужно указывать все свойства сущности.
В запросе OData:
’Санкт-Петербург’
;guid’7426fe18-e7e6-11ec-872c-fa163e21d4b7’
;datetime’2022-09-25T12:30:59’
.В результате выполнения запроса клиентское приложение получает ответ сервера, который может содержать данные, предоставленные сервером. Формат этих данных может быть XML (по умолчанию) или JSON.
Чтобы получить от сервера данные в формате JSON, можно:
Идентификатор ресурса, указываемый в URL стандартного интерфейса OData, начинается с указания типа и имени объекта конфигурации:
Обозначение в URL | Что означает |
---|---|
Catalog_имя | Обращение к справочнику с указанным именем |
Document_имя | Обращение к документу/документам с указанным именем |
DocumentJournal_имя | Обращение к журналу документов с указанным именем |
Constant_имя | Обращение к константе с указанным именем |
ExchangePlan_имя | Обращение к плану обмена с указанным именем |
ChartOfAccounts_имя | Обращение к плану счетов с указанным именем |
ChartOfCalculationTypes_имя | Обращение к плану видов расчета с указанным именем |
ChartOfCharacteristicTypes_имя | Обращение к плану видов характеристик с указанным именем |
InformationRegister_имя | Обращение к регистру сведений с указанным именем |
AccumulationRegister_имя | Обращение к регистру накопления с указанным именем |
CalculationRegister_имя | Обращение к регистру расчета с указанным именем |
AccountingRegister_имя | Обращение к регистру бухгалтерии с указанным именем |
BusinessProcess_имя | Обращение к бизнес-процессу с указанным именем |
Task_имя | Обращение к задаче/задачам с указанным именем |
Здесь имя объекта записывается так, как оно показано в свойстве объекта Имя в конфигураторе.
После указания типа и имени объекта конфигурации может быть указан суффикс, начинающийся с символа подчеркивания:
Суффикс | Что означает |
---|---|
_имя-табличной-части | Обращение к табличной части объекта |
_RowType | Обращение к строке табличной части объекта |
_RecordType | Обращение к записи регистра |
Для справочников, документов, регистров, задач, бизнес-процессов и табличных частей с помощью стандартного интерфейса 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 |
В заключительной части идентификатора ресурса можно указать после символа / действие с ресурсом. Например:
Действие | Описание | Условие применения |
---|---|---|
$count | В ответе нужно вывести не элементы, а только их количество | Для GET-запросов, выдающих список элементов |
Наименование-реквизита-объекта | В ответе нужно вывести только значение указанного реквизита | Для запросов, результатом которых является объект |
Наименование-табличной-части | В ответе нужно вывести только указанную табличную часть | Для запросов, результатом которых является объект |
Наименование-метода(параметры) | Для выбранного объекта нужно применить указанный метод | Для объектов тех видов, к которым применим данный метод |
Замечание. В ответе можно вывести значение реквизита подчиненного объекта. В этом случае полное имя реквизита формируется с использованием разделителя /. Например, /Контрагент/ИНН означает, что в запросе следует вывести только значение реквизита ИНН объекта, на который ссылается реквизит ответа Контрагент.
Вот некоторые методы, которые можно использовать в OData-запросах (подробнее см. здесь):
Метод | Описание | Условие применения |
---|---|---|
SliceLast(Period=дата, Condition='строка-условия') | Выдать срез последних | Для запросов к периодическим регистрам сведений |
SliceFirst(Period=дата, Condition='строка-условия') | Выдать срез первых | Для запросов к периодическим регистрам сведений |
Post() | Проведение документа | Для документов |
Post(PostingModeOperational=true) | Проведение документа в оперативном режиме | Для документов |
Unpost() | Отмена проведения документа | Для документов |
Unpost(PostingModeOperational=true) | Отмена проведения документа в оперативном режиме | Для документов |
ExecuteTask() | Выполение задачи | Для задач |
Start() | Запуск бизнес-процесса | Для бизнес-процессов |
Start(RoutePoint=имя-точки-маршрута) | Запуск бизнес-процесса с заданной точки маршрута | Для бизнес-процессов |
Ниже приведены примеры использования некоторых из этих методов:
Также имеются специальные методы для регистров накопления, бухгалтерии и расчета подробнее (см. здесь, здесь и здесь):
Объект | Метод | Обеспечивает доступ к виртуальной таблице |
---|---|---|
Регистр накопления | Balance | Остатков регистра накопления |
Turnovers | Оборотов регистра накопления | |
BalanceAndTurnovers | Оборотов и оборотов регистра накопления | |
Регистр бухгалтерии | Balance | Остатков регистра бухгалтерии |
Turnovers | Оборотов регистра бухгалтерии | |
BalanceAndTurnovers | Оборотов и оборотов регистра бухгалтерии | |
ExtDimensions | Субконто регистра бухгалтерии | |
RecordsWithExtDimensions | Движений с субконто регистра бухгалтерии | |
DrCrTurnover | Оборотов с агрегацией регистра бухгалтерии | |
Регистр расчета | ScheduledData | Графика регистра расчета |
ActualActionPeriod | Фактического периода действия регистра расчета | |
ИмяПерерасчета | Записей перерасчета | |
BaseИмяБазовогоРегистраРасчета | Базовых данных регистра расчета |
Как уже говорилось, в HTTP-запросе стандартного интерфейса OData после символа ? могут указываться параметры запроса в виде разделенных амперсендами пар ключ=значение. Если параметры отсутствуют, то символ ?, разделяющий имя ресурса и параметры, в запросе не указывается.
Параметр | Описание |
---|---|
$filter=условие-отбора | В ответ нужно включить только элементы, удовлетворяющие заданному условию (об условиях рассказано ниже) |
$top=число | В ответ нужно включить не более указанного количества элементов |
$skip=число | Исключить из ответа указанное количество первых записей. Если параметры $top и $skip указываются одновременно, то параметр $skip будет применен раньше, чем параметр $top |
allowedOnly=true | Включать в ответ только те элементы, которые не попадают под ограничения доступа к данным. Если этот параметр не указан, то при наличии ограничений доступа к каким-либо данным, подпадающим под условия отбора, запрос возвращает ошибку с кодом 401. |
Параметр | Описание |
---|---|
$inlinecount=allpages | В ответ нужно включить не только полученные элементы, но и их количество. Количество сообщается в реквизите ответа odata.count |
$orderby=порядок-сортировки | Задает порядок отображения результатов запросов, выдающих список элементов. Здесь порядок-сортировки это перечисление через запятую реквизитов, по которым выполняется упорядочение результатов, причем после реквизита через пробел или несколько пробелов может указываться обозначение направления сортировки по данному реквизиту: asc (по возрастанию) или desc (по убыванию). По умолчанию выполняется сортировка по возрастанию. Если в порядке сортировки указано более одного реквизита, то сначала выполняется упорядочение по первому реквизиту, потом по второму, и т.д. |
$expand=список-реквизитов | Для реквизитов с составными значениями в ответе интерфейса OData по умолчанию передается только ключ объекта (его guid) в поле с именем имя-реквизита_Key. С помощью параметра expand можно указать, что в ответ интерфейса OData надо включить также и сам объект. Имена реквизитов перечисляется через запятую. |
$select=список-полей-ответа | Включать в ответ только указанные поля. Имена полей перечисляются через запятую. |
Параметры $inlinecount, $orderby и $expand применимы только для запросов, выдающих список элементов. Параметр $expand не может использоваться для расширения реквизитов табличных частей.
В параметре $orderby возможны:
В параметре $select при использовании совместно с параметром $expand возможно использование символов * и **:
Обозначение | Описание |
---|---|
* | Необходимо развернуть все реквизиты получаемого объекта |
** | Необходимо развернуть все реквизиты получаемого объекта, кроме табличных частей. |
Подробнее о правилах составления HTTP-запросов стандартного интерфейса OData рассказано здесь и здесь.
В параметрах запроса $filter, а также в параметрах Condition, AccountCondition, BalancedAccountCondition применяемых для выполнения действий с ресурсами (см. раздел 5.6.4), указывается условие отбора. Условие формируется из:
При указании условий запроса (параметр $filter) или реквизита, по которому выполняется упорядочивание результатов (параметр $orderby) могут применяться следующие функции:
В условиях отбора запросов OData могут использоваться арифметические и логические операции.
Обозначение | Описание | Пример |
---|---|---|
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(Артикул, 'Кофе') |
Не поддерживаются операции сравнения с реквизитом типа ХранилищеЗначения.
Обозначение | Описание | Пример |
---|---|---|
add | Сложение | Количество add 1 |
sub | Вычитание | Количество sub Расход |
mul | Умножение | Количество mul Цена |
div | Деление | СтавкаНДС div 100 |
В параметрах запроса $filter и $orderby, а также в параметрах Condition, AccountCondition, BalancedAccountCondition методов, применяемых для выполнения действий с ресурсами (см. раздел 5.6.4), могут применяться следующие функции.
Функция | Описание |
---|---|
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, если значение строки удовлетворяет шаблону. Синтаксис шаблона аналогичен функции ПОДОБНО() языка запросов (см. здесь) |
Функция | Описание | Пример |
---|---|---|
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 |
Для отбора по реквизитам табличных частей в запросах стандартного интерфейса OData можно использовать лямбда-функции all и any. Эти функции проверяют указанное условие для всех строк табличной части объекта, и возвращают значение true:
В иных случаях эти функции возвращают значение 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.
Функция | Описание |
---|---|
round(число) | Округление числа до ближайшего целого |
isof(выражение, тип) | true, если заданное выражение имеет указанный тип. Тип задается в виде строки с названием типа, например: 'String', 'Number', 'Boolean', 'Date', 'Catalog_Товары' и т. д. |
cast(выражение, тип) | Приведение выражения к указанному типу. Тип задается в виде строки с названием типа, например: 'String', 'Number', 'Boolean', 'Date', 'Catalog_Товары' и т. д. |
Приведенные ниже примеры показывают лишь некоторые самые простые возможности запросов с помощью стандартного интерфейса OData. Более полные сведения можно прочесть в руководстве разработчика 1С:Предприятия.
Для удобства приведем сквозной пример использования стандартного интерфейса OData. В нем мы будем использовать демонстрационное приложение Управление нашей фирмой. В нем нужно:
В обработке Настройка автоматического REST-сервиса (см. раздел 4) включить доступ через интерфейс OData к следующим объектам конфигурации:
GET-запросы стандартного интерфейса OData можно выполнять с помощью браузера. В адресной строке браузера нужно вводить только URL, без указания метода GET.
Для выдачи всех видов HTTP-запросов можно использовать расширение REST Client среды разработки Visual Studio Code (ссылка) или любое аналогичное приложение.
Все OData-запросы к приложению начинаются со строки адрес-приложения/odata/standard.odata. Например, если адрес приложения https://1cfresh.com/a/sbm_demo/1962515, то OData-запросы к этому приложению начинаются со строки https://1cfresh.com/a/sbm_demo/1962515/odata/standard.odata
Для наглядности и экономии места мы будем в дальнейшем вместо этой строки использовать обозначение ПрефиксURL.
Покажем применение методов стандартного интерфейса OData, выдающих списки различных сущностей — записей справочника, записей регистров, документов и т.д. Мы будем это делать на примере справочников Сотрудники, ФизическиеЛица и Номенклатура. Аналогичным образом можно получать сведения о других видах объектов прикладного решения.
Просмотрим сведения о справочнике Сотрудники. Для начала узнаем количество записей в этом справочнике. Для этого укажем в GET-запросе после имени объекта Catalog_Сотрудники нужное действие /$count:
GET ПрефиксURL/Catalog_Сотрудники/$count
Здесь вместо ПрефиксURL нужно использовать строку, как указано в разделе 6.1.3. Далее это замечание мы повторять не будем.
Запрос можно ввести в адресной строке браузера (только URL, без указания метода GET).
Должен быть выдан ответ — количество сотрудников, например:
29
Выведем первые 2 записи справочника ФизическиеЛица. Для этого укажем в запросе параметр $top=2. Также зададим в этом запросе и будем указывать в последующих запросах параметр $format=json, указывающий применение формата JSON для кодирования данных в теле ответа и в теле запроса.
GET ПрефиксURL/Catalog_ФизическиеЛица?$format=json&$top=2
Должен быть выдан примерно такой ответ:
{
"odata.metadata": "https://1cfresh.com: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": ""
}
]
}
Пусть нас интересуют только ФИО, пол и дата рождения. Выведем первые 3 записи справочника ФизическиеЛица только с этими реквизитами. Для этого укажем в запросе параметры $top=3 и $select=Description,Пол,ДатаРождения. Введем GET-запрос:
GET ПрефиксURL/Catalog_ФизическиеЛица?$format=json&$top=3&$select=Description,Пол,ДатаРождения
Должен быть выдан примерно такой ответ:
{
"odata.metadata": "https://1cfresh.com: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"
}
]
}
Пусть нас интересуют только сведения о мужчинах. Выведем ФИО и дату рождения для первых 3 записей справочника ФизическиеЛица, в которых Пол='Мужской'. Для этого добавим в запрос параметр $filter=Пол eq 'Мужской':
GET ПрефиксURL/Catalog_ФизическиеЛица?$format=json&$top=3&$select=Description,ДатаРождения&$filter=Пол eq 'Мужской'
Должен быть выдан примерно такой ответ:
{
"odata.metadata": "https://1cfresh.com: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"
}
]
}
Указав в запросе OData параметр $inlinecount=allpages, можно одновременно получить записи, удовлетворяющие условиям отбора, и общее количество таких записей.
Выведем ФИО и дату рождения для первых 3 записей справочника ФизическиеЛица, в которых Пол='Мужской', и получим общее количество записей, в которых Пол='Мужской'. Введем запрос:
GET ПрефиксURL/Catalog_ФизическиеЛица?$format=json&$top=3&$select=Description,ДатаРождения&$filter=Пол eq 'Мужской'&$inlinecount=allpages
Должен быть выдан примерно такой ответ:
{
"odata.metadata": "https://1cfresh.com: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.
В запросе OData, выдающем список, можно использовать функции (см. раздел 5.10):
Покажем пример использования функции при задании условий отбора. Выведем список наименований и артикулов первых трех записей справочника Номенклатура, в которых наименование начинается со строки 'Таз'.
Для проверки будем использовать функцию startswith. Введем такой запрос:
GET ПрефиксURL/Catalog_Номенклатура?$format=json&$filter=startswith(НаименованиеПолное,'Таз')&$select=НаименованиеПолное,Артикул&$top=3
Должен быть выдан примерно такой ответ:
{
"odata.metadata": "https://1cfresh.com:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_Номенклатура",
"value": [
{
"НаименованиеПолное": "Таз пластмассовый овальный с ручками (\"POBEDA\"), 25 л",
"Артикул": "8940"
},
{
"НаименованиеПолное": "Таз пластмассовый овальный с ручками (\"POBEDA\"), 35 л",
"Артикул": "8941"
},
{
"НаименованиеПолное": "Таз пластмассовый овальный с ручками (\"POBEDA\"), 55 л",
"Артикул": "8942"
}
]
}
Посмотрим, как устроена запись справочника Сотрудники:
GET ПрефиксURL/Catalog_Сотрудники?$format=json&$top=1
Должен быть выдан примерно такой ответ:
{
"odata.metadata": "https://1cfresh.com: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')/Физлицо",
"СчетРасчетовСПерсоналом@navigationLinkUrl": "Catalog_Сотрудники(guid'baebacef-b80e-11e4-826f-001e101fe696')/СчетРасчетовСПерсоналом",
"СчетРасчетовСПодотчетниками@navigationLinkUrl": "Catalog_Сотрудники(guid'baebacef-b80e-11e4-826f-001e101fe696')/СчетРасчетовСПодотчетниками",
"СчетРасчетовПоПерерасходу@navigationLinkUrl": "Catalog_Сотрудники(guid'baebacef-b80e-11e4-826f-001e101fe696')/СчетРасчетовПоПерерасходу"
}
]
}
Как видно, в этой записи есть реквизит Физлицо_Key. Это ссылка на запись справочника ФизическиеЛица. Попросим включить эту запись в ответ интерфейса OData. Для этого добавим к запросу параметр $expand=Физлицо. Введем запрос:
GET ПрефиксURL/Catalog_Сотрудники??$format=json&$top=1&$expand=Физлицо
Должен быть выдан примерно такой ответ:
{
"odata.metadata": "https://1cfresh.com: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')/СчетРасчетовПоПерерасходу"
}
]
}
Пусть нам нужны только ФИО, код, тип занятости, дата рождения и пол сотрудника. Переформулируем запрос так, чтобы получать только эту информацию. Для этого добавим в запрос параметр:
$expand=Физлицо&$select=Description,Code,ТипЗанятости,Физлицо/Пол,Физлицо/ДатаРождения
Так как реквизиты Пол и ДатаРождения входят в подчиненный объект Физлицо, то они указываются в параметре $select как Физлицо/Пол и Физлицо/ДатаРождения. Получается следующий запрос:
GET ПрефиксURL/Catalog_Сотрудники?$format=json&$top=1&$expand=Физлицо&$select=Description,Code,ТипЗанятости,Физлицо/Пол,Физлицо/ДатаРождения
Должен быть выдан примерно такой ответ:
{
"odata.metadata": "https://1cfresh.com: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"
}
}
]
}
Упорядочим записи справочника Сотрудники по реквизитам Тип занятости и Code, и выведем значения реквизитов Тип занятости, Code и Description для первых 3 записей упорядоченного списка. Для упорядочения записей в запросе нужно указать параметр $orderby=ТипЗанятости desc,Code:
GET ПрефиксURL/Catalog_Сотрудники?$format=json&$orderby=ТипЗанятости desc,Code&$select=Description,Code,ТипЗанятости&$top=3
Должен быть выдан примерно такой ответ:
{
"odata.metadata": "https://1cfresh.com:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_Сотрудники",
"value": [
{
"Description": "Администратор",
"Code": "",
"ТипЗанятости": "ОсновноеМестоРаботы"
},
{
"Description": "Абдулов Юрий Владимирович",
"Code": "В-01",
"ТипЗанятости": "ОсновноеМестоРаботы"
},
{
"Description": "Абнагимова Ирина Витальевна",
"Code": "В-02",
"ТипЗанятости": "ОсновноеМестоРаботы"
}
]
}
Пусть нам нужно получить сведения о сотрудниках, упорядоченные по полу, типу занятости и коду. Пол сотрудника хранится в подчиненном объекте Физлицо. Поэтому в запрос нужно включить:
Получается запрос следующего вида:
GET ПрефиксURL/Catalog_Сотрудники?$format=json&$expand=Физлицо&$select=Description,Code,ТипЗанятости,Физлицо/Пол&$orderby=Физлицо/Пол,Code,Description&$top=3
Должен быть выдан примерно такой ответ:
{
"odata.metadata": "https://1cfresh.com: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')/Физлицо",
"Физлицо": {
"Пол": "Мужской"
}
}
]
}
С помощью стандартного интерфейса OData можно не только получать списки объектов, но также читать, изменять, создавать и удалять отдельные объекты. Покажем эти действия на примерах.
Получим запись справочника ФизическиеЛица с ключом baebad03-b80e-11e4-826f-001e101fe696:
GET ПрефиксURL/Catalog_ФизическиеЛица(guid'baebad03-b80e-11e4-826f-001e101fe696')?$format=json
Должен быть выдан примерно такой ответ:
{
"odata.metadata": "https://1cfresh.com: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
}
Получим ту же запись справочника, но выведем только ФИО, пол и дату рождения. Для этого нужно добавить в запрос параметр $select=Description,Пол,ДатаРождения
:
GET ПрефиксURL/Catalog_ФизическиеЛица(guid'baebad03-b80e-11e4-826f-001e101fe696')?$format=json&$select=Description,Пол,ДатаРождения
Должен быть выдан примерно такой ответ:
{
"odata.metadata": "https://1cfresh.com:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_ФизическиеЛица/@Element",
"Description": "Аввакумов Вадим Иванович",
"ДатаРождения": "1966-06-04T00:00:00",
"Пол": "Мужской"
}
При получении одной записи справочника нельзя сразу же раскрыть содержимое подчиненных объектов с помощью оператора $expand. Как было сказано ранее, этот оператор применим только при получении списка элементов. Если требуется получить ФИО, код, тип занятости, дату рождения и пол конкретного сотрудника, то для этого придется выполнить два запроса. Первым запросом получаем ФИО, код, тип занятости сотрудника из записи справочника Сотрудники:
GET ПрефиксURL/Catalog_Сотрудники(guid'baebacfa-b80e-11e4-826f-001e101fe696')?$format=json&$select=Description,Code,ТипЗанятости
Должен быть выдан примерно такой ответ:
{
"odata.metadata": "https://1cfresh.com: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://1cfresh.com:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Catalog_ФизическиеЛица/@Element",
"Пол": "Мужской",
"ДатаРождения": "1966-06-04T00:00:00"
}
Исправим данные записи справочника ФизическиеЛица, которую мы получили в разделе 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://1cfresh.com: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=",
"СтраховойНомерПФР": ""
}
Как видно, результат запроса — это исправленная запись справочника ФизическиеЛица. Реквизиты ИНН и ДатаРождения в ней получили новые значения.
При желании можно вывести карточку этого физического лица в приложении (меню Персонал — Физические лица), и убедиться, что в карточке показаны исправленные значения реквизитов ИНН и Дата рождения.
Добавим в справочник ФизическиеЛица новую запись. Для этого можно использовать 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://1cfresh.com: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
}
Как видно, результат запроса содержит сведения о добавленной записи справочника ФизическиеЛица.
При желании можно вывести в приложении форму справочника ФизическиеЛица (меню Персонал — Физические лица) и убедиться, что в справочнике имеется добавленная запись.
Удалим созданную запись из справочника ФизическиеЛица. Для этого можно использовать DELETE-запрос:
DELETE ПрефиксURL/Catalog_ФизическиеЛица(guid'1683a3cc-44e5-11ed-8d7b-005056892602')
В запросе указывается ключ (guid) той записи, которую нужно удалить.
Ответ на запрос будет с HTTP-кодом состояния 204 No content и пустым телом. При желании можно вывести в приложении форму справочника ФизическиеЛица и убедиться, что запись удалена из справочника.
Внимание. Следует иметь в виду, что при удалении объектов посредством стандартного интерфейса OData пометка на удаление не выполняется, а объект удаляется непосредственно.
Стандартный интерфейс OData содержит специальные средства для работы с табличными частями документов, справочников, задач и бизнес-процессов. Покажем их использование на примерах.
Покажем пример применения функции 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://1cfresh.com: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"
}
]
}
В OData-запросе можно вывести список табличных частей объектов. Предположим, что мы хотим получить список типов и представлений контактной информации для записей справочника Организации. Для этого можно использовать следующий запрос:
GET ПрефиксURL/Catalog_Организации_КонтактнаяИнформация/?$format=json&$top=5&$select=Тип,Представление
Здесь мы запросили сведения только о 5 первых строках табличных частей (параметр $top=5). Должен быть выдан примерно такой ответ:
{
"odata.metadata": "https://1cfresh.com: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_Организации_КонтактнаяИнформация.
В OData-запросе к табличной части можно задать условие отбора. Предположим, что мы заметили неточность в электронной почте assol@mail.ru. Получим все сведения строки табличной части, в которой указана эта электронная почта. Для этого можно использовать следующий запрос:
GET ПрефиксURL/Catalog_Организации_КонтактнаяИнформация/?$format=json&$filter=Представление eq 'assol@mail.ru'
Должен быть выдан примерно такой ответ:
{
"odata.metadata": "https://1cfresh.com: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)/ВидДляСписка"
}
]
}
Для показа табличной части объекта можно задать параметр $select=имя-табличной-части. Например, для показа табличной части Запасы документа Доверенность с guid 98043082-f588-11e5-98a6-bcaec5b897eb можно использовать следующий запрос:
GET ПрефиксURL/Document_Доверенность(guid'98043082-f588-11e5-98a6-bcaec5b897eb')/?$format=json&$select=Запасы
Должен быть выдан примерно такой ответ:
{
"odata.metadata": "https://1cfresh.com: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://1cfresh.com:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#Collection(StandardODATA.Document_Доверенность_Запасы_RowType)",
"value": [
{
"LineNumber": "1",
"НаименованиеТовара": "Ручка",
"ЕдиницаИзмерения": "шт",
"Количество": 1
}
]
}
Для изменения табличной части объекта можно использовать 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-запросе нужно передать все данные табличной части, даже если меняется только один реквизит в одной строке.
В ответе будут выданы данные измененного документе Доверенность.
Для отдельных видов объектов предусмотрены методы, позволяющие выполнить действия с этими объектами (см. раздел 5.6.5). Покажем два примера:
Покажем возможность проведения и отмены проведения документа на примере документа ЗаказПокупателя. Создадим в приложении заказ покупателя (пункт меню Продажи — Заказы покупателя), например, скопировав один из имеющихся заказов.
Установим для нового заказа состояние Обсуждение КП и заполним дату отгрузки, иначе приложение не позволит провести документ. Сохраним документ, нажав кнопку Записать (не Провести и закрыть).
В приложении в списке заказов покупателя значок данного заказа должен выводиться без галочки, обозначающей, что документ проведен.
Теперь узнаем 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://1cfresh.com: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. Причину ошибки можно узнать, попробовав провести или отменить проведение документа интерактивно в приложении:
Покажем применение метода 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://1cfresh.com:443/a/sbm_demo/1962515/odata/standard.odata/$metadata#InformationRegister_КурсыВалют",
"value": [
{
"Курс": 57.413,
"Period": "2022-09-30T00:00:00"
}
]
}
Таким образом, значение курса валюты USD на 30 сентября 2022 г. — 57.413.
Раздел «Cтандартный интерфейс OData» в Руководстве разработчика 1С:Предприятия
Описание сущностей, предоставляемых через стандартный интерфейс OData
Использование сервиса OData для интеграции подсистемы Фреш с другими сервисами
Раздел «Автоматический REST-интерфейс (OData)» книги «Технологии интеграции «1С:Предприятия 8.3»
Пользовательская документация подсистемы «Интерфейс OData» Библиотеки стандартных подсистем