Использование REST web-сервисов в "1C:Предприятии 8". Личный опыт.

Часть 1. Чтение данных

Описание
Подробнее

Описание

Использование REST web-сервисов в «1C:Предприятии 8». Личный опыт.

Когда мне понадобилось использовать REST сервисы в 1С, я столкнулся с «лаконичностью» имеющейся документации и минимумом реальных примеров. Данная статья основана, в первую очередь, на материалах фирмы 1С (http://its.1c.ru/db/metod8dev/content/3790/hdoc/_top/post и http://v8.1c.ru/o7/201312rest/ и https://wonderland.v8.1c.ru/blog/rasshirenie-podderzhki-protokola-odata/) и собственном опыте и призвана немного прояснить тему.

Итак, начнем сначала.

Что такое REST и зачем он нужен

REST (REpresentation State Transfer) подход является одним из наиболее популярных подходов, использующихся для реализации web-сервисов в Интернете. REST web-сервисы являются более легковесными альтернативами SOAP веб-сервисам.

REST с технической точки зрения не является ни технологией, ни стандартом. Это всего лишь подход, если можно так сказать, набор принципов, которые помогают реализовать «правильный» web-сервис. Под «правильным» здесь понимается масштабируемый, безопасный, надежный, легкий в использовании и т. д.

REST определяет следующие принципы построения web-сервисов:

Функциональность приложения делится на набор ресурсов. Каждый ресурс может выполнять определенное действие (REST ресурс является аналогом SOAP операции). Например, ресурс получения новостей выдает список заголовков текущих новостей;
Каждый ресурс имеет уникальный идентификатор (URL), по которому к нему можно обратиться как из программного кода, так и из Web-браузера;
Все ресурсы используют унифицированный интерфейс для передачи данных между клиентом и ресурсом. Интерфейс имеет ограниченный набор операций и типов данных для передачи. Как правило, в качестве транспорта используется инфраструктура HTTP, а набор операций, которые можно выполнить над ресурсом, определяется HTTP стандартом. Наиболее используемыми операциями могут быть: HTTP GET — получение данных от ресурса и HTTP POST отправка данных в ресурс. Также могут использоваться HTTP PUT, HTTP DELETE и т. д.;
REST протокол взаимодействия (RESTful) должен быть клиент-серверным и не иметь состояния.

Преимуществами REST подхода являются:

Возможность работы на уже существующей HTTP инфраструктуре — Web-серверах, Web-браузерах и др.
Простота использования и высокая совместимость между реализациями за счет того, что кодирование данных сведено к минимуму. Кодируются только прикладные данные (т. е. то, что нужно передать), вспомогательная маркировка данных (например, такая как soap:Envelope) не используется.
Хорошая масштабируемость, т. к. REST протоколы не поддерживают состояния между вызовами.
Хорошая безопасность, которая опять-таки основана на HTTP инфраструктуре.

Недостатки REST’а являются продолжением его достоинств:

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

Протокол, который основывается на принципах REST, является RESTful протоколом. Два наиболее популярных типа RESTful протоколов — это JSON (JavaScript Object Notation) и POX (Plain Old XML). JSON использует для кодирования данных JavaScript и в основном применяется в Ajax (Asynchronous JavaScript and XML) клиентах для обмена данными с сервером. Поскольку Ajax клиенты работают в браузере, который понимает JavaScript, то использование JavaScript позволяет сэкономить как на объеме передаваемых данных, так и на времени разбора данных. Однако использование JSON в других клиентах проблематично, т. к. клиенты, как правило, не поддерживают JavaScript.

POX использует для кодирования данных XML и поэтому может использоваться практически везде.

REST в 1С

Начиная с версии 8.3.5.1068. платформа может автоматически формировать REST интерфейс для всего прикладного решения. REST интерфейс позволяет читать данные 1С:Предприятия, изменять их, создавать новые объекты данных и удалять существующие. В качестве протокола доступа платформа использует протокол OData версии 3.0. Это открытый веб-протокол для запроса и обновления данных. Он позволяет оперировать данными, используя в качестве запросов HTTP-команды. Получать ответы можно в различных форматах, но пока платформа поддерживает только работу с данными в формате Atom/XML.

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

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

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

и указать доступные объекты конфигурации:

Чтение данных через REST

Чтение данных выполняется GET-запросом. Сначала устанавливаем HTTPСоединение с базой. Потом формируем текст запроса. Например, получение списка УИДов элементов справочника Контрагенты выглядит так:

/Base1C/odata/standard.odata/Catalog_Контрагенты?$select=Ref_Key&$format=json;odata=nometadata

Что означает это заклинание?

«Base1C» — имя базы, как оно опубликовано на веб-сервере,

«odata/standard.odata» — «магическое» слово, означающее доступ через odata интерфейс

«Catalog_Контрагенты» — состоит из указания на тип объекта «Catalog» — справочник и типа справочника

«select» — оператор чтения данных, после него через «=» идет описание считываемых данных, в данном случае это «Ref_Key» — уникальный идентификатор

«format=json» — задает формат представления считываемых данных JSON

«odata=nometadata» — заклинание, указывающее не передавать в ответе описание метаданных.

Из текста запроса создаем объект HTTPЗапрос:

Запрос = Новый HTTPЗапрос(СтрокаЗапроса);

и отправляем его:

Ответ = HTTPсоединение.Получить(Запрос);

Полученный объект HTTPОтвет надо разобрать, удобнее анализировать строку:

ОтветСтрокой = Ответ.ПолучитьТелоКакСтроку();

Если все хорошо, в ОтветСтрокой находится что-то вроде:

{

«value»: [{

«Ref_Key»: «a913b5c7-9594-4680-8013-e6a8ff2ef33e»

},{

«Ref_Key»: «e29427d9-9cbb-421d-8089-e9859b2427c3»

},{

}

Разобрать ответ можно например так:

		Если Ответ.КодСостояния > 299 Тогда
			ТекстОшибки = "Error, код ошибки: " + Ответ.КодСостояния + "
						|" + ОтветСтрокой;
			
		Иначе
			
			КолСтрок = СтрЧислоСтрок(ОтветСтрокой);
			
			Для НомерСтроки=1 По КолСтрок Цикл
				
				СтрокаАнализа = СтрПолучитьСтроку(ОтветСтрокой, НомерСтроки);
				Если СтрНайти(СтрокаАнализа,"Ref_Key") > 0 Тогда
					ПозицияДо = СтрНайти(СтрокаАнализа, """",НаправлениеПоиска.СКонца);
					ПозицияС = СтрНайти(СтрокаАнализа, """Ref_Key"": """);
					Если (ПозицияС > 0) И (ПозицияДо = (ПозицияС + 48))  Тогда
						НачалоID = ПозицияС + 12;
						GUID = Сред(СтрокаАнализа, НачалоID, 36);
						РезультатМассив.Добавить(GUID);
					КонецЕсли;
					
				КонецЕсли;
				
			КонецЦикла;
			
			БулевРезФун = Истина;
			ТекстОшибки = "OK. Считано элементов: " + Формат(РезультатМассив.Количество(), "ЧН=0; ЧГ=");
			
		КонецЕсли;

Если нужно получить не один реквизит, текст запроса выглядит так:

/Base1C/odata/standard.odata/Catalog_Контрагенты?$select=Ref_Key,Description &$format=json;odata=nometadata

нужные поля добавляются через запятую в select.

Как правило все записи справочника читать не требуется, используем оператор filter:

СтрокаЗапроса = СтрокаЗапроса + «&$filter=Ref_Key eq guid'» + KeyID + «‘»;

где в KeyID строковое представление УИД

Наименование реквизитов как видите порой неочевидно. Необходимо запомнить:

Code — код,

DeletionMark — пометка удаления,

IsFolder — признак группы,

Parent_Key — родитель.

Если реквизит ссылочного типа, к его имени следует добавить суффикс _Key, например Организация_Key.

Для документов используется схожий синтаксис:

/Base1C/odata/standard.odata/Document_СчетНаОплатуПокупателю?$select=Ref_Key, Number, Date&$format=json;odata=nometadata

Для документов:

Number — номер документа,

Date — дата документа.

Создание и изменения объектов через REST будет в следующей части.

Каталог решений - Использование REST web-сервисов в "1C:Предприятии 8". Личный опыт.