Creatio development guide

DataService. Обновление записи. Пример

Glossary Item Box

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

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

Свойство Тип Описание
RootSchemaName string Строка, содержащая название корневой схемы объекта добавляемой записи.
OperationType QueryOperationType

Тип операции с записью. Задается значением перечисления QueryOperationType пространства имен Terrasoft.Nui.ServiceModel.DataContract. Для InsertQuery устанавливается значение QueryOperationType.Insert.

Значения перечисления QueryOperationType:

Select 0
Insert 1
Update 2
Delete 3
Batch 4
IsForceUpdate bool Признак принудительного обновления. Если имеет значение true, то сущность будет принудительно сохранена на сервере, даже если значения колонок не были изменены. По умолчанию имеет значение false.
ColumnValues ColumnValues Содержит коллекцию значений колонок добавляемой записи. Имеет тип ColumnValues, определенный в пространстве имен Terrasoft.Nui.ServiceModel.DataContract.
Filters Filters Коллекция фильтров запросов. Имеет тип Filters, определенный в пространстве имен Terrasoft.Nui.ServiceModel.DataContract.

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

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

Свойство Описание
ExpressionType

Тип выражения, определяющий значение, которое будет содержаться в добавляемой колонке. Задается значением перечисления EntitySchemaQueryExpressionType пространства имен Terrasoft.Core.Entities, определенного в библиотеке классов Terrasoft.Core. Для InsertQuery устанавливается значение EntitySchemaQueryExpressionType.Parameter.

Значения перечисления EntitySchemaQueryExpressionType:

SchemaColumn 0
Function 1
Parameter 2
SubQuery 3
ArithmeticOperation 4
Parameter

Определяет значение, которое будет содержаться в добавляемой колонке. Имеет тип Parameter, определенный в пространстве имен Terrasoft.Nui.ServiceModel.DataContract.

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

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

Свойство Описание
DataValueType

Тип данных значения, которое будет содержаться в добавляемой колонке. Задается значением перечисления DataValueType пространства имен Terrasoft.Nui.ServiceModel.DataContract

Значения перечисления DataValueType:

Guid 0
Text 1
Integer 4
Float 5
Money 6
DateTime 7
Date 8
Time 9
Lookup 10
Enum 11
Boolean 12
Blob 13
Image 14
ImageLookup 16
Color 18
Mapping 26
Value

Объект, содержащий значение добавляемой колонки. Имеет тип Object.

 Класс 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());
    }
}

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

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

© Terrasoft 2002-2016.

Был ли данный материал полезен?

Как можно улучшить эту статью?