Синхронизация с веб-сервисом. Интеграция по OData

Введение

Comindware Platform поддерживает автоматический и ручной импорт и экспорт данных посредством подключения к внешнему OData-сервису.

Подробные сведения о формате данных OData см. в статье «URI Conventions (OData Version 2.0)» (официальное руководство по OData, английский язык).

Порядок настройки и использования интеграции с внешним сервисом посредством OData

1. Настройте подключение типа «Подключения REST и OData» — «Синхронизация с веб-сервисом».
2. Настройте конфигурацию интеграции для импорта или экспорта данных по OData.
3. Запустите синхронизацию с OData-сервисом.
4. Проверьте результат синхронизации и журналы интеграции.

Настройка конфигурации интеграции по OData

1. Настройте подключение к OData-сервису.
2. Откройте приложение из списка приложений.
3. На странице «Администрирование» приложения нажмите пункт «Интеграции» ‌.
4. В списке интеграций создайте или откройте имеющуюся интеграцию.

5. Настройте конфигурацию интеграции:

   • Параметры синхронизации
   • Параметры импорта данных
     • Постпроцессинг
   • Параметры экспорта данных

Настройка синхронизации

Настройте параметры на вкладке «Основные свойства».

• Включить — установите этот флажок, чтобы задействовать данную конфигурацию интеграции.
• Название — введите наглядное название конфигурации интеграции.
• Подключение по OData — выберите ранее созданное подключение к OData-сервису.
• Тип — выберите направление синхронизации данных:
  • Импорт — передача данных из OData-сервиса в приложение;
  • Экспорт — передача данных из приложения в OData-сервис.
• Шаблон записи — выберите шаблон, с которым будут синхронизироваться данные.
• Внешняя сущность — укажите таблицу (набор данных) в OData-сервисе, с которой будут синхронизироваться данные.
• Синхронизируемые объекты — выберите, следует ли импортировать все данные или только изменённые:
  • Все;
  • По изменению полей объекта.

• Режим запуска — выберите способ запуска синхронизации:

  • Вручную — для запуска синхронизации потребуется выбрать интеграцию в списке и нажать кнопку «Запустить синхронизацию».
  • По расписанию — настройте расписание автоматической синхронизации:
    • Первый запуск;
    • Периодичность;
    • Дни запуска;
    • Интервал запуска.

• Сопоставление данных — задайте соответствие атрибутов внешней сущности и атрибутов шаблона записи и укажите ключевой атрибут.

  Принцип сопоставления записей по ключевым атрибутам

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

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

  • при импорте запись в шаблоне будет обновлена данными из внешней сущности;
  • при экспорте запись во внешней сущности будет обновлена данными из шаблона;

  Если при синхронизации значения ключевых атрибутов не совпадут, будет создана новая запись:

  • в выбранном шаблоне — при импорте;
  • во внешней сущности — при экспорте.
  • В столбце «Внешний атрибут» квадратных скобках указаны свойства атрибутов:
    • [Primary key] — первичный ключ, по умолчанию выбран в качестве ключевого атрибута;
    • [Not null] — атрибуты, которые не могут быть пустыми (при экспорте данных необходимо установить соответствие всех внешних и внутренних атрибутов с данным свойством).

Настройка импорта данных

Если на вкладке «Основные свойства» выбран импорт данных, настройте параметры на вкладке «Настройки импорта»:

• Зависит от — укажите интеграцию, синхронизацию по которой необходимо запускать перед запуском синхронизации по данной интеграции. Это может быть необходимо, например, для того, чтобы предварительно обновить данные в связанных шаблонах, к которым требуется привязать синхронизируемые записи.

• Фильтр — задайте фильтр данных посредством выражений OData. Синтаксис фильтров см. в статье «Использование выражений фильтров в URI для OData» (учебник Microsoft, английский язык).

  Например, следующий фильтр выбирает записи с порядковым номером (SequenceNumber) от 11 до 14:

  SequenceNumber gt 10 and SequenceNumber lt 15 
  

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

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

