Введение

Comindware Platform позволяет отправлять HTTP-запросы типов GET, POST, PUT, DELETE с помощью сценариев для взаимодействия с внешними системами.

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

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

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

Требуется отправить заказ из нескольких позиций и получить статус заказа: Принят или Отклонён.

Рассмотрим настройку отправки запросов на сервер и получение от него ответов.

• Имеются шаблоны записей:
  • «Заказы» с атрибутами:
  • «Номер заказа» типа «Текст»;
  • «Позиции» типа «Запись», ссылается на шаблон «Позиции заказов» и хранит несколько значений;
  • «Статус заказа» типа «Текст».
  • «Позиции заказов» с атрибутами:
  • «Товар» типа «Текст»;
  • «Количество» типа «Число».
• Базовый URL для HTTP-запросов: https://<hostname>/api

• Путь для отправки заказа на проверку статуса: https://<hostname>/api/place-order

  При настройке приложения подставьте реальный адрес вместо https://<hostname>/api/place-order

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

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

• Запрос содержит данные позиций в формате JSON вида:

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

• В ответ на запрос сервер возвращает JSON-ответ вида:

  { 
      "status": "string" 
  } 
  

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

1. Откройте раздел «Администрирование» — «Подключения».

2. В меню «Создать» выберите пункт «Подключения REST и OData» — «Отправка HTTP-запросов».

   

3. Настройте подключение для отправки HTTP-запросов со следующими параметрами:

   • URI — https://<hostname>/api. Символ / в конце URI не требуется.
   • Формат данных — JSON. Также поддерживаются XML и простой текст, но здесь рассматривается обработка данных в формате JSON.

4. Остальные параметры подключения настройте в соответствии с конфигурацией используемого сервера. См. «Отправка HTTP-запросов. Настройка подключения».

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

1. Откройте раздел «Администрирование» — «Пути передачи данных».

2. В меню «Создать» выберите пункт «Подключения REST и OData» — «Отправка HTTP-запросов».

   

3. Настройте путь передачи данных для отправки HTTP-запросов на вкладках «Основные свойства», «Атрибуты сообщений», «Интеграция».

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

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

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

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

• Запрос — добавьте следующие атрибуты:

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

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

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

• Ответ — добавьте атрибут status типа «Строка» — этот атрибут будет содержать статус с ответом от сервера.

• Ответ с ошибкой — добавьте атрибут status типа «Строка» — этот атрибут будет содержать статус с ошибкой от сервера.

Интеграция

• Метод запроса — выберите POST.

• Шаблон пути запроса — введите place-order (фактический путь к HTTP-запросу на сервере), этот суффикс будет добавлен к URI, указанному в свойствах подключения для отправки HTTP-запросов.

  То есть, при шаблоне пути запроса place-order для URI https://<hostname>/api результирующий путь запроса будет https://<hostname>/api/place-order.

• Атрибут для сериализации в тело запроса — введите через запятую системные имена атрибутов из таблицы «Запрос» на вкладке «Атрибуты сообщений», в нашем примере: orderNumber, items.

  

• Атрибуты для десериализации ответа без ошибки и Атрибуты для десериализации ответа с ошибкой — создайте одну строку в каждой таблице и введите символ $ в столбцы «Путь к атрибуту» и «Выражение на языке запросов». Этот символ обозначает передачу всей структуры JSON.

  

Настройка сценария отправки HTTP-запроса

1. Создайте сценарий, например, выполняющийся по нажатию кнопки.

2. В свойствах действия «Нажатие кнопки» укажите контекстный шаблон, содержащий атрибуты для HTTP-запроса и ответа.

   

