4.8.1.2.9. Вызов сервисов

Доступные для вызова методы сервисов перечислены в конфигурационном файле, имя которого задается свойством cuba.restServicesConfig.

Пример файла конфигурации сервисов для REST API:

<services xmlns="http://schemas.haulmont.com/cuba/restapi-service-v2.xsd">
   <service name="refapp_PortalTestService">
      <method name="findAllCars"/>
      <method name="updateCarVin"/>
   </service>
</services>

Вызов метода сервиса можно осуществить как с помощью GET, так и с помощью POST запроса. POST запрос дополнительно позволяет передавать сущность или коллекцию сущностей в вызываемый метод.

Вызов сервиса с помощью GET запроса

Формат запроса:

{host:port}/app-portal/api/service.<format>?service=<serviceName>&method=<methodName>&view=<view>&param0=<value 0>&paramN=<value N>&param0_type=<type 0>&paramN_type=<type N>&s=<sessionId>

  • format - задает формат вывода результата. Принимает два значения: xml или json.

  • service - имя вызываемого сервиса.

  • method - имя вызываемого метода.

  • param0 .. paramN - значения параметров метода.

  • param0_type .. paramN_type - типы параметров метода.

  • s - идентификатор текущей сессии

Если сервис имеет лишь один метод с указанным именем и количеством параметров, то явное определение типов параметров не обязательно. В противном случае указывать типы параметров необходимо.

Вызов сервиса с помощью POST запроса

Формат запроса:

{host:port}/app-portal/api/service?s=<sessionId>

  • s - идентификатор текущей сессии.

В теле запроса передается JSON или XML с описанием вызова метода.

Формат JSON

В качестве заголовка Content-Type следует использовать значение application/json.

{
"service": "refapp_PortalTestService",
"method": "updateCarVin",
"view": "carEdit",
"params": {
    "param0": {
        "id": "ref$Car-32261b09-b7f7-4b8c-88cc-6dee6fa8e6ab",
        "vin": "WV00001",
        "colour" : {
            "id": "ref$Colour-b32a6412-d4d9-11e2-a20b-87b22b1460c7",
            "name": "Red"
        },
        "driverAllocations": [
            {
                "id": "ref$DriverAllocation-b32e43e8-d4d9-11e2-8c8b-2b2939d67fff"
            },
            {
                "id": "NEW-ref$DriverAllocation"
            }
        ]
    },
        "param1": "WV00001",
        "param0_type": "com.haulmont.refapp.core.entity.Car",
        "param1_type": "java.lang.String"
        }
    }

Свойства передаваемого объекта:

  • service - имя вызываемого сервиса.

  • method - имя вызываемого метода.

  • param0 .. paramN - значения параметров метода.

  • param0_type .. paramN_type - типы параметров метода.

Формат XML

В качестве заголовка Content-Type следует использовать значение text/xml.

<ServiceRequest xmlns="http://schemas.haulmont.com/cuba/restapi-service-v2.xsd">
    <service>refapp_PortalTestService</service>
    <method>updateCarVin</method>
    <view>carEdit</view>
    <params>
        <param name="param0">
            <instance id="ref$Car-32261b09-b7f7-4b8c-88cc-6dee6fa8e6ab">
                <field name="vin">WV00000</field>
                <reference name="colour">
                    <instance id="ref$Colour-b32a6412-d4d9-11e2-a20b-87b22b1460c7">
                        <field name="name">Red</field>
                    </instance>
                </reference>
                <collection name="driverAllocations">
                    <instance id="ref$DriverAllocation-b32e43e8-d4d9-11e2-8c8b-2b2939d67fff"/>
                    <instance id="NEW-ref$DriverAllocation"/>
                </collection>
            </instance>
        </param>
        <param name="param1">WV00001</param>
        <param name="param0_type">com.haulmont.refapp.core.entity.Car</param>
        <param name="param1_type">java.lang.String</param>
        </params>
</ServiceRequest>

Основные элементы передаваемого документа:

  • service - имя вызываемого сервиса.

  • method - имя вызываемого метода.

  • param - значение параметра метода или тип параметра. Имя параметра (атрибут name) должно быть вида param0 .. paramN или param0_type .. paramN_type.

Если сервис имеет лишь один метод с указанным именем и количеством параметров, то явное определение типов параметров не обязательно. В противном случае указывать типы параметров необходимо.

Элемент <param> может содержать в себе как текст (для задания значений простых типов данных), так и вложенный элемент <instance> для сущности или <instances> для коллекции сущностей.

XSD запроса доступна по адресу http://schemas.haulmont.com/cuba/6.4/restapi-service-v2.xsd.

Поддерживаемые типы параметров метода сервиса

  • примитивные типы Java. В качестве имени типа указывается long, int, boolean и т.д.

  • обертки для примитивных типов Java. В качестве имени типа указывается полное имя класса: java.lang.Boolean, java.lang.Integer и т.д.

  • строка (java.lang.String).

  • дата (java.util.Date).

  • UUID (java.util.UUID).

  • BigDecimal (java.math.BigDecimal).

Результат вызова сервиса

В зависимости от объявления вызова метода, результат будет в формате JSON или XML. В настоящее временя поддерживается возврат из методов простых типов данных, сущностей и коллекций сущностей.

Пример результата в формате JSON

Результат имеет простой тип данных:

{
   "result": "10"
}

Результатом является сущность:

{
   "result": {
      "id" : "ref$Colour-b32e43e8-d4d9-11e2-8c8b-2b2939d67fff",
           "name": "Red"
        }
}
Пример результата в формате XML

Результат имеет простой тип данных:

<result>
        10
</result>

Результатом является сущность:

<result>
   <instance id="ref$Colour-b32a6412-d4d9-11e2-a20b-87b22b1460c7">
      <field name="name">Red</field>
   </instance>
</result>

XSD результата доступна по адресу http://schemas.haulmont.com/cuba/6.4/restapi-service-v2.xsd.