• Динамический фильтр — настройте фильтрацию данных по дате и времени. Для этого укажите атрибут типа «Дата и время». Значение этого атрибута в импортируемых записях будет сравниваться с датой и временем отправки запроса на синхронизацию за вычетом интервала фильтра.

  • Интервал фильтра — интервал времени для динамической фильтрации. При выборке записей значение интервала фильтра вычитается из даты и времени отправки запроса на синхронизацию (в часовом поясе UTC+0).

  Логика работы динамического фильтра

  • Динамический фильтр позволяет импортировать только записи, относящиеся ко времени после определённой даты.
  • Пример
    • Для динамического фильтра выбран атрибут «Дата создания».
    • Интервал фильтра равен 1 д.
    • Синхронизация началась 05.01.2025 (в часовом поясе UTC+0).
    • Импортированы будут записи, у которых Дата создания больше или равна 04.01.2025.

• Удалить несуществующие записи — установите этот флажок, чтобы при синхронизации удалять записи, которые отсутствуют на внешнем сервере.

• Удалить по условию — укажите атрибуты и значения, чтобы при синхронизации удалять записи, соответствующие заданным условиям.

Настройка постпроцессинга

1. Нажмите кнопку «Добавить новую настройку постпроцессинга».

2. Настройте сопоставление атрибутов между шаблоном записи и OData-сервисом:

   • Целевой атрибут — выберите атрибут типа «Запись», связанный с шаблоном записи, выбранным на вкладке «Основные свойства».
   • Атрибут в выбранном шаблоне — выберите ключевой атрибут в шаблоне записи, выбранным на вкладке «Основные свойства» для синхронизации.
   • Атрибут в связанном шаблоне — выберите ключевой атрибут шаблона, связанного с целевым атрибутом.

Настройка экспорта данных

Если на вкладке «Основные свойства» выбран экспорт данных, настройте параметры на вкладке «Настройки экспорта»:

• Удалить записи после экспорта — установите этот флажок, чтобы при синхронизации удалять экспортированные записи.
• Экспортировать архивные записи — установите этот флажок, чтобы при синхронизации экспортировать архивные записи.
• Фильтр — укажите атрибуты и значения, чтобы при синхронизации экспортировать только записи, соответствующие заданному фильтру.

Запуск синхронизации посредством интеграции

1. Установите один или несколько флажков в списке интеграций.
2. Нажмите кнопку «Запустить синхронизацию».
3. Будет запущена синхронизация посредством выбранных интеграций.
4. Результаты синхронизации можно просмотреть в журналах интеграции.

Журналирование интеграции

Журнал событий

Журнал сеансов синхронизации посредством интеграций отображается на вкладке «Интеграция по OData» в разделе «Администрирование» — «Инфраструктура» — «Журналы событий».

Сведения в журнале «Интеграция по OData»

• Без ошибок — в этом столбце отображается флажок, если синхронизация выполнена без ошибок.
• Сеанс — идентификатор сеанса синхронизации.
• Событие — описание события синхронизации. Для просмотра цепочки событий, приведших к событию в журнале, дважды нажмите строку в журнале.
• Дата — дата запуска синхронизации.
• Подключение — подключение, использованное для синхронизации. Перейдите по этой гиперссылке для просмотра свойств подключения.
• Конфигурация — идентификатор конфигурации интеграции. Перейдите по этой гиперссылке для просмотра свойств интеграции.
• Инициатор — аккаунт, запустивший синхронизацию. Перейдите по этой гиперссылке для просмотра свойств аккаунта.

Файловый журнал

При синхронизации посредством интеграции соответствующие события записываются в файл журнала с именем вида: integration_raw_ГГГГ-ММ-ЧЧ.log.

При успешной синхронизации в этом файле будут указаны все синхронизированные объекты. При сбое синхронизации в файл записывается ИД записи, на которой была обнаружена ошибка, и описание ошибки.