Общие положения

Веб-служба DataService приложения bpm'online является RESTful-сервисом, т.е. поддерживает передачу состояния представления (Representational State Transfer, REST). В общем случае REST является очень простым интерфейсом управления информацией без использования каких-то дополнительных внутренних прослоек, т.е. данные не нужно преобразовывать в какой-либо сторонний формат, например, XML. В простом RESTful-сервисе каждая единица информации однозначно определяется глобальным идентификатором, таким как URL. Каждый URL, в свою очередь, имеет строго заданный формат. Однако это не всегда удобно для передачи больших массивов данных.

В DataService данные автоматичеcки могут быть сконфигурированы в различные форматы данных, такие как XML, JSON, HTML, CSV и JSV. Структура данных определяется так называемыми контрактами данных. Полный перечень контрактов данных, используемых службой DataService, изложен в статье "Веб-служба DataService".

Контракт данных UpdateQuery

Для обновления содержимого записей раздела используется контракт данных UpdateQuery. Передача непосредственно данных в службу DataService осуществляется по HTTP-протоколу при помощи POST-запроса по следующему URL:

// Формат URL для POST-запроса к DataService на обновление данных.
http(s)://[Адрес приложения bpm'online]/[Номер конфигурации]/dataservice/[Формат данных]/reply/UpdateQuery
// Пример URL для POST-запроса к DataService на обновление данных.
http(s)://example.bpmonline.com/0/dataservice/json/reply/UpdateQuery

Контракт данных UpdateQuery имеет иерархическую структуру с несколькими уровнями вложенности. В серверной части ядра приложения bpm'online он представлен классом UpdateQuery пространства имен Terrasoft.Nui.ServiceModel.DataContract библиотеки классов Terrasoft.Nui.ServiceModel.dll. Однако для простоты восприятия иерархическую структуру контракта данных UpdateQuery удобно представить в формате объекта JSON:

{
    "RootSchemaName":"[Корневая схема]",
    "OperationType":[Тип операции с записью],
    "IsForceUpdate":[Принудительное обновление],
   "ColumnValues":{
        "Items":{
            "Имя добавляемой колонки":{
                "ExpressionType":[Тип выражения],
                "Parameter":{
                    "DataValueType":[Тип данных],
                    "Value":"[Значение колонки]"
                }
            }...
        }
    },
    "Filters":[Фильтры запроса]
}

Основные свойства класса UpdateQuery и их возможные значения представлены в таблице 1.

Табл. 1. — Свойства класса UpdateQuery

Класс ColumnValues имеет единственное свойство Items, которое определено как коллекция ключей и значений Dictionary<string, ColumnExpression>. Ключом является строка с названием добавляемой колонки, а значением — объект типа ColumnExpression, определенный в пространстве имен Terrasoft.Nui.ServiceModel.DataContract. Основные свойства класса ColumnExpression, используемые при добавлении записей, приведены в табл. 2.

Табл. 2. — Основные свойства класса ColumnExpression

Класс Parameter имеет несколько свойств, из которых только два используются для добавления записи (табл.3).

Табл. 3. — Основные свойства класса Parameter

 Класс Filters определен в пространстве имен Terrasoft.Nui.ServiceModel.DataContract. Подробности о свойствах этого класса и пример его использования изложены в статье "DataService. Фильтрация данных". 

ВАЖНО Экземпляр класса запроса UpdateQuery обязательно должен содержать в свойстве Filters ссылку на корректно инициализированный экземпляр класса Filters. В противном случае новые значения колонок из свойства ColumnValues будут установлены для ВСЕХ записей раздела.

Пример обновления записи в стороннем приложении

Описание кейса

Необходимо создать консольное приложение, которое, используя службу DataService, обновит запись контакта "Иванов Иван Иванович", добавленную в примере статьи "DataService. Создание записи. Пример". Для этой записи необходимо добавить в колонку [Email] значение i.ivanov@bpmonline.com.

Пример реализации

Полностью исходный код выполнения данного примера можно посмотреть в репозитории GitHub здесь.

Алгоритм реализации кейса

1. Создать и настроить проект консольного приложения C#

