Введение

Comindware Platform может получать и обрабатывать HTTP-запросы из внешних систем с помощью сценариев.

Здесь представлен пример настройки подключения, пути передачи данных и сценария для получения и обработки HTTP-запроса в формате JSON с использованием C#-скриптов и записи данных в атрибуты шаблона записи.

Настройка для обработки данных в формате XML и простого текста будет аналогичной.

См. также «HTTP-запросы с составным содержимым. Получение файлов в сценарии»

Прикладная задача

Требуется получить заказ из внешней системы, создать заказ с позициями в Comindware Platform и отправить ответ с датой создания заказа и массивом статусов позиций: Принята или Отклонена.

Рассмотрим настройку получения запросов от сервера и обработку данных с помощью C#-скрипта.

• Имеются шаблоны записей:
  • «Заказы» с атрибутами:
    • «Номер заказа» типа «Текст»;
    • «Позиции» типа «Запись», ссылается на шаблон «Позиции заказов» и хранит несколько значений.
  • «Позиции заказов» с атрибутами:
    • Товар типа «Текст»;
    • Количество типа «Число».

• Внешний сервер отправляет в Comindware Platform HTTP-запросы с данными в формате JSON следующего вида:

  { 
      "orderNumber": "string", 
      "items": [ 
          { 
              "product": "string", 
              "quantity": "int" 
          } 
      ] 
  } 
  

• Сценарий выполняет следующие операции:

  • получает HTTP-запрос от внешнего сервера;
  • с помощью C#-скрипта обрабатывает полученные данные, создаёт позиции и заказ;
  • с помощью C#-скрипта формирует ответ для отправки обратно во внешнюю систему с массивом позиций и их статусами.
  • отправляет JSON-ответ следующего вида:

  { 
      "date": "dateTime", 
      "items": [ 
          { 
              "product": "string", 
              "status": "string" 
          } 
      ] 
  } 
  

Порядок настройки получения HTTP-запросов

1. Настройте подключение для получения HTTP-запросов.
2. Настройте путь передачи данных для получения HTTP-запросов.
3. Настройте сценарий для обработки входящих HTTP-запросов.
4. Проверьте работоспособность настроенной конфигурации.

Настройка подключения

1. На странице «Администрирование» выберите пункт «Инфраструктура» — «Подключения» .
2. Откройте или создайте подключение типа «Подключения REST и OData» — «Получение HTTP-запросов».

3. Настройте подключение к Comindware Platform для внешних систем:

   • Путь URI — введите суффикс, соответствующий назначению подключения, например orders.

   При необходимости введите дополнительный путь URI на вкладке «Интеграция» в свойствах пути передачи данных, например place.

   Укажите результирующий путь (базовый путь получения HTTP-запросов + путь URI из подключения + путь URI из пути передачи данных) на внешнем сервере в качестве получателя запросов, например:

   ``` 
   https://<hostname>/api/public/adapter/orders/place 
   ``` 
   

   • Формат данных — выберите JSON для использования в данном примере.

4. Остальные параметры настройте согласно своим бизнес-требованиям.

5. Сохраните подключение.

Настройка пути передачи данных

1. Откройте страницу «Администрирование» — «Архитектура» или страницу «Администрирование» приложения.
2. Выберите пункт «Пути передачи данных» ‌.
3. Откройте или создайте путь передачи данных типа «Подключения REST и OData» — «Получение HTTP-запросов».

4. Настройте свойства пути передачи данных на следующих вкладках:

   • Основные свойства
   • Атрибуты сообщений
   • Интеграция

5. Сохраните путь передачи данных.

Основные свойства

На вкладке «Основные свойства» настройте параметры использования пути передачи данных:

• Подключение — выберите подключение для получения HTTP-запросов.
• Системное имя — введите уникальное имя пути передачи данных.
• Отключить — установите этот флажок, если требуется временно деактивировать путь передачи данных.
• Описание — введите наглядное описание пути передачи данных, например «Получение заказов по HTTP».
• Номер шины данных — выберите номер от 0 до 3, если требуется распределить потоки данных нескольких путей для повышения производительности.

Атрибуты сообщений

1. Выберите тип сообщения «Обработка HTTP-запросов».

2. В таблице «Запрос» воссоздайте структуру JSON входящего запроса, добавив следующие атрибуты:

   • orderNumber типа «Строка» — номер заказа.
   • items типа «Объект»:
     • items типа «Объект»:
     • Установите флажок «Массив» — атрибут items будет содержать массив позиций.
     • Установите флажок слева от атрибута items и добавьте в него дочерние атрибуты:
       • product типа «Строка» — название товара.
       • quantity типа «Число» — количество товара.

   В эти атрибуты будут передаваться данные позиций для обработки.

   Системные имена этих атрибутов должны совпадать с именами соответствующих полей HTTP-запроса.

3. В таблице «Ответ» составьте структуру атрибутов для ответа в случае успешной обработки заказа:

   • data типа «Дата/время» — дата и время обработки заказа.
   • items типа «Объект»:
   • Установите флажок «Массив» — атрибут items будет содержать массив статусов позиций.
   • Установите флажок слева от атрибута items и добавьте в него дочерние атрибуты:
     • product типа «Строка» — название товара.
     • status типа «Строка» — статус позиции.

   

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

Интеграция

1. При необходимости укажите дополнительный суффикс в поле «Путь URI», например place. Этот суффикс будет добавлен к URL-адресу, настроеннjve в подключении.

   Укажите результирующий путь (базовый путь получения HTTP-запросов + путь URI из подключения + путь URI из пути передачи данных) на внешнем сервере в качестве получателя запросов, например:

   https://<hostname>/api/public/adapter/orders/place 
   

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

3. При необходимости укажите атрибут для заголовков, в котором будут содержаться все атрибуты заголовков запроса, атрибут для параметров запроса, в котором будут содержаться все параметры запроса, и атрибут для тела запроса, в котором будет содержаться всё тело запроса.

   

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

1. Создайте новый сценарий «Обработка заказов».

2. У начального события измените тип на «Получение сообщения» и настройте его:

   • Контекстный шаблон: Заказы
   • Подключение: подключение для получения HTTP-запросов
   • Путь передачи данных: путь передачи данных для получения HTTP-запросов
   • Имя переменной: IncomingMessage

   

