logo

[ELMA3] Обновление Web API до версии 1.0.1 (ELMA 3.2)

Обновление до версии API 1.0.1 произошло с версии сервера 3.2.0. Это обновление не ломает текущий функционал, просто добавляет несколько полезных функций для работы с данными из внешних приложений.
Описания методов и формат передачи вы, как обычно, можете посмотреть на своем сервере по адресу ~/API/Help/Services.

Изменены форматы значений перечислений в объектах

В версии 1.0.0 значения перечислений приходили как строки с названиями этих значений, что во многих случаях неверно, т.к. непосредственно в базе данных значения сохраняются в другом виде. С версии 1.0.1 будет возвращаться именно значение перечисления, которое сохранено в БД, то есть для обычных перечислений – это целое число, для расширяемых – это значение типа Guid.

Добавлены методы получения дерева объектов

В сервис EntityService добавлены методы LoadTree и QueryTree для получения объектов с возможностью развернуть их данные. Например, можно получить список задач и сразу же развернуть список Комментариев, чтобы не делать дополнительный запрос. Для этого вам нужно передать в параметр select этих методов значение "*,Comments/*". Вы можете более подробно ознакомиться с форматом выбора свойств объектов.

Добавлен сервис для выполнения нескольких запросов одновременно

Часто необходимо выполнить запрос на получение разных типов данных, раньше для этого нужно было выполнить несколько веб-запросов к API. В новой версии добавлен сервис BatchOperationService для выполнения нескольких операций одновременно. В этом сервисе реализован метод Query для выполнения нескольких запросов к объектам в рамках одного веб-запроса, этот метод так же поддерживает выборку по свойствам объектов.

Добавлен облегченный протокол получения данных

Для уменьшения размера веб-запроса добавлена возможность указать облегченный протокол данных через заголовок веб-запроса WebData-Version: 2.0

Внимание! Облегченный протокол данных работает только для REST сервисов и требует указания формата вывода JSON

Если говорить кратко, то в этом протоколе объекты будут возвращаться не при помощи универсального объекта WebData а в обычном формате JSON. Этот формат можно использовать при запросе к методам сервиса EntityService, EntityHeadService, BatchOperationService. Также можно использовать этот формат при работе с методами сервисов модулей, например Tasks, Docflow, но обязательно надо учитывать, что данные передаваемые в теле POST-запроса также должны быть в новом формате.

Например, результат получения задачи в обычном протоколе:

{
    "Items": [
        {
            "Data": null,
            "DataArray": [],
            "Name": "Id",
            "Value": "45888"
        },
        {
            "Data": null,
            "DataArray": [],
            "Name": "TypeUid",
            "Value": "f532ef81-20e1-467d-89a4-940c57a609bc"
        },
        {
            "Data": null,
            "DataArray": [],
            "Name": "Uid",
            "Value": "5c192ab0-a48a-48c4-9ce7-4d86d2e964e2"
        },
        {
            "Data": null,
            "DataArray": [],
            "Name": "Subject",
            "Value": "Смирнова.19.11.2012-25.11.2012.xls"
        },
        {
            "Data": null,
            "DataArray": [],
            "Name": "Description",
            "Value": ""
        },
        {
            "Data": null,
            "DataArray": [],
            "Name": "CreationDate",
            "Value": "11\/26\/2012 10:36:03"
        },
        {
            "Data": {
                "Items": [
                    {
                        "Data": null,
                        "DataArray": [],
                        "Name": "Id",
                        "Value": "273"
                    },
                    {
                        "Data": null,
                        "DataArray": [],
                        "Name": "Name",
                        "Value": "Смирнова Наталья"
                    },
                    {
                        "Data": null,
                        "DataArray": [],
                        "Name": "TypeUid",
                        "Value": "18faf3ae-03c9-4e64-b02a-95dd63e54c4d"
                    },
                    {
                        "Data": null,
                        "DataArray": [],
                        "Name": "Uid",
                        "Value": "b1c5ed1f-6d79-45e6-a774-feb5071212db"
                    }
                ]
            },
            "DataArray": [],
            "Name": "CreationAuthor",
            "Value": null
        },
        {
            "Data": {
                "Items": [
                    {
                        "Data": null,
                        "DataArray": [],
                        "Name": "Id",
                        "Value": "30"
                    },
                    {
                        "Data": null,
                        "DataArray": [],
                        "Name": "Name",
                        "Value": "Кононов Антон Александрович"
                    },
                    {
                        "Data": null,
                        "DataArray": [],
                        "Name": "TypeUid",
                        "Value": "18faf3ae-03c9-4e64-b02a-95dd63e54c4d"
                    },
                    {
                        "Data": null,
                        "DataArray": [],
                        "Name": "Uid",
                        "Value": "86c7bd21-c722-aaab-c506-8c7f8548a5de"
                    }
                ]
            },
            "DataArray": [],
            "Name": "Executor",
            "Value": null
        },
        {
            "Data": null,
            "DataArray": [],
            "Name": "StartDate",
            "Value": "11\/26\/2012 00:00:10"
        },
        {
            "Data": null,
            "DataArray": [],
            "Name": "EndDate",
            "Value": "11\/26\/2012 23:59:50"
        },
        {
            "Data": null,
            "DataArray": [],
            "Name": "Priority",
            "Value": "Medium"
        },
        {
            "Data": null,
            "DataArray": [],
            "Name": "Comments",
            "Value": null
        },
        {
            "Data": null,
            "DataArray": [],
            "Name": "Attachments",
            "Value": null
        },
        {
            "Data": null,
            "DataArray": [],
            "Name": "Tags",
            "Value": null
        },
        {
            "Data": null,
            "DataArray": [],
            "Name": "ChildTasks",
            "Value": null
        },
        {
            "Data": null,
            "DataArray": [],
            "Name": "Status",
            "Value": "NewOrder(34387afa-6b70-476f-9d34-748732059003)"
        }
    ]
}

и тот же самый объект, но в новом формате:

{
    "Id": "45888",
    "TypeUid": "f532ef81-20e1-467d-89a4-940c57a609bc",
    "Uid": "5c192ab0-a48a-48c4-9ce7-4d86d2e964e2",
    "Subject": "Смирнова.19.11.2012-25.11.2012.xls",
    "Description": "",
    "CreationDate": "11/26/2012 10:36:03",
    "CreationAuthor": {
        "Id": "273",
        "Name": "Смирнова Наталья",
        "TypeUid": "18faf3ae-03c9-4e64-b02a-95dd63e54c4d",
        "Uid": "b1c5ed1f-6d79-45e6-a774-feb5071212db"
    },
    "Executor": {
        "Id": "30",
        "Name": "Кононов Антон Александрович",
        "TypeUid": "18faf3ae-03c9-4e64-b02a-95dd63e54c4d",
        "Uid": "86c7bd21-c722-aaab-c506-8c7f8548a5de"
    },
    "StartDate": "11/26/2012 00:00:10",
    "EndDate": "11/26/2012 23:59:50",
    "Priority": "Medium",
    "Comments": null,
    "Attachments": null,
    "Tags": null,
    "ChildTasks": null,
    "Status": "NewOrder(34387afa-6b70-476f-9d34-748732059003)"
}

как видите, разница в размере очевидна, и если в вашем приложении используется REST-сервис и данные передаются через JSON, то обязательно рассмотрите возможность перехода на новый протокол получения данных.