4.8.1.2.4. Выполнение JPQL запроса для выборки данных

Для выполнения запроса необходимо выполнить GET запрос {host:port}/app-portal/api/query.<format> с параметрами:

  • e − имя сущности

  • q − строка запроса к данным на JPQL. Запрос может содержать параметры. Их значения указываются как значения одноименных параметров HTTP запроса.

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

  • view − опционально, представление, с которым требуется загружать данные

  • max − опционально, максимальное количество строк возвращаемых данных (аналогично JPA setMaxResults)

  • first − опционально, номер первой строки возвращаемых данных (аналогично JPA setFirstResult)

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

Например:

http://localhost:8080/app-portal/api/query.json?e=sales$Customer&q=select+c+from+sales$Customer+c&s=748e5d3f-1eaf-4b38-bf9d-8d838587367d&view=_local
http://localhost:8080/app-portal/api/query.json?e=sales$Customer&q=select+c+from+sales$Customer+c+where+c.name=:name&s=748e5d3f-1eaf-4b38-bf9d-8d838587367d&name=Петров

Для каждого из передаваемых параметров можно явно указать его тип, добавив в запрос одноименный параметр с суффиксом _type. Например:

http://localhost:8080/app-portal/api/query.json?e=sales$Customer&q=select+c+from+sales$Customer+c+where+c.name=:name&s=748e5d3f-1eaf-4b38-bf9d-8d838587367d&name=Петров&name_type=string

Указание типа параметра не является обязательным, но позволяет избежать ошибок парсинга, если система не сможет определить тип. В общем случае тип стоит указывать лишь для строковых параметров, которые по какой-либо причине имеют формат более узких типов (дат, чисел, uuid), но должны интерпретироваться именно как строки. Список доступных типов можно увидеть в описании мета-модели (пункт меню Помощь −> Модель данных) или получив HTML-описание модели.

JPQL-запрос можно также выполнить с помощью HTTP POST на URL вида {host:port}/app-portal/api/query.<format>?s=<sessionId>, где <sessionId> - это идентификатор пользовательской сессии. В данном случае JPQL-запрос и его параметры передаются в теле запроса как показано в примерах ниже.

Пример POST запроса формата JSON (заголовок Content-Type должен быть установлен в application/json):

http://localhost:8080/app-portal/api/query.json?s=748e5d3f-1eaf-4b38-bf9d-8d838587367d

Тело запроса:

{
  "entity": "sales$Customer",
  "query": "select c from sales$Customer c where c.name=:name",
  "params": [
      {
        "name": "name",
        "value": "Smith",
        "type": "string"
      }
  ]
}

Пример POST запроса формата XML (заголовок Content-Type должен быть установлен в text/xml):

http://localhost:8080/app-portal/api/query.xml?s=748e5d3f-1eaf-4b38-bf9d-8d838587367d

Тело запроса:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<QueryRequest xmlns="http://schemas.haulmont.com/cuba/restapi-query-request-v2.xsd">
    <entity>sales$Customer</entity>
    <query>select c from sales$Customer c where c.name=:name</query>
    <params>
        <param>
            <name>name</name>
            <value>Smith</value>
            <type>string</type>
        </param>
    </params>
</QueryRequest>