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

Веб-служба 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.

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

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

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

В секцию 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;
// Помещение 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());
    }
}

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

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