Используя среду разработки Microsoft Visual Studio (версии не ниже 2017), необходимо создать проект консольного приложения Visual C#, указав в качестве названия проекта, например, DataServiceUpdateExample. Свойству проекта [Target framework] необходимо установить значение .NET Framework 4.7.

В секцию References проекта нужно добавить зависимости от следующих библиотек:

• System.Web.Extensions.dll — библиотека классов, входящая в .NET Farmework;
• Terrasoft.Core.dll — библиотека основных классов серверного ядра приложения. Можно найти по следующему пути: [Каталог с установленным приложением]\Terrasoft.WebApp\bin\Terrasoft.Core.dll;
• Terrasoft.Nui.ServiceModel.dll — библиотека классов служб приложения. Можно найти по следующему пути: [Каталог с установленным приложением]\Terrasoft.WebApp\bin\Terrasoft.Nui.ServiceModel.dll;
• Terrasoft.Common.dll — библиотека основных классов серверного ядра приложения. Можно найти по следующему пути: [Каталог с установленным приложением]\Terrasoft.WebApp\bin\Terrasoft.Common.dll.

В файл исходного кода приложения необходимо добавить директивы using:

using System;
using System.Text;
using System.IO;
using System.Net;
using System.Collections.Generic;
using Terrasoft.Nui.ServiceModel.DataContract;
using Terrasoft.Core.Entities;
using System.Web.Script.Serialization;
using Terrasoft.Common;

2. В исходный код приложения добавить объявления полей и констант

Для доступа к возможностям службы DataService в исходный код приложения необходимо добавить следующие поля и константы:

// Основной URL приложения bpm'online. Необходимо заменить на пользовательский.
private const string baseUri = @"http://example.bpmonline.com";
// Строка запроса к методу Login сервиса AuthService.svc.
private const string authServiceUri = baseUri + @"/ServiceModel/AuthService.svc/Login";
// Строка пути запроса UpdateQuery.
private const string updateQueryUri = baseUri + @"/0/DataService/json/reply/UpdateQuery";
// Cookie аутентификации bpm'online.
private static CookieContainer AuthCookie = new CookieContainer();

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

3. Добавить метод, выполняющий аутентификацию в приложении bpm'online

Для доступа создаваемого приложения к веб-службе DataService необходимо выполнить аутентификацию.

Алгоритм действия и пример реализации метода, который выполняет запрос к службе AuthService.svc для аутентификации пользователя, подробно изложены в статье Аутентификация внешних запросов к веб-сервисам bpm'online".

4. Добавить непосредственную реализацию запроса на добавление записи

Поскольку объявленная ранее константа updateQueryUri содержит путь для отправки данных в формате JSON, то отправляемые данные нужно предварительно сконфигурировать в виде строки, содержащей описание JSON-объекта, соответствующего контракту данных UpdateQuery. Это можно сделать непосредственно в некоторой строчной переменной, однако намного удобнее и безопаснее с точки зрения возможности возникновения ошибок — создать экземпляр класса UpdateQuery, заполнить его свойства, а затем сериализовать его в строку. Сделать это можно, добавив следующий исходный код:

// Экземпляр класса запроса.
 var updateQuery = new UpdateQuery()
 {
     // Название корневой схемы.
     RootSchemaName = "Contact",
     // Новые значения колонок.
     ColumnValues = new ColumnValues()
     {
         // Коллекция ключ-значение.
         Items = new Dictionary<string, ColumnExpression>()
         {
             // Колонка Email.
             {
                 // Ключ.
                 "Email",
                 // Значение — экземпляр класса выражения запроса к схеме объекта.
                 // Конфигурирование колонки [Email].
                 new ColumnExpression()
                 {
                     // Тип выражения запроса к схеме объекта — параметр.
                     ExpressionType = EntitySchemaQueryExpressionType.Parameter,
                     // Параметр выражения запроса.
                     Parameter = new Parameter()
                     {
                         // Значение пареметра.
                         Value = "i.ivanov@bpmonline.com",
                         // Тип данных параметра — строка.
                         DataValueType = DataValueType.Text
                     }
                 }
             }
         }
     },
     // Фильтры запроса.
     Filters = new Filters()
     {
         // Тип фильтра — группа.
         FilterType = Terrasoft.Nui.ServiceModel.DataContract.FilterType.FilterGroup,
         // Коллекция фильтров.
         Items = new Dictionary<string, Filter>()
         {
              // Фильтрация по имени.
             {
                 // Ключ.
                 "FilterByName",
                 // Значение.
                 new Filter
                 {
                     // Тип фильтра — фильтр сравнения.
                     FilterType = Terrasoft.Nui.ServiceModel.DataContract.FilterType.CompareFilter,
                     // Тип сравнения — начинается выражением.
                     ComparisonType = FilterComparisonType.Equal,
                     // Выражение, подлежащее проверке.
                     LeftExpression = new BaseExpression()
                     {
                         // Тип выражения — колонка схемы.
                         ExpressionType = EntitySchemaQueryExpressionType.SchemaColumn,
                         // Пкть к колонке.
                         ColumnPath = "Name"
                     },
                     // Выражение фильтрации.
                     RightExpression = new BaseExpression()
                     {
                         // Тип выражения — параметр.
                         ExpressionType = EntitySchemaQueryExpressionType.Parameter,
                          // Параметр выражения.
                         Parameter = new Parameter()
                         {
                             // Тип данных параметра — текст.
                             DataValueType = DataValueType.Text,
                             // Значение параметра.
                             Value = "Иванов Иван Иванович"
                         }
                     }
                 }
             }
         }
     }
 };
 // Сериализация экземпляра класса запроса на добавление в JSON-строку.
 var json = new JavaScriptSerializer().Serialize(updateQuery);

Здесь создается экземпляр класса UpdateQuery, в свойстве ColumnValues которого устанавливается значение "i.ivanov@bpmonline.com" для колонки [Email]. Для того чтобы это значение было применено только для определенной записи или группы записей, необходимо свойству Filters присвоить значение ссылки на корректно инициализированный экземпляр класса Filters. В данном случае в коллекцию фильтров добавлен единственный фильтр, который отбирает только те записи, у которых значение колонки  [ФИО] равно "Иванов Иван Иванович".

На завершающем шаге необходимо выполнить POST-запрос к службе DataService. Для этого необходимо создать экземпляр класса HttpWebRequest, заполнить его свойства, присоединить к запросу созданную ранее строку с JSON-объектом, а затем выполнить и обработать результат запроса к службе DataService. Для этого нужно добавить следующий исходный код:

// Преобразование строки JSON-объекта в массив байтов.
byte[] jsonArray = Encoding.UTF8.GetBytes(json);
// Создание экземпляра HTTP-запроса.
var updateRequest = HttpWebRequest.Create(updateQueryUri) as HttpWebRequest;
// Определение метода запроса.
updateRequest.Method = "POST";
// Определение типа содержимого запроса.
updateRequest.ContentType = "application/json";
// Добавление полученных ранее аутентификационных cookie в запрос на получение данных.
updateRequest.CookieContainer = AuthCookie;
// Установить длину содержимого запроса.
updateRequest.ContentLength = jsonArray.Length;

// Добавление CSRF токена в заголовок запроса.
CookieCollection cookieCollection = AuthCookie.GetCookies(new Uri(authServiceUri));
string csrfToken = cookieCollection["BPMCSRF"].Value;
updateRequest.Headers.Add("BPMCSRF", csrfToken);

// Помещение JSON-объекта в содержимое запроса .
using (var requestStream = updateRequest.GetRequestStream())
{
    requestStream.Write(jsonArray, 0, jsonArray.Length);
}
// Выполнение HTTP-запроса и получение ответа от сервера.
using (var response = (HttpWebResponse)updateRequest.GetResponse())
{
    // Вывод ответа в консоль.
    using (StreamReader reader = new StreamReader(response.GetResponseStream()))
    {
        Console.WriteLine(reader.ReadToEnd());
    }
}

Полностью исходный код выполнения данного примера можно посмотреть в репозитории GitHub здесь.

Смотрите также