REST API

Универсальный REST API предоставляет следующую функциональность для дополнения Reports:

  • Получение списка отчётов.

  • Получение информации об отдельном отчёте.

  • Запуск отчёта и скачивание результата.

  • Получение информации о конкретной группе отчетов.

  • Получение документации Swagger.

REST API Reports использует протокол OAuth2 для аутентификации так же, как и Универсальный REST.

Чтобы включить REST API для отчетов, убедитесь, что ваш build.gradle содержит следующие зависимости:

implementation 'io.jmix.reports:jmix-reports-rest-starter'
implementation 'io.jmix.security:jmix-security-oauth2-starter'

Чтобы отчет был доступен в REST API, установите флажок Visible for REST API на вкладке Report structure:

visible for rest
Figure 1. Флажок REST API checkbox

Ниже приведено формальное описание некоторых особенностей REST API для дополнения Reports. Больше информации о REST API и получении OAuth-токена можно найти в документации по REST API.

Получение списка отчетов

Чтобы получить список всех существующих отчётов, выполните GET запрос по адресу:

/rest/reports/report

Например:

GET http://localhost:8080/rest/reports/report

Authorization: Bearer j-Rn3PPAiH7cZZfaDiDWQEDp9YU
Content-Type: application/json

Ответ будет содержать краткую информацию обо всех отчетах с установленным флажком Visible for REST API:

[
    {
        "id": "cb090350-2694-e2bb-f5d9-813daa8dc418", (1)
        "name": "booksAvailability(xlsx)",(2)
        "code": "BOOKS_AVAIL",(3)
        "group": "4e083530-0b9c-11e1-9b41-6bdaa41bff94"(4)
    },
    {
        "id": "d8c7f4c5-2dd7-c7f1-7286-f8dd286d2603",
        "name": "LiteratureTypes(csv)",
        "group": "4e083530-0b9c-11e1-9b41-6bdaa41bff94"
    }
]
1 ID отчета,
2 Имя отчета,
3 Код отчета (если задан),
4 ID группы.

Получение информации об отчете

Для получения детальной информации об отчете выполните GET запрос по адресу:

/rest/reports/report/{id}

Последняя часть запроса здесь – это идентификатор нужного отчета:

GET http://localhost:8080/rest/reports/report/cb090350-2694-e2bb-f5d9-813daa8dc418

Возвращаемый объект JSON будет содержать следующую информацию об отчете:

{
  "id": "cb090350-2694-e2bb-f5d9-813daa8dc418",
  "name": "booksAvailability(xlsx)",
  "code": "BOOKS_AVAIL",
  "group": "4e083530-0b9c-11e1-9b41-6bdaa41bff94",
  "templates": [
    {
      "code": "DEFAULT",
      "outputType": "XLSX"
    }
  ],
  "inputParameters": []
}

Запуск отчета

Чтобы выполнить отчет, выполните POST запрос по адресу:

/rest/reports/run/{id}

Последняя часть запроса здесь – это идентификатор нужного отчета:

POST http://localhost:8080/rest/reports/run/2dd27fbf-8830-416a-899f-339543f8f27a

Параметры отчета можно передать в теле запроса:

{parameters: [{name: 'author',value: '4b3a21b0-d6b7-4161-b0b6-55f118fbaac5'}]}

TЕсли необходимо запустить отчет с шаблоном, отличным от шаблона по умолчанию, передайте код шаблона в теле запроса:

{template: 'Template_1', parameters: [{name: 'author',value: '4b3a21b0-d6b7-4161-b0b6-55f118fbaac5'}]}

Получение информации о группе отчетов

Для получения детальной информации о группе отчетов выполните GET запрос по адресу:

/rest/reports/group/{groupId}

Последняя часть запроса здесь – это идентификатор нужной группы:

GET http://localhost:8080/rest/reports/group/4e083530-0b9c-11e1-9b41-6bdaa41bff94

Возвращаемый объект JSON будет содержать следующую информацию о группе:

  • ID группы

  • Название группы

  • Код группы (если задан)

{
  "id": "4e083530-0b9c-11e1-9b41-6bdaa41bff94",
  "title": "General",
  "code": "ReportGroup.default"
}

Получение документации OpenAPI

Полная документация OpenAPI для дополнения Reports доступна с помощью GET запроса по адресу:

http://localhost:8080/rest/reports/docs/openapi.json
http://localhost:8080/rest/reports/docs/openapi.yaml

При получении openapi.yaml с сервера ответ возвращает тип содержимого application/yaml, поэтому в заголовке запроса следует использовать Accept: application/yaml.