Рекомендации по работе с Reporting API

Обновлено: 25.04.2026

Когда есть смысл работать с Reporting APIКогда есть смысл работать с Reporting API

Использование Reporting API оправдано в следующих сценариях:

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

ОграниченияОграничения

Reporting API — это не витрина данных. Его не следует использовать для полной выгрузки всей базы организации с максимальной детализацией. Такие операции могут привести к ошибкам и отказам в обслуживании.

При работе с Reporting API необходимо учитывать лимиты сервера:

• не более 500 запросов за 10 секунд на одного пользователя;
• не более 5 одинаковых запросов за 1 минуту на одного пользователя;
• не более 75 000 сущностей за один запрос.

Рекомендации по проектированию запросовРекомендации по проектированию запросов

Чтобы отчеты работали стабильно и не перегружали систему, соблюдайте следующие практики.

1. Разделяйте данные и справочники.
   Не пытайтесь получить всё одним большим запросом с множественными вложенными $expand. Лучше выгружать данные и справочники отдельными запросами. Связывание выполняйте на стороне приёмника по ID. Это упрощает отладку, уменьшает объём ответа и снижает риск обрыва тяжёлого запроса.

2. Используйте минимально достаточный уровень агрегации.
   Например, запрашивать ресурсный план по дням, задачам и пользователям — слишком тяжёлая операция. Запрашивайте данные сгруппированными: по месяцам, кварталам или неделям. Группировку выполняйте на стороне сервера с помощью синтаксиса OData.

3. Настройте инкрементальную загрузку.
   Не запрашивайте исторические данные при каждом обновлении отчёта. Обновляйте только новые или изменённые данные.

4. Явно ограничивайте набор полей.
   Всегда используйте параметр $select, чтобы сервер возвращал только нужные колонки. Исключение тяжёлых системных полей экономит трафик и память.

Тестирование и отладкаТестирование и отладка

Запросы к Reporting API можно выполнять из разных сред. Перед внедрением в Excel или BI-системы отладьте их в изолированной среде, например в Postman. Это поможет отделить проблемы самого OData-запроса от особенностей и кэширования коннектора.

Аутентификация и права доступаАутентификация и права доступа

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

• Basic Authentication;
• Bearer Authentication.

Для интеграций рекомендуется использовать Bearer Authentication с API Token — долгоживущим access token сроком действия 1 год. Токен передаётся в заголовке запроса:

Authorization: Bearer <ACCESS_TOKEN>

Как изучить структуру данныхКак изучить структуру данных

МетаданныеМетаданные

Чтобы понять, какие таблицы и колонки доступны для выгрузки, изучите метамодель системы. Метаданные Reporting API в формате XML доступны по адресу https://reporting.timetta.com/odata/$metadata.

В метаданных описаны все типы данных, ключи и связи между сущностями.

Навигатор ExcelНавигатор Excel

Для первичного знакомства со структурой Reporting API можно подключить источник через Get External Data и открыть навигатор Excel. Это позволяет просмотреть список доступных таблиц и состав полей. Пошаговый порядок подключения описан в статье Reporting API.

Примитивные и навигационные свойстваПримитивные и навигационные свойства

При проектировании запросов важно различать типы свойств:

• Примитивные свойства (Property) — поля, хранящие собственные значения сущности: текст, числа, даты, GUID.
• Навигационные свойства (NavigationProperty) — поля, описывающие связи с другими сущностями и позволяющие получать связанные данные.

Для сущности Project поля startDate, endDate, code, name, description, managerId, organizationId, contractId, stateId, id, created, modified, isActive являются примитивными. Их можно выбрать с помощью $select.

Связанные данные по руководителю, организации, договору и состоянию получаются через навигационные свойства manager, organization, contract и state с помощью $expand.

Пример раскрытия навигационных свойств:

GET https://reporting.timetta.com/OData/Projects?
$select=name,code,managerId,organizationId,contractId,stateId&
$expand=
manager($select=name,email),
organization($select=name),
contract($select=name),
state($select=name)

Пример вложенной навигации:

GET https://reporting.timetta.com/OData/Projects?
$select=name,organizationId&
$expand=organization(
    $select=name,managerId;
    $expand=manager($select=name,email)
)

Основные выражения синтаксиса ODataОсновные выражения синтаксиса OData

При работе с Reporting API чаще всего используются следующие параметры:

• $select — выбор определённых свойств;
• $expand — раскрытие навигационных свойств;
• $filter — серверная фильтрация строк;
• $apply и groupby — серверная группировка и агрегация.

Параметр $filter поддерживает логические операторы:

• eq — равно;
• ne — не равно;
• gt / ge — больше / больше или равно;
• lt / le — меньше / меньше или равно;
• and / or — логическое И / ИЛИ.

Примеры:

• Выбор нескольких полей:

GET https://reporting.timetta.com/OData/Projects?$select=name,code,startDate,endDate

• Фильтр по записям:

GET https://reporting.timetta.com/OData/Projects?$filter=isActive eq true

• Фильтрация по навигационному свойству:

GET https://reporting.timetta.com/OData/Projects?$filter=organization/name eq 'ООО Ромашка'

• Группировка данных на стороне сервера:

GET https://reporting.timetta.com/OData/Projects?
$apply=groupby((State/Name,Organization/Name),aggregate($count as ProjectsCount))

Рекомендации по работе из MS ExcelРекомендации по работе из MS Excel

Для рабочей загрузки данных в Excel рекомендуется создать в Power Query пустой запрос и явно указать URL к Reporting API с нужными параметрами OData.

Код запросов в Power Query пишется на языке Power Query M. Документация по языку доступна на сайте Microsoft.
`
Перед созданием запроса можно вынести параметры в именованные ячейки Excel:

• BaseURL — базовый адрес Reporting API;
• Token — API token или access token;
• startDate — начало периода;
• endDate — конец периода.

Пример запроса в Power Query M:

let
    GetCellValue = (rangeName) =>
        Excel.CurrentWorkbook(){[Name=rangeName]}[Content]{0}[Column1],

    BaseURL = GetCellValue("BaseURL"),
    Token = GetCellValue("Token"),
    StartDate = Date.ToText(Date.From(GetCellValue("startDate")), "yyyy-MM-dd"),
    EndDate = Date.ToText(Date.From(GetCellValue("endDate")), "yyyy-MM-dd"),

    Table = "ResourcePlan",
    ApplyQuery =
        "$apply=filter(ResourceName ne null and month ge " & StartDate &
        " and month le " & EndDate &
        ")/groupby((Month, Project/Name, ResourceName), aggregate(EstimatedHours with sum as EstimatedHours))",

    FullURL = BaseURL & Table & "?" & ApplyQuery,

    Source = Json.Document(
        Web.Contents(
            FullURL,
            [Headers = [Authorization = "Bearer " & Token]]
        )
    )
in
    Source

В этом примере запрос получает данные из источника ResourcePlan, фильтрует их по периоду и группирует по месяцу, проекту и ресурсу. Значения периода, токена и базового адреса берутся из именованных ячеек Excel.

После выполнения запроса:

• преобразуйте полученный список записей в таблицу;
• разверните нужные колонки;
• задайте корректные типы данных для дат, числовых и текстовых полей.

Дополнительно рекомендуется:

• заменять null на 0 в числовых колонках, используемых в вычислениях;
• явно задавать типы данных после загрузки;
• при объединении таблиц включать в запрос только нужные колонки из связанной таблицы.