3. После события «Получение сообщения» добавьте действие «Проверить результат скрипта» для обработки входящего сообщения и подготовки ответа с помощью C#-скрипта:

   • Сообщение об ошибке — введите текст сообщения, которое будет отображено, если скрипт вернёт false (например, «Ошибка»).

     Скрипт должен возвращать true. Если скрипт вернёт false, сценарий будет остановлен.

   • Выражение — задайте C#-скрипт для обработки входящего сообщения по следующему образцу:

   using System; 
   using System.Collections.Generic; 
   using System.Linq; 
   using Comindware.Data.Entity; 
   using Comindware.TeamNetwork.Api.Data.UserCommands; 
   using Comindware.TeamNetwork.Api.Data; 
    
   class Script 
   { 
       public static bool Main(Object o) 
       { 
           // Получаем входящее сообщение. 
           // IncomingRootMessage – класс сообщения (структура данных) 
           // Имя RawIncomingMessage состоит из двух частей: 
           // 1. Raw – неизменный системный префикс 
           // 2. IncomingMessage – имя переменной с сообщением, заданной в событии «Получение сообщения» 
           var input = Api.Base.LocalVariablesService.Get<IncomingRootMessage>("RawIncomingMessage"); 
    
           // Объявляем списки для хранения идентификаторов созданных позиций и данных для ответа 
           var newItems = new List<string>(); 
           var itemsStatus = new List<ItemStatus>(); 
    
           // Обрабатываем каждую позицию из входящего запроса 
           foreach(var item in input.items) 
           { 
               // Создаём позицию в системе 
               // ПозицииЗаказов – системное имя шаблона записи 
               // Товар, Количество – системные имена атрибутов шаблона «Позиции заказов» 
               var itemId = Api.TeamNetwork.ObjectService.CreateWithAlias("ПозицииЗаказов", new Dictionary<string,object>{{"Товар", item.product},{"Количество", item.quantity}}); 
               newItems.Add(itemId); 
    
               // Формируем данные для ответа со статусом позиции 
               itemsStatus.Add(new ItemStatus{product = item.product, status = "Принята"}); 
           } 
    
           // Создаём заказ в системе 
           // Заказы — системное имя шаблона записи 
           // НомерЗаказа, Позиции — системные имена атрибутов шаблона «Заказы» 
           Api.TeamNetwork.ObjectService.CreateWithAlias("Заказы", new Dictionary<string,object>{{"НомерЗаказа", input.name},{"Позиции", newItems}}); 
    
           // Формируем корневой объект ответа 
           // OutgoingRootMessage – класс сообщения (структура данных) 
           var outgoingMessage = new OutgoingRootMessage 
           { 
               data = DateTime.Now, 
               items = itemsStatus 
           }; 
    
           // Проставляем в локальную переменную значение для последующей отправки 
           // Имя RawReplyIncomingMessage состоит из двух частей: 
           // 1. Raw — неизменный системный префикс 
           // 2. ReplyIncomingMessage — имя переменной, заданной в настройках события «Получение сообщения» 
           // Ответ будет отправлен только после выполнения всего сценария 
           Api.Base.LocalVariablesService.Set<OutgoingRootMessage>("RawReplyIncomingMessage", outgoingMessage); 
    
           return true; 
       } 
   } 
    
   public class IncomingRootMessage 
   { 
       public string name {get; set;} 
       public List<Item> items {get; set;} 
   } 
    
   public class Item 
   { 
       public string product {get; set;} 
       public int quantity {get; set;} 
   } 
    
   public class OutgoingRootMessage 
   { 
       public DateTime data {get; set;} 
       public List<ItemStatus> items {get;set;} 
   } 
    
   public class ItemStatus 
   { 
       public string product {get;set;} 
       public string status {get;set;} 
   } 
   

4. Результирующий сценарий должен выглядеть, как показано на следующей иллюстрации.

   

5. Проверьте работу приложения.

Тестирование

Сценарий должен получать HTTP-запрос с данными заказов, обрабатывать их с помощью C#-скрипта, создавать позиции и заказ, а также формировать ответ с массивом позиций и их статусами.

1. С внешнего сервера отправьте в Comindware Platform запрос с данными заказов, например:

   curl -X POST \ 
       -u username:password \ 
       -H "Content-Type: application/json" \ 
       -d '{ 
           "orderNumber": "Заказ №1", 
           "items": [ 
               { 
                   "product": "Бумага", 
                   "quantity": 2 
               }, 
               { 
                   "product": "Картридж", 
                   "quantity": 1 
               } 
           ] 
       }' \ 
       https://<hostname>/api/public/adapter/orders/place 
       -v 
   

   Здесь:

   • -X POST — метод запроса;
   • -u username:password — базовая аутентификация c учётными данными аккаунта с разрешением на вызовы API Comindware Platform;
   • -H "Content-Type: application/json" — заголовок, указывающий на формат данных JSON;
   • -d '...' — тело запроса с JSON-структурой заказа;
   • https://<hostname>/api/public/adapter/orders/place — базовый путь получения HTTP-запросов + путь URI из подключения + путь URI из пути передачи данных;
   • -v — вывод отладочных данных (необязательный ключ).

2. Проверьте обработку запроса: должны быть созданы записи в шаблоне «Заказы», соответствующие полученному запросу.