3. После действия «Нажатие кнопки» добавьте действие «Проверить результат скрипта» для подготовки данных HTTP-запроса с помощью 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) 
       {       
           // Получаем ID текущей записи (заказа) 
           var id = o.ToString().Replace("user.", ""); 
    
           // Получаем данные записи: 
           // значения атрибутов «Позиции» и «Номер заказа» 
           var data = Api.TeamNetwork.ObjectService.GetPropertyValues(new []{id}, new []{"Позиции", "НомерЗаказа"}); 
           var itemsIdsArray = data[id]["Позиции"] as object[]; 
    
           // Объявляем массив позиций (класс Item) 
           var listItems = new List<Item>(); 
    
           // Получаем данные каждой позиции 
           foreach(var itemId in itemsIdsArray) 
           { 
               var itemData = Api.TeamNetwork.ObjectService.GetPropertyValues(new []{itemId.ToString()}, new []{"Товар", "Количество"}); 
               // Собираем экземпляр класса Item 
               var item = new Item{product = itemData[itemId.ToString()]["Товар"].ToString(), number = Convert.ToInt32(itemData[itemId.ToString()]["Количество"].ToString())}; 
               // Собираем массив позиций для отправки 
               listItems.Add(item); 
           } 
    
           // Переменная для отправляемых данных 
           var outMessage = new OutgoingRootMessage{name = data[id]["НомерЗаказа"].ToString(), items = listItems}; 
           // Проставляем в локальную переменную значение для последующей отправки 
           // OutgoingRootMessage – класс сообщения (структура данных) 
           // Имя RawBody – состоит из двух частей: 
           //1. Raw – системная часть 
           //2. Body – имя переменной с сообщением, заданной в действии «Отправить сообщение» 
           Api.Base.LocalVariablesService.Set<OutgoingRootMessage>("RawBody", outMessage); 
    
           return true; 
       } 
   } 
    
   public class OutgoingRootMessage 
   { 
       public string name {get; set;} 
       public List<Item> items {get; set;} 
   } 
    
   public class Item 
   { 
       public string product {get; set;} 
       public int number {get; set;} 
   } 
   

4. Добавьте и настройте действие «Отправить сообщение»:

   • Подключение — выберите подключение для отправки HTTP-запросов.
   • Путь передачи данных — выберите ранее настроенный путь для передачи данных HTTP-запроса.
   • Переменная с сообщением — введите системное имя переменной, в которую предшествующее действие «Проверить результат скрипта» помещает данные запроса (в нашем примере Body, без префикса Raw).
   • Переменная для успешного ответа — введите системное имя переменной, в которую будет помещён ответ сервера на HTTP-запрос (например, Success).

   • Переменная для ответа с ошибкой — введите системное имя переменной, в которую будет помещён ответ сервера в случае ошибки (например, Error).

     

5. Добавьте и настройте второе действие «Проверить результат скрипта» для проверки ответа после отправки.

   Это действие использует C#-скрипт для проверки и обработки ответа от сервера. Если скрипт вернёт false, сценарий будет остановлен.

   • Сообщение об ошибке — введите текст сообщения, которое будет отображено, если скрипт вернёт 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) 
       { 
    
           // Получаем ID текущей записи 
           var id = o.ToString().Replace("user.", ""); 
    
           // Получаем значения из успешного ответа. 
           // Имя RawSuccess состоит из двух частей: 
           // 1. Raw – неизменный системный префикс 
           // 2. Success – имя переменной для успешного ответа, заданной в действии «Отправить сообщение» 
           var inputSuccess = Api.Base.LocalVariablesService.Get<IncomingRootMessage>("RawSuccess"); 
           // Получаем значение из ответа с ошибкой. 
           // Имя RawError состоит из двух частей: 
           // 1. Raw – неизменный системный префикс 
           // 2. Error – имя переменной для ответа с ошибкой, заданной в действии «Отправить сообщение» 
           var inputError = Api.Base.LocalVariablesService.Get<IncomingRootMessage>("RawError"); 
    
    
           // Помещает полученный статус в атрибут «Статус заказа» 
           // СтатусЗаказа — системное имя атрибута 
           if(inputSuccess != null) 
           { 
               Api.TeamNetwork.ObjectService.EditWithAlias(id, new Dictionary<string,object>{{"СтатусЗаказа",inputSuccess.status}}); 
           } 
           else if(inputError != null) 
           { 
               Api.TeamNetwork.ObjectService.EditWithAlias(id, new Dictionary<string,object>{{"СтатусЗаказа",inputError.status}}); 
           } 
           else 
           { 
               Api.TeamNetwork.ObjectService.EditWithAlias(id, new Dictionary<string,object>{{"СтатусЗаказа","Произошла ошибка"}}); 
           } 
    
           return true; 
       } 
   } 
    
    
   public class IncomingRootMessage 
   { 
       public string status {get; set;} 
   } 
   

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

   

7. Проверьте работу приложения: сценарий должен отправлять HTTP-запрос с позициями заказа и получать статус заказа от внешнего сервера.