Reporting API

Обновлено: 25.12.2023

НазначениеНазначение

Reporting API — это программный интерфейс, позволяющий получить источники данных отчетов Timetta в виде OData V4 Feed.

С помощью отчетов данные можно анализировать в веб-приложении или экспортировать их в MS Excel в виде статичного файла. С помощью Reporting API данные Timetta можно подключить к средству аналитики, тем самым обеспечив обновление данных «на лету».

Использование Reporting API позволяет:

• Создать сложный отчет, использующий несколько источников данных Timetta.
• Объединять в стороннем средстве аналитики данные Timetta и других систем, например, финансово-учетной системы.
• Использовать данные Timetta в корпоративных средствах бизнес-аналитики, таких как MS Power BI или QlikView.

API доступно по адресу https://reporting.timetta.com/OData.

АутентификацияАутентификация

Reporting API поддерживает 2 способа аутентификации:

1. Basic Authentication (подробнее Basic Authentication)
2. Bearer Authentication (подробнее Bearer Authentication)

При разработке интеграций рекомендуется использовать второй способ, как более безопасный.

Примеры запросов к Reporting API при помощи обоих способов аутентификации находятся в Postman коллекции.

Пример настройки подключения в MS ExcelПример настройки подключения в MS Excel

В качестве примера построим простой отчет: сводную таблицу с агрегацией по выработанным часам, группировкой по проектам и разрезом по месяцам.

1. На ленте Данные выберите пункт Получить данные -> Из других источников -> Из канала OData:

2. Введите URL канала: https://reporting.timetta.com/OData. Нажмите OK.

3. Выберите тип аутентификации Базовый и укажите ваш адрес электронной почты и пароль, используемые для входа в Timetta и нажмите Подключиться:

4. Выберите источник данных ActualData (Фактические данные) и нажмите Преобразовать данные:

5. В открывшемся редакторе запроса выберем только нужные колонки. Это ускорит работу отчета и упростит дальнейшую настройку. Для этого используйте команду Выбрать колонки:

И оставьте только следующие колонки: Month, Project и HoursTotal. Нажмите ОК:

6. Выполним развертывание колонки-сущности Project. Для этого выберите команду развернуть на ленте или в заголовке колонки:

Выберем одно свойство проекта для отображения — «Наименование». Выберите свойство и нажмите ОК:

7. Сохраните запрос нажав кнопку Закрыть и Загрузить:

8. Данные подключены к Excel. Для построения сводной таблицы на ленте Вставка нажмите кнопку Сводная таблица:

9. Настройте сводную таблицу:

Особенности работы Power QueryОсобенности работы Power Query

Power Query — средство извлечения и трансформации данных из внешних источников, является встроенной функцией продуктов MS Excel (актуальных версий) и Power BI. Для подключения к каналу OData используется коннектор OData.Feed, подробнее — https://docs.microsoft.com/en-us/powerquery-m/odata-feed. В актуальных версиях Power Query доступна вторая версия коннектора, которая включается параметром Implementation = «2.0», этот параметр устанавливается по умолчанию.

Рекомендуем использовать именно эту версию коннектора в виду значительной оптимизации. В частности фильтрация данных в запросе Power Query новой версии приводит к фильтрации на уровне сервера, т. е. в Excel передается ограниченный набор данных. Учитывая ограничение на максимальный набор данных в Reporting API (500 000 строк) для относительно крупных наборов данных подобная фильтрация является полностью необходимой.

Расширенные возможности для крупных командРасширенные возможности для крупных команд

Power Query — удобный и мощный инструмент с простой настройкой без написания запросов. Однако для крупных источников данных (более 250 000 строк) вопрос производительности встает на первый план.

Power Query выполняет так называемый Query Folding. Идея, лежащая в основе Query Folding, заключается в том, чтобы перенести логику, встроенную в запрос Power BI, обратно на сервер источника данных и выполнить его там, вместо преобразования данных на стороне клиента. До второй реализации коннектора, которая включается ключом Implementation = «2.0», данная функция работает очень ограниченно и не во всех случаях. На сторону сервера Power Query переносит несколько операций, в частности: select (выбор колонок), expand («раскрывает» колонки сущности и выбирает только нужные колонки) и filter (фильтрация данных). Этого достаточно в большинстве случаев.

Однако Reporting API отдает данные без группировки, в отличии от того, как это делается в веб-отчетах, подробнее — Группировка и суммирование данных отчета. Например, если вам требуется вывести повременные сведения сводку по утилизации сотрудников на основе источника Фактические данные, то исходных данных может оказаться слишком много для передачи в средство бизнес аналитики и потребуется серверная группировка.

Для решения задач серверной группировки данных Timetta поддерживает расширение стандарта OData по агрегации данных, подробнее — OData Extension for Data Aggregation Version 4.0. Однако его пока не поддерживает Power Query Folding и если вы группируете данные в редакторе запроса, то вначале все данные будут запрошены с сервера и только потом на клиенте будут сгруппированы.

Обходным путем является использование коннектора Json.Document с применение собственного запроса к Reporting API. Следующий пример показывает запрос суммы фактических часов, с группировкой данных и сортировкой по имени сотрудника:

https://reporting.timetta.com/OData/ActualData?$apply=filter(Year ge 2010-01-01)/groupby((User/Name,WeekNumber), aggregate(HoursTotal with sum as HoursTotal))&$orderBy=User/Name

Подобный подход позволяет полностью контролировать запросы, направляемые серверу, и оптимизировать производительность.

Для запроса данных за определенный период необходимо использовать параметры periodStart и periodFinish.
Пример запроса:
https://reporting.timetta.com/OData/Projects?periodStart=2023-01-01&periodFinish=2023-12-31