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

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

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

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

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

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

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

{
    "RootSchemaName":"[Корневая схема]",
    "OperationType":[Тип операции с записью],
    "ColumnValues":[Значения колонок. Не используется.],
    "Filters":[Фильтры запроса]
}

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

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

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

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

Пример удаления записи из стороннего приложения

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

Необходимо создать консольное приложение, которое, используя службу DataService, удалит запись контакта "Иванов Иван Иванович", добавленную в примере статьи "DataService. Создание записи. Пример".

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

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

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

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

Используя среду разработки Microsoft Visual Studio (версии не ниже 2017), необходимо создать проект консольного приложения Visual C#, указав в качестве названия проекта, например, DataServiceDeleteExample. Свойству проекта [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";
 // Строка пути запроса DeleteQuery.
 private const string deleteQueryUri = baseUri + @"/0/DataService/json/reply/DeleteQuery";
 // 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 deleteQuery = new DeleteQuery()
{
    // Название корневой схемы.
    RootSchemaName = "Contact",
    // Фильтры запроса.
    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);

Здесь создается экземпляр класса DeleteQuery, в свойстве RootSchemaName которого устанавливается значение "Contact". Для того чтобы удалена была только определенная запись или группа записей, необходимо свойству 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 здесь.

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