GET дерево

Материал из Документация Ключ-АСТРОМ

Выполняет запрос USQL и возвращает результаты в виде древовидной структуры запрошенных столбцов — плоский список, содержащий запрошенные столбцы.

Чтобы получить правильную древовидную структуру, вам нужно указать группировку в запросе. Поля, используемые в GROUP BYпредложении, образуют «ветви» дерева, каждая из которых содержит «листья» — выбранные поля, которые не использовались для группировки.

Запрос создает в качестве полезной нагрузкиapplication/json формат.

GET Managed https://{your-domain}/e/{your-environment-id}/api/v1/userSessionQueryLanguage/tree
Среда АктивногоШлюза https://{your-activegate-domain}/e/{your-environment-id}/api/v1/userSessionQueryLanguage/tree

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

Чтобы выполнить этот запрос, вам нужен токен доступа с областью сеансов пользователей ( DTAQLAccess) . Чтобы узнать, как его получить и использовать, см. раздел Токены и аутентификация .

Параметры

Параметр Тип Описание In Необходимость
query string Выполняемый запрос сеанса пользователя. Подробнее о синтаксисе см. на странице документации USQL .

Вы можете найти доступные столбцы таблицы usersession в UserSessionобъекте.

Вот пример запроса: SELECT country, city, COUNT(*) FROM usersession GROUP BY country, city.

query требуется
startTimestamp integer Отметка времени начала запроса в миллисекундах UTC.

Если не установлено или установлено как 0, используется отставание от текущего времени на 2 часа.

Если важны точные времена, задайте таймфрейм в самом запросе ( параметр запроса ).

query по желанию
endTimestamp integer Отметка времени окончания запроса в миллисекундах UTC.

Если не установлено или установлено как 0, используется текущая метка времени.

Если важны точные времена, задайте таймфрейм в самом запросе ( параметр запроса ).

query по желанию
offsetUTC integer Дополнительное смещение местного времени относительно времени UTC в минутах. Смещение будет применено к полям даты, встречающимся в запросе.

Может быть положительным или отрицательным. Например, если местное время UTC+02:00, timeOffset равно 120. Если это UTC-05:00, timeOffset равно -300.

query по желанию
addDeepLinkFields boolean Добавьте ( true), чтобы включить прямые ссылки на дополнительные поля в запросе.

Если не установлено, то falseиспользуется

query по желанию
explain boolean Добавьте ( true) или не добавляйте ( false) дополнительную информацию о результате в ответ.

Это помогает понять запрос и то, как был рассчитан результат.

Если не установлено, то falseиспользуется

query по желанию

Ответ

Коды ответов

Код Тип Описание
199 UserSession Структура данных сеанса пользователя. Этот код ответа никогда не возвращается.
200 DtaqlResultAsTree Успех. Ответ содержит результат запроса.
400 Не удалось. Запрос отсутствует.
404 Не удалось. Запрос недействителен. Дополнительную информацию см. в теле ответа.

Объекты тела ответа

Объект DtaqlResultAsTree

Результат запроса сеанса пользователя в виде дерева.

Элемент Тип Описание
extrapolationLevel integer Уровень экстраполяции результата.

Для повышения производительности некоторые результаты могут быть рассчитаны на основе подмножества фактических данных. Уровень экстраполяции указывает на долю фактических данных в результате.

Число является знаменателем дроби и указывает количество фактических данных. Значение 1означает, что результат содержит только фактические данные. Значение 4означает, что результат рассчитывается с использованием 1/4 фактических данных.

Если вам нужно, чтобы анализ основывался на реальных данных, уменьшите временные рамки вашего запроса. Например, в случае уровня экстраполяции 4попробуйте использовать 1/4 исходного таймфрейма.

additionalColumnNames string[] Список столбцов в таблице AdditionalValues.

Присутствует только в том случае, если конечная точка была вызвана с deepLinkFields=trueпараметром.

additionalValues array[] Список строк данных.

Каждый элемент массива представляет строку в таблице дополнительно связанных полей.

Размер каждой строки данных и порядок элементов соответствуют содержимому AdditionalColumnNames .

Присутствует только в том случае, если конечная точка была вызвана с deepLinkFields=trueпараметром.

explanations string[] Дополнительная информация о запросе и результате, помогающая понять запрос и способ расчета результата.

Появляется только тогда, когда для параметра объяснения установлено значение true.

Пример. Количество результатов по умолчанию ограничено 50. Используйте LIMITпункт, чтобы увеличить или уменьшить это ограничение.

branchNames string[] Список ветвей дерева.

Как правило, это поля из SELECTпредложения, которые использовались в GROUP BYпредложении.

leafNames string[] Список листьев на каждой ветке дерева.

Как правило, это поля из SELECTпредложения, которые не использовались в GROUP BYпредложении.

values object Результат запроса сеанса пользователя в виде дерева.

JSON-модель тела ответа

{
  "extrapolationLevel": 1,
  "branchNames": [
    "country",
    "city"
  ],
  "leafNames": [
    "avg(duration)",
    "max(duration)"
  ],
  "values": {
    "Austria": {
      "Klagenfurt": [
        "65996.75",
        "129940"
      ],
      "Linz": [
        "57360.86",
        "222912"
      ]
    },
    "Poland": {
      "Gdansk": [
        "22482.2",
        "351263"
      ]
    }
  }
}

Пример

В этом примере запрос выполняет SELECT country, city, avg(duration), max(duration) FROM usersession GROUP BY country, cityзапрос.

Маркер API передается в заголовке авторизации .

Результат усекается до 4 записей.

Поскольку временной интервал не указан, запрос использует временной интервал по умолчанию, равный 2 часам назад от текущего времени.

В полученной структуре все значения изначально сгруппированы по странам , причем каждый объект массива значений представляет страну. Каждый из этих объектов содержит массивы средней и максимальной продолжительности пользовательских сеансов для каждого города .

Значение extrapolationLevel , равное 4, указывает, что значения экстраполируются на основе 1/4 фактических данных.

Завиток

curl -X GET \
  'https://mySampleEnv.live.ruscomtech.ru/api/v1/userSessionQueryLanguage/api/v1/userSessionQueryLanguage/tree?query=select%20country,%20city,%20avg%28duration%29,%20max%28duration%29%20from%20usersession%20group%20by%20country,%20city' \
  -H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890'

URL-адрес запроса

https://mySampleEnv.live.ruscomtech.ru/api/v1/userSessionQueryLanguage/api/v1/userSessionQueryLanguage/tree?query=select%20country,%20city,%20avg%28duration%29,%20max%28duration%29%20from%20usersession%20group%20by%20country,%20city

Тело ответа

{
  "extrapolationLevel": 4,
  "branchNames": [
    "country",
    "city"
  ],
  "leafNames": [
    "avg(duration)",
    "max(duration)"
  ],
  "values": {
    "Austria": {
      "Vienna": [
        64423.908602150535,
        557649
      ]
    },
    "United States": {
      "Detroit": [
        58984.49809402796,
        504369
      ],
      "Boston": [
        53865.68464730291,
        434636
      ]
    },
    "Poland": {
      "Gdańsk": [
        31177.50773993808,
        445353
      ]
    }
  }
}

Код ответа

200