История страницы

Версия 1.4 6 от 1109.0708.2017

Содержание

Протокол обмена

Общее описание протокола и точки подключения

Grotem.Mobile имеет удобный API-интерфейс, позволяющий с помощью специальных запросов обмениваться данными со сторонними системами.

...

{идентификатор внешнего клиента} - уникальный идентификатор внешней БД. Должен быть уникальным и фискированным для каждой внешней системы.

Алгоритм синхронизации

Общее описание

При синхронизации сервер GROTEM.Mobile позволяет отслеживать изменения. Для этих целей у всех объектов в БД Grotem.Mobile используется служебное поле Timestamp, где хранится время последнего изменения. При обмене данными в структуре файла обмена предусмотрены поля TimestampFrom и TimestampTo.

...

• Обмен инициируется со стороны клиента (внешней системы).

• Клиент отправляет свой документ с данными и заполненным полем TimestampFrom, в нем передается время последней успешной синхронизации с сервером. Если это поле = 0, то синхронизация считается начальной и клиент получит полный набор данных с сервера.

• Сервер обрабатывает полученные данные:

  • получает документ с данными
  • заполняет в нём поле TimestampTo текущей датой 
  • выполняет обновление записей или помечает их как удаленные
  • всем затронутым (обновленным или удаленным) записям присваивается одно и то же значение Timestamp = TimestampTo

• Сервер формирует набор данных для клиента:

  • получает список записей из всех таблиц изменённых после TimestampFrom (у которых Timestamp >= TimestampFrom)
  • дополняет список записей связанными сущностями (подробнее см. “Выгрузка связанных данных”)
  • производит фильтрацию данных в соответствии с настроенными для каждой таблицы фильтрами (подробнее см. “Фильтрация данных”)
  • исключает из выгрузки объекты, которые пришли со стороны клиента в рамках текущей сессии обмена
  • формирует JSON-файл, сжимает и возвращает клиенту.

• Клиент обрабатывает полученные данные

  • измененные записи обновляются в БД
  • записи к удалению - удаляются из БД
    
    

Выгрузка связанных данных

У всех объектов БД добавлено служебное поле KeyFieldTimestamp. При выгрузке сервер анализирует значение времени в этом поле. И если хотя бы у одного объекта это поле попадает в условия выгрузки (KeyFieldTimestamp >= TimestampFrom):

...

Установка поля KeyFieldTimestamp может приводить к увеличению времени синхронизации.

Фильтрация данных

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

...

Фильтры формируются на этапе проектирования структуры данных. Текущие фильтры описаны в разделе “Типовые фильтры”.

Структура файла обмена

Общее описание

Файл обмена формируется и получается в JSON-формате (кодировка UTF-8).

...

{
    "Id":"2aedcc06-3d1b-4b29-b5af-d5bacf8326c7",
    "TimestampFrom":0,
    "TimestampTo":636062561934757950,
    "DeletedEntities":[],
    "ChangedEntities":[],
    "FiltersToApply":[]
}

Описание параметров:

• "Id" - уникальный идентификатор сессии обмена. По этому идентификатору также в дальнейшем можно получать информацию о сессии.
• "TimestampFrom" - начальная граница промежутка времени для получения изменений (см. “Общее описание алгоритма синхронизации”)
• "TimestampTo" - конечная граница промежутка времени для получения изменений (обычно сюда передается текущее время). Будет установлено в качестве метки времени “Timestamp” для всех объектов, переданных в файле
• "DeletedEntities"- список удаленных объектов (подробнее см. “Формат выгрузки объекта”)
• "ChangedEntities"- список измененных объектов (подробнее см. “Формат выгрузки объекта”)
• "FiltersToApply" - перечень фильтров (не используется и в текущей версии протокола игнорируется)

Формат выгрузки объекта

Для передачи в файле обмена в секциях "DeletedEntities" и "ChangedEntities" используются списки объектов. Каждый элемент списка представляет собой следующий формат

...

...
"ChangedEntities":[
    {
        "Id": "f365b190-1690-11e6-b0e4-6c71d97753d2",
        "IsDeleted": false,
        "Timestamp": 636217442594783700,
        "Tablename": "Catalog.Contacts",
        "SyncFilter": null,
        "Fields": {
            ...
            ...
        },
    }
]
...

Описание полей:

• Обязательные поля для всех объектов (независимо от типа)

  • "Id" - Идентификатор объекта (в формате GUID)
  • "IsDeleted" - признак удаления объекта (такие объекты будут удалены из БД)
  • "Timestamp" - метка времени изменения объекта
  • "Tablename" - имя таблицы, к которой принадлежит объект (подробнее см. “Описание таблиц и полей”)
  • "SyncFilter" - в текущей версии протокола не используется и игнорируется

• "Fields" - поля объекта, характерные для каждой таблицы (подробнее см. “Описание таблиц и полей”)

Пример файла выгрузки

Приведенный пример отображает передачу / получение измененных объектов таблиц:

...

{
    "Id": "055c2053-8e2f-4b78-b83f-f60b9ecff815", 
    "TimestampFrom": 0,
    "TimestampTo": 636219989844656600,
    "DeletedEntities": [],
    "ChangedEntities": [
        {
            "Id": "f4a4d5d0-1dd3-11e6-b0e7-6c71d97753d2",
            "IsDeleted": false,
            "Timestamp": 636219989755439200,
            "Tablename": "Catalog.Client",
            "SyncFilter": null,
            "Fields": {
                "Id": "f4a4d5d0-1dd3-11e6-b0e7-6c71d97753d2",
                "IsDeleted": false,
                "Timestamp": 636219989755439200,
                "KeyFieldTimestamp": 636217442594783700,
                "Predefined": false,
                "DeletionMark": false,
                "Description": "Иванов Михаил Петрович",
                "Code": "000000003",
                "Latitude": 0,
                "Longitude": 0,
                "Address": "г. Санкт-Петербург, ул. Почтамтская, д. 3-5",
                "Contractor": null
            }
        },
        {
            "Id": "9e0d9b3d-71ef-4568-810f-d8e2bfdea923",
            "IsDeleted": false,
            "Timestamp": 636217442594783700,
            "Tablename": "Catalog.Client_Contacts",
            "SyncFilter": null,
            "Fields": {
                "Id": "9e0d9b3d-71ef-4568-810f-d8e2bfdea923",
                "IsDeleted": false,
                "Timestamp": 636217442594783700,
                "KeyFieldTimestamp": 636217442594783700,
                "Ref": "f4a4d5d0-1dd3-11e6-b0e7-6c71d97753d2",
                "LineNumber": 1,
                "Contact": "f4a4d5cd-1dd3-11e6-b0e7-6c71d97753d2",
                "Actual": false
            }
        },
        {
            "Id": "f4a4d5cd-1dd3-11e6-b0e7-6c71d97753d2",
            "IsDeleted": false,
            "Timestamp": 636217442594783700,
            "Tablename": "Catalog.Contacts",
            "SyncFilter": null,
            "Fields": {
                "Id": "f4a4d5cd-1dd3-11e6-b0e7-6c71d97753d2",
                "IsDeleted": false,
                "Timestamp": 636217442594783700,
                "KeyFieldTimestamp": 636217442594783700,
                "Predefined": false,
                "DeletionMark": false,
                "Description": "Иванов Михаил",
                "Code": "000000002",
                "Position": "",
                "Tel": "+7 (812) 325-49-49",
                "EMail": ""
            }
        }
    ],
    "FiltersToApply":[]
}

Примеры отправки запроса (полная синхронизация)

В приведенных ниже примерах HTTP-заголовок для авторизации ‘authorization’ считаем заранее известным

Предполагаем, что точка входа находится по адресу http://server.ru/grotem/admin/SyncSolutionDatabase

...

var client = new RestClient("http://server.ru/grotem/admin/SyncSolutionDatabase");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Basic RGV2MTpEZXYx")
       .AddHeader("configversion", "1.1.0.0")
       .AddHeader("configname", "GrotemExpress")
       .AddHeader("content-type", "application/json")
       .AddHeader("deviceId", "66baa76a-71fe-4395-b4a6-0b77bee9526d")
       .AddParameter("application/json", "{\"Id\":\"f8685de0-b174-44ea-9d89-b36bab8e8043\",\"TimestampFrom\":0,\"TimestampTo\":636219988969526110,\"DeletedEntities\":[],\"ChangedEntities\":[],\"FiltersToApply\":[]}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

...

Описание таблиц и полей

Типы данных

Перечисления (ENum)

Для всех перечислений структура таблиц единая

Enum.ChequeType

Значения:

Enum.PositionPaymentType

Значения:

Enum.CheckListStatus

Значения:

Enum.FoReminders

Значения:

Enum.ResultEvent

Значения:

Enum.StatsNeedNum

Значения:

Enum.StatusEquipment

Значения:

Enum.StatusImportance

Значения:

Enum.StatusTasks

Значения:

Enum.StatusyEvents

Значения:

Enum.TypesDataParameters

Значения:

Enum.TypesEvents

Значения:

Enum.VATS

Значения:

Enum.Webactions

Значения:

...

Catalog.Accounts

Список полей:

Catalog.Actions

Список полей:

Catalog.Actions_ValueList

Список полей:

Catalog.Client

Список полей:

Catalog.Client_Contacts

Список полей:

Catalog.Client_AdditionalAddresses

Список полей:

Catalog.Client_Files

Список полей:

Catalog.Client_Parameters

Список полей:

Catalog.ClientOptions

Список полей:

Catalog.ClientOptions_ListValues

Список полей:

Catalog.Contacts

Список полей:

Catalog.Equipment

Список полей:

Catalog.Equipment_Equipments

Список полей:

Catalog.Equipment_EquipmentsHistory

Список полей:

Catalog.Equipment_Files

Список полей:

Catalog.Equipment_Parameters

Список полей:

Catalog.EquipmentOptions

Список полей:

Catalog.EquipmentOptions_ListValues

Список полей:

Catalog.EventOptions

Список полей:

Catalog.EventOptions_ListValues

Список полей:

Catalog.ListOfPayments

Список полей:

Catalog.Positions

Список полей:

Catalog.RIM

Список полей:

Catalog.Roles

Список полей:

Catalog.RoleWebactions

Список полей:

Catalog.ServiceAgreement

Список полей:

Catalog.SettingMobileApplication

Список полей:

Catalog.SKU

Список полей:

Catalog.TypesDepartures

Список полей:

Catalog.User

Список полей:

Catalog.User_Bag

Список полей:

Catalog.User_RemainsNorms

Список полей:

...

Document.CheckList

Список полей:

Document.CheckList_Actions

Список полей:

Document.Event

Список полей:

Document.Event_CheckList

Список полей:

Document.Event_Equipments

Список полей:

Document.Event_EventFiskalProperties

Список полей:

Document.Event_Files

Список полей:

Document.Event_Parameters

Список полей:

Document.Event_Photos

Список полей:

Document.Event_ServicesMaterials

Список полей:

Document.Event_TypeDepartures

Список полей:

Document.Cheque

Список полей:

Document.Cheque_Nomenclature

Список полей:

Document.Cheque_Payment

Список полей:

Document.Cheque_ChequePhoto

Список полей:

Document.EventHistory

Список полей:

Document.NeedMat

Список полей: