ENetrebin: Новая страница: «Выполняет запрос USQL и возвращает результаты в виде древовидной структуры запрошенных с...»

2022-10-19T10:26:06Z

Новая страница: «Выполняет запрос USQL и возвращает результаты в виде древовидной структуры запрошенных с...»

Новая страница

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

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

Запрос создает в качестве полезной нагрузки<code>application/json</code> формат.
{| class="wikitable"
| rowspan="2" |GET
|Managed
|<code><nowiki>https://{your-domain}/e/{your-environment-id}/api/v1/userSessionQueryLanguage/tree</nowiki></code>
|-
|Среда АктивногоШлюза
|<code><nowiki>https://{your-activegate-domain}/e/{your-environment-id}/api/v1/userSessionQueryLanguage/tree</nowiki></code>
|}

== Аутентификация ==
Чтобы выполнить этот запрос, вам нужен токен доступа с областью сеансов пользователей ( <code>DTAQLAccess</code>) . Чтобы узнать, как его получить и использовать, см. раздел [[Токены и аутентификация (API)|Токены и аутентификация]] .

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

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

Вот пример запроса: <code>SELECT country, city, COUNT(*) FROM usersession GROUP BY country, city</code>.
|query
|требуется
|-
|startTimestamp
|integer
|Отметка времени начала запроса в миллисекундах UTC.

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

Если важны точные времена, задайте таймфрейм в самом запросе ( параметр запроса ).
|query
|по желанию
|-
|endTimestamp
|integer
|Отметка времени окончания запроса в миллисекундах UTC.

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

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

Может быть положительным или отрицательным. Например, если местное время UTC+02:00, timeOffset равно 120. Если это UTC-05:00, timeOffset равно -300.
|query
|по желанию
|-
|addDeepLinkFields
|boolean
|Добавьте ( <code>true</code>), чтобы включить прямые ссылки на дополнительные поля в запросе.

Если не установлено, то <code>false</code>используется
|query
|по желанию
|-
|explain
|boolean
|Добавьте ( <code>true</code>) или не добавляйте ( <code>false</code>) дополнительную информацию о результате в ответ.

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

Если не установлено, то <code>false</code>используется
|query
|по желанию
|}

== Ответ ==

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

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

==== Объект <code>DtaqlResultAsTree</code> ====
Результат запроса сеанса пользователя в виде дерева.
{| class="wikitable"
!Элемент
!Тип
!Описание
|-
|extrapolationLevel
|integer
|Уровень экстраполяции результата.

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

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

Если вам нужно, чтобы анализ основывался на реальных данных, уменьшите временные рамки вашего запроса. Например, в случае уровня экстраполяции <code>4</code>попробуйте использовать 1/4 исходного таймфрейма.
|-
|additionalColumnNames
|string[]
|Список столбцов в таблице AdditionalValues.

Присутствует только в том случае, если конечная точка была вызвана с <code>deepLinkFields=true</code>параметром.
|-
|additionalValues
|array[]
|Список строк данных.

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

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

Присутствует только в том случае, если конечная точка была вызвана с <code>deepLinkFields=true</code>параметром.
|-
|explanations
|string[]
|Дополнительная информация о запросе и результате, помогающая понять запрос и способ расчета результата.

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

Пример. Количество результатов по умолчанию ограничено 50. Используйте <code>LIMIT</code>пункт, чтобы увеличить или уменьшить это ограничение.
|-
|branchNames
|string[]
|Список ветвей дерева.

Как правило, это поля из <code>SELECT</code>предложения, которые использовались в <code>GROUP BY</code>предложении.
|-
|leafNames
|string[]
|Список листьев на каждой ветке дерева.

Как правило, это поля из <code>SELECT</code>предложения, которые не использовались в <code>GROUP BY</code>предложении.
|-
|values
|object
|Результат запроса сеанса пользователя в виде дерева.
|}

=== JSON-модель тела ответа ===
<code>{
"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"
]
}
}
}</code>

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

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

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

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

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

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

==== Завиток ====
<code>curl -X GET \
'<nowiki>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'</nowiki> \
-H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890'</code>

==== URL-адрес запроса ====
<code><nowiki>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</nowiki></code>

==== Тело ответа ====
<code>{
"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
]
}
}
}</code>

==== Код ответа ====
200

GET дерево - История изменений

ENetrebin: Новая страница: «Выполняет запрос USQL и возвращает результаты в виде древовидной структуры запрошенных с...»