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

Примером обработки для эмуляции синхронизации является обработка ИнтеграцияОбъектовОбластейДанных.epf, встроенная в конфигурацию 1cv8_service.cf из дистрибутива Библиотеки технологии сервиса.

Получение данных из приложения

  1. Запрос – получатель запрашивает для себя изменения
  2. Ожидание – получатель проверяет готовность запрошенных данных
  3. Получение – получатель загружает данные к себе
  4. Подтверждение – получатель обрабатывает данные и подтверждает, что изменения загружены и обработаны.
Внешнее приложение
Внешнее приложение
Приложение
в облаке 1С:Фреш
Приложение...
POST
get
POST...
Транспорт
/hs/dt/storage/
Транспорт /hs/dt/storage/
integration/get
integration/get
jobs/{id}
jobs/{id}
files/{id}
files/{id}
Очистка инфомрации
по изменениям
Очистка инфомрации...
integration/confirm
integration/confirm
Очередь
заданий
Очередь заданий
Подготовленные
данные
Подготовленные данные
Изменения
Изменения
Подготовка
данных
Подготовка данных
Обработчик
подтверждения
Обработчик подтверждения
Даные
пользователя
Даные пользователя
1 Запрос
1 Запрос
2 Ожидание
2 Ожидание
3 Получение
3 Получение
4 Подтверждение
4 Подтверждение
POST
confirm
POST...
GET
GET
GET
GET
Облачная подсистема
Облачная подсистема
Прикладное решение
Прикладное решение
Обработчик
внешнего
приложения
Обработчиквнешнегоприложения...
Получение данных
Получение данных
Запрос
данных
Запрос данных
Text is not SVG - cannot display

Отправка данных в приложение

  1. Отправитель формирует пакет данных и отправляет файл данных для обработки
  2. Отправитель ожидает завершения обработки данных
POST
post
POST...
GET
GET
Транспорт
/hs/dt/storage/
Транспорт /hs/dt/storage/
Очередь
заданий
Очередь...
 integration/post
 integration/post
Данные
пользователя
Данные пользователя
Обработчик
данных
Обработчик...
jobs/{id}
jobs/{id}
Файловое
хранилище
Файловое...
Внешнее
приложение
Внешнее приложение
Приложение
в облаке 1С:Фреш
Приложение...
1 Отправка
1 Отправка
2 Ожидание
2 Ожидание
Отправка данных
Отправка данных
Облачная подсистема
Облачная подсистема
Прикладное решение
Прикладное решение
Обработчик
внешнего
приложения
Обработчиквнешнегоприложения...
Данные
Данные
Text is not SVG - cannot display


Отправка оповещений из приложения 1С в приложение провайдера

  1. Приложение отправляет оповещение в приложение провайдера при изменении данных
  2. Приложение провайдера забирает изменения
  3. Приложение провайдера подтверждает изменения


Внешнее
приложение
Внешнее приложение
Приложение
в облаке1С:Фреш
Приложение в облаке1С:Фреш
Транспорт
/hs/dt/storage/
Транспорт /hs/dt/storage/
Файловое
хранилище
Файловое...
Данные пользователя
Данные пользователя
Изменения
Изменения
files/{id}
files/{id}
integration/confirm
integration/confirm
GET
GET
POST
confirm
POST...
Очистка информации
по изменениям
Очистка информации...
Обработчик
подтверждения
Обработчик подтверждения
1 Оповещение
1 Оповещение
3 Подтверждение
3 Подтверждение
Оповещение об изменении
Оповещение об изменении
2 Получение
2 Получение
Подготовка
данных
Подготовка...
Облачная подсистема
Облачная подсистема
Прикладное решение
Прикладное решение
 Оповещение об изменении (POST) 
 Оповещение об изменении (POST) 
Запрос
данных
Запрос...
Обработчик
внешнего
приложения
Обработчиквнешнегоприложения...
Text is not SVG - cannot display

Отправка команд в приложение

В прикладном решении может быть реализован механизм обработки команд от внешней учетной системы. 

Примеры команд:

  • Создание объектов (документов, справочников)
  • Выполнение расчетов

Если в процессе выполнения команды был создан объект, то информация о нем будет возвращена в результате на 2-м шаге.

Программный интерфейс подсистемы

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

  • Пароль - Строка - пароль аутентификации в сервисе приема оповещений (используется при basic-аутентификации)
  • ПарольСертификата - Строка - пароль сертификата (используется, если задано свойство ИспользоватьСертификат);
  • ДанныеСертификата - ДвоичныеДанные - двоичные данные сертификата в Base64 (используется, если задано свойство ИспользоватьСертификат )
  • КлючПодписи - Строка - секретное слово, для подписи отправляемых данных. Подпись выполняется с помощью алгоритма HMACSHA256.

Также этот тип определяет:

  • разрез хранения объектов к отправке в регистре сведений  ОбъектыКОтправке .
  • хранение настроек учетных систем в регистре сведений НастройкиУчетныхСистем .

В регистре сведений НастройкиУчетныхСистем  хранятся настройки для определения учетной системы и для отправки оповещений.

  • Пользователь - СправочникСсылка.Пользователи - для определения учетной системы по авторизованному пользователю при обращении к API.
  • ОповещатьОбИзменениях - Булево - признак использования оповещений при создании/изменении данных в приложении
  • АдресСервиса - Строка - адрес сервиса приема оповещений об изменениях
  • СпособАутентификации - ПеречислениеСсылка.СпособыАутентификации - способ аутентификации в сервисе приема оповещений
  • Логин - Строка - логин аутентификации в сервисе приема оповещений (используется при basic-аутентификации)
  • ИспользоватьСертификат - Булево - признак использования сертификата при установке соединения с сервисом приема оповещений
  • ИмяСертификата - Строка - имя файла сертификата
  • ПодписыватьДанные - Булево - признак использования подписи данных при отправке их в сервис приема оповещений

Интерфейс объектного хранилища

Методы интерфейса объектного хранилища для DataTransfer.

  1. Описание - метод не поддерживается
  2. Данные - метод не поддерживается
  3. Загрузить - основной метод работы с объектным хранилищем интеграции объектов.

Поддерживаются идентификаторы данных для метода Загрузить:

  1. setup - для установки настроек учетной системы
  2. get - для получения данных из приложения
  3. post - для добавления данных в приложение
  4. confirm - для подтверждения получения данных от приложения
  5. execute для отправки команды на выполнение действий

Методы программного интерфейса подсистемы

Находятся в общем модуле ИнтеграцияОбъектовОбластейДанных

Процедура ДобавитьОбъектКОтправке

Позволяет добавить объект к отправке во внешнюю учетную систему.

Параметры метода:

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

Процедура УдалитьОбъектКОтправке

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

  • УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных - учетная система.
  • ИдентификаторОбъекта - Строка - идентификатор объекта
  • Обработчик - Строка - идентификатор обработчика объекта.

Функция ОповеститьОбИзмененииОбъекта

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

  • УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных - учетная система.
  • ИдентификаторОбъекта - Строка - идентификатор объекта
  • ВызыватьИсключение - Булево - признак вызова исключения при неудачной отправке оповещения.

Функция Настройки

Возвращает настройки учетной системы.
Параметры метода:

  • УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных - учетная система.
  • КлючиНастроек - Строка, Массив - ключи настроек, по которым нужно вернуть значения.

Функция НовыйРезультатыВыполненияКоманды

Возвращает шаблон для помещения результатов выполнения команды.

Возвращаемое значение:

  • ТаблицаЗначений - шаблон выполнения команды для возврата результатов. Содержит колонки:
    • ИдентификаторОбъекта - Строка - идентификатор объекта.
    • Обработчик - Строка - идентификатор обработчика.

Методы, возвращающие коды возврата по имени

Могут использоваться в коде учетной системы при выполнении обработки или подготовки данных, а также при обработке подтверждений.
Находятся в общем модуле ИнтеграцияОбъектовОбластейДанныхСловарь.

  • КодВозвратаОшибкаДанных - возвращает число 10400
  • КодВозвратаВнутренняяОшибка - возвращает число 10500
  • КодВозвратаВыполненоСПредупреждениями - возвращает число 10240
  • КодВозвратаВыполнено - возвращает число 10200
  • КодВозвратаНеНайдено - возвращает число 10404

Возвращаемое значение

  • Число - стандартный код возврата по имени метода

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

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

  • ОбластьДанныхВспомогательныеДанные = Автоматически
  • ОбластьДанныхОсновныеДанные = Автоматически

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

Процедура УстановитьНастройки

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

  • УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных
  • ПотокДанных - ФайловыйПоток, ПотокВПамяти - данные настроек (передаются в формате json)
  • КодВозврата - Число - код возврата обработчика установки настроек (по умолчанию - 10200).
  • Ошибка - Булево - признак ошибки (по умолчанию - Ложь)
  • СообщениеОбОшибке - Строка - подробности ошибки (по умолчанию не заполнено).
  • СтандартнаяОбработка - Булево - признак стандартной обработки.

Процедура  УстановитьПраваДоступа

Устанавливает права пользователя, от имени которого обращается внешняя учетная система.

Параметры метода:

  • УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных - учетная система.
  • Пользователь - СправочникСсылка.Пользователи - пользователь, от имени которого обращается внешняя учетная система.

Установка прав доступа должна быть определена прикладным разработчиком в соответствии с используемой ролевой моделью.
Для работы интеграции объектов пользователю нужно предоставить роль УдаленныйДоступПередачаДанных.

Функция ТипУчетнойСистемы

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

Функция ДанныеОбъекта

Возвращает двоичные данныеобъекта, которые будут переданы в составе zip-архива во внешнюю учетную систему.
Параметры:

  • УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных
  • ИдентификаторОбъекта - Строка - идентификатор объекта.
  • Обработчик - Строка - обработчик данных объекта.

Возвращаемое значение:

  • ДвоичныеДанные - данные объекта.

Процедура ОбработатьПодтверждения

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

  • УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных
  • Подтверждения - Соответствие
    • Ключ - Строка - это идентификатор объекта
    • Значение - Структура
      • Версия - Строка - версия объекта
      • КодВозврата - Число - код возврата, определяется во внешней учетной системе. Рекомендуемые коды возврата см. модуле ИнтеграцияОбъектовОбластейДанныхСловарь
      • Ошибка - Булево - признак ошибки (по умолчанию - Ложь)
      • СообщениеОбОшибке - Строка - подробности ошибки (по умолчанию не заполнено)
  • СтандартнаяОбработка - Булево - признак стандартной обработки. Если Ложь, то у обработанные объекты не будут удалены из списка объектов к отправке.

Функция ОбработатьДанные

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

  • УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных - учетная система.
  • ИдентификаторОбъекта - Строка - идентификатор объекта для обработка
  • ПотокДанных - ФайловыйПоток, ПотокВПамяти - данные объекта
  • Обработчик - Строка - идентификатор обработчика
  • КодВозврата - Число - код возврата обработчика (по умолчанию - 10200)
  • Ошибка - Булево - признак ошибки (по умолчанию - Ложь)
  • СообщениеОбОшибке - Строка - подробности ошибки (по умолчанию не заполнено).

Функция ВыполнитьКоманду

Обработчик выполнения команды от учетной системы.
Параметры:

  • УчетнаяСистема - ОпределяемыйТип.УчетныеСистемыИнтеграцииОбластейДанных - учетная система.
  • ПотокДанныхКоманды - ФайловыйПоток, ПотокВПамяти - данные команды.
  • КодВозврата - Число - код возврата обработчика (по умолчанию - 10200)
  • Ошибка - Булево - признак ошибки (по умолчанию - Ложь)
  • СообщениеОбОшибке - Строка - подробности ошибки (по умолчанию не заполнено).

Возвращаемое значение:

  • Неопределено - если не подразумевается создание объектов, или в процессе выполнения произошла ошибка.

или

  • ТаблицаЗначений - результаты выполнения команды, информация о созданных или измененных объектах (см. ИнтеграцияОбъектовОбластейДанных.НовыйРезультатыВыполненияКоманды).

Собственные прикладные